mcp-probe-kit 3.0.11 → 3.0.13

package/README.md

@@ -316,10 +316,10 @@ No installation needed, use the latest version directly.
 }
 ```
 
-### Method 2: Global Installation
-
-```bash
-npm install -g mcp-probe-kit
+### Method 2: Global Installation
+
+```bash
+npm install -g mcp-probe-kit
 ```
 
 Use in config file:
@@ -330,12 +330,44 @@ Use in config file:
       "command": "mcp-probe-kit"
     }
   }
-}
-```
-
-### Restart Client
-
-After configuration, **completely quit and reopen** your MCP client.
+}
+```
+
+### Windows Notes for Graph Tools
+
+Applies to `code_insight`, `start_feature`, `start_bugfix`, and `init_project_context`.
+
+- The GitNexus bridge uses `npx -y gitnexus@latest mcp` by default.
+- On Windows, the first cold start can take 20+ seconds because `npx` may check/download packages.
+- Some GitNexus dependencies use `tree-sitter-*` native modules. If your machine lacks Visual Studio Build Tools, the first install may fail with errors like `gyp ERR! find VS could not find a version of Visual Studio 2017 or newer to use`.
+
+Recommended on Windows:
+
+1. Install Visual Studio Build Tools with the C++ workload if you use graph-aware tools regularly.
+2. Prefer stable local/global CLI usage for GitNexus when your MCP client supports `env`.
+3. Increase GitNexus connect/call timeouts on slower or first-run environments.
+
+Example config using a preinstalled `gitnexus` CLI:
+
+```json
+{
+  "mcpServers": {
+    "mcp-probe-kit": {
+      "command": "mcp-probe-kit",
+      "env": {
+        "MCP_GITNEXUS_COMMAND": "gitnexus",
+        "MCP_GITNEXUS_ARGS": "mcp",
+        "MCP_GITNEXUS_CONNECT_TIMEOUT_MS": "30000",
+        "MCP_GITNEXUS_TIMEOUT_MS": "45000"
+      }
+    }
+  }
+}
+```
+
+### Restart Client
+
+After configuration, **completely quit and reopen** your MCP client.
 
 **👉 [Detailed Installation Guide](https://mcp-probe-kit.bytezonex.com/pages/getting-started.html)**
 
@@ -426,17 +458,41 @@ npx -y mcp-probe-kit@latest 2>&1 | tee ./mcp-probe-kit.log
 3. Confirm JSON format is correct, no syntax errors
 4. Check client developer tools or logs for error messages
 
-### Q3: How to update to latest version?
-
-**npx method (Recommended):**
-Use `@latest` tag in config, automatically uses latest version.
-
-**Global installation method:**
-```bash
-npm update -g mcp-probe-kit
-```
+### Q3: How to update to latest version?
+
+**npx method (Recommended):**
+Use `@latest` tag in config, automatically uses latest version.
 
-**👉 [More FAQ](https://mcp-probe-kit.bytezonex.com/pages/getting-started.html)**
+**Global installation method:**
+```bash
+npm update -g mcp-probe-kit
+```
+
+### Q4: Why are graph-aware tools slow or timing out on Windows the first time?
+
+This usually affects `code_insight`, `start_feature`, `start_bugfix`, and `init_project_context`.
+
+Common causes:
+
+1. `npx -y gitnexus@latest mcp` performs a cold start and may spend 20+ seconds checking/downloading packages.
+2. GitNexus may need native `tree-sitter-*` modules, which can require Visual Studio Build Tools on Windows.
+
+If you see logs like:
+
+```text
+gyp ERR! find VS could not find a version of Visual Studio 2017 or newer to use
+gyp ERR! find VS - missing any VC++ toolset
+```
+
+Try this:
+
+1. Install Visual Studio Build Tools with the C++ workload.
+2. Retry once after dependencies finish installing.
+3. If your client supports `env`, switch the bridge to a preinstalled `gitnexus` CLI and raise:
+   `MCP_GITNEXUS_CONNECT_TIMEOUT_MS`
+   `MCP_GITNEXUS_TIMEOUT_MS`
+
+**👉 [More FAQ](https://mcp-probe-kit.bytezonex.com/pages/getting-started.html)**
 
 ---
 

package/build/lib/__tests__/gitnexus-bridge.unit.test.js

@@ -1,8 +1,9 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import spawn from "cross-spawn";
 import { afterEach, describe, expect, test } from "vitest";
-import { prepareBridgeWorkspace, resolveExecutableCommand, resolveSpawnCommand } from "../gitnexus-bridge.js";
+import { prepareBridgeWorkspace, resolveExecutableCommand, resolveGitNexusBridgeCommand, resolveSpawnCommand, rerankQueryStructuredContent, } from "../gitnexus-bridge.js";
 const tempRoots = [];
 afterEach(() => {
     while (tempRoots.length > 0) {
@@ -17,6 +18,23 @@ function makeTempDir(prefix) {
     tempRoots.push(dir);
     return dir;
 }
+async function runSpawned(command, args) {
+    return await new Promise((resolve, reject) => {
+        const child = spawn(command, args, { windowsHide: true });
+        let stdout = "";
+        let stderr = "";
+        child.stdout?.on("data", (chunk) => {
+            stdout += String(chunk);
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr += String(chunk);
+        });
+        child.on("error", reject);
+        child.on("close", (code) => {
+            resolve({ code, stdout, stderr });
+        });
+    });
+}
 describe("gitnexus-bridge workspace preparation", () => {
     test("Windows 下将 npx/git 解析为 cmd 可执行文件", () => {
         const npxResolved = resolveExecutableCommand("npx", "win32").toLowerCase();
@@ -27,34 +45,75 @@ describe("gitnexus-bridge workspace preparation", () => {
         expect(resolveExecutableCommand("git", "win32").toLowerCase()).toContain("git");
         expect(resolveExecutableCommand("npx", "linux").toLowerCase()).toContain("npx");
     });
-    test("Windows 下将 cmd 工具包装为 cmd.exe /c 启动", () => {
+    test("Windows 下 npx 命令直接交给底层 spawn 处理", () => {
         const wrapped = resolveSpawnCommand("npx", ["-y", "gitnexus@latest", "mcp"], "win32");
-        expect(wrapped.command.toLowerCase()).toContain("cmd");
-        expect(wrapped.args.slice(0, 3)).toEqual(["/d", "/s", "/c"]);
-        expect(String(wrapped.args[3]).toLowerCase()).toContain("npx");
+        expect(wrapped.command.toLowerCase()).not.toContain("cmd.exe");
+        expect(wrapped.command.toLowerCase()).toContain("npx");
+        expect(wrapped.args).toEqual(["-y", "gitnexus@latest", "mcp"]);
+    });
+    test("优先使用本地 gitnexus CLI 启动 bridge", () => {
+        const root = makeTempDir("gitnexus-cli-");
+        const executable = path.join(root, "gitnexus.cmd");
+        fs.writeFileSync(executable, "@echo off\r\necho gitnexus %*\r\n", "utf-8");
+        const resolved = resolveGitNexusBridgeCommand({
+            PATH: root,
+            PATHEXT: ".CMD;.EXE;.BAT",
+        }, "win32");
+        expect(resolved.strategy).toBe("local");
+        expect(resolved.command).toBe(executable);
+        expect(resolved.args).toEqual(["mcp"]);
+    });
+    test("显式 MCP_GITNEXUS_COMMAND 配置优先于本地 CLI 自动发现", () => {
+        const resolved = resolveGitNexusBridgeCommand({
+            MCP_GITNEXUS_COMMAND: "npx",
+            MCP_GITNEXUS_ARGS: "-y gitnexus@1.4.1 mcp",
+            PATH: "",
+        }, "win32");
+        expect(resolved.strategy).toBe("env");
+        expect(resolved.command.toLowerCase()).toContain("npx");
+        expect(resolved.args).toEqual(["-y", "gitnexus@1.4.1", "mcp"]);
     });
-    test("Windows 下带空格路径的 cmd 可执行文件会被正确加引号", () => {
+    test("query 结果会按关键词对流程做轻量重排", () => {
+        const reranked = rerankQueryStructuredContent({
+            processes: [
+                { heuristicLabel: "Main -> Sleep", priority: 0.12, summary: "background idle loop" },
+                { heuristicLabel: "Login -> GenerateToken", priority: 0.08, filePath: "src/auth/login.ts" },
+            ],
+        }, {
+            query: "login authentication user signin auth",
+            goal: "理解登录流程",
+        });
+        expect(reranked.changed).toBe(true);
+        expect(reranked.structuredContent.processes[0].heuristicLabel).toBe("Login -> GenerateToken");
+        expect(reranked.note).toMatch(/Top matches/i);
+    });
+    test.runIf(process.platform === "win32")("Windows 下带空格路径的 cmd 可执行文件可以真实启动", async () => {
         const root = makeTempDir("gitnexus-space-");
-        const executable = path.join(root, "Program Files", "nodejs", "npx.cmd");
+        const executable = path.join(root, "Program Files", "tool.cmd");
         fs.mkdirSync(path.dirname(executable), { recursive: true });
-        fs.writeFileSync(executable, "@echo off\r\n", "utf-8");
+        fs.writeFileSync(executable, "@echo off\r\necho ok %*\r\n", "utf-8");
         const wrapped = resolveSpawnCommand(executable, ["-y", "gitnexus@latest", "mcp"], "win32");
-        expect(wrapped.command.toLowerCase()).toContain("cmd");
-        expect(wrapped.args.slice(0, 3)).toEqual(["/d", "/s", "/c"]);
-        expect(wrapped.args[3]).toBe(`"${executable}"`);
+        const result = await runSpawned(wrapped.command, wrapped.args);
+        expect(wrapped.command).toBe(executable);
+        expect(wrapped.args).toEqual(["-y", "gitnexus@latest", "mcp"]);
+        expect(result.code).toBe(0);
+        expect(result.stdout).toContain("ok");
+        expect(result.stdout).toContain("-y");
+        expect(result.stdout).toContain("gitnexus@latest");
+        expect(result.stdout).toContain("mcp");
+    });
+    test.runIf(process.platform === "win32")("Windows 下 resolveSpawnCommand 生成的 npx 命令可真实执行", async () => {
+        const spawned = resolveSpawnCommand("npx", ["--version"], "win32");
+        const result = await runSpawned(spawned.command, spawned.args);
+        expect(result.code).toBe(0);
+        expect(result.stdout.trim().length).toBeGreaterThan(0);
     });
     test("Windows 下 git.exe 直接启动，不走 git.cmd 壳层", () => {
         const resolved = resolveExecutableCommand("git", "win32").toLowerCase();
         const spawned = resolveSpawnCommand("git", ["init", "-q"], "win32");
         expect(resolved).toContain("git");
-        expect(resolved.endsWith(".exe") || resolved === "git").toBe(true);
-        expect(spawned.command.toLowerCase()).not.toContain("cmd.exe /d /s /c git.cmd");
-        if (spawned.command.toLowerCase().includes("cmd")) {
-            expect(String(spawned.args[3]).toLowerCase()).not.toContain("git.cmd");
-        }
-        else {
-            expect(spawned.command.toLowerCase()).toContain("git");
-        }
+        expect(resolved.endsWith(".exe") || resolved === "git" || resolved === "git.cmd").toBe(true);
+        expect(spawned.command.toLowerCase()).toContain("git");
     });
     test("git 目录直接使用源仓库", async () => {
         const repoRoot = makeTempDir("gitnexus-direct-");

package/build/lib/gitnexus-bridge.d.ts

@@ -1,9 +1,24 @@
 export type CodeInsightMode = "auto" | "query" | "context" | "impact";
 export type CodeInsightDirection = "upstream" | "downstream";
+export type GitNexusLaunchStrategy = "local" | "npx" | "env";
+export interface CodeInsightCandidate {
+    uid?: string;
+    name?: string;
+    file_path?: string;
+    kind?: string;
+    [key: string]: unknown;
+}
+export interface CodeInsightAmbiguity {
+    tool: string;
+    message?: string;
+    candidates: CodeInsightCandidate[];
+}
 export interface CodeInsightRequest {
     mode?: CodeInsightMode;
     query?: string;
     target?: string;
+    uid?: string;
+    filePath?: string;
     repo?: string;
     projectRoot?: string;
     goal?: string;
@@ -11,6 +26,7 @@ export interface CodeInsightRequest {
     direction?: CodeInsightDirection;
     maxDepth?: number;
     includeTests?: boolean;
+    includeContent?: boolean;
     signal?: AbortSignal;
 }
 export interface CodeInsightExecution {
@@ -20,6 +36,7 @@ export interface CodeInsightExecution {
     args: Record<string, unknown>;
     text?: string;
     structuredContent?: unknown;
+    status?: string;
     error?: string;
 }
 export interface CodeInsightBridgeResult {
@@ -33,6 +50,8 @@ export interface CodeInsightBridgeResult {
     executions: CodeInsightExecution[];
     warnings: string[];
     repo?: string;
+    launcherStrategy: GitNexusLaunchStrategy;
+    ambiguities: CodeInsightAmbiguity[];
     workspaceMode: "direct" | "temp-repo";
     sourceRoot: string;
     analysisRoot: string;
@@ -48,11 +67,25 @@ export interface EmbeddedGraphContext {
     mode: "query" | "context" | "impact";
     highlights: string[];
 }
-export declare function resolveExecutableCommand(command: string, platform?: NodeJS.Platform): string;
-export declare function resolveSpawnCommand(command: string, args: string[], platform?: NodeJS.Platform): {
+export declare function resolveGitNexusBridgeCommand(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): {
+    command: string;
+    args: string[];
+    strategy: GitNexusLaunchStrategy;
+};
+export declare function resolveExecutableCommand(command: string, platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): string;
+export declare function resolveSpawnCommand(command: string, args: string[], platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): {
     command: string;
     args: string[];
 };
+export declare function rerankQueryStructuredContent(structuredContent: unknown, hints: {
+    query?: string;
+    goal?: string;
+    taskContext?: string;
+}): {
+    structuredContent: unknown;
+    changed: boolean;
+    note?: string;
+};
 export interface BridgeWorkspace {
     workspaceMode: "direct" | "temp-repo";
     sourceRoot: string;