mcp-probe-kit 3.6.0 → 3.6.1

package/build/index.js

@@ -14,7 +14,8 @@ import { withOutputSchema } from "./lib/output-schema-registry.js";
 import { shouldAutoEscalateToTask } from "./lib/task-defaults.js";
 import { attachHandles } from "./lib/handles.js";
 import { buildMcpAppHtml, isMcpUiAppTool } from "./lib/mcp-apps.js";
-import { ensureMcpProbeKitBootstrapForToolCall } from "./lib/workflow-skill-installer.js";
+import { ensureMcpProbeKitBootstrapForToolCall, } from "./lib/workflow-skill-installer.js";
+import { resolveWorkspaceRoot } from "./lib/workspace-root.js";
 import { isAbortError, } from "./lib/tool-execution-context.js";
 const EXTENSIONS_CAPABILITY_KEY = "io.github.mybolide/extensions";
 const MAX_UI_APP_RESOURCES = 30;
@@ -184,6 +185,53 @@ function renderGraphSnapshotMarkdown(snapshot) {
         "",
     ].join("\n");
 }
+function buildGraphHistorySummary(summaryLimit = 200) {
+    const items = graphSnapshotOrder
+        .slice()
+        .reverse()
+        .map((id) => graphSnapshots.get(id))
+        .filter((item) => Boolean(item))
+        .map((item) => ({
+        id: item.id,
+        uri: item.uri,
+        toolName: item.toolName,
+        createdAt: item.createdAt,
+        status: item.status,
+        summary: trimText(item.summary, summaryLimit),
+        files: {
+            json: item.jsonFilePath ?? null,
+            markdown: item.markdownFilePath ?? null,
+        },
+    }));
+    return { count: items.length, items };
+}
+function buildGraphFilesIndex(fileLimit = 40) {
+    const latestId = graphSnapshotOrder[graphSnapshotOrder.length - 1];
+    const latest = latestId ? (graphSnapshots.get(latestId) ?? null) : null;
+    const hasDir = fs.existsSync(graphSnapshotDir);
+    const files = hasDir
+        ? fs
+            .readdirSync(graphSnapshotDir, { withFileTypes: true })
+            .filter((entry) => entry.isFile() && /\.(json|md)$/i.test(entry.name))
+            .map((entry) => toPosixPath(path.join(graphSnapshotDir, entry.name)))
+            .sort((a, b) => b.localeCompare(a))
+            .slice(0, fileLimit)
+        : [];
+    return {
+        snapshotDir: toPosixPath(graphSnapshotDir),
+        exists: hasDir,
+        latest: latest
+            ? {
+                id: latest.id,
+                uri: latest.uri,
+                toolName: latest.toolName,
+                jsonFilePath: latest.jsonFilePath ?? null,
+                markdownFilePath: latest.markdownFilePath ?? null,
+            }
+            : null,
+        files,
+    };
+}
 function persistGraphSnapshot(snapshot) {
     try {
         ensureGraphSnapshotDir();
@@ -324,8 +372,31 @@ function withStructuredHandles(result, handles) {
         structuredContent: attachHandles(result.structuredContent, handles),
     };
 }
-function decorateResult(toolName, args, raw, traceMeta) {
+function withBootstrapMeta(result, bootstrap) {
+    if (!bootstrap) {
+        return result;
+    }
+    const base = result.structuredContent &&
+        typeof result.structuredContent === "object" &&
+        !Array.isArray(result.structuredContent)
+        ? result.structuredContent
+        : {};
+    return {
+        ...result,
+        structuredContent: {
+            ...base,
+            mcp_probe_bootstrap: {
+                projectRoot: bootstrap.projectRoot,
+                skill: bootstrap.skill,
+                agentsMd: bootstrap.agentsMd,
+                workspaceWarning: bootstrap.workspaceWarning ?? null,
+            },
+        },
+    };
+}
+function decorateResult(toolName, args, raw, traceMeta, bootstrap = null) {
     let result = withTraceMeta(raw, traceMeta);
+    result = withBootstrapMeta(result, bootstrap);
     const snapshot = rememberGraphSnapshot(toolName, result);
     if (snapshot) {
         result = withGraphSnapshotMeta(result, snapshot);
@@ -360,6 +431,9 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
 });
 async function executeTool(name, args, context) {
     const bootstrap = ensureMcpProbeKitBootstrapForToolCall(name, args);
+    if (bootstrap?.workspaceWarning) {
+        console.error(`[MCP Probe Kit] ${bootstrap.workspaceWarning}`);
+    }
     if (bootstrap?.skill.created) {
         console.error(`[MCP Probe Kit] 已创建 MCP Skill: ${bootstrap.skill.skillRelPath} (v${bootstrap.skill.version})`);
     }
@@ -372,70 +446,102 @@ async function executeTool(name, args, context) {
     else if (bootstrap?.agentsMd.updated) {
         console.error(`[MCP Probe Kit] 已更新 AGENTS.md（添加 Skill 引用）: ${bootstrap.agentsMd.path}`);
     }
+    let result;
     switch (name) {
         case "init_project":
-            return await initProject(args);
+            result = (await initProject(args));
+            break;
         case "gencommit":
-            return await gencommit(args);
+            result = (await gencommit(args));
+            break;
         case "code_review":
-            return await codeReview(args);
+            result = (await codeReview(args));
+            break;
         case "code_insight":
-            return await codeInsight(args, context);
+            result = (await codeInsight(args, context));
+            break;
         case "gentest":
-            return await gentest(args);
+            result = (await gentest(args));
+            break;
         case "refactor":
-            return await refactor(args);
+            result = (await refactor(args));
+            break;
         case "init_project_context":
-            return await initProjectContext(args);
+            result = (await initProjectContext(args));
+            break;
         case "workflow":
-            return await workflow(args);
+            result = (await workflow(args));
+            break;
         case "add_feature":
-            return await addFeature(args);
+            result = (await addFeature(args));
+            break;
         case "check_spec":
-            return await checkSpec(args);
+            result = (await checkSpec(args));
+            break;
         case "fix_bug":
-            return await fixBug(args);
+            result = (await fixBug(args));
+            break;
         case "estimate":
-            return await estimate(args);
+            result = (await estimate(args));
+            break;
         case "start_feature":
-            return await startFeature(args, context);
+            result = (await startFeature(args, context));
+            break;
         case "start_bugfix":
-            return await startBugfix(args, context);
+            result = (await startBugfix(args, context));
+            break;
         case "start_onboard":
-            return await startOnboard(args, context);
+            result = (await startOnboard(args, context));
+            break;
         case "start_ralph":
-            return await startRalph(args, context);
+            result = (await startRalph(args, context));
+            break;
         case "interview":
-            return await interview(args);
+            result = (await interview(args));
+            break;
         case "ask_user":
-            return await askUser(args);
+            result = (await askUser(args));
+            break;
         case "ui_design_system":
-            return await uiDesignSystem(args);
+            result = (await uiDesignSystem(args));
+            break;
         case "ui_search":
-            return await uiSearch(args);
+            result = (await uiSearch(args));
+            break;
         case "sync_ui_data":
-            return await syncUiData(args, context);
+            result = (await syncUiData(args, context));
+            break;
         case "start_ui":
-            return await startUi(args, context);
+            result = (await startUi(args, context));
+            break;
         case "start_product":
-            return await startProduct((args ?? {}), context);
+            result = (await startProduct((args ?? {}), context));
+            break;
         case "git_work_report":
-            return await gitWorkReport(args);
+            result = (await gitWorkReport(args));
+            break;
         case "search_memory":
-            return await searchMemory(args);
+            result = (await searchMemory(args));
+            break;
         case "read_memory_asset":
-            return await readMemoryAsset(args);
+            result = (await readMemoryAsset(args));
+            break;
         case "memorize_asset":
-            return await memorizeAsset(args);
+            result = (await memorizeAsset(args));
+            break;
         case "delete_memory_asset":
-            return await deleteMemoryAsset(args);
+            result = (await deleteMemoryAsset(args));
+            break;
         case "update_memory_asset":
-            return await updateMemoryAsset(args);
+            result = (await updateMemoryAsset(args));
+            break;
         case "scan_and_extract_patterns":
-            return await scanAndExtractPatterns(args);
+            result = (await scanAndExtractPatterns(args));
+            break;
         default:
             throw new Error(`未知工具: ${name}`);
     }
+    return { bootstrap, result };
 }
 function makeToolError(errorMessage) {
     return {
@@ -528,11 +634,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
         void (async () => {
             try {
                 await taskContext.reportProgress?.(5, `开始执行工具: ${name}`);
-                const rawResult = await executeTool(name, args, taskContext);
+                const { bootstrap, result: rawResult } = await executeTool(name, args, taskContext);
                 if (!rawResult || typeof rawResult !== "object") {
                     throw new Error(`工具 ${name} 返回了无效响应`);
                 }
-                const result = decorateResult(name, args, rawResult, traceMeta);
+                const result = decorateResult(name, args, rawResult, traceMeta, bootstrap);
                 const latestTask = await extra.taskStore?.getTask(task.taskId);
                 if (!latestTask || isTerminalTaskStatus(latestTask.status)) {
                     return;
@@ -583,12 +689,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
     try {
         ensureNotAborted();
         await emitProgress(5, `开始执行工具: ${name}`);
-        const rawResult = await executeTool(name, args, toolContext);
+        const { bootstrap, result: rawResult } = await executeTool(name, args, toolContext);
         if (!rawResult || typeof rawResult !== "object") {
             throw new Error(`工具 ${name} 返回了无效响应`);
         }
         ensureNotAborted();
-        const result = decorateResult(name, args, rawResult, traceMeta);
+        const result = decorateResult(name, args, rawResult, traceMeta, bootstrap);
         await emitProgress(100, `工具执行完成: ${name}`);
         return result;
     }
@@ -603,7 +709,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
         return withTraceMeta(makeToolError(errorMessage), traceMeta);
     }
 });
-// 定义资源列表
+// 定义资源列表（Cursor 设置页会展示为条目；仅保留 status + graph/latest，其余 URI 仍可 ReadResource）
 server.setRequestHandler(ListResourcesRequestSchema, async () => {
     const resources = [
         {
@@ -614,41 +720,11 @@ server.setRequestHandler(ListResourcesRequestSchema, async () => {
         },
         {
             uri: "probe://graph/latest",
-            name: "图谱快照（最新）",
-            description: "最近一次 code_insight 或 start_* 生成的图谱快照",
-            mimeType: "application/json",
-        },
-        {
-            uri: "probe://graph/history",
-            name: "图谱快照（历史）",
-            description: `最近 ${graphSnapshotOrder.length} 条图谱快照摘要`,
-            mimeType: "application/json",
-        },
-        {
-            uri: "probe://graph/latest.md",
-            name: "图谱快照（最新 Markdown）",
-            description: "最近一次图谱快照的 Markdown 视图",
-            mimeType: "text/markdown",
-        },
-        {
-            uri: "probe://graph/files",
-            name: "图谱快照（文件索引）",
-            description: `图谱快照落盘目录: ${toPosixPath(graphSnapshotDir)}`,
+            name: "图谱快照",
+            description: "最新图谱快照（含历史摘要与落盘索引；Markdown 可读 probe://graph/latest.md）",
             mimeType: "application/json",
         },
     ];
-    for (const id of graphSnapshotOrder.slice().reverse().slice(0, 10)) {
-        const snapshot = graphSnapshots.get(id);
-        if (!snapshot) {
-            continue;
-        }
-        resources.push({
-            uri: snapshot.uri,
-            name: `图谱快照 · ${snapshot.toolName}`,
-            description: `${snapshot.status} · ${trimText(snapshot.summary, 120)} (${snapshot.createdAt})`,
-            mimeType: "application/json",
-        });
-    }
     if (uiAppsEnabled) {
         for (const uri of uiAppResourceOrder.slice().reverse()) {
             const entry = uiAppResources.get(uri);
@@ -776,6 +852,13 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
                             json: snapshot.jsonFilePath ?? null,
                             markdown: snapshot.markdownFilePath ?? null,
                         },
+                        history: buildGraphHistorySummary(),
+                        fileIndex: buildGraphFilesIndex(),
+                        relatedUris: {
+                            markdown: "probe://graph/latest.md",
+                            history: "probe://graph/history",
+                            files: "probe://graph/files",
+                        },
                     }, null, 2),
                 },
             ],
@@ -812,67 +895,24 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
         };
     }
     if (uri === "probe://graph/history") {
-        const history = graphSnapshotOrder
-            .slice()
-            .reverse()
-            .map((id) => graphSnapshots.get(id))
-            .filter((item) => Boolean(item))
-            .map((item) => ({
-            id: item.id,
-            uri: item.uri,
-            toolName: item.toolName,
-            createdAt: item.createdAt,
-            status: item.status,
-            summary: trimText(item.summary, 200),
-            files: {
-                json: item.jsonFilePath ?? null,
-                markdown: item.markdownFilePath ?? null,
-            },
-        }));
+        const history = buildGraphHistorySummary();
         return {
             contents: [
                 {
                     uri,
                     mimeType: "application/json",
-                    text: JSON.stringify({
-                        count: history.length,
-                        items: history,
-                    }, null, 2),
+                    text: JSON.stringify(history, null, 2),
                 },
             ],
         };
     }
     if (uri === "probe://graph/files") {
-        const latestId = graphSnapshotOrder[graphSnapshotOrder.length - 1];
-        const latest = latestId ? graphSnapshots.get(latestId) ?? null : null;
-        const hasDir = fs.existsSync(graphSnapshotDir);
-        const files = hasDir
-            ? fs
-                .readdirSync(graphSnapshotDir, { withFileTypes: true })
-                .filter((entry) => entry.isFile() && /\.(json|md)$/i.test(entry.name))
-                .map((entry) => toPosixPath(path.join(graphSnapshotDir, entry.name)))
-                .sort((a, b) => b.localeCompare(a))
-                .slice(0, 40)
-            : [];
         return {
             contents: [
                 {
                     uri,
                     mimeType: "application/json",
-                    text: JSON.stringify({
-                        snapshotDir: toPosixPath(graphSnapshotDir),
-                        exists: hasDir,
-                        latest: latest
-                            ? {
-                                id: latest.id,
-                                uri: latest.uri,
-                                toolName: latest.toolName,
-                                jsonFilePath: latest.jsonFilePath ?? null,
-                                markdownFilePath: latest.markdownFilePath ?? null,
-                            }
-                            : null,
-                        files,
-                    }, null, 2),
+                    text: JSON.stringify(buildGraphFilesIndex(), null, 2),
                 },
             ],
         };
@@ -914,7 +954,8 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error("MCP Probe Kit 服务器已启动");
+    const workspace = resolveWorkspaceRoot("");
+    console.error(`MCP Probe Kit v${VERSION} 已启动 | workspace=${workspace}`);
 }
 // 启动服务器
 main().catch((error) => {

package/build/lib/__tests__/workspace-root.unit.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/lib/__tests__/workspace-root.unit.test.js

@@ -0,0 +1,31 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, describe, expect, test } from "vitest";
+import { resolveFromWorkspaceFolderPathsEnv, resolveWorkspaceRoot, } from "../workspace-root.js";
+const original = process.env.WORKSPACE_FOLDER_PATHS;
+const tempDirs = [];
+afterEach(() => {
+    if (original === undefined) {
+        delete process.env.WORKSPACE_FOLDER_PATHS;
+    }
+    else {
+        process.env.WORKSPACE_FOLDER_PATHS = original;
+    }
+    while (tempDirs.length > 0) {
+        const dir = tempDirs.pop();
+        if (dir) {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    }
+});
+describe("workspace-root WORKSPACE_FOLDER_PATHS", () => {
+    test("解析 JSON 数组形式", () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), "ws-"));
+        tempDirs.push(root);
+        fs.writeFileSync(path.join(root, "package.json"), "{}", "utf8");
+        process.env.WORKSPACE_FOLDER_PATHS = JSON.stringify([root]);
+        expect(resolveFromWorkspaceFolderPathsEnv()).toBe(path.resolve(root));
+        expect(resolveWorkspaceRoot("")).toBe(path.resolve(root));
+    });
+});

package/build/lib/workflow-skill-installer.d.ts

@@ -17,6 +17,8 @@ export interface McpProbeKitBootstrapResult {
     projectRoot: string;
     skill: SkillEnsureResult;
     agentsMd: AgentsMdEnsureResult;
+    /** 工作区可能解析失败（写到了 mcp-probe-kit 安装目录） */
+    workspaceWarning?: string;
 }
 export declare function resolveProjectRootFromToolArgs(args: unknown): string;
 /**

package/build/lib/workflow-skill-installer.js

@@ -5,7 +5,19 @@ import { mergeAgentsMdBlock } from "./merge-agents-md.js";
 import { detectDocumentLocale, resolveProjectContextLayout, toPosixPath, } from "./project-context-layout.js";
 import { generateWorkflowSkillContent, LEGACY_WORKFLOW_SKILL_REL_PATH, MCP_PROBE_SKILL_REL_PATH, } from "./workflow-skill-template.js";
 import { agentsContextNeedsUpgrade, getMcpProbeSkillVersion, parseSkillVersionMarker, skillContentNeedsUpgrade, } from "./workflow-skill-version.js";
-import { isLikelyProjectNamedRelativePath, resolveWorkspaceRoot, } from "./workspace-root.js";
+import { isLikelyProjectNamedRelativePath, getMcpPackageInstallRoot, resolveWorkspaceRoot, } from "./workspace-root.js";
+function buildWorkspaceWarning(projectRoot) {
+    const normalizedRoot = path.resolve(projectRoot);
+    const packageRoot = path.resolve(getMcpPackageInstallRoot());
+    if (normalizedRoot === packageRoot) {
+        return [
+            "未能解析用户项目根目录，Skill/AGENTS.md 可能写入了 mcp-probe-kit 安装目录。",
+            "请在 MCP 配置 env 中设置 MCP_PROJECT_ROOT 为 ${workspaceFolder}，",
+            "或调用工具时传 project_root 绝对路径。",
+        ].join("");
+    }
+    return undefined;
+}
 function flattenToolArgs(args) {
     if (!args || typeof args !== "object" || Array.isArray(args)) {
         return {};
@@ -131,10 +143,12 @@ export function ensureAgentsMdSkillReference(projectRoot) {
  */
 export function ensureMcpProbeKitBootstrap(projectRoot) {
     const root = path.resolve(projectRoot);
+    const workspaceWarning = buildWorkspaceWarning(root);
     return {
         projectRoot: root,
         skill: ensureMcpProbeSkill(root),
         agentsMd: ensureAgentsMdSkillReference(root),
+        workspaceWarning,
     };
 }
 export function ensureMcpProbeKitBootstrapForToolCall(_toolName, args) {

package/build/lib/workspace-root.d.ts

@@ -1,3 +1,7 @@
+/** MCP 包自身安装目录（bootstrap 误写此处说明工作区未解析成功） */
+export declare function getMcpPackageInstallRoot(): string;
+/** 解析 Cursor 等客户端注入的 WORKSPACE_FOLDER_PATHS */
+export declare function resolveFromWorkspaceFolderPathsEnv(): string | null;
 export declare function isLikelyProjectNamedRelativePath(inputPath?: string): boolean;
 export declare function buildProjectRootRetryHint(inputPath?: string): {
     preferred: {

package/build/lib/workspace-root.js

@@ -3,6 +3,7 @@ import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { discoverProjectRootFromLayout } from "./project-context-layout.js";
 const WORKSPACE_ENV_KEYS = [
+    "WORKSPACE_FOLDER_PATHS",
     "MCP_PROJECT_ROOT",
     "MCP_WORKSPACE_ROOT",
     "CURSOR_WORKSPACE_ROOT",
@@ -76,6 +77,34 @@ function getRuntimePackageRoot() {
     const moduleDir = path.dirname(fileURLToPath(import.meta.url));
     return path.resolve(moduleDir, "..", "..");
 }
+/** MCP 包自身安装目录（bootstrap 误写此处说明工作区未解析成功） */
+export function getMcpPackageInstallRoot() {
+    return getRuntimePackageRoot();
+}
+/** 解析 Cursor 等客户端注入的 WORKSPACE_FOLDER_PATHS */
+export function resolveFromWorkspaceFolderPathsEnv() {
+    const raw = process.env.WORKSPACE_FOLDER_PATHS?.trim();
+    if (!raw) {
+        return null;
+    }
+    if (raw.startsWith("[")) {
+        try {
+            const parsed = JSON.parse(raw);
+            if (Array.isArray(parsed) && parsed.length > 0) {
+                const first = safeResolve(String(parsed[0]));
+                if (isExistingDirectory(first)) {
+                    return first;
+                }
+            }
+        }
+        catch {
+            // fall through
+        }
+    }
+    const firstSegment = raw.split(/[|;]/)[0]?.trim() || raw;
+    const candidate = safeResolve(firstSegment);
+    return isExistingDirectory(candidate) ? candidate : null;
+}
 function looksLikeWorkspaceRoot(target) {
     return WORKSPACE_MARKERS.some((marker) => fs.existsSync(path.join(target, marker)));
 }
@@ -134,6 +163,10 @@ export function resolveWorkspaceRoot(explicitProjectRoot) {
     if (isExistingDirectory(explicit)) {
         return discoverProjectRootFromLayout(explicit) ?? explicit;
     }
+    const fromCursorWorkspace = resolveFromWorkspaceFolderPathsEnv();
+    if (fromCursorWorkspace) {
+        return discoverProjectRootFromLayout(fromCursorWorkspace) ?? fromCursorWorkspace;
+    }
     const packageRoot = getRuntimePackageRoot();
     const cwd = safeResolve(process.cwd()) || packageRoot;
     const fromLayout = discoverProjectRootFromLayout(cwd);

package/build/schemas/basic-tools.d.ts

@@ -15,6 +15,10 @@ export declare const basicToolSchemas: readonly [{
                 readonly type: "string";
                 readonly description: "项目名称。可选，默认为'新项目'";
             };
+            readonly project_root: {
+                readonly type: "string";
+                readonly description: "项目根目录绝对路径。用于 Skill/AGENTS.md 自动安装；未传则解析 Cursor 工作区";
+            };
         };
         readonly required: readonly [];
         readonly additionalProperties: true;

package/build/schemas/basic-tools.js

@@ -16,6 +16,10 @@ export const basicToolSchemas = [
                     type: "string",
                     description: "项目名称。可选，默认为'新项目'",
                 },
+                project_root: {
+                    type: "string",
+                    description: "项目根目录绝对路径。用于 Skill/AGENTS.md 自动安装；未传则解析 Cursor 工作区",
+                },
             },
             required: [],
             additionalProperties: true,

package/build/schemas/index.d.ts

@@ -15,6 +15,10 @@ export declare const allToolSchemas: ({
                 readonly type: "string";
                 readonly description: "项目名称。可选，默认为'新项目'";
             };
+            readonly project_root: {
+                readonly type: "string";
+                readonly description: "项目根目录绝对路径。用于 Skill/AGENTS.md 自动安装；未传则解析 Cursor 工作区";
+            };
         };
         readonly required: readonly [];
         readonly additionalProperties: true;