mcp-probe-kit 3.0.13 → 3.0.14

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/gitnexus-bridge.js

@@ -333,6 +333,60 @@ 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");
+}
+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 +437,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 (field.key.includes("path") || field.key.includes("file") || field.key.includes("module")) {
-                score += 10;
+            else if (inDocs) {
+                score += wholeWord ? 26 : 16;
+            }
+            else if (inCode) {
+                score += wholeWord ? 18 : 10;
             }
             else {
-                score += 4;
+                score += wholeWord ? 24 : 12;
             }
         }
         if (matched) {
@@ -407,15 +476,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,6 +1029,28 @@ export async function runCodeInsightBridge(request) {
                 warnings.push("缺少 target/uid 参数，已跳过 impact");
                 return;
             }
+            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;
+                    }
+                }
+            }
             executions.push(await callBridgeTool(client, "impact", {
                 target: request.uid || request.target,
                 direction: request.direction || "upstream",

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-probe-kit",
-  "version": "3.0.13",
+  "version": "3.0.14",
   "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",