mcp-probe-kit 3.6.0 → 3.6.2

package/build/index.js

@@ -9,12 +9,13 @@ import { initProject, gencommit, codeReview, codeInsight, gentest, refactor, ini
 import { VERSION, NAME } from "./version.js";
 import { allToolSchemas } from "./schemas/index.js";
 import { filterTools, getToolsetFromEnv } from "./lib/toolset-manager.js";
-import { withToolAnnotations } from "./lib/tool-annotations.js";
-import { withOutputSchema } from "./lib/output-schema-registry.js";
+import { prepareToolForToolsList } 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, resolveWorkspaceRootWithMeta } from "./lib/workspace-root.js";
+import { PROJECT_BOOTSTRAP_URI, discoverProjectResources, readProjectResourceContent, } from "./lib/project-mcp-resources.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);
@@ -353,13 +424,16 @@ const server = new Server({
 server.setRequestHandler(ListToolsRequestSchema, async () => {
     const toolset = getToolsetFromEnv();
     const filteredTools = filterTools(allToolSchemas, toolset);
-    console.error(`[MCP Probe Kit] 当前工具集: ${toolset} (${filteredTools.length}/${allToolSchemas.length} 个工具)`);
-    return {
-        tools: filteredTools.map((tool) => withOutputSchema(withToolAnnotations(tool))),
-    };
+    const tools = filteredTools.map((tool) => prepareToolForToolsList(tool));
+    const payloadBytes = Buffer.byteLength(JSON.stringify({ tools }), "utf8");
+    console.error(`[MCP Probe Kit] 当前工具集: ${toolset} (${tools.length}/${allToolSchemas.length} 个工具) | tools/list ≈ ${(payloadBytes / 1024).toFixed(1)} KB`);
+    return { tools };
 });
 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);
     }
 });
-// 定义资源列表
+// 定义资源列表（轻量只读；bootstrap 写盘仅在 resources/read probe://project/bootstrap 或工具调用时）
 server.setRequestHandler(ListResourcesRequestSchema, async () => {
     const resources = [
         {
@@ -613,56 +719,32 @@ server.setRequestHandler(ListResourcesRequestSchema, async () => {
             mimeType: "application/json",
         },
         {
-            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)}`,
+            uri: PROJECT_BOOTSTRAP_URI,
+            name: "项目 MCP 自检",
+            description: "读取时自动补齐 Skill + AGENTS.md，并返回 probe://project/skill|agents|context|graph 入口",
             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);
-            if (!entry) {
-                continue;
+    try {
+        if (uiAppsEnabled) {
+            for (const uri of uiAppResourceOrder.slice().reverse()) {
+                const entry = uiAppResources.get(uri);
+                if (!entry) {
+                    continue;
+                }
+                resources.push({
+                    uri: entry.uri,
+                    name: entry.name,
+                    description: `${entry.description} (${entry.createdAt})`,
+                    mimeType: entry.mimeType,
+                });
             }
-            resources.push({
-                uri: entry.uri,
-                name: entry.name,
-                description: `${entry.description} (${entry.createdAt})`,
-                mimeType: entry.mimeType,
-            });
         }
     }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`[MCP Probe Kit] resources/list UI 资源合并失败: ${message}`);
+    }
     return {
         resources,
     };
@@ -719,11 +801,49 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
                             })(),
                         },
                         toolCount: allToolSchemas.length,
+                        projectResources: (() => {
+                            try {
+                                const discovered = discoverProjectResources(resolveWorkspaceRoot(""));
+                                return {
+                                    bootstrapUri: PROJECT_BOOTSTRAP_URI,
+                                    projectRoot: toPosixPath(discovered.projectRoot),
+                                    available: discovered.resources
+                                        .filter((item) => item.exists)
+                                        .map((item) => item.uri),
+                                    note: "读取 probe://project/bootstrap 时执行 Skill/AGENTS 自动补齐",
+                                };
+                            }
+                            catch (error) {
+                                const message = error instanceof Error ? error.message : String(error);
+                                return { bootstrapUri: PROJECT_BOOTSTRAP_URI, error: message };
+                            }
+                        })(),
                     }, null, 2),
                 },
             ],
         };
     }
+    if (uri === PROJECT_BOOTSTRAP_URI || uri.startsWith("probe://project/")) {
+        try {
+            const content = readProjectResourceContent(uri, resolveWorkspaceRoot(""));
+            if (!content) {
+                throw new Error(`未知项目 resource: ${uri}`);
+            }
+            return {
+                contents: [
+                    {
+                        uri: content.uri,
+                        mimeType: content.mimeType,
+                        text: content.text,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`读取项目 resource 失败 (${uri}): ${message}`);
+        }
+    }
     if (uri.startsWith("ui://")) {
         const entry = uiAppResources.get(uri);
         if (!entry) {
@@ -776,6 +896,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 +939,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 +998,11 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error("MCP Probe Kit 服务器已启动");
+    const workspaceMeta = resolveWorkspaceRootWithMeta("");
+    console.error(`MCP Probe Kit v${VERSION} 已启动 | workspace=${workspaceMeta.root} | source=${workspaceMeta.source}`);
+    if (workspaceMeta.warning) {
+        console.error(`[MCP Probe Kit] ${workspaceMeta.warning}`);
+    }
 }
 // 启动服务器
 main().catch((error) => {

package/build/lib/__tests__/custom-mcp-resources.unit.test.d.ts

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

package/build/lib/__tests__/custom-mcp-resources.unit.test.js

@@ -0,0 +1,135 @@
+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 { CUSTOM_RESOURCES_MANIFEST_REL, listCustomResourceDescriptors, loadCustomResourcesManifest, parseCustomResourcesManifest, readCustomResourceContent, resolveCustomResourcesManifestPath, } from "../custom-mcp-resources.js";
+function withTempProject(run) {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "mcp-custom-res-"));
+    try {
+        run(root);
+    }
+    finally {
+        fs.rmSync(root, { recursive: true, force: true });
+    }
+}
+function writeManifest(root, body) {
+    const dir = path.join(root, ".mcp-probe-kit");
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, "resources.json"), JSON.stringify(body, null, 2), "utf-8");
+}
+describe("custom-mcp-resources", () => {
+    const prevEnv = { ...process.env };
+    afterEach(() => {
+        process.env = { ...prevEnv };
+    });
+    test("parseCustomResourcesManifest validates version and uri prefix", () => {
+        const entries = parseCustomResourcesManifest(JSON.stringify({
+            version: 1,
+            resources: [
+                {
+                    uri: "project://guide/readme",
+                    name: "Guide",
+                    mimeType: "text/markdown",
+                    text: "# hello",
+                },
+            ],
+        }));
+        expect(entries).toHaveLength(1);
+        expect(entries[0]?.uri).toBe("project://guide/readme");
+        expect(() => parseCustomResourcesManifest(JSON.stringify({
+            version: 1,
+            resources: [
+                {
+                    uri: "probe://status",
+                    name: "Bad",
+                    mimeType: "text/plain",
+                    text: "x",
+                },
+            ],
+        }))).toThrow(/project:\/\//);
+    });
+    test("listCustomResourceDescriptors respects list flag", () => {
+        withTempProject((root) => {
+            writeManifest(root, {
+                version: 1,
+                resources: [
+                    {
+                        uri: "project://visible",
+                        name: "Visible",
+                        mimeType: "text/plain",
+                        text: "a",
+                        list: true,
+                    },
+                    {
+                        uri: "project://hidden",
+                        name: "Hidden",
+                        mimeType: "text/plain",
+                        text: "b",
+                        list: false,
+                    },
+                ],
+            });
+            const listed = listCustomResourceDescriptors(root);
+            expect(listed.map((item) => item.uri)).toEqual(["project://visible"]);
+        });
+    });
+    test("readCustomResourceContent reads inline text and file", () => {
+        withTempProject((root) => {
+            const docsDir = path.join(root, "docs");
+            fs.mkdirSync(docsDir, { recursive: true });
+            fs.writeFileSync(path.join(docsDir, "note.md"), "# Note", "utf-8");
+            writeManifest(root, {
+                version: 1,
+                resources: [
+                    {
+                        uri: "project://inline",
+                        name: "Inline",
+                        mimeType: "text/plain",
+                        text: "inline-body",
+                    },
+                    {
+                        uri: "project://file/note",
+                        name: "File",
+                        mimeType: "text/markdown",
+                        file: "docs/note.md",
+                    },
+                ],
+            });
+            expect(readCustomResourceContent("project://inline", root)?.text).toBe("inline-body");
+            expect(readCustomResourceContent("project://file/note", root)?.text).toBe("# Note");
+        });
+    });
+    test("readCustomResourceContent rejects path traversal", () => {
+        withTempProject((root) => {
+            writeManifest(root, {
+                version: 1,
+                resources: [
+                    {
+                        uri: "project://escape",
+                        name: "Escape",
+                        mimeType: "text/plain",
+                        file: "../outside.txt",
+                    },
+                ],
+            });
+            expect(() => readCustomResourceContent("project://escape", root)).toThrow(/\.\./);
+        });
+    });
+    test("loadCustomResourcesManifest returns empty when manifest missing", () => {
+        withTempProject((root) => {
+            const result = loadCustomResourcesManifest(root);
+            expect(result.entries).toEqual([]);
+            expect(result.error).toBeNull();
+            expect(result.manifestPath).toBeNull();
+        });
+    });
+    test("resolveCustomResourcesManifestPath honors MCP_CUSTOM_RESOURCES_PATH", () => {
+        withTempProject((root) => {
+            const custom = path.join(root, "cfg", "my-resources.json");
+            process.env.MCP_CUSTOM_RESOURCES_PATH = "cfg/my-resources.json";
+            expect(resolveCustomResourcesManifestPath(root)).toBe(custom);
+            delete process.env.MCP_CUSTOM_RESOURCES_PATH;
+            expect(resolveCustomResourcesManifestPath(root)).toBe(path.join(root, CUSTOM_RESOURCES_MANIFEST_REL));
+        });
+    });
+});

package/build/lib/__tests__/project-mcp-resources.unit.test.d.ts

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