mcp-probe-kit 3.3.0 → 3.6.1

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

@@ -0,0 +1,68 @@
+import { VERSION } from "../version.js";
+/** Skill 文件首行版本标记：`<!-- mcp-probe-kit-skill-version: 3.5.0 -->` */
+export const SKILL_VERSION_MARKER = "mcp-probe-kit-skill-version";
+/** AGENTS.md mcp-probe 块内版本标记 */
+export const AGENTS_CONTEXT_VERSION_MARKER = "mcp-probe:context-version";
+export function getMcpProbeSkillVersion() {
+    return VERSION;
+}
+export function formatSkillVersionMarker(version = VERSION) {
+    return `<!-- ${SKILL_VERSION_MARKER}: ${version} -->`;
+}
+export function formatAgentsContextVersionMarker(version = VERSION) {
+    return `<!-- ${AGENTS_CONTEXT_VERSION_MARKER}: ${version} -->`;
+}
+export function parseSkillVersionMarker(content) {
+    const pattern = new RegExp(`<!--\\s*${SKILL_VERSION_MARKER}:\\s*([^\\s>]+)\\s*-->`, "i");
+    const match = content.match(pattern);
+    return match?.[1]?.trim() ?? null;
+}
+export function parseAgentsContextVersion(content) {
+    const pattern = new RegExp(`<!--\\s*${AGENTS_CONTEXT_VERSION_MARKER}:\\s*([^\\s>]+)\\s*-->`, "i");
+    const match = content.match(pattern);
+    return match?.[1]?.trim() ?? null;
+}
+/** 比较 semver（仅主版本号段，忽略 prerelease 后缀） */
+export function compareSemver(a, b) {
+    const normalize = (value) => value
+        .trim()
+        .replace(/^v/i, "")
+        .split("-")[0]
+        .split(".")
+        .map((part) => {
+        const n = Number.parseInt(part, 10);
+        return Number.isFinite(n) ? n : 0;
+    });
+    const left = normalize(a);
+    const right = normalize(b);
+    const length = Math.max(left.length, right.length);
+    for (let i = 0; i < length; i += 1) {
+        const diff = (left[i] ?? 0) - (right[i] ?? 0);
+        if (diff !== 0) {
+            return diff > 0 ? 1 : -1;
+        }
+    }
+    return 0;
+}
+/** 已安装 Skill 是否落后于当前 kit 版本（无标记视为过期） */
+export function skillContentNeedsUpgrade(existing, targetVersion = VERSION) {
+    if (!existing?.trim()) {
+        return true;
+    }
+    const installed = parseSkillVersionMarker(existing);
+    if (!installed) {
+        return true;
+    }
+    return compareSemver(installed, targetVersion) < 0;
+}
+/** AGENTS.md mcp-probe 块是否落后于当前 kit 版本 */
+export function agentsContextNeedsUpgrade(existing, targetVersion = VERSION) {
+    if (!existing?.trim()) {
+        return true;
+    }
+    const installed = parseAgentsContextVersion(existing);
+    if (!installed) {
+        return true;
+    }
+    return compareSemver(installed, targetVersion) < 0;
+}

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;
@@ -193,6 +197,25 @@ export declare const allToolSchemas: ({
         readonly required: readonly [];
         readonly additionalProperties: true;
     };
+} | {
+    readonly name: "workflow";
+    readonly description: "当不确定该用哪个 MCP 工具时使用。根据意图返回分阶段 MCP 指南（firstTool + phases）。同时确保用户项目已存在 .agents/skills/mcp-probe-kit/SKILL.md 与 AGENTS.md 中的 Skill 引用（缺失则自动创建/更新）。";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly intent: {
+                readonly type: "string";
+                readonly description: "用户目标或任务描述（自然语言）";
+            };
+            readonly scenario: {
+                readonly type: "string";
+                readonly enum: readonly ["auto", "feature", "bugfix", "ui", "explore", "commit", "review", "refactor", "onboard", "spec", "memory"];
+                readonly description: "可选：显式场景；默认 auto 从 intent 推断";
+            };
+        };
+        readonly required: readonly [];
+        readonly additionalProperties: true;
+    };
 } | {
     readonly name: "init_project_context";
     readonly description: "生成/更新项目上下文：默认写入 AGENTS.md（含 MCP 与 GitNexus 触发规则）及 docs/project-context/。新功能请先 start_feature，修 bug 请先 start_bugfix。完成后 Agent 应阅读 AGENTS.md。";
@@ -371,6 +394,14 @@ export declare const allToolSchemas: ({
                 readonly type: "string";
                 readonly description: "项目根目录绝对路径。建议显式传入；docs_dir 等相对路径参数应统一相对该项目根目录解析，避免依赖客户端 cwd。";
             };
+            readonly docs_dir: {
+                readonly type: "string";
+                readonly description: "文档目录。可选，默认 docs";
+            };
+            readonly feature_name: {
+                readonly type: "string";
+                readonly description: "关联功能规格名（对应 docs/specs/<feature_name>/）。提供后或能自动识别时，修复闭环会插入 check_spec 闸门";
+            };
             readonly analysis_mode: {
                 readonly type: "string";
                 readonly description: "分析方法。默认 tbp8（丰田问题分析 8 步法）";
@@ -814,6 +845,89 @@ export declare const allToolSchemas: ({
         readonly required: readonly ["name", "description", "summary"];
         readonly additionalProperties: true;
     };
+} | {
+    readonly name: "delete_memory_asset";
+    readonly description: "按 asset_id 从共享记忆库删除一条资产。适用于过时、错误或重复沉淀的清理；删除前建议先用 read_memory_asset 确认内容。";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly asset_id: {
+                readonly type: "string";
+                readonly description: "要删除的记忆资产 ID（通常来自 search_memory 或 read_memory_asset）";
+            };
+            readonly confirm: {
+                readonly type: "boolean";
+                readonly description: "为 true 时执行删除；省略或 false 时仅返回预览并要求确认（软确认）";
+            };
+        };
+        readonly required: readonly ["asset_id"];
+        readonly additionalProperties: true;
+    };
+} | {
+    readonly name: "update_memory_asset";
+    readonly description: "按 asset_id 更新共享记忆库中的已有资产（保留原 ID）。适用于修正摘要、正文或标签；content 变更会重新向量化。跨仓库共享时勿填 source_project/source_path。";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly asset_id: {
+                readonly type: "string";
+                readonly description: "要更新的记忆资产 ID";
+            };
+            readonly name: {
+                readonly type: "string";
+                readonly description: "资产名称";
+            };
+            readonly type: {
+                readonly type: "string";
+                readonly description: "资产类型：bugfix / pattern / component / code 等";
+            };
+            readonly description: {
+                readonly type: "string";
+                readonly description: "资产描述";
+            };
+            readonly summary: {
+                readonly type: "string";
+                readonly description: "检索用一句话摘要";
+            };
+            readonly content: {
+                readonly type: "string";
+                readonly description: "完整内容";
+            };
+            readonly code_snippet: {
+                readonly type: "string";
+                readonly description: "代码片段，content 的别名";
+            };
+            readonly file_path: {
+                readonly type: "string";
+                readonly description: "已废弃：勿用于跨仓库沉淀，路径写入 content";
+            };
+            readonly source_project: {
+                readonly type: "string";
+                readonly description: "已废弃：仅同仓库追溯时可选";
+            };
+            readonly source_path: {
+                readonly type: "string";
+                readonly description: "已废弃：仅同仓库追溯时可选";
+            };
+            readonly usage: {
+                readonly type: "string";
+                readonly description: "适用场景/使用方式";
+            };
+            readonly confidence: {
+                readonly type: "number";
+                readonly description: "置信度，0-1";
+            };
+            readonly tags: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+                readonly description: "标签列表";
+            };
+        };
+        readonly required: readonly ["asset_id"];
+        readonly additionalProperties: true;
+    };
 } | {
     readonly name: "scan_and_extract_patterns";
     readonly description: "当需要从单段代码、单文件或整个目录中抽取可复用模式，再决定是否沉淀到记忆系统时使用。目录扫描时，优先传 `project_root` 为项目根目录绝对路径，并让 `directory_path` 传相对项目根的路径，例如 `app/utils`；只有无法确定项目根时，才把 `directory_path` 直接设为绝对路径。不要传带项目名的半相对路径，例如 `font-miniapp-api/app/utils`。";

package/build/schemas/index.js

@@ -13,6 +13,7 @@ import { uiUxSchemas } from "./ui-ux-schemas.js";
 import { productDesignSchemas } from "./product-design-schemas.js";
 import { memoryToolSchemas } from "./memory-tools.js";
 // 合并所有工具 schemas
+// 增删工具时同步更新 src/lib/mcp-tool-skill-registry.ts（prebuild 会 verify-workflow-skill 校验）
 export const allToolSchemas = [
     ...basicToolSchemas,
     ...gitToolSchemas,

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

@@ -102,6 +102,89 @@ export declare const memoryToolSchemas: readonly [{
         readonly required: readonly ["name", "description", "summary"];
         readonly additionalProperties: true;
     };
+}, {
+    readonly name: "delete_memory_asset";
+    readonly description: "按 asset_id 从共享记忆库删除一条资产。适用于过时、错误或重复沉淀的清理；删除前建议先用 read_memory_asset 确认内容。";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly asset_id: {
+                readonly type: "string";
+                readonly description: "要删除的记忆资产 ID（通常来自 search_memory 或 read_memory_asset）";
+            };
+            readonly confirm: {
+                readonly type: "boolean";
+                readonly description: "为 true 时执行删除；省略或 false 时仅返回预览并要求确认（软确认）";
+            };
+        };
+        readonly required: readonly ["asset_id"];
+        readonly additionalProperties: true;
+    };
+}, {
+    readonly name: "update_memory_asset";
+    readonly description: "按 asset_id 更新共享记忆库中的已有资产（保留原 ID）。适用于修正摘要、正文或标签；content 变更会重新向量化。跨仓库共享时勿填 source_project/source_path。";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly asset_id: {
+                readonly type: "string";
+                readonly description: "要更新的记忆资产 ID";
+            };
+            readonly name: {
+                readonly type: "string";
+                readonly description: "资产名称";
+            };
+            readonly type: {
+                readonly type: "string";
+                readonly description: "资产类型：bugfix / pattern / component / code 等";
+            };
+            readonly description: {
+                readonly type: "string";
+                readonly description: "资产描述";
+            };
+            readonly summary: {
+                readonly type: "string";
+                readonly description: "检索用一句话摘要";
+            };
+            readonly content: {
+                readonly type: "string";
+                readonly description: "完整内容";
+            };
+            readonly code_snippet: {
+                readonly type: "string";
+                readonly description: "代码片段，content 的别名";
+            };
+            readonly file_path: {
+                readonly type: "string";
+                readonly description: "已废弃：勿用于跨仓库沉淀，路径写入 content";
+            };
+            readonly source_project: {
+                readonly type: "string";
+                readonly description: "已废弃：仅同仓库追溯时可选";
+            };
+            readonly source_path: {
+                readonly type: "string";
+                readonly description: "已废弃：仅同仓库追溯时可选";
+            };
+            readonly usage: {
+                readonly type: "string";
+                readonly description: "适用场景/使用方式";
+            };
+            readonly confidence: {
+                readonly type: "number";
+                readonly description: "置信度，0-1";
+            };
+            readonly tags: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+                readonly description: "标签列表";
+            };
+        };
+        readonly required: readonly ["asset_id"];
+        readonly additionalProperties: true;
+    };
 }, {
     readonly name: "scan_and_extract_patterns";
     readonly description: "当需要从单段代码、单文件或整个目录中抽取可复用模式，再决定是否沉淀到记忆系统时使用。目录扫描时，优先传 `project_root` 为项目根目录绝对路径，并让 `directory_path` 传相对项目根的路径，例如 `app/utils`；只有无法确定项目根时，才把 `directory_path` 直接设为绝对路径。不要传带项目名的半相对路径，例如 `font-miniapp-api/app/utils`。";

package/build/schemas/memory-tools.js

@@ -52,6 +52,49 @@ export const memoryToolSchemas = [
             additionalProperties: true,
         },
     },
+    {
+        name: 'delete_memory_asset',
+        description: '按 asset_id 从共享记忆库删除一条资产。适用于过时、错误或重复沉淀的清理；删除前建议先用 read_memory_asset 确认内容。',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                asset_id: {
+                    type: 'string',
+                    description: '要删除的记忆资产 ID（通常来自 search_memory 或 read_memory_asset）',
+                },
+                confirm: {
+                    type: 'boolean',
+                    description: '为 true 时执行删除；省略或 false 时仅返回预览并要求确认（软确认）',
+                },
+            },
+            required: ['asset_id'],
+            additionalProperties: true,
+        },
+    },
+    {
+        name: 'update_memory_asset',
+        description: '按 asset_id 更新共享记忆库中的已有资产（保留原 ID）。适用于修正摘要、正文或标签；content 变更会重新向量化。跨仓库共享时勿填 source_project/source_path。',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                asset_id: { type: 'string', description: '要更新的记忆资产 ID' },
+                name: { type: 'string', description: '资产名称' },
+                type: { type: 'string', description: '资产类型：bugfix / pattern / component / code 等' },
+                description: { type: 'string', description: '资产描述' },
+                summary: { type: 'string', description: '检索用一句话摘要' },
+                content: { type: 'string', description: '完整内容' },
+                code_snippet: { type: 'string', description: '代码片段，content 的别名' },
+                file_path: { type: 'string', description: '已废弃：勿用于跨仓库沉淀，路径写入 content' },
+                source_project: { type: 'string', description: '已废弃：仅同仓库追溯时可选' },
+                source_path: { type: 'string', description: '已废弃：仅同仓库追溯时可选' },
+                usage: { type: 'string', description: '适用场景/使用方式' },
+                confidence: { type: 'number', description: '置信度，0-1' },
+                tags: { type: 'array', items: { type: 'string' }, description: '标签列表' },
+            },
+            required: ['asset_id'],
+            additionalProperties: true,
+        },
+    },
     {
         name: 'scan_and_extract_patterns',
         description: '当需要从单段代码、单文件或整个目录中抽取可复用模式，再决定是否沉淀到记忆系统时使用。目录扫描时，优先传 `project_root` 为项目根目录绝对路径，并让 `directory_path` 传相对项目根的路径，例如 `app/utils`；只有无法确定项目根时，才把 `directory_path` 直接设为绝对路径。不要传带项目名的半相对路径，例如 `font-miniapp-api/app/utils`。',

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

@@ -69,6 +69,14 @@ export declare const orchestrationToolSchemas: readonly [{
                 readonly type: "string";
                 readonly description: "项目根目录绝对路径。建议显式传入；docs_dir 等相对路径参数应统一相对该项目根目录解析，避免依赖客户端 cwd。";
             };
+            readonly docs_dir: {
+                readonly type: "string";
+                readonly description: "文档目录。可选，默认 docs";
+            };
+            readonly feature_name: {
+                readonly type: "string";
+                readonly description: "关联功能规格名（对应 docs/specs/<feature_name>/）。提供后或能自动识别时，修复闭环会插入 check_spec 闸门";
+            };
             readonly analysis_mode: {
                 readonly type: "string";
                 readonly description: "分析方法。默认 tbp8（丰田问题分析 8 步法）";

package/build/schemas/orchestration-tools.js

@@ -71,6 +71,14 @@ export const orchestrationToolSchemas = [
                     type: "string",
                     description: "项目根目录绝对路径。建议显式传入；docs_dir 等相对路径参数应统一相对该项目根目录解析，避免依赖客户端 cwd。",
                 },
+                docs_dir: {
+                    type: "string",
+                    description: "文档目录。可选，默认 docs",
+                },
+                feature_name: {
+                    type: "string",
+                    description: "关联功能规格名（对应 docs/specs/<feature_name>/）。提供后或能自动识别时，修复闭环会插入 check_spec 闸门",
+                },
                 analysis_mode: {
                     type: "string",
                     description: "分析方法。默认 tbp8（丰田问题分析 8 步法）",

package/build/schemas/output/code-insight-tools.d.ts

@@ -0,0 +1,65 @@
+/**
+ * code_insight 结构化输出 Schema（精简版，覆盖 handles 与核心字段）
+ */
+export declare const CodeInsightSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly status: {
+            readonly type: "string";
+            readonly enum: readonly ["ok", "degraded", "ambiguous", "not_found"];
+        };
+        readonly provider: {
+            readonly type: "string";
+        };
+        readonly mode: {
+            readonly type: "object";
+            readonly properties: {
+                readonly requested: {
+                    readonly type: "string";
+                };
+                readonly resolved: {
+                    readonly type: "string";
+                };
+            };
+        };
+        readonly summary: {
+            readonly type: "string";
+        };
+        readonly warnings: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly nextAction: {
+            readonly type: readonly ["string", "null"];
+        };
+        readonly handles: {
+            readonly type: "object";
+            readonly properties: {
+                readonly graph_snapshot: {
+                    readonly type: "string";
+                };
+                readonly graph_resource: {
+                    readonly type: "string";
+                };
+                readonly memory_assets: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly id: {
+                                readonly type: "string";
+                            };
+                            readonly tool: {
+                                readonly type: "string";
+                            };
+                        };
+                        readonly required: readonly ["id", "tool"];
+                    };
+                };
+            };
+        };
+    };
+    readonly required: readonly ["status", "summary"];
+};

package/build/schemas/output/code-insight-tools.js

@@ -0,0 +1,42 @@
+/**
+ * code_insight 结构化输出 Schema（精简版，覆盖 handles 与核心字段）
+ */
+export const CodeInsightSchema = {
+    type: 'object',
+    properties: {
+        status: {
+            type: 'string',
+            enum: ['ok', 'degraded', 'ambiguous', 'not_found'],
+        },
+        provider: { type: 'string' },
+        mode: {
+            type: 'object',
+            properties: {
+                requested: { type: 'string' },
+                resolved: { type: 'string' },
+            },
+        },
+        summary: { type: 'string' },
+        warnings: { type: 'array', items: { type: 'string' } },
+        nextAction: { type: ['string', 'null'] },
+        handles: {
+            type: 'object',
+            properties: {
+                graph_snapshot: { type: 'string' },
+                graph_resource: { type: 'string' },
+                memory_assets: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            id: { type: 'string' },
+                            tool: { type: 'string' },
+                        },
+                        required: ['id', 'tool'],
+                    },
+                },
+            },
+        },
+    },
+    required: ['status', 'summary'],
+};