mcp-spec-comments

基于注释实现的规范驱动开发的MCP服务器

这是一个支持简单注释驱动设计的MCP服务器。它在AI与文件之间充当桥梁，帮助从设计文档创建到注释放置再到实现的整个过程。

特征

• 🎯 简单设计: MCP服务器专注于文件的读写，复杂的处理交给AI完成
• 📝 注释驱动: 使用 @spec-impl 标记明确实现位置和步骤
• ⚙️ 可定制: 可根据项目需求定制模板和规则
• 🔄 工作流管理: 支持从设计文档创建到注释放置再到实现及进度确认的工作流程

状态

⚠️ 目前仅支持本地使用

此项目当前不作为npm包发布。 预计在本地环境或公司内部Git仓库中使用。

安装

本地使用

1. 克隆仓库:

git clone <repository-url> ~/mcp-spec-comments
cd ~/mcp-spec-comments

2. 安装依赖:

npm install

3. 构建:

npm run build

内部共享

详情请参阅 内部使用设置指南。

设置

1. 创建 spec-comments.config.yml 文件

如果需要反映特定于项目的设置，请创建该文件。如果没有创建，则会应用默认设置。
在项目根目录下创建 spec-comments.config.yml 文件:

# 模板设置
templates:
  directory: "./templates"  # 自定义模板的位置
  use_defaults: true        # 使用默认模板

# 规则文件（可选）
rules:
  design_rules: "./rules/design-rules.md"
  comment_rules: "./rules/comment-rules.md"
  implementation_rules: "./rules/implementation-rules.md"

# 输出的默认设置
output:
  base_directory: "./.spec-comments"
  requirements_filename: "requirements.md"
  design_filename: "design.md"
  implementation_log_filename: "implementation.log"

# 项目设置
project:
  root: "."
  source: "./src"

2. 在 Claude 中设置

方法A: 通过 Claude CLI 注册（推荐）

claude mcp add spec-comments -- node /path/to/mcp-spec-comments/dist/index.js

注意: /path/to/mcp-spec-comments 应替换为实际安装路径。

方法B: 手动编辑设置文件

编辑 claude_desktop_config.json 文件:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "spec-comments": {
      "command": "node",
      "args": [
        "/path/to/mcp-spec-comments/dist/index.js"
      ],
      "cwd": "/path/to/mcp-spec-comments"
    }
  }
}

注意: /path/to/mcp-spec-comments 应替换为实际安装路径。

3. 重启 Claude

为了使设置生效，请重启 Claude。

使用方法

工作流

此MCP服务器采用分阶段的工作流，每个阶段都需用户确认。

阶段1: 创建需求文档
   pass_to_ai_for_requirements 从用户需求生成需求文档
   ↓
   ✅ 用户确认与批准
   ↓
阶段2: 创建详细设计文档
   pass_to_ai_for_design 从需求文档生成设计文档
   ↓
   ✅ 用户确认与批准
   ↓
阶段3: 注释放置
   pass_to_ai_for_comments 从设计文档放置注释
   ↓
   ✅ 用户确认与批准
   ↓
阶段4: 实现处理
   pass_to_ai_for_implementation 根据注释进行实现
   ↓
   ✅ 完成

重要: 每个阶段完成后，必须获得用户的批准才能进入下一阶段。

工具列表

1. pass_to_ai_for_requirements

将用户需求传递给AI以生成需求文档（工作流的第一步）。

参数:

• user_input (必需): 用户的需求或想要构建的内容的描述
• feature_name (必需): 功能名称（例如: user-authentication, payment-system）
• output_path (可选): 输出文件路径（默认: .spec-comments/{feature_name}/requirements.md）

示例:

用户输入: 具有用户认证功能的Web应用程序
功能名称: user-authentication
输出路径: .spec-comments/user-authentication/requirements.md (自动生成)

2. pass_to_ai_for_design

根据需求文档让AI生成设计文档（工作流的第二步）。

参数:

• requirements_path (必需): 需求文档的文件路径
• feature_name (必需): 功能名称（与需求文档创建时相同）
• output_path (可选): 输出文件路径（默认: .spec- comments/{feature_name}/design.md）

示例:

需求文档: .spec-comments/user-authentication/requirements.md
功能名称: user-authentication
输出路径: .spec-comments/user-authentication/design.md (自动生成)

3. pass_to_ai_for_comments

根据设计文档让AI放置注释 (@spec-impl 标记)（工作流的第三步）。

参数:

• design_path (必需): 设计文档的文件路径
• target_files (可选): 注释的目标文件路径数组

示例:

设计文档: docs/design.md
目标文件: ["src/auth.ts", "src/user.ts"]

4. pass_to_ai_for_implementation

将带有注释的文件传递给AI以进行实现（工作流的最后一步）。

参数:

• target_files (必需): 实现目标文件路径数组
• implementation_order (可选): 实现顺序

示例:

目标文件: ["src/auth.ts"]

注释标记格式

// @spec-impl [ID] [优先级] [状态]
// [实现内容的说明]
// [实现步骤的列表]
// @spec-end

示例:

// @spec-impl AUTH-001 HIGH TODO
// 实现用户认证处理
// 1. 从请求中获取Authorization头
// 2. 使用JWT库验证令牌
// 3. 如果令牌无效，则返回401错误
// 4. 如果有效，则解码并返回用户信息
// @spec-end

实现后:

// @spec-impl AUTH-001 HIGH DONE
// 实现用户认证处理
export function authenticateUser(token: string): User | null {
  // 实现的代码
}
// @spec-end

默认模板

该包包含以下默认模板:

requirements.md - 需求文档模板

一个全面的需求文档模板，适用于从小型到大型项目。

主要特点:

• 用户故事形式（As a/I want/so that）
• WHEN/THEN 形式的验收标准
• 优先级和依赖关系管理
• 详细的非功能性需求（代码架构、性能、安全性、可靠性、可扩展性、易用性、可维护性）
• 风险管理和成功标准
• 时间表和里程碑
• 审批流程和修订历史

包含的部分:

• 项目概述与愿景的一致性
• 利益相关者信息
• 功能需求（带优先级和依赖关系）
• 非功能性需求（详细）
• 技术限制和范围
• 前提条件和依赖关系
• 术语表
• 风险和对策
• 成功标准
• 时间表和里程碑
• 审批流程和修订历史

其他模板

• design.md: 详细设计文档模板
• comment-rules.md: 注释编写规则
• implementation-rules.md: 实现规则

这些可以通过在 spec-comments.config.yml 中设置 use_defaults: true 来使用。

目录结构

此MCP服务器采用按功能组织文档的结构:

your-project/
├── .spec-comments/              # 按功能组织的文档基础目录
│   ├── user-authentication/     # 功能1: 用户认证
│   │   ├── requirements.md      # 需求文档
│   │   └── design.md            # 详细设计文档
│   ├── payment-system/          # 功能2: 支付系统
│   │   ├── requirements.md
│   │   └── design.md
│   └── dashboard-ui/            # 功能3: 仪表盘UI
│       ├── requirements.md
│       └── design.md
├── src/                         # 实现代码
├── templates/                   # 自定义模板（可选）
│   ├── requirements.md
│   └── design.md
└── spec-comments.config.yml     # 配置文件

要点:

• 功能名称（feature_name）在每次工具执行时指定
• 文档会自动放置在 .spec-comments/{feature_name}/ 下
• 如果需要自定义输出路径，可以使用 output_path 参数覆盖

自定义

模板的自定义

可以在项目的 templates/ 目录中放置自定义模板:

your-project/
├── templates/
│   ├── requirements.md      # 自定义需求模板
│   ├── design.md            # 自定义设计文档模板
│   └── my-custom.md         # 自定义模板
└── spec-comments.config.yml

输出路径的自定义

可以在 spec-comments.config.yml 中更改基础目录和文件名:

output:
  base_directory: "./docs/features"  # 更改基础目录
  requirements_filename: "spec.md"   # 更改文件名
  design_filename: "architecture.md"

未来功能

实现情况管理功能（未实现）

目前，@spec-impl 标记的状态管理需要手动完成，但未来计划添加以下功能:

• 实现情况的自动扫描: 扫描项目中的 @spec-impl 标记并列出
• 进度报告: 按状态（TODO/IN_PROGRESS/DONE）汇总
• 实现顺序管理: 根据 [实现顺序:数字] 提议下一个应实现的项目
• 优先级过滤: 按优先级筛选显示

在这些功能实现之前，可以使用编辑器的搜索功能（如 @spec-impl[状态:TODO]）手动管理。

许可证

MIT

作者

yerabu