mcp-probe-kit 1.4.0 → 1.7.0

package/build/tools/init_project.js

@@ -3,6 +3,7 @@ export async function initProject(args) {
     try {
         const input = args?.input || "";
         const projectName = args?.project_name || "新项目";
+        const featureSlug = projectName.toLowerCase().replace(/\s+/g, '-');
         const message = `你需要按照 Spec-Driven Development（规范驱动开发）的方式初始化项目，参考 https://github.com/github/spec-kit 的工作流程。
 
 📋 **项目需求**：
@@ -15,106 +16,150 @@ ${input}
 
 \`\`\`
 .
-├── memory/
-│   └── constitution.md    # 项目宪法（核心原则和约束）
-├── specs/
-│   └── 001-${projectName.toLowerCase().replace(/\s+/g, '-')}/
-│       ├── spec.md        # 功能规格说明
-│       ├── plan.md        # 实现计划
-│       ├── tasks.md       # 任务分解
-│       └── research.md    # 技术调研
+├── docs/
+│   ├── project-context.md           # 项目上下文（技术栈、架构、规范）
+│   ├── constitution.md              # 项目宪法（核心原则和约束）
+│   └── specs/
+│       └── ${featureSlug}/
+│           ├── requirements.md      # 需求文档（EARS 格式）
+│           ├── design.md            # 设计文档
+│           ├── tasks.md             # 任务分解
+│           └── research.md          # 技术调研
 ├── scripts/
 │   ├── check-prerequisites.sh
 │   └── setup.sh
-└── templates/
-    ├── spec-template.md
-    ├── plan-template.md
-    └── tasks-template.md
+└── src/                             # 源代码目录
 \`\`\`
 
-**第二步：生成 constitution.md**
-在 \`memory/constitution.md\` 中定义项目的核心原则，包括：
+**第二步：生成 project-context.md**
+在 \`docs/project-context.md\` 中记录项目的核心信息：
+- 项目概览（名称、版本、类型、描述）
+- 技术栈（语言、框架、构建工具、测试框架）
+- 项目结构（目录说明、入口文件）
+- 架构模式（设计模式、模块划分）
+- 编码规范（代码风格、命名规范）
+- 依赖管理（主要依赖列表）
+- 开发流程（常用命令）
+
+**第三步：生成 constitution.md**
+在 \`docs/constitution.md\` 中定义项目的核心原则：
 - 代码风格规范
 - 架构原则
 - 安全准则
 - 测试要求
 - 文档标准
 
-**第三步：生成 spec.md（功能规格）**
-在 \`specs/001-${projectName.toLowerCase().replace(/\s+/g, '-')}/spec.md\` 中详细描述：
-- 项目背景和目标
-- 用户故事（User Stories）
-- 功能需求
-- 非功能需求
-- 约束条件
-- 验收标准
-
-**第四步：生成 plan.md（实现计划）**
-分析需求并生成实现计划，包括：
-- 技术栈选择（框架、数据库、部署方式等）
-- 系统架构设计
-- 模块划分
-- 数据模型设计
-- API 设计
-- 关键技术决策
-
-**第五步：生成 research.md（技术调研）**
-对选定的技术栈进行调研：
-- 确认版本兼容性
-- 识别潜在风险
-- 记录最佳实践
-- 列出参考文档
-
-**第六步：生成 tasks.md（任务分解）**
-将实现计划分解为可执行的任务，格式如下：
+**第四步：生成 requirements.md（需求文档）**
+在 \`docs/specs/${featureSlug}/requirements.md\` 中详细描述：
+- 功能概述
+- 术语定义
+- 需求列表（使用 EARS 格式）
+  - 用户故事（As a... I want... So that...）
+  - 验收标准（WHEN/WHILE/IF...THEN...SHALL）
+- 非功能需求（性能、安全、兼容性）
+- 依赖关系
+
+**EARS 格式说明**：
+| 模式 | 格式 | 适用场景 |
+|------|------|----------|
+| Ubiquitous | THE [system] SHALL [response] | 始终适用的需求 |
+| Event-driven | WHEN [trigger], THE [system] SHALL [response] | 事件触发的需求 |
+| State-driven | WHILE [condition], THE [system] SHALL [response] | 状态相关的需求 |
+| Unwanted | IF [condition], THEN THE [system] SHALL [response] | 异常处理需求 |
+
+**第五步：生成 design.md（设计文档）**
+在 \`docs/specs/${featureSlug}/design.md\` 中描述：
+- 技术方案（技术选型及理由）
+- 架构设计（系统架构图）
+- 数据模型（数据结构定义）
+- API 设计（接口定义）
+- 文件结构（新增/修改的文件）
+- 设计决策（重要决策及理由）
+- 风险评估
+
+**第六步：生成 research.md（技术调研）**
+在 \`docs/specs/${featureSlug}/research.md\` 中记录：
+- 技术栈调研结果
+- 版本兼容性确认
+- 潜在风险识别
+- 最佳实践记录
+- 参考文档链接
+
+**第七步：生成 tasks.md（任务分解）**
+在 \`docs/specs/${featureSlug}/tasks.md\` 中分解任务：
+
 \`\`\`markdown
-# 任务分解
-
-## 阶段 1：项目初始化
-- [ ] Task 1.1: 搭建项目骨架 (文件: ./setup.sh)
-- [ ] Task 1.2: 配置开发环境 (文件: ./devcontainer.json)
-- [ ] Task 1.3: [P] 初始化数据库 (文件: ./database/schema.sql)
-
-## 阶段 2：核心功能实现
-- [ ] Task 2.1: 实现数据模型 (文件: ./src/models/)
-- [ ] Task 2.2: [P] 实现用户认证 (文件: ./src/auth/)
-- [ ] Task 2.3: [P] 实现业务逻辑 (文件: ./src/services/)
-  依赖: Task 2.1
-
-## 阶段 3：API 开发
-- [ ] Task 3.1: 创建 REST API (文件: ./src/api/)
-  依赖: Task 2.2, Task 2.3
-- [ ] Task 3.2: [P] 编写 API 测试 (文件: ./tests/api/)
-
-## 阶段 4：前端开发
-- [ ] Task 4.1: 搭建前端框架 (文件: ./frontend/)
-- [ ] Task 4.2: [P] 实现 UI 组件 (文件: ./frontend/components/)
-- [ ] Task 4.3: [P] 集成 API (文件: ./frontend/services/)
-  依赖: Task 3.1
-
-## 阶段 5：测试与部署
-- [ ] Task 5.1: 集成测试 (文件: ./tests/integration/)
-- [ ] Task 5.2: 性能测试 (文件: ./tests/performance/)
-- [ ] Task 5.3: 部署配置 (文件: ./deploy/)
+# 任务清单：${projectName}
+
+## 概述
+实现 ${projectName} 的任务分解。
 
 ---
+
+## 任务列表
+
+### 阶段 1: 项目初始化
+- [ ] 1.1 搭建项目骨架
+  - 创建目录结构
+  - 初始化 package.json
+  - _需求: 1.1_
+
+- [ ] 1.2 配置开发环境
+  - 配置 TypeScript/ESLint/Prettier
+  - _需求: 1.1_
+
+### 阶段 2: 核心功能实现
+- [ ] 2.1 实现数据模型
+  - 定义数据结构
+  - _需求: 2.1_
+
+- [ ] 2.2 实现业务逻辑
+  - 核心功能开发
+  - 依赖: 任务 2.1
+  - _需求: 2.2_
+
+### 阶段 3: 集成测试
+- [ ] 3.1 编写测试用例
+  - 单元测试
+  - 集成测试
+  - _需求: 3.1_
+
+---
+
+## 检查点
+- [ ] 阶段 1 完成后：项目可运行
+- [ ] 阶段 2 完成后：核心功能可用
+- [ ] 阶段 3 完成后：测试通过
+
+---
+
+## 文件变更清单
+| 文件 | 操作 | 说明 |
+|------|------|------|
+| src/index.ts | 新建 | 入口文件 |
+| package.json | 新建 | 项目配置 |
+
+---
+
 **标记说明**：
 - [P]: 可以并行执行的任务
 - 依赖: 必须在指定任务完成后才能开始
+- _需求: x.x_: 关联的需求编号
 \`\`\`
 
-**第七步：生成辅助脚本**
+**第八步：生成辅助脚本**
 创建项目管理脚本：
 - \`scripts/check-prerequisites.sh\`: 检查环境依赖
 - \`scripts/setup.sh\`: 自动化项目初始化
-- \`scripts/create-new-feature.sh\`: 创建新功能分支
 
 📝 **注意事项**：
-1. 所有文件使用 Markdown 格式，保持清晰的结构
-2. 遵循项目 constitution 中定义的原则
-3. 任务分解要足够细致，每个任务应该在 2-4 小时内完成
-4. 标记清楚任务之间的依赖关系
-5. 识别可以并行执行的任务以优化开发效率
+1. 所有文档统一放在 \`docs/\` 目录下
+2. 功能规格放在 \`docs/specs/{feature-name}/\` 目录
+3. 所有文件使用 Markdown 格式，保持清晰的结构
+4. 遵循项目 constitution 中定义的原则
+5. 任务分解要足够细致，每个任务应该在 2-4 小时内完成
+6. 标记清楚任务之间的依赖关系
+7. 识别可以并行执行的任务以优化开发效率
 
 🚀 **开始执行**：
 现在请按照上述步骤创建项目结构和所有必需的文档。`;

package/build/tools/init_project_context.d.ts

@@ -0,0 +1,26 @@
+/**
+ * init_project_context 工具
+ *
+ * 功能：生成项目上下文文档，帮助 AI 理解项目的技术栈、架构和规范
+ * 模式：指令生成器模式 - 返回详细的分析指南，由 AI 执行实际操作
+ */
+/**
+ * init_project_context 工具实现
+ *
+ * @param args - 工具参数
+ * @param args.docs_dir - 文档目录，默认 "docs"
+ * @returns MCP 响应，包含项目分析指南
+ */
+export declare function initProjectContext(args: any): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError?: undefined;
+} | {
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError: boolean;
+}>;

package/build/tools/init_project_context.js

@@ -0,0 +1,331 @@
+/**
+ * init_project_context 工具
+ *
+ * 功能：生成项目上下文文档，帮助 AI 理解项目的技术栈、架构和规范
+ * 模式：指令生成器模式 - 返回详细的分析指南，由 AI 执行实际操作
+ */
+// 默认文档目录
+const DEFAULT_DOCS_DIR = "docs";
+// 提示词模板
+const PROMPT_TEMPLATE = `# 项目上下文初始化指南
+
+## 🎯 任务目标
+
+在 \`{docs_dir}/\` 目录下生成 \`project-context.md\` 文件，记录项目的核心信息。
+
+**输出文件**: \`{docs_dir}/project-context.md\`
+
+**文件用途**: 记录项目的技术栈、架构模式、编码规范等核心信息，供后续功能开发时参考。
+
+---
+
+## 📋 执行步骤
+
+请按照以下步骤分析项目并生成文档：
+
+### 步骤 1: 分析技术栈
+
+**目标**: 识别项目使用的语言、框架和工具。
+
+**操作**:
+1. 读取 \`package.json\` 文件
+2. 从 \`dependencies\` 中识别主要框架:
+   - React、Vue、Angular → 前端框架
+   - Express、Koa、Fastify、NestJS → 后端框架
+   - Next.js、Nuxt.js → 全栈框架
+   - @modelcontextprotocol/sdk → MCP 服务器
+3. 从 \`devDependencies\` 中识别开发工具:
+   - typescript → TypeScript 项目
+   - webpack、vite、rollup、esbuild → 构建工具
+   - jest、vitest、mocha → 测试框架
+   - eslint、prettier → 代码规范工具
+4. 检查配置文件:
+   - \`tsconfig.json\` → TypeScript 配置
+   - \`vite.config.js/ts\` → Vite 项目
+   - \`webpack.config.js\` → Webpack 项目
+   - \`.eslintrc.*\` → ESLint 配置
+   - \`.prettierrc.*\` → Prettier 配置
+
+**记录**: 语言、框架、构建工具、测试框架、代码规范工具
+
+---
+
+### 步骤 2: 分析项目结构
+
+**目标**: 理解项目的目录组织方式。
+
+**操作**:
+1. 列出项目根目录下的文件和文件夹
+2. 重点关注以下目录:
+   - \`src/\` → 源代码目录
+   - \`lib/\` → 库代码目录
+   - \`tests/\` 或 \`__tests__/\` → 测试目录
+   - \`docs/\` → 文档目录
+   - \`build/\` 或 \`dist/\` → 构建输出目录
+3. 识别入口文件:
+   - \`src/index.ts\` 或 \`src/index.js\`
+   - \`src/main.ts\` 或 \`src/main.js\`
+   - \`src/app.ts\` 或 \`src/app.js\`
+4. 生成目录树（深度 2-3 层，忽略 node_modules、.git、dist、build）
+
+**记录**: 目录结构、入口文件、主要模块
+
+---
+
+### 步骤 3: 分析编码规范
+
+**目标**: 识别项目的代码风格和规范。
+
+**操作**:
+1. 检查是否存在以下配置文件:
+   - \`.eslintrc.*\` → ESLint 配置
+   - \`.prettierrc.*\` → Prettier 配置
+   - \`tsconfig.json\` → TypeScript 配置
+2. 从现有代码中识别命名规范:
+   - 文件命名: kebab-case / camelCase / PascalCase
+   - 变量命名: camelCase
+   - 常量命名: UPPER_SNAKE_CASE
+   - 类/接口命名: PascalCase
+3. 检查 TypeScript 配置:
+   - \`strict\` 是否为 true
+   - \`target\` 和 \`module\` 设置
+   - 其他重要配置项
+
+**记录**: 代码风格工具、命名规范、TypeScript 配置
+
+---
+
+### 步骤 4: 分析依赖
+
+**目标**: 列出项目的主要依赖。
+
+**操作**:
+1. 从 \`package.json\` 读取 \`dependencies\`
+2. 从 \`package.json\` 读取 \`devDependencies\`
+3. 识别关键依赖并说明用途
+4. 统计依赖数量
+
+**记录**: 主要生产依赖（前 10 个）、主要开发依赖（前 10 个）、依赖总数
+
+---
+
+### 步骤 5: 分析开发流程
+
+**目标**: 识别项目的开发、构建、测试命令。
+
+**操作**:
+1. 从 \`package.json\` 读取 \`scripts\` 字段
+2. 识别常用命令:
+   - \`dev\` 或 \`start\` → 开发启动命令
+   - \`build\` → 构建命令
+   - \`test\` → 测试命令
+   - \`lint\` → 代码检查命令
+
+**记录**: 开发命令、构建命令、测试命令、其他重要命令
+
+---
+
+## 📝 文档模板
+
+请在 \`{docs_dir}/project-context.md\` 中生成以下内容：
+
+\`\`\`markdown
+# 项目上下文
+
+> 本文档由 MCP Probe Kit 的 init_project_context 工具生成，记录项目的核心信息。
+> 用于帮助 AI 理解项目，生成更准确的代码和文档。
+
+## 项目概览
+
+| 属性 | 值 |
+|------|-----|
+| 名称 | [从 package.json 的 name 字段读取] |
+| 版本 | [从 package.json 的 version 字段读取] |
+| 类型 | [分析得出: Web应用 / API服务 / CLI工具 / 库 / MCP服务器] |
+| 描述 | [从 package.json 的 description 字段读取] |
+
+## 技术栈
+
+| 类别 | 技术 |
+|------|------|
+| 语言 | [JavaScript / TypeScript] |
+| 运行时 | [Node.js / Browser / Deno] |
+| 框架 | [识别的框架，如 React、Express、Next.js] |
+| 构建工具 | [识别的工具，如 TypeScript、Webpack、Vite] |
+| 包管理器 | [npm / yarn / pnpm] |
+| 测试框架 | [识别的测试框架，如 Jest、Vitest，或 "未配置"] |
+
+## 项目结构
+
+\\\`\\\`\\\`
+[生成目录树，深度 2-3 层]
+[示例:]
+project/
+├── src/
+│   ├── index.ts
+│   └── tools/
+│       ├── index.ts
+│       └── ...
+├── docs/
+├── package.json
+└── tsconfig.json
+\\\`\\\`\\\`
+
+### 主要目录说明
+
+| 目录 | 用途 |
+|------|------|
+| src/ | [源代码目录，描述主要内容] |
+| docs/ | [文档目录] |
+| tests/ | [测试目录，如果存在] |
+| build/ | [构建输出目录，如果存在] |
+
+### 入口文件
+
+- 主入口: \`[入口文件路径，如 src/index.ts]\`
+
+## 架构模式
+
+- **项目类型**: [MCP服务器 / Web应用 / API服务 / 库]
+- **设计模式**: [识别的模式，如 工具模式、MVC、组件化、服务层]
+- **模块划分**: [主要模块说明]
+
+## 编码规范
+
+### 代码风格
+
+| 工具 | 状态 | 配置文件 |
+|------|------|----------|
+| ESLint | [已配置 / 未配置] | [配置文件路径] |
+| Prettier | [已配置 / 未配置] | [配置文件路径] |
+
+### 命名规范
+
+| 类型 | 规范 | 示例 |
+|------|------|------|
+| 文件命名 | [kebab-case / camelCase / PascalCase] | [示例] |
+| 变量命名 | camelCase | userName |
+| 常量命名 | UPPER_SNAKE_CASE | MAX_COUNT |
+| 函数命名 | camelCase | getUserInfo |
+| 类/接口命名 | PascalCase | UserService |
+
+### TypeScript 配置
+
+| 配置项 | 值 |
+|--------|-----|
+| strict | [true / false] |
+| target | [ES2020 / ES2022 / ...] |
+| module | [CommonJS / ESNext / Node16 / ...] |
+
+## 依赖管理
+
+### 主要生产依赖
+
+| 依赖 | 版本 | 用途 |
+|------|------|------|
+| [依赖名] | [版本] | [用途说明] |
+
+### 主要开发依赖
+
+| 依赖 | 版本 | 用途 |
+|------|------|------|
+| [依赖名] | [版本] | [用途说明] |
+
+### 依赖统计
+
+- 生产依赖: [数量] 个
+- 开发依赖: [数量] 个
+- 总计: [数量] 个
+
+## 开发流程
+
+### 常用命令
+
+| 命令 | 用途 |
+|------|------|
+| \`npm run dev\` | [开发启动，描述具体行为] |
+| \`npm run build\` | [构建，描述输出位置] |
+| \`npm test\` | [测试，或 "未配置"] |
+| \`npm run lint\` | [代码检查，或 "未配置"] |
+
+### 开发环境要求
+
+- Node.js: [版本要求，从 engines 字段读取或推断]
+- 包管理器: [npm / yarn / pnpm]
+
+---
+
+*生成时间: [当前时间，格式: YYYY-MM-DD HH:mm:ss]*
+*生成工具: MCP Probe Kit - init_project_context*
+\`\`\`
+
+---
+
+## ✅ 检查清单
+
+生成文档后，请验证以下内容：
+
+- [ ] 文件已创建: \`{docs_dir}/project-context.md\`
+- [ ] 项目概览完整（名称、版本、类型、描述都已填写）
+- [ ] 技术栈准确（语言、框架、构建工具正确识别）
+- [ ] 目录结构清晰（树形结构正确，深度适当）
+- [ ] 入口文件正确（主入口文件已识别）
+- [ ] 架构模式已识别（项目类型、设计模式）
+- [ ] 编码规范完整（ESLint、Prettier、命名规范已记录）
+- [ ] TypeScript 配置已记录（如果是 TS 项目）
+- [ ] 依赖列表完整（主要依赖已列出并说明用途）
+- [ ] 开发命令正确（dev、build、test 命令已记录）
+- [ ] 所有占位符已替换（没有 [xxx] 格式的占位符）
+- [ ] Markdown 格式正确（表格、代码块格式正确）
+
+---
+
+## 📌 注意事项
+
+1. **如果某项信息无法获取**，请填写 "未配置" 或 "无"，不要留空
+2. **目录树生成时**，忽略 \`node_modules\`、\`.git\`、\`dist\`、\`build\`、\`coverage\` 等目录
+3. **依赖说明**，只列出主要依赖（前 10 个），其他可省略
+4. **时间格式**，使用 YYYY-MM-DD HH:mm:ss 格式
+5. **如果 docs 目录不存在**，请先创建该目录
+
+---
+
+*指南版本: 1.0.0*
+*工具: MCP Probe Kit - init_project_context*
+`;
+/**
+ * init_project_context 工具实现
+ *
+ * @param args - 工具参数
+ * @param args.docs_dir - 文档目录，默认 "docs"
+ * @returns MCP 响应，包含项目分析指南
+ */
+export async function initProjectContext(args) {
+    try {
+        // 解析参数
+        const docsDir = args?.docs_dir || DEFAULT_DOCS_DIR;
+        // 构建指南文本（替换占位符）
+        const guide = PROMPT_TEMPLATE.replace(/{docs_dir}/g, docsDir);
+        // 返回结果
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: guide,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `❌ 初始化项目上下文失败: ${errorMessage}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}

package/build/tools/security_scan.d.ts

@@ -0,0 +1,22 @@
+/**
+ * security_scan 工具
+ *
+ * 功能：代码安全扫描，检测常见漏洞和不安全编码实践
+ * 模式：指令生成器模式 - 返回安全检查指南，由 AI 执行实际分析
+ */
+/**
+ * security_scan 工具实现
+ */
+export declare function securityScan(args: any): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError?: undefined;
+} | {
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError: boolean;
+}>;