mcp-probe-kit 3.1.0 → 3.3.0

package/build/schemas/index.d.ts

@@ -281,6 +281,28 @@ export declare const allToolSchemas: ({
         readonly required: readonly [];
         readonly additionalProperties: true;
     };
+} | {
+    readonly name: "check_spec";
+    readonly description: "校验已落盘的功能规格（docs/specs/<feature_name>/requirements|design|tasks.md）是否完整：检测残留 [填写] 占位、缺失章节、缺 FR/验收标准、FR 未进覆盖矩阵。写完规格后、进入实现前调用；未通过按报告补全后重跑。";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly feature_name: {
+                readonly type: "string";
+                readonly description: "要校验的规格目录名，对应 docs/specs/<feature_name>/";
+            };
+            readonly docs_dir: {
+                readonly type: "string";
+                readonly description: "文档根目录，默认为 docs";
+            };
+            readonly project_root: {
+                readonly type: "string";
+                readonly description: "项目根目录绝对路径。可选，默认自动探测工作区根";
+            };
+        };
+        readonly required: readonly [];
+        readonly additionalProperties: true;
+    };
 } | {
     readonly name: "start_feature";
     readonly description: "当用户需要完整的新功能开发流程时使用。编排：检查上下文→生成规格→估算工作量。若只需规格文档请用 add_feature";

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

@@ -89,4 +89,26 @@ export declare const projectToolSchemas: readonly [{
         readonly required: readonly [];
         readonly additionalProperties: true;
     };
+}, {
+    readonly name: "check_spec";
+    readonly description: "校验已落盘的功能规格（docs/specs/<feature_name>/requirements|design|tasks.md）是否完整：检测残留 [填写] 占位、缺失章节、缺 FR/验收标准、FR 未进覆盖矩阵。写完规格后、进入实现前调用；未通过按报告补全后重跑。";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly feature_name: {
+                readonly type: "string";
+                readonly description: "要校验的规格目录名，对应 docs/specs/<feature_name>/";
+            };
+            readonly docs_dir: {
+                readonly type: "string";
+                readonly description: "文档根目录，默认为 docs";
+            };
+            readonly project_root: {
+                readonly type: "string";
+                readonly description: "项目根目录绝对路径。可选，默认自动探测工作区根";
+            };
+        };
+        readonly required: readonly [];
+        readonly additionalProperties: true;
+    };
 }];

package/build/schemas/project-tools.js

@@ -93,4 +93,27 @@ export const projectToolSchemas = [
             additionalProperties: true,
         },
     },
+    {
+        name: "check_spec",
+        description: "校验已落盘的功能规格（docs/specs/<feature_name>/requirements|design|tasks.md）是否完整：检测残留 [填写] 占位、缺失章节、缺 FR/验收标准、FR 未进覆盖矩阵。写完规格后、进入实现前调用；未通过按报告补全后重跑。",
+        inputSchema: {
+            type: "object",
+            properties: {
+                feature_name: {
+                    type: "string",
+                    description: "要校验的规格目录名，对应 docs/specs/<feature_name>/",
+                },
+                docs_dir: {
+                    type: "string",
+                    description: "文档根目录，默认为 docs",
+                },
+                project_root: {
+                    type: "string",
+                    description: "项目根目录绝对路径。可选，默认自动探测工作区根",
+                },
+            },
+            required: [],
+            additionalProperties: true,
+        },
+    },
 ];

package/build/tools/__tests__/cursor-history.unit.test.d.ts

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

package/build/tools/__tests__/cursor-history.unit.test.js

@@ -0,0 +1,38 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+const readConversationMock = vi.fn();
+vi.mock('../../lib/cursor-history-client.js', () => ({
+    createCursorHistoryClient: () => ({
+        readConversation: readConversationMock,
+    }),
+}));
+import { cursorReadConversation } from '../cursor_read_conversation.js';
+beforeEach(() => {
+    readConversationMock.mockReset();
+});
+afterEach(() => {
+    vi.clearAllMocks();
+});
+describe('cursor history tools', () => {
+    test('cursor_read_conversation 返回消息时间线', async () => {
+        readConversationMock.mockResolvedValue({
+            composerId: 'c1',
+            messages: [
+                { bubbleId: 'b1', type: 1, text: '我们先聊需求' },
+                { bubbleId: 'b2', type: 2, text: '听懂了' },
+            ],
+        });
+        const result = await cursorReadConversation({ composer_id: 'c1', limit: 50, include_empty: true });
+        expect(result.isError).toBe(false);
+        expect('structuredContent' in result).toBe(true);
+        if (!('structuredContent' in result)) {
+            throw new Error('structuredContent 缺失');
+        }
+        expect(result.content[0].text).toContain('共 2 条消息');
+        expect(result.structuredContent.messageCount).toBe(2);
+        expect(readConversationMock).toHaveBeenCalledWith({
+            composerId: 'c1',
+            limit: 50,
+            includeEmpty: true,
+        });
+    });
+});

package/build/tools/check_spec.d.ts

@@ -0,0 +1,7 @@
+export declare function checkSpec(args: any): Promise<import("../lib/response.js").ToolResponse | {
+    content: Array<{
+        type: string;
+        text: string;
+    }>;
+    isError: true;
+}>;

package/build/tools/check_spec.js

@@ -0,0 +1,81 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { parseArgs, getString } from '../utils/parseArgs.js';
+import { okStructured } from '../lib/response.js';
+import { handleToolError } from '../utils/error-handler.js';
+import { resolveWorkspaceRoot } from '../lib/workspace-root.js';
+import { validateSpecDocuments } from '../lib/spec-validator.js';
+/**
+ * check_spec 工具（P1「填写后校验」闸门）
+ *
+ * 读取 docs/specs/{feature_name}/{requirements,design,tasks}.md，
+ * 机械校验完整性。未通过则列出逐条待修项并要求补全后重跑，通过前不应进入实现。
+ */
+const DEFAULT_DOCS_DIR = 'docs';
+function readIfExists(filePath) {
+    try {
+        return fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf-8') : null;
+    }
+    catch {
+        return null;
+    }
+}
+function formatIssue(issue) {
+    const tag = issue.severity === 'error' ? '必须修复' : '提醒';
+    return `- [${tag}] (${issue.file}) ${issue.message}`;
+}
+export async function checkSpec(args) {
+    try {
+        const parsed = parseArgs(args, {
+            defaultValues: {
+                feature_name: '',
+                docs_dir: DEFAULT_DOCS_DIR,
+            },
+            primaryField: 'feature_name',
+            fieldAliases: {
+                feature_name: ['name', 'feature', 'spec', '功能名', '功能名称', '规格'],
+                docs_dir: ['dir', 'output', '目录', '文档目录'],
+                project_root: ['projectRoot', 'project_path', 'projectPath', 'root', '项目路径', '项目根目录'],
+            },
+        });
+        const featureName = getString(parsed.feature_name);
+        const docsDir = getString(parsed.docs_dir) || DEFAULT_DOCS_DIR;
+        const projectRoot = resolveWorkspaceRoot(getString(parsed.project_root));
+        if (!featureName) {
+            throw new Error('请提供 feature_name（要校验的规格目录名，对应 docs/specs/<feature_name>/）');
+        }
+        const specDir = path.join(projectRoot, docsDir, 'specs', featureName);
+        const report = validateSpecDocuments({
+            requirements: readIfExists(path.join(specDir, 'requirements.md')),
+            design: readIfExists(path.join(specDir, 'design.md')),
+            tasks: readIfExists(path.join(specDir, 'tasks.md')),
+        });
+        const relDir = `${docsDir}/specs/${featureName}`;
+        const issueLines = report.issues.length > 0
+            ? report.issues.map(formatIssue).join('\n')
+            : '- 无';
+        const text = report.passed
+            ? `# ✅ 规格校验通过：${featureName}
+
+${report.summary}
+
+**需求清单**: ${report.frIds.join(', ') || '（未发现 FR）'}
+${report.warningCount > 0 ? `\n仍有 ${report.warningCount} 个提醒（非阻塞，建议处理）：\n${issueLines}\n` : ''}
+**下一步**: 规格已具备可实现性，可进入实现/估算阶段。`
+            : `# ❌ 规格校验未通过：${featureName}
+
+${report.summary}
+
+## 待修复（${relDir}）
+${issueLines}
+
+## 处理方式
+1. 按上述每一条补全 \`${relDir}/\` 下的 requirements.md / design.md / tasks.md
+2. **重新运行** \`check_spec\`（同样的 feature_name）直到通过
+3. **校验通过前不要开始写实现代码** —— 这是为了确保需求被完整实现，而不是写到一半才发现规格有缺口`;
+        return okStructured(text, report);
+    }
+    catch (error) {
+        return handleToolError(error, 'check_spec');
+    }
+}

package/build/tools/code_insight.js

@@ -136,10 +136,10 @@ function createProjectDocsPlan(layout, docsSnapshot) {
         latestJsonFilePath: layout.latestJsonPath,
         archiveMarkdownFilePath: docsSnapshot.markdownFilePath,
         archiveJsonFilePath: docsSnapshot.jsonFilePath,
-        navigationSnippet: `### [代码图谱洞察](./graph-insights/latest.md)
-最近一次 code_insight 分析结果，包含调用链、上下文与影响面摘要
+        navigationSnippet: `### [代码图谱洞察](./graph-insights/latest.md)
+最近一次 code_insight 分析结果，包含调用链、上下文与影响面摘要
 `,
-        devGuideSnippet: `- **代码图谱洞察**: [graph-insights/latest.md](./graph-insights/latest.md) - 需要理解模块依赖、调用链和影响面时优先查看
+        devGuideSnippet: `- **代码图谱洞察**: [graph-insights/latest.md](./graph-insights/latest.md) - 需要理解模块依赖、调用链和影响面时优先查看
 `,
     };
 }
@@ -187,15 +187,15 @@ export function buildCodeInsightDelegatedPlan(input) {
     };
 }
 function renderUsageGuide() {
-    return `## 使用场景指南
-- 探索调用链: \`{ mode: "query", query: "login", goal: "理解登录认证流程" }\`
-- 深入函数上下文: \`{ mode: "context", target: "login", file_path: "src/auth/login.ts" }\`
-- 评估影响范围: \`{ mode: "impact", target: "login", direction: "upstream", file_path: "..." }\`
-- 查看代码内容: \`{ mode: "context", target: "login", include_content: true }\`
-
-## 下一步建议
-- 查询不精确: 增加 \`goal\`（例如“理解登录认证流程”）
-- 出现歧义: 传入 \`uid\` 或 \`file_path\` 重新执行
+    return `## 使用场景指南
+- 探索调用链: \`{ mode: "query", query: "login", goal: "理解登录认证流程" }\`
+- 深入函数上下文: \`{ mode: "context", target: "login", file_path: "src/auth/login.ts" }\`
+- 评估影响范围: \`{ mode: "impact", target: "login", direction: "upstream", file_path: "..." }\`
+- 查看代码内容: \`{ mode: "context", target: "login", include_content: true }\`
+
+## 下一步建议
+- 查询不精确: 增加 \`goal\`（例如“理解登录认证流程”）
+- 出现歧义: 传入 \`uid\` 或 \`file_path\` 重新执行
 - 需要落盘: 传 \`save_to_docs: true\`，再按 delegated plan 写入 docs/graph-insights`;
 }
 export function resolveCodeInsightQuery(input) {
@@ -307,22 +307,22 @@ export async function codeInsight(args, context) {
             status: item.status,
         })));
         const ambiguityText = formatAmbiguities(result.ambiguities);
-        const message = `# code_insight 图谱分析结果
-
-状态: ${formatStatusLabel(status)}
-模式: ${result.modeRequested} -> ${result.modeResolved}
-来源: ${result.provider}
-启动策略: ${result.launcherStrategy}
-工作区: ${result.workspaceMode}
-源目录: ${result.sourceRoot}
-
-摘要:
-${result.summary}
-
-执行详情:
-${executionSummary}
-
-${ambiguityText ? `歧义候选:\n${ambiguityText}\n\n` : ""}\
+        const message = `# code_insight 图谱分析结果
+
+状态: ${formatStatusLabel(status)}
+模式: ${result.modeRequested} -> ${result.modeResolved}
+来源: ${result.provider}
+启动策略: ${result.launcherStrategy}
+工作区: ${result.workspaceMode}
+源目录: ${result.sourceRoot}
+
+摘要:
+${result.summary}
+
+执行详情:
+${executionSummary}
+
+${ambiguityText ? `歧义候选:\n${ambiguityText}\n\n` : ""}\
 ${result.warnings.length > 0 ? `警告: ${result.warnings.join(", ")}` : ""}`.trim();
         const usageGuide = renderUsageGuide();
         const structured = {
@@ -391,20 +391,20 @@ ${result.warnings.length > 0 ? `警告: ${result.warnings.join(", ")}` : ""}`.tr
                     `工作区模式: ${result.workspaceMode}`,
                     `来源目录: ${result.sourceRoot}`,
                 ],
-            })}${message}
-
-## delegated plan
-${renderPlanSteps(delegatedPlan.steps)}
-
-${delegatedPlan.kind === "docs" && projectDocs ? `后续操作:
-- 如需落盘，写入 ${projectDocs.latestMarkdownFilePath} 与 ${projectDocs.latestJsonFilePath}
-- 如需长期沉淀，可再补充 ${projectDocs.projectContextFilePath} 的图谱入口` : `后续操作:
-- 请先从 candidates 中选定唯一符号
-- 重新传入 uid 或 file_path 后再继续 context / impact 分析`}
-
+            })}${message}
+
+## delegated plan
+${renderPlanSteps(delegatedPlan.steps)}
+
+${delegatedPlan.kind === "docs" && projectDocs ? `后续操作:
+- 如需落盘，写入 ${projectDocs.latestMarkdownFilePath} 与 ${projectDocs.latestJsonFilePath}
+- 如需长期沉淀，可再补充 ${projectDocs.projectContextFilePath} 的图谱入口` : `后续操作:
+- 请先从 candidates 中选定唯一符号
+- 重新传入 uid 或 file_path 后再继续 context / impact 分析`}
+
 ${usageGuide}`
-            : `${message}
-
+            : `${message}
+
 ${usageGuide}`, structured);
     }
     catch (error) {

package/build/tools/code_review.js

@@ -2,6 +2,7 @@ import { parseArgs, getString } from "../utils/parseArgs.js";
 import { okText } from "../lib/response.js";
 import { renderGuidanceHeader } from "../lib/guidance.js";
 import { handleToolError } from "../utils/error-handler.js";
+import { renderCodeLimits, renderBannedPatterns, CODE_LIMITS } from "../lib/quality-constraints.js";
 // code_review 工具实现
 export async function codeReview(args) {
     try {
@@ -38,11 +39,13 @@ ${code || "请提供需要审查的代码"}
 
 ### 1️⃣ 代码质量检查
 
+${renderCodeLimits()}
+
 **代码坏味道（Code Smells）**：
 - [ ] 重复代码（Duplicated Code）
-- [ ] 过长函数（Long Function）> 30 行
-- [ ] 过长参数列表（Long Parameter List）> 3 个
-- [ ] 复杂条件判断（Complex Conditional）> 3 层嵌套
+- [ ] 过长函数（Long Function）> ${CODE_LIMITS.maxFunctionLines} 行
+- [ ] 过长参数列表（Long Parameter List）> ${CODE_LIMITS.maxParameters} 个
+- [ ] 复杂条件判断（Complex Conditional）> ${CODE_LIMITS.maxNestingDepth} 层嵌套
 - [ ] 魔法数字（Magic Numbers）
 - [ ] 命名不清晰（Poor Naming）
 
@@ -88,7 +91,11 @@ ${code || "请提供需要审查的代码"}
 - [ ] 大列表未虚拟化
 - [ ] 状态管理不当
 
-### 4️⃣ 最佳实践检查
+### 4️⃣ 完整性检查
+
+${renderBannedPatterns()}
+
+### 5️⃣ 最佳实践检查
 
 **TypeScript/JavaScript**：
 - [ ] 类型定义完整（避免 any）

package/build/tools/cursor_read_conversation.d.ts

@@ -0,0 +1,7 @@
+export declare function cursorReadConversation(args: any): Promise<import("../lib/response.js").ToolResponse | {
+    content: Array<{
+        type: string;
+        text: string;
+    }>;
+    isError: true;
+}>;

package/build/tools/cursor_read_conversation.js

@@ -0,0 +1,36 @@
+import { parseArgs, getString, getNumber, getBoolean } from '../utils/parseArgs.js';
+import { okStructured } from '../lib/response.js';
+import { handleToolError } from '../utils/error-handler.js';
+import { createCursorHistoryClient } from '../lib/cursor-history-client.js';
+export async function cursorReadConversation(args) {
+    try {
+        const parsed = parseArgs(args, {
+            defaultValues: {
+                composer_id: '',
+                limit: 200,
+                include_empty: false,
+            },
+            fieldAliases: {
+                composer_id: ['conversation_id', 'chat_id'],
+            },
+        });
+        const composerId = getString(parsed.composer_id).trim();
+        if (!composerId) {
+            throw new Error('缺少必填参数: composer_id');
+        }
+        const client = createCursorHistoryClient();
+        const conversation = await client.readConversation({
+            composerId,
+            limit: getNumber(parsed.limit, 200),
+            includeEmpty: getBoolean(parsed.include_empty, false),
+        });
+        return okStructured(`已读取 Cursor 会话 ${composerId}，共 ${conversation.messages.length} 条消息。`, {
+            composerId,
+            messageCount: conversation.messages.length,
+            conversation,
+        });
+    }
+    catch (error) {
+        return handleToolError(error, 'cursor_read_conversation');
+    }
+}