MCP Spec Comments

mcp规范注释

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

支持基于简单注释的设计驱动开发MCP服务器。AI在和文件之间架起模板和规则的桥梁，支持从设计书的制作到评论部署和实施。

特徴

• 🎯 简单设计: MCP服务器彻底读写文件，复杂的处理AI委任
• 📝 注释驱动: @spec-impl 用标记明确安装位置和步骤
• 🔄 工作流管理：支持设计书制作→注释放置→实施→进度确认流程
• ⚙️ 可定制：根据项目定制模板和规则

状态

⚠️ 当前仅支持本地使用

现在npm 没有作为包装公开。 本地或内部Git 设想在存储库中使用。

安装

本地使用时

1. 克隆存储库：

git clone  ~/mcp-spec-comments
cd ~/mcp-spec-comments

1. 安装依赖关系：

npm install

1. 构建：

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 视窗: %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] 等已弃用的函数的缺少的支持。

许可证

麻省理工学院

作者

伊拉布