mcp-probe-kit 3.0.12 → 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

@@ -3,7 +3,7 @@ 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) {
@@ -51,6 +51,42 @@ describe("gitnexus-bridge workspace preparation", () => {
         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("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", "tool.cmd");

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;