mcp-probe-kit 3.6.1 → 3.6.3

package/build/lib/workspace-root.js

@@ -2,15 +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 = [
-    "WORKSPACE_FOLDER_PATHS",
+/** 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",
@@ -23,6 +31,10 @@ const WORKSPACE_MARKERS = [
     "go.mod",
     "pyproject.toml",
     "requirements.txt",
+    "opencode.json",
+    ".opencode",
+    "AGENTS.md",
+    ".agents",
     ".cursor",
     ".vscode",
     ".kiro",
@@ -81,7 +93,7 @@ function getRuntimePackageRoot() {
 export function getMcpPackageInstallRoot() {
     return getRuntimePackageRoot();
 }
-/** 解析 Cursor 等客户端注入的 WORKSPACE_FOLDER_PATHS */
+/** 解析 MCP 客户端注入的 WORKSPACE_FOLDER_PATHS（如 Cursor） */
 export function resolveFromWorkspaceFolderPathsEnv() {
     const raw = process.env.WORKSPACE_FOLDER_PATHS?.trim();
     if (!raw) {
@@ -114,7 +126,9 @@ function findWorkspaceAncestor(start, packageRoot) {
     }
     let current = start;
     while (true) {
-        if (current !== packageRoot && looksLikeWorkspaceRoot(current)) {
+        if (current !== packageRoot &&
+            !isFilesystemRoot(current) &&
+            looksLikeWorkspaceRoot(current)) {
             return current;
         }
         const parent = path.dirname(current);
@@ -124,6 +138,50 @@ 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 isFilesystemRoot(target) {
+    const normalized = path.resolve(target);
+    return normalized === path.parse(normalized).root;
+}
+function isUsableWorkspaceCandidate(target, packageRoot) {
+    if (!isExistingDirectory(target)) {
+        return false;
+    }
+    if (target === packageRoot || isFilesystemRoot(target)) {
+        return false;
+    }
+    return true;
+}
+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 (isUsableWorkspaceCandidate(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;
@@ -158,33 +216,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 fromCursorWorkspace = resolveFromWorkspaceFolderPathsEnv();
-    if (fromCursorWorkspace) {
-        return discoverProjectRootFromLayout(fromCursorWorkspace) ?? fromCursorWorkspace;
+    const cwd = safeResolve(process.cwd());
+    if (isUsableWorkspaceCandidate(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 };
+        }
     }
-    const packageRoot = getRuntimePackageRoot();
-    const cwd = safeResolve(process.cwd()) || packageRoot;
-    const fromLayout = discoverProjectRootFromLayout(cwd);
-    if (fromLayout) {
-        return fromLayout;
+    const fromRuntimeCwd = resolveFromEnvKeys(RUNTIME_CWD_ENV_KEYS, packageRoot);
+    if (fromRuntimeCwd) {
+        return { root: fromRuntimeCwd, source: "env", 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 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

@@ -17,7 +17,7 @@ export declare const basicToolSchemas: readonly [{
             };
             readonly project_root: {
                 readonly type: "string";
-                readonly description: "项目根目录绝对路径。用于 Skill/AGENTS.md 自动安装；未传则解析 Cursor 工作区";
+                readonly description: "可选。项目根目录绝对路径；未传时自动从 MCP 客户端工作区解析（如 Cursor 注入 WORKSPACE_FOLDER_PATHS、OpenCode/客户端配置的 cwd 等）。仅边缘场景需手动传入。";
             };
         };
         readonly required: readonly [];

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",
@@ -18,7 +19,7 @@ export const basicToolSchemas = [
                 },
                 project_root: {
                     type: "string",
-                    description: "项目根目录绝对路径。用于 Skill/AGENTS.md 自动安装；未传则解析 Cursor 工作区",
+                    description: PROJECT_ROOT_SCHEMA_DESCRIPTION,
                 },
             },
             required: [],

package/build/schemas/index.d.ts

@@ -17,7 +17,7 @@ export declare const allToolSchemas: ({
             };
             readonly project_root: {
                 readonly type: "string";
-                readonly description: "项目根目录绝对路径。用于 Skill/AGENTS.md 自动安装；未传则解析 Cursor 工作区";
+                readonly description: "可选。项目根目录绝对路径；未传时自动从 MCP 客户端工作区解析（如 Cursor 注入 WORKSPACE_FOLDER_PATHS、OpenCode/客户端配置的 cwd 等）。仅边缘场景需手动传入。";
             };
         };
         readonly required: readonly [];
@@ -320,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: [],

package/build/tools/init_project.js

@@ -2,7 +2,8 @@ import { parseArgs, getString } from "../utils/parseArgs.js";
 import { okStructured } from "../lib/response.js";
 import { ensureMcpProbeKitBootstrap } from "../lib/workflow-skill-installer.js";
 import { MCP_PROBE_SKILL_REL_PATH } from "../lib/workflow-skill-template.js";
-import { resolveWorkspaceRoot } from "../lib/workspace-root.js";
+import { resolveWorkspaceRootWithMeta } from "../lib/workspace-root.js";
+import { toPosixPath } from "../lib/project-context-layout.js";
 /**
  * init_project 工具
  *
@@ -22,31 +23,45 @@ export async function initProject(args) {
             fieldAliases: {
                 input: ["requirement", "description", "需求", "项目需求"],
                 project_name: ["name", "project", "项目名", "项目名称"],
-                project_root: ["root", "path", "项目路径"],
+                project_root: ["root", "path", "项目路径", "projectRoot", "projectPath", "workspace"],
             },
         });
         const input = getString(parsedArgs.input);
         const projectName = getString(parsedArgs.project_name) || "新项目";
-        const projectRoot = resolveWorkspaceRoot(getString(parsedArgs.project_root));
+        const rootResolution = resolveWorkspaceRootWithMeta(getString(parsedArgs.project_root));
+        const projectRoot = rootResolution.root;
         const bootstrap = ensureMcpProbeKitBootstrap(projectRoot);
+        const pathWarnings = [rootResolution.warning, bootstrap.workspaceWarning].filter((item) => Boolean(item));
+        const warningBlock = pathWarnings.length
+            ? `\n⚠️ **路径 / 工作区**\n${pathWarnings.map((w) => `- ${w}`).join("\n")}\n`
+            : "";
         const featureSlug = projectName.toLowerCase().replace(/\s+/g, '-');
+        const agentsRel = toPosixPath(bootstrap.agentsMd.path);
         const message = `你需要按照 Spec-Driven Development（规范驱动开发）的方式初始化项目，参考 https://github.com/github/spec-kit 的工作流程。
 
 📋 **项目需求**：
 ${input}
-
-📌 **MCP Skill 已同步**（项目根: \`${projectRoot}\`）：
+${warningBlock}
+📌 **MCP 已自动同步（必须先落盘）**（项目根: \`${toPosixPath(projectRoot)}\`）：
 - \`${MCP_PROBE_SKILL_REL_PATH}\`${bootstrap.skill.created ? "（已创建）" : bootstrap.skill.updated ? "（已升级）" : "（已是最新）"}
-- \`${bootstrap.agentsMd.path}\`${bootstrap.agentsMd.created ? "（已创建）" : bootstrap.agentsMd.updated ? "（已更新）" : ""}
-${bootstrap.workspaceWarning ? `\n⚠️ ${bootstrap.workspaceWarning}\n` : ""}
+- \`${agentsRel}\`${bootstrap.agentsMd.created ? "（已创建）" : bootstrap.agentsMd.updated ? "（已更新）" : ""}
 
 🎯 **初始化步骤**：
 
+**第零步：确认 MCP 产物（已完成服务端写入，Agent 勿跳过）**
+- Skill 与 AGENTS.md 已由 mcp-probe-kit 写入上述路径
+- 若未看到文件，确认已从目标项目目录打开 MCP 客户端，或在工具参数中传 \`project_root\` 绝对路径
+
 **第一步：创建项目基础结构**
 在当前工作区创建以下目录和文件：
 
 \`\`\`
 .
+├── .agents/
+│   └── skills/
+│       └── mcp-probe-kit/
+│           └── SKILL.md             # MCP 调用时机（已自动创建）
+├── AGENTS.md                        # Agent 规则（已自动创建/更新）
 ├── docs/
 │   ├── project-context.md           # 项目上下文（技术栈、架构、规范）
 │   ├── constitution.md              # 项目宪法（核心原则和约束）
@@ -198,8 +213,21 @@ ${bootstrap.workspaceWarning ? `\n⚠️ ${bootstrap.workspaceWarning}\n` : ""}
         const structuredData = {
             summary: `初始化项目：${projectName}`,
             projectName: projectName,
+            projectRoot: toPosixPath(projectRoot),
+            bootstrap: {
+                skillPath: MCP_PROBE_SKILL_REL_PATH,
+                agentsMdPath: agentsRel,
+                skillCreated: bootstrap.skill.created,
+                skillUpdated: bootstrap.skill.updated,
+                agentsCreated: bootstrap.agentsMd.created,
+                agentsUpdated: bootstrap.agentsMd.updated,
+                workspaceWarnings: pathWarnings,
+                rootSource: rootResolution.source,
+                explicitHonored: rootResolution.explicitHonored,
+            },
             structure: {
                 directories: [
+                    '.agents/skills/mcp-probe-kit/',
                     'docs/',
                     'docs/specs/',
                     `docs/specs/${featureSlug}/`,
@@ -207,6 +235,8 @@ ${bootstrap.workspaceWarning ? `\n⚠️ ${bootstrap.workspaceWarning}\n` : ""}
                     'src/'
                 ],
                 files: [
+                    MCP_PROBE_SKILL_REL_PATH,
+                    agentsRel,
                     'docs/project-context.md',
                     'docs/constitution.md',
                     `docs/specs/${featureSlug}/requirements.md`,
@@ -218,6 +248,7 @@ ${bootstrap.workspaceWarning ? `\n⚠️ ${bootstrap.workspaceWarning}\n` : ""}
                 ]
             },
             nextSteps: [
+                '确认 .agents/skills/mcp-probe-kit/SKILL.md 与 AGENTS.md 已落盘',
                 '创建项目目录结构',
                 '生成 project-context.md',
                 '生成 constitution.md',

package/build/tools/scan_and_extract_patterns.js

@@ -306,7 +306,7 @@ export async function scanAndExtractPatterns(args) {
         const { resolvedPath: targetDir, attemptedRoots } = resolveTargetDirectory(projectRoot, directoryPath);
         if (!fs.existsSync(targetDir) || !fs.statSync(targetDir).isDirectory()) {
             const attempted = attemptedRoots.map((root) => path.resolve(root, directoryPath).replace(/\\/g, '/'));
-            return okStructured(`目录不存在或不可访问: ${targetDir.replace(/\\/g, '/')}。相对路径解析依赖工作区根目录；请显式传入 project_root，或让客户端传递 MCP_PROJECT_ROOT。`, {
+            return okStructured(`目录不存在或不可访问: ${targetDir.replace(/\\/g, '/')}。相对路径解析依赖工作区根目录；请显式传入 project_root，或从目标项目目录打开 MCP 客户端以自动识别工作区。`, {
                 mode: 'directory',
                 scannedFiles: 0,
                 patterns: [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-probe-kit",
-  "version": "3.6.1",
+  "version": "3.6.3",
   "description": "AI-Powered Development Toolkit - MCP Server with 30 tools covering code quality, development efficiency, project management, and UI/UX design. Features: Structured Output, Workflow Orchestration, MCP Skill auto-sync, UI/UX Pro Max, and Requirements Interview.",
   "mcpName": "io.github.mybolide/mcp-probe-kit",
   "type": "module",