mcp-probe-kit 3.6.0 → 3.6.2

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 客户端（Cursor / OpenCode 等会自动传入工作区），",
+            "或在工具参数中传 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/workflow-skill-template.js

@@ -37,7 +37,7 @@ export function generateWorkflowSkillBody(skillVersion = VERSION) {
     return `# MCP 调用时机 — mcp-probe-kit
 
 > 本 Skill 只回答一件事：**什么情况 → 调哪个 MCP**。不是开发流程剧本。
-> 由 mcp-probe-kit 自动安装；Cursor 从 \`.agents/skills/\` 加载。
+> 由 mcp-probe-kit 自动安装；支持 MCP 的 Agent 客户端可从 \`.agents/skills/\` 加载。
 
 ## 总规则
 

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

@@ -1,3 +1,9 @@
+/** Schema / 文档：project_root 参数说明（自动探测，无需用户配置 MCP_PROJECT_ROOT） */
+export declare const PROJECT_ROOT_SCHEMA_DESCRIPTION = "\u53EF\u9009\u3002\u9879\u76EE\u6839\u76EE\u5F55\u7EDD\u5BF9\u8DEF\u5F84\uFF1B\u672A\u4F20\u65F6\u81EA\u52A8\u4ECE MCP \u5BA2\u6237\u7AEF\u5DE5\u4F5C\u533A\u89E3\u6790\uFF08\u5982 Cursor \u6CE8\u5165 WORKSPACE_FOLDER_PATHS\u3001OpenCode/\u5BA2\u6237\u7AEF\u914D\u7F6E\u7684 cwd \u7B49\uFF09\u3002\u4EC5\u8FB9\u7F18\u573A\u666F\u9700\u624B\u52A8\u4F20\u5165\u3002";
+/** MCP 包自身安装目录（bootstrap 误写此处说明工作区未解析成功） */
+export declare function getMcpPackageInstallRoot(): string;
+/** 解析 MCP 客户端注入的 WORKSPACE_FOLDER_PATHS（如 Cursor） */
+export declare function resolveFromWorkspaceFolderPathsEnv(): string | null;
 export declare function isLikelyProjectNamedRelativePath(inputPath?: string): boolean;
 export declare function buildProjectRootRetryHint(inputPath?: string): {
     preferred: {
@@ -8,5 +14,20 @@ export declare function buildProjectRootRetryHint(inputPath?: string): {
         project_root: string;
     };
 };
+export type WorkspaceRootSource = "explicit" | "explicit-not-yet-created" | "workspace-env" | "layout" | "env" | "cwd" | "package-fallback";
+export interface WorkspaceRootResolution {
+    root: string;
+    source: WorkspaceRootSource;
+    /** 用户传入的 project_root 原始值 */
+    explicitRequested?: string;
+    /** 是否采用了用户显式路径（未回退到 MCP 安装目录等） */
+    explicitHonored: boolean;
+    warning?: string;
+}
+/**
+ * 解析项目根目录。
+ * 若调用方显式传入 project_root（非空），优先信任该路径，不再向上游走 layout 到父目录。
+ */
+export declare function resolveWorkspaceRootWithMeta(explicitProjectRoot?: string): WorkspaceRootResolution;
 export declare function resolveWorkspaceRoot(explicitProjectRoot?: string): string;
 export declare function toWorkspacePath(explicitProjectRoot?: string): string;

package/build/lib/workspace-root.js

@@ -2,14 +2,23 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { discoverProjectRootFromLayout } from "./project-context-layout.js";
-const WORKSPACE_ENV_KEYS = [
+/** Schema / 文档：project_root 参数说明（自动探测，无需用户配置 MCP_PROJECT_ROOT） */
+export const PROJECT_ROOT_SCHEMA_DESCRIPTION = "可选。项目根目录绝对路径；未传时自动从 MCP 客户端工作区解析（如 Cursor 注入 WORKSPACE_FOLDER_PATHS、OpenCode/客户端配置的 cwd 等）。仅边缘场景需手动传入。";
+/** MCP 客户端注入的工作区路径（最高优先级，信任客户端，不向父级 layout 上爬） */
+const RUNTIME_CWD_ENV_KEYS = ["INIT_CWD", "PWD", "CWD"];
+/** 用户可选覆盖（不要求在 MCP 配置里逐个填写） */
+const OPTIONAL_OVERRIDE_ENV_KEYS = [
     "MCP_PROJECT_ROOT",
     "MCP_WORKSPACE_ROOT",
     "CURSOR_WORKSPACE_ROOT",
     "WORKSPACE_ROOT",
     "PROJECT_ROOT",
-    "INIT_CWD",
-    "PWD",
+    "OPENCODE_WORKSPACE",
+    "OPENCODE_CWD",
+    "OPENCODE_PROJECT_ROOT",
+    "VSCODE_CWD",
+    "CLAUDE_PROJECT_DIR",
+    "CODEX_CWD",
 ];
 const WORKSPACE_MARKERS = [
     ".git",
@@ -22,6 +31,10 @@ const WORKSPACE_MARKERS = [
     "go.mod",
     "pyproject.toml",
     "requirements.txt",
+    "opencode.json",
+    ".opencode",
+    "AGENTS.md",
+    ".agents",
     ".cursor",
     ".vscode",
     ".kiro",
@@ -76,6 +89,34 @@ function getRuntimePackageRoot() {
     const moduleDir = path.dirname(fileURLToPath(import.meta.url));
     return path.resolve(moduleDir, "..", "..");
 }
+/** MCP 包自身安装目录（bootstrap 误写此处说明工作区未解析成功） */
+export function getMcpPackageInstallRoot() {
+    return getRuntimePackageRoot();
+}
+/** 解析 MCP 客户端注入的 WORKSPACE_FOLDER_PATHS（如 Cursor） */
+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)));
 }
@@ -95,6 +136,37 @@ function findWorkspaceAncestor(start, packageRoot) {
         current = parent;
     }
 }
+/**
+ * 信任 MCP 客户端注入的工作区路径：仅在客户端给定目录及其子树内找 marker，
+ * 不向父级 layout 上爬（避免 monorepo 父目录抢走子项目）。
+ */
+function resolveTrustedClientWorkspace(clientPath, packageRoot) {
+    if (looksLikeWorkspaceRoot(clientPath)) {
+        return clientPath;
+    }
+    return findWorkspaceAncestor(clientPath, packageRoot) ?? clientPath;
+}
+function resolveFromEnvKeys(keys, packageRoot) {
+    for (const key of keys) {
+        const candidate = safeResolve(process.env[key] || "");
+        const resolved = findWorkspaceAncestor(candidate, packageRoot);
+        if (resolved) {
+            return resolved;
+        }
+        if (isExistingDirectory(candidate) && candidate !== packageRoot) {
+            return candidate;
+        }
+    }
+    return null;
+}
+function buildPackageFallbackWarning(resolved) {
+    return [
+        "未能自动识别用户项目根目录，Skill/AGENTS.md 可能写入了 mcp-probe-kit 安装目录。",
+        "请从目标项目目录打开 MCP 客户端（Cursor / OpenCode 等会自动传入工作区），",
+        "或在工具参数中传 project_root 绝对路径。",
+        `当前回退路径: ${resolved}`,
+    ].join(" ");
+}
 export function isLikelyProjectNamedRelativePath(inputPath) {
     if (!inputPath || path.isAbsolute(inputPath)) {
         return false;
@@ -129,29 +201,97 @@ export function buildProjectRootRetryHint(inputPath) {
         },
     };
 }
-export function resolveWorkspaceRoot(explicitProjectRoot) {
-    const explicit = safeResolve(explicitProjectRoot || "");
-    if (isExistingDirectory(explicit)) {
-        return discoverProjectRootFromLayout(explicit) ?? explicit;
+function buildExplicitIgnoredWarning(requested, resolved) {
+    return [
+        `未能采用传入的 project_root: ${requested}`,
+        `实际使用: ${resolved}`,
+        "请传绝对路径（Windows 建议 E:/project 或 E:\\\\project），或从目标项目目录打开 MCP 客户端以自动识别工作区。",
+    ].join(" ");
+}
+function resolveAutoWorkspaceRoot(packageRoot) {
+    const fromWorkspaceEnv = resolveFromWorkspaceFolderPathsEnv();
+    if (fromWorkspaceEnv) {
+        const root = resolveTrustedClientWorkspace(fromWorkspaceEnv, packageRoot);
+        return {
+            root,
+            source: "workspace-env",
+            explicitHonored: false,
+        };
     }
-    const packageRoot = getRuntimePackageRoot();
-    const cwd = safeResolve(process.cwd()) || packageRoot;
-    const fromLayout = discoverProjectRootFromLayout(cwd);
-    if (fromLayout) {
-        return fromLayout;
+    const cwd = safeResolve(process.cwd());
+    if (isExistingDirectory(cwd) && cwd !== packageRoot) {
+        if (looksLikeWorkspaceRoot(cwd)) {
+            return { root: cwd, source: "cwd", explicitHonored: false };
+        }
+        const fromCwdAncestor = findWorkspaceAncestor(cwd, packageRoot);
+        if (fromCwdAncestor) {
+            return { root: fromCwdAncestor, source: "cwd", explicitHonored: false };
+        }
     }
-    for (const key of WORKSPACE_ENV_KEYS) {
-        const candidate = safeResolve(process.env[key] || "");
-        const resolved = findWorkspaceAncestor(candidate, packageRoot);
-        if (resolved) {
-            return resolved;
+    const fromRuntimeCwd = resolveFromEnvKeys(RUNTIME_CWD_ENV_KEYS, packageRoot);
+    if (fromRuntimeCwd) {
+        return { root: fromRuntimeCwd, source: "env", explicitHonored: false };
+    }
+    const fromOverride = resolveFromEnvKeys(OPTIONAL_OVERRIDE_ENV_KEYS, packageRoot);
+    if (fromOverride) {
+        return { root: fromOverride, source: "env", explicitHonored: false };
+    }
+    if (isExistingDirectory(cwd)) {
+        const fromLayout = discoverProjectRootFromLayout(cwd);
+        if (fromLayout) {
+            return { root: fromLayout, source: "layout", explicitHonored: false };
         }
     }
-    const cwdWorkspace = findWorkspaceAncestor(cwd, packageRoot);
-    if (cwdWorkspace) {
-        return cwdWorkspace;
+    return {
+        root: packageRoot,
+        source: "package-fallback",
+        explicitHonored: false,
+        warning: buildPackageFallbackWarning(packageRoot),
+    };
+}
+/**
+ * 解析项目根目录。
+ * 若调用方显式传入 project_root（非空），优先信任该路径，不再向上游走 layout 到父目录。
+ */
+export function resolveWorkspaceRootWithMeta(explicitProjectRoot) {
+    const explicitRaw = (explicitProjectRoot || "").trim();
+    const explicit = safeResolve(explicitRaw);
+    const packageRoot = getRuntimePackageRoot();
+    if (explicitRaw) {
+        if (isExistingDirectory(explicit)) {
+            return {
+                root: explicit,
+                source: "explicit",
+                explicitRequested: explicitRaw,
+                explicitHonored: true,
+            };
+        }
+        const userMeantAbsolute = path.isAbsolute(explicitRaw) ||
+            /^[a-zA-Z]:[\\/]/.test(explicitRaw) ||
+            explicitRaw.startsWith("/") ||
+            explicitRaw.startsWith("\\\\");
+        if (explicit && userMeantAbsolute) {
+            return {
+                root: explicit,
+                source: "explicit-not-yet-created",
+                explicitRequested: explicitRaw,
+                explicitHonored: true,
+                warning: `project_root 目录尚不存在，将按该路径创建 Skill/AGENTS.md: ${explicit}`,
+            };
+        }
+        const fallback = resolveAutoWorkspaceRoot(packageRoot);
+        return {
+            root: fallback.root,
+            source: fallback.source,
+            explicitRequested: explicitRaw,
+            explicitHonored: false,
+            warning: buildExplicitIgnoredWarning(explicitRaw, fallback.root),
+        };
     }
-    return packageRoot;
+    return resolveAutoWorkspaceRoot(packageRoot);
+}
+export function resolveWorkspaceRoot(explicitProjectRoot) {
+    return resolveWorkspaceRootWithMeta(explicitProjectRoot).root;
 }
 export function toWorkspacePath(explicitProjectRoot) {
     return resolveWorkspaceRoot(explicitProjectRoot).replace(/\\/g, "/");

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: "可选。项目根目录绝对路径；未传时自动从 MCP 客户端工作区解析（如 Cursor 注入 WORKSPACE_FOLDER_PATHS、OpenCode/客户端配置的 cwd 等）。仅边缘场景需手动传入。";
+            };
         };
         readonly required: readonly [];
         readonly additionalProperties: true;

package/build/schemas/basic-tools.js

@@ -1,6 +1,7 @@
 /**
  * 基础工具的 Schema 定义
  */
+import { PROJECT_ROOT_SCHEMA_DESCRIPTION } from "../lib/workspace-root.js";
 export const basicToolSchemas = [
     {
         name: "init_project",
@@ -16,6 +17,10 @@ export const basicToolSchemas = [
                     type: "string",
                     description: "项目名称。可选，默认为'新项目'",
                 },
+                project_root: {
+                    type: "string",
+                    description: PROJECT_ROOT_SCHEMA_DESCRIPTION,
+                },
             },
             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: "可选。项目根目录绝对路径；未传时自动从 MCP 客户端工作区解析（如 Cursor 注入 WORKSPACE_FOLDER_PATHS、OpenCode/客户端配置的 cwd 等）。仅边缘场景需手动传入。";
+            };
         };
         readonly required: readonly [];
         readonly additionalProperties: true;
@@ -316,7 +320,7 @@ export declare const allToolSchemas: ({
             };
             readonly project_root: {
                 readonly type: "string";
-                readonly description: "项目根目录绝对路径。可选，默认自动探测工作区根";
+                readonly description: "可选。项目根目录绝对路径；未传时自动从 MCP 客户端工作区解析（如 Cursor 注入 WORKSPACE_FOLDER_PATHS、OpenCode/客户端配置的 cwd 等）。仅边缘场景需手动传入。";
             };
         };
         readonly required: readonly [];

package/build/schemas/output/project-tools.d.ts

@@ -15,6 +15,46 @@ export declare const ProjectInitSchema: {
         readonly projectName: {
             readonly type: "string";
         };
+        readonly projectRoot: {
+            readonly type: "string";
+            readonly description: "解析后的项目根目录（POSIX）";
+        };
+        readonly bootstrap: {
+            readonly type: "object";
+            readonly description: "MCP Skill / AGENTS.md 自动安装结果";
+            readonly properties: {
+                readonly skillPath: {
+                    readonly type: "string";
+                };
+                readonly agentsMdPath: {
+                    readonly type: "string";
+                };
+                readonly skillCreated: {
+                    readonly type: "boolean";
+                };
+                readonly skillUpdated: {
+                    readonly type: "boolean";
+                };
+                readonly agentsCreated: {
+                    readonly type: "boolean";
+                };
+                readonly agentsUpdated: {
+                    readonly type: "boolean";
+                };
+                readonly workspaceWarnings: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                };
+                readonly rootSource: {
+                    readonly type: "string";
+                };
+                readonly explicitHonored: {
+                    readonly type: "boolean";
+                };
+            };
+        };
         readonly structure: {
             readonly type: "object";
             readonly description: "项目结构";
@@ -404,6 +444,18 @@ export declare const ConflictResolutionSchema: {
 export interface ProjectInit {
     summary: string;
     projectName: string;
+    projectRoot?: string;
+    bootstrap?: {
+        skillPath: string;
+        agentsMdPath: string;
+        skillCreated: boolean;
+        skillUpdated: boolean;
+        agentsCreated: boolean;
+        agentsUpdated: boolean;
+        workspaceWarnings: string[];
+        rootSource: string;
+        explicitHonored: boolean;
+    };
     structure: {
         directories?: string[];
         files?: string[];

package/build/schemas/output/project-tools.js

@@ -11,6 +11,22 @@ export const ProjectInitSchema = {
     properties: {
         summary: { type: 'string' },
         projectName: { type: 'string' },
+        projectRoot: { type: 'string', description: '解析后的项目根目录（POSIX）' },
+        bootstrap: {
+            type: 'object',
+            description: 'MCP Skill / AGENTS.md 自动安装结果',
+            properties: {
+                skillPath: { type: 'string' },
+                agentsMdPath: { type: 'string' },
+                skillCreated: { type: 'boolean' },
+                skillUpdated: { type: 'boolean' },
+                agentsCreated: { type: 'boolean' },
+                agentsUpdated: { type: 'boolean' },
+                workspaceWarnings: { type: 'array', items: { type: 'string' } },
+                rootSource: { type: 'string' },
+                explicitHonored: { type: 'boolean' },
+            },
+        },
         structure: {
             type: 'object',
             description: '项目结构',

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

@@ -124,7 +124,7 @@ export declare const projectToolSchemas: readonly [{
             };
             readonly project_root: {
                 readonly type: "string";
-                readonly description: "项目根目录绝对路径。可选，默认自动探测工作区根";
+                readonly description: "可选。项目根目录绝对路径；未传时自动从 MCP 客户端工作区解析（如 Cursor 注入 WORKSPACE_FOLDER_PATHS、OpenCode/客户端配置的 cwd 等）。仅边缘场景需手动传入。";
             };
         };
         readonly required: readonly [];

package/build/schemas/project-tools.js

@@ -1,6 +1,7 @@
 /**
  * 项目管理工具的 Schema 定义
  */
+import { PROJECT_ROOT_SCHEMA_DESCRIPTION } from "../lib/workspace-root.js";
 export const projectToolSchemas = [
     {
         name: "workflow",
@@ -129,7 +130,7 @@ export const projectToolSchemas = [
                 },
                 project_root: {
                     type: "string",
-                    description: "项目根目录绝对路径。可选，默认自动探测工作区根",
+                    description: PROJECT_ROOT_SCHEMA_DESCRIPTION,
                 },
             },
             required: [],