mcp-probe-kit 3.0.13 → 3.0.15

package/README.md

@@ -347,6 +347,12 @@ Recommended on Windows:
 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.
 
+Quick install command (Windows):
+
+```powershell
+winget install Microsoft.VisualStudio.2022.BuildTools
+```
+
 Example config using a preinstalled `gitnexus` CLI:
 
 ```json

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, resolveGitNexusBridgeCommand, resolveSpawnCommand, rerankQueryStructuredContent, } from "../gitnexus-bridge.js";
+import { extractResolvedSymbolIdFromContext, prepareBridgeWorkspace, resolveExecutableCommand, resolveGitNexusBridgeCommand, resolveSpawnCommand, rerankQueryStructuredContent, } from "../gitnexus-bridge.js";
 const tempRoots = [];
 afterEach(() => {
     while (tempRoots.length > 0) {
@@ -87,6 +87,14 @@ describe("gitnexus-bridge workspace preparation", () => {
         expect(reranked.structuredContent.processes[0].heuristicLabel).toBe("Login -> GenerateToken");
         expect(reranked.note).toMatch(/Top matches/i);
     });
+    test("impact 可复用 context 解析出的 symbol id", () => {
+        expect(extractResolvedSymbolIdFromContext({
+            target: { id: "Method:sysAuthController.js:login:18", name: "login" },
+        })).toBe("Method:sysAuthController.js:login:18");
+        expect(extractResolvedSymbolIdFromContext({
+            symbol: { uid: "Function:src/auth.ts:login" },
+        })).toBe("Function:src/auth.ts:login");
+    });
     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

@@ -77,6 +77,7 @@ export declare function resolveSpawnCommand(command: string, args: string[], pla
     command: string;
     args: string[];
 };
+export declare function extractResolvedSymbolIdFromContext(value: unknown): string | undefined;
 export declare function rerankQueryStructuredContent(structuredContent: unknown, hints: {
     query?: string;
     goal?: string;

package/build/lib/gitnexus-bridge.js

@@ -333,6 +333,83 @@ function buildAmbiguities(executions) {
         };
     });
 }
+function getLastExecutionByTool(executions, tool) {
+    for (let index = executions.length - 1; index >= 0; index -= 1) {
+        if (executions[index]?.tool === tool) {
+            return executions[index];
+        }
+    }
+    return undefined;
+}
+function inferSymbolKind(value) {
+    const record = toRecord(value);
+    if (!record) {
+        return undefined;
+    }
+    for (const key of ["kind", "type", "symbolType"]) {
+        const candidate = record[key];
+        if (typeof candidate === "string" && candidate.trim()) {
+            return candidate.trim();
+        }
+    }
+    const id = record.id;
+    if (typeof id === "string" && id.includes(":")) {
+        return id.split(":")[0];
+    }
+    return undefined;
+}
+function isNonCallableSymbolKind(kind) {
+    if (!kind) {
+        return false;
+    }
+    const normalized = kind.toLowerCase();
+    return normalized.includes("folder")
+        || normalized.includes("file")
+        || normalized.includes("module")
+        || normalized.includes("community")
+        || normalized.includes("process")
+        || normalized.includes("package");
+}
+export function extractResolvedSymbolIdFromContext(value) {
+    const record = toRecord(value);
+    if (!record) {
+        return undefined;
+    }
+    const direct = [record.uid, record.id, record.targetUid, record.targetId]
+        .find((item) => typeof item === "string" && item.trim());
+    if (typeof direct === "string") {
+        return direct.trim();
+    }
+    for (const key of ["target", "symbol", "node", "element"]) {
+        const nested = toRecord(record[key]);
+        if (!nested) {
+            continue;
+        }
+        const candidate = [nested.uid, nested.id]
+            .find((item) => typeof item === "string" && item.trim());
+        if (typeof candidate === "string") {
+            return candidate.trim();
+        }
+    }
+    return undefined;
+}
+function normalizeImpactTargetByContext(contextExecution, originalTarget) {
+    const target = toRecord(contextExecution.structuredContent)?.target;
+    const kind = inferSymbolKind(target);
+    if (!isNonCallableSymbolKind(kind)) {
+        return contextExecution;
+    }
+    const message = `impact 目标 "${originalTarget}" 被解析为 ${kind}，请改用函数/方法 uid 或补充 file_path 再重试。`;
+    contextExecution.status = "ambiguous";
+    contextExecution.text = message;
+    contextExecution.structuredContent = {
+        status: "ambiguous",
+        message,
+        suggestion: "For impact analysis, prefer Method/Function over Folder/File.",
+        candidates: target ? [target] : [],
+    };
+    return contextExecution;
+}
 const QUERY_STOP_WORDS = new Set([
     "the", "and", "for", "with", "from", "into", "that", "this", "user", "flow",
     "sign", "code", "project", "module",
@@ -383,23 +460,38 @@ function scoreQueryCandidate(candidate, terms) {
     if (fields.length === 0 || terms.length === 0) {
         return 0;
     }
-    let score = 0;
+    let score = -30;
     let matchedTerms = 0;
     for (const term of terms) {
         let matched = false;
         for (const field of fields) {
-            if (!field.value.includes(term)) {
+            const value = field.value;
+            const key = field.key;
+            const exact = value === term;
+            const wholeWord = new RegExp(`\\b${term.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "i").test(value);
+            const partial = value.includes(term);
+            if (!partial) {
                 continue;
             }
             matched = true;
-            if (field.key.includes("name") || field.key.includes("title") || field.key.includes("label")) {
-                score += field.value === term ? 24 : 16;
+            const inName = key.includes("name") || key.includes("title") || key.includes("label") || key.includes("symbol");
+            const inPath = key.includes("path") || key.includes("file") || key.includes("module");
+            const inDocs = key.includes("comment") || key.includes("doc") || key.includes("description") || key.includes("summary");
+            const inCode = key.includes("content") || key.includes("source") || key.includes("body") || key.includes("code");
+            if (inName) {
+                score += exact ? 120 : wholeWord ? 90 : 55;
+            }
+            else if (inPath) {
+                score += wholeWord ? 70 : 45;
+            }
+            else if (inDocs) {
+                score += wholeWord ? 26 : 16;
             }
-            else if (field.key.includes("path") || field.key.includes("file") || field.key.includes("module")) {
-                score += 10;
+            else if (inCode) {
+                score += wholeWord ? 18 : 10;
             }
             else {
-                score += 4;
+                score += wholeWord ? 24 : 12;
             }
         }
         if (matched) {
@@ -407,15 +499,18 @@ function scoreQueryCandidate(candidate, terms) {
         }
     }
     if (matchedTerms > 0) {
-        score += matchedTerms * 5;
+        score += matchedTerms * 14;
+    }
+    else {
+        score -= 60;
     }
     if (matchedTerms === terms.length) {
-        score += 12;
+        score += 35;
     }
     const candidateRecord = toRecord(candidate);
     const priority = candidateRecord?.priority;
     if (typeof priority === "number" && Number.isFinite(priority)) {
-        score += priority;
+        score += matchedTerms > 0 ? (priority * 5) : (priority * 0.5);
     }
     return score;
 }
@@ -957,8 +1052,35 @@ export async function runCodeInsightBridge(request) {
                 warnings.push("缺少 target/uid 参数，已跳过 impact");
                 return;
             }
+            let impactTarget = request.uid || request.target;
+            if (!request.uid && request.target) {
+                let contextExecution = getLastExecutionByTool(executions, "context");
+                if (!contextExecution) {
+                    contextExecution = await callBridgeTool(client, "context", {
+                        name: request.target,
+                        ...(request.filePath ? { file_path: request.filePath } : {}),
+                        ...(effectiveRepo ? { repo: effectiveRepo } : {}),
+                    }, request.signal, workspace);
+                    executions.push(contextExecution);
+                }
+                if (contextExecution.ok && contextExecution.status === "ambiguous") {
+                    warnings.push("impact_target_ambiguous");
+                    return;
+                }
+                if (contextExecution.ok) {
+                    normalizeImpactTargetByContext(contextExecution, request.target);
+                    if (contextExecution.status === "ambiguous") {
+                        warnings.push("impact_target_non_callable");
+                        return;
+                    }
+                    const resolvedTargetId = extractResolvedSymbolIdFromContext(contextExecution.structuredContent);
+                    if (resolvedTargetId) {
+                        impactTarget = resolvedTargetId;
+                    }
+                }
+            }
             executions.push(await callBridgeTool(client, "impact", {
-                target: request.uid || request.target,
+                target: impactTarget,
                 direction: request.direction || "upstream",
                 ...(request.maxDepth ? { maxDepth: request.maxDepth } : {}),
                 ...(typeof request.includeTests === "boolean"

package/build/tools/__tests__/code_insight.unit.test.js

@@ -101,6 +101,7 @@ describe("code_insight 单元测试", () => {
         });
         expect(status).toBe("ambiguous");
         expect(plan?.kind).toBe("ambiguity");
+        expect(plan?.steps).toHaveLength(2);
         expect(plan?.steps[1].action).toMatch(/uid 或 file_path/);
     });
     test("未显式要求保存时不生成 docs delegated plan", async () => {
@@ -113,7 +114,8 @@ describe("code_insight 单元测试", () => {
             expect(result.isError).toBe(false);
             const text = String(result.content?.[0]?.text || "");
             const structured = result.structuredContent;
-            expect(text).not.toMatch(/delegated plan/);
+            expect(text).not.toMatch(/## delegated plan/);
+            expect(text).toMatch(/使用场景指南/);
             expect(structured.plan).toBeUndefined();
             expect(structured.projectDocs).toBeUndefined();
         }
@@ -141,15 +143,16 @@ describe("code_insight 单元测试", () => {
             expect(text).toMatch(/delegated plan/);
             expect(text).toMatch(/不要只口头总结而不写文件/);
             expect(text).toMatch(/docs\/graph-insights\/latest\.md/);
-            expect(text).toMatch(/docs\/project-context\.md/);
+            expect(text).toMatch(/使用场景指南/);
             expect(structured.projectDocs.latestMarkdownFilePath).toContain("/docs/graph-insights/latest.md");
             expect(structured.projectDocs.archiveMarkdownFilePath).toContain("/docs/graph-insights/");
             expect(structured.projectDocs.projectContextFilePath).toContain("/docs/project-context.md");
             expect(structured.projectDocs.navigationSnippet).toMatch(/代码图谱洞察/);
             expect(structured.plan.mode).toBe("delegated");
-            expect(structured.plan.steps[0].outputs[0]).toContain("/docs/project-context.md");
-            const updateIndexStep = structured.plan.steps.find((step) => step.id === "update-project-context-index");
-            expect(updateIndexStep.note).toMatch(/代码图谱洞察/);
+            expect(structured.plan.steps).toHaveLength(2);
+            expect(structured.plan.steps[0].id).toBe("consume-result");
+            expect(structured.plan.steps[1].id).toBe("optional-save");
+            expect(structured.plan.steps[1].outputs[0]).toContain("/docs/graph-insights/latest.md");
             expect(fs.existsSync(path.join(projectRoot, "docs", "graph-insights", "latest.md"))).toBe(false);
         }
         finally {

package/build/tools/code_insight.js

@@ -151,17 +151,12 @@ export function buildCodeInsightDelegatedPlan(input) {
             kind: "ambiguity",
             steps: [
                 {
-                    id: "inspect-candidates",
-                    action: "阅读本次返回的 candidates，确认目标符号对应的 uid 或 file_path",
-                    note: "若存在同名符号，优先使用 uid；需要限定文件时使用 file_path",
+                    id: "consume-candidates",
+                    action: "消费本次 candidates 列表，确认唯一目标符号（优先 uid，其次 file_path）",
                 },
                 {
                     id: "rerun-with-disambiguate",
-                    action: "重新调用 code_insight，并显式传入 uid 或 file_path 完成消歧",
-                },
-                {
-                    id: "resume-analysis",
-                    action: "消歧后再继续 context/impact 分析，必要时再决定是否保存到 docs/graph-insights",
+                    action: "重新调用 code_insight，并传入 uid 或 file_path 后继续 context/impact 分析",
                 },
             ],
         };
@@ -175,45 +170,32 @@ export function buildCodeInsightDelegatedPlan(input) {
         kind: "docs",
         steps: [
             {
-                id: "ensure-project-context",
-                action: projectContextExists
-                    ? `确认 ${input.projectDocs.projectContextFilePath} 已存在并可更新`
-                    : `检查 ${input.projectDocs.projectContextFilePath} 是否存在；若不存在，先调用 init_project_context 生成项目上下文索引`,
-                outputs: [input.projectDocs.projectContextFilePath],
-                note: projectContextExists
-                    ? "已有项目上下文，可直接补充图谱入口"
-                    : "只有 project-context.md 存在，后续图谱文档入口才可持续复用",
-            },
-            {
-                id: "save-latest-md",
-                action: `将本次 code_insight 的文本分析结果写入 ${input.projectDocs.latestMarkdownFilePath}`,
-                outputs: [input.projectDocs.latestMarkdownFilePath],
-            },
-            {
-                id: "save-archive-md",
-                action: `将本次 code_insight 的文本分析结果归档到 ${input.projectDocs.archiveMarkdownFilePath}`,
-                outputs: [input.projectDocs.archiveMarkdownFilePath],
-            },
-            {
-                id: "save-latest-json",
-                action: `将本次 code_insight 的 structuredContent 写入 ${input.projectDocs.latestJsonFilePath}`,
-                outputs: [input.projectDocs.latestJsonFilePath],
-                note: "建议保留完整结构化结果，便于后续 AI 继续读取",
-            },
-            {
-                id: "save-archive-json",
-                action: `将本次 code_insight 的 structuredContent 归档到 ${input.projectDocs.archiveJsonFilePath}`,
-                outputs: [input.projectDocs.archiveJsonFilePath],
+                id: "consume-result",
+                action: "先消费本次分析结果（processes/symbols/impact），确认是否满足当前问题",
             },
             {
-                id: "update-project-context-index",
-                action: `更新 ${input.projectDocs.projectContextFilePath}，在“## 📚 文档导航”加入图谱文档入口，并在“## 💡 开发时查看对应文档”加入代码图谱洞察链接`,
-                outputs: [input.projectDocs.projectContextFilePath],
-                note: `建议插入内容:\n${input.projectDocs.navigationSnippet}\n${input.projectDocs.devGuideSnippet}`,
+                id: "optional-save",
+                action: `如需保存，再写入 ${input.projectDocs.latestMarkdownFilePath}（文本）和 ${input.projectDocs.latestJsonFilePath}（结构化）`,
+                outputs: [input.projectDocs.latestMarkdownFilePath, input.projectDocs.latestJsonFilePath],
+                note: projectContextExists
+                    ? `可选同步更新 ${input.projectDocs.projectContextFilePath} 的图谱入口`
+                    : "若后续要持续沉淀，建议先补 init_project_context",
             },
         ],
     };
 }
+function renderUsageGuide() {
+    return `## 使用场景指南
+- 探索调用链: \`{ mode: "query", query: "login", goal: "理解登录认证流程" }\`
+- 深入函数上下文: \`{ mode: "context", target: "login", file_path: "src/auth/login.ts" }\`
+- 评估影响范围: \`{ mode: "impact", target: "login", direction: "upstream", file_path: "..." }\`
+- 查看代码内容: \`{ mode: "context", target: "login", include_content: true }\`
+
+## 下一步建议
+- 查询不精确: 增加 \`goal\`（例如“理解登录认证流程”）
+- 出现歧义: 传入 \`uid\` 或 \`file_path\` 重新执行
+- 需要落盘: 传 \`save_to_docs: true\`，再按 delegated plan 写入 docs/graph-insights`;
+}
 export function resolveCodeInsightQuery(input) {
     const finalTarget = input.target || ((input.mode === "context" || input.mode === "impact") ? input.input : "");
     const finalQuery = input.query
@@ -325,6 +307,7 @@ ${executionSummary}
 
 ${ambiguityText ? `歧义候选:\n${ambiguityText}\n\n` : ""}\
 ${result.warnings.length > 0 ? `警告: ${result.warnings.join(", ")}` : ""}`.trim();
+        const usageGuide = renderUsageGuide();
         const structured = {
             status,
             provider: result.provider,
@@ -397,13 +380,15 @@ ${result.warnings.length > 0 ? `警告: ${result.warnings.join(", ")}` : ""}`.tr
 ${renderPlanSteps(delegatedPlan.steps)}
 
 ${delegatedPlan.kind === "docs" && projectDocs ? `后续操作:
-- 请先确保 ${projectDocs.projectContextFilePath} 可用，并把图谱入口挂到该索引中
-- 请将本次分析保存到 ${projectDocs.latestMarkdownFilePath}
-- 如需归档，请额外保存到 ${projectDocs.archiveMarkdownFilePath}
-- 如需结构化副本，请保存 JSON 到 ${projectDocs.latestJsonFilePath} 或 ${projectDocs.archiveJsonFilePath}` : `后续操作:
+- 如需落盘，写入 ${projectDocs.latestMarkdownFilePath} 与 ${projectDocs.latestJsonFilePath}
+- 如需长期沉淀，可再补充 ${projectDocs.projectContextFilePath} 的图谱入口` : `后续操作:
 - 请先从 candidates 中选定唯一符号
-- 重新传入 uid 或 file_path 后再继续 context / impact 分析`}`
-            : message, structured);
+- 重新传入 uid 或 file_path 后再继续 context / impact 分析`}
+
+${usageGuide}`
+            : `${message}
+
+${usageGuide}`, structured);
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);

package/docs/i18n/en.json

@@ -93,6 +93,8 @@
         "item1": "The first cold start may take 20+ seconds while npx checks or downloads dependencies.",
         "item2": "Some GitNexus dependencies use tree-sitter native modules and may require Visual Studio Build Tools.",
         "item3": "If your MCP client supports env, prefer a preinstalled gitnexus CLI and raise GitNexus timeouts.",
+        "item4": "Quick install Build Tools on Windows: winget install Microsoft.VisualStudio.2022.BuildTools",
+        "quickInstallTitle": "Quick install command:",
         "exampleTitle": "Example using a preinstalled gitnexus CLI:"
       },
       "source": {

package/docs/i18n/ja.json

@@ -93,6 +93,8 @@
         "item1": "初回のコールドスタートでは、npx が依存関係を確認またはダウンロードするため 20 秒以上かかることがあります。",
         "item2": "GitNexus の一部依存関係は tree-sitter ネイティブモジュールを使用しており、Windows では Visual Studio Build Tools が必要になる場合があります。",
         "item3": "MCP クライアントが env をサポートしている場合は、プリインストール済みの gitnexus CLI を優先し、GitNexus のタイムアウトを引き上げてください。",
+        "item4": "Windows では winget で Build Tools をすばやくインストールできます：winget install Microsoft.VisualStudio.2022.BuildTools",
+        "quickInstallTitle": "クイックインストールコマンド：",
         "exampleTitle": "プリインストール済み gitnexus CLI を使う設定例："
       },
       "source": {

package/docs/i18n/ko.json

@@ -93,6 +93,8 @@
         "item1": "첫 콜드 스타트에서는 npx 가 의존성을 확인하거나 다운로드하므로 20초 이상 걸릴 수 있습니다.",
         "item2": "GitNexus 의 일부 의존성은 tree-sitter 네이티브 모듈을 사용하며 Windows 에서는 Visual Studio Build Tools 가 필요할 수 있습니다.",
         "item3": "MCP 클라이언트가 env 를 지원하면, 미리 설치한 gitnexus CLI 를 우선 사용하고 GitNexus 타임아웃을 늘리세요.",
+        "item4": "Windows 에서 Build Tools 빠른 설치: winget install Microsoft.VisualStudio.2022.BuildTools",
+        "quickInstallTitle": "빠른 설치 명령:",
         "exampleTitle": "미리 설치한 gitnexus CLI 를 사용하는 구성 예시:"
       },
       "source": {

package/docs/i18n/zh-CN.json

@@ -93,6 +93,8 @@
         "item1": "首次冷启动时，npx 可能检查或下载依赖，耗时可能超过 20 秒。",
         "item2": "GitNexus 的部分依赖使用 tree-sitter 原生模块，在 Windows 上可能需要 Visual Studio Build Tools。",
         "item3": "如果 MCP 客户端支持 env，优先使用预装的 gitnexus CLI，并适当增大 GitNexus 超时。",
+        "item4": "Windows 下可用 winget 快速安装 Build Tools：winget install Microsoft.VisualStudio.2022.BuildTools",
+        "quickInstallTitle": "快速安装命令：",
         "exampleTitle": "使用预装 gitnexus CLI 的配置示例："
       },
       "source": {

package/docs/pages/getting-started.html

@@ -317,7 +317,10 @@ npm run build</code></pre>
                             <li data-i18n="gettingStarted.step1.windowsGraph.item1">The first cold start may take 20+ seconds while npx checks or downloads dependencies.</li>
                             <li data-i18n="gettingStarted.step1.windowsGraph.item2">Some GitNexus dependencies use tree-sitter native modules and may require Visual Studio Build Tools.</li>
                             <li data-i18n="gettingStarted.step1.windowsGraph.item3">If your MCP client supports env, prefer a preinstalled gitnexus CLI and raise GitNexus timeouts.</li>
+                            <li data-i18n="gettingStarted.step1.windowsGraph.item4">Quick install Build Tools on Windows: winget install Microsoft.VisualStudio.2022.BuildTools</li>
                         </ul>
+                        <p class="mb-2" data-i18n="gettingStarted.step1.windowsGraph.quickInstallTitle">Quick install command:</p>
+                        <pre class="code-block mb-3 p-3 text-sm text-slate-200 bg-slate-900 rounded overflow-x-auto"><code>winget install Microsoft.VisualStudio.2022.BuildTools</code></pre>
                         <p class="mb-2" data-i18n="gettingStarted.step1.windowsGraph.exampleTitle">Example using a preinstalled gitnexus CLI:</p>
                         <div class="bg-slate-900 rounded-lg overflow-hidden">
                             <div class="flex items-center justify-between px-3 py-2 bg-slate-800">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-probe-kit",
-  "version": "3.0.13",
+  "version": "3.0.15",
   "description": "AI-Powered Development Toolkit - MCP Server with 22 tools covering code quality, development efficiency, project management, and UI/UX design. Features: Structured Output, Workflow Orchestration, UI/UX Pro Max, and Requirements Interview.",
   "mcpName": "io.github.mybolide/mcp-probe-kit",
   "type": "module",