Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-spec-comments Write requirements for user registration feature"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server for spec-driven development with comment-based implementation
シンプルなコメントベースの設計駆動開発を支援するMCPサーバーです。AIとファイルの間でテンプレートやルールを橋渡しし、設計書の作成からコメント配置、実装までをサポートします。
🎯 シンプル設計: MCPサーバーはファイルの読み書きに徹し、複雑な処理はAIに委譲
📝 コメント駆動: @spec-impl マーカーで実装箇所と手順を明確化
🔄 ワークフロー管理: 設計書作成 → コメント配置 → 実装 → 進捗確認の流れをサポート
⚙️ カスタマイズ可能: テンプレートとルールをプロジェクトに合わせてカスタマイズ
Related MCP server: Gigaspec
⚠️ 現在はローカル利用のみ対応
このプロジェクトは現在、npm パッケージとしての公開は行っていません。 ローカル環境または社内 Git リポジトリでの利用を想定しています。
リポジトリをクローン:
git clone <repository-url> ~/mcp-spec-comments
cd ~/mcp-spec-comments依存関係をインストール:
npm installビルド:
npm run build詳細は 社内利用セットアップガイド を参照してください。
プロジェクト固有の設定を反映したい場合は作成してください。もし作成しなかった場合、デフォルトの設定が反映されます。
プロジェクトルートに 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"claude mcp add spec-comments -- node /path/to/mcp-spec-comments/dist/index.js注意: /path/to/mcp-spec-comments は実際のインストールパスに置き換えてください。
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 は実際のインストールパスに置き換えてください。
設定を反映させるため、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 でコメントに従って実装
↓
✅ 完了重要: 各フェーズ完了後、必ずユーザーの承認を得てから次のフェーズに進みます。
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 (自動生成)pass_to_ai_for_design要件定義書を元にAIに設計書を作成させる（ワークフローの2番目のステップ）。
パラメータ:
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 (自動生成)pass_to_ai_for_comments設計書を元にAIにコメント(@spec-implマーカー)を配置させる（ワークフローの3番目のステップ）。
パラメータ:
design_path (必須): 設計書のファイルパス
target_files (任意): コメントを配置する対象ファイルのパス配列
例:
設計書: docs/design.md
対象ファイル: ["src/auth.ts", "src/user.ts"]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.ymlspec-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
設計書を元にAIにコメント(@spec-implマーカー)を書かせる（ワークフローの3番目のステップ）。既存ファイルにコメントを追加したり、新規ファイルを作成できる。
| Name | Required | Description | Default |
|---|---|---|---|
| design_path | Yes | 設計書のファイルパス | |
| target_files | No | 対象ファイルのパス配列（省略時は設計書から判断） |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the transparency burden. It does disclose that the tool can add comments to existing files or create new files, which are key behavioral traits. However, it omits details about whether existing comments are overwritten or how file modifications are handled, leaving some ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences effectively convey the tool's purpose, workflow step, and capabilities. Every sentence contributes meaningful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is well-suited to its workflow context, with sibling tools and step numbering providing additional context. Parameter details are fully covered in the schema. However, it lacks information about output format or prerequisites, which would enhance completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter already described in the schema. The tool description adds no extra parameter semantics beyond what the schema provides, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: having AI write comments with @spec-impl markers based on a design document. It also specifies it's the 3rd workflow step, distinguishing it from sibling tools like requirements, design, and implementation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly positions the tool as the 3rd step in a workflow, providing clear sequencing context. It doesn't explicitly state when not to use it, but the sibling tool names and step numbering strongly imply appropriate usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
要件定義書を元にAIに設計書を作成させる（ワークフローの2番目のステップ）。出力先は .spec-comments/{feature_name}/design.md となる。
| Name | Required | Description | Default |
|---|---|---|---|
| output_path | No | 出力先のファイルパス（省略可能）。指定しない場合は .spec-comments/{feature_name}/design.md が使用される。 | |
| feature_name | Yes | 機能名（例: user-authentication）。要件定義書作成時に使用したものと同じ名前を指定。 | |
| requirements_path | Yes | 要件定義書のファイルパス |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It specifies the output path and that the design is based on the requirements file, but it does not disclose whether existing files are overwritten, required permissions, or potential error conditions. This is some useful context but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the core purpose and ends with the output destination. It is free of fluff and every word earns its place, conveying the tool's function in exactly one line.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with three parameters and no output schema, the description covers the essential aspects: purpose, input (requirements), output location, and workflow step. It does not mention error handling or permissions, but for a simple pipeline step, this is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description repeats the default output path already described in the schema, adding no new semantic detail beyond what structured data provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool creates a design document from a requirements definition document, and identifies it as the second step of a workflow. This distinguishes it from sibling tools like pass_to_ai_for_requirements, pass_to_ai_for_implementation, and pass_to_ai_for_comments, which are for other phases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The workflow step designation ('2番目のステップ') indicates when this tool should be used relative to the overall process. It does not explicitly name alternatives or exclusions, but the context makes it clear this is for the design phase, not for requirements, comments, or implementation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
コメント付きファイルをAIに渡して実装させる（ワークフローの最後のステップ）。@spec-implマーカーに従って実装し、完了後はDONE状態に更新する。
| Name | Required | Description | Default |
|---|---|---|---|
| target_files | Yes | 実装対象のファイルパス配列 | |
| implementation_order | No | 実装順序（省略可能） |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full transparency burden. It discloses that the tool updates files to a DONE state after implementation, which is a key side effect. It also mentions following @spec-impl markers. It does not detail all potential side effects (e.g., file modifications, error handling), but the main behavioral traits are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the primary purpose and includes workflow context. Every clause earns its place, with no redundant information. It is appropriately concise for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential behavior—passing files, implementing per marker, and updating to DONE—which is sufficient for a simple workflow step. There is no output schema, but the description does not need to explain return values. It lacks details on failure modes or what the DONE state entails, but overall it is reasonably complete given the tool's scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds meaningful context beyond the schema by indicating that target_files should contain comments and that implementation follows @spec-impl markers. This enriches the plain 'implementation target files' definition with domain-specific semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it passes commented files to AI for implementation, with a specific verb ('実装させる') and resource (commented files). It also positions itself as the workflow's final step and references the @spec-impl marker, distinguishing it from sibling tools like pass_to_ai_for_requirements and pass_to_ai_for_design.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly mentions it is the workflow's last step, giving clear usage context and implying it should be used after other pass_to_ai steps. It does not explicitly name alternatives or provide when-not conditions, but the workflow positioning and sibling tool names make the intended usage clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
ユーザー要件をAIに渡して要件定義書を作成させる（ワークフローの最初のステップ）。出力先は .spec-comments/{feature_name}/requirements.md となる。
| Name | Required | Description | Default |
|---|---|---|---|
| user_input | Yes | ユーザーが作りたいものの説明や要件 | |
| output_path | No | 出力先のファイルパス（省略可能）。指定しない場合は .spec-comments/{feature_name}/requirements.md が使用される。 | |
| feature_name | Yes | 機能名（例: user-authentication, payment-system）。この名前でディレクトリが作成される。 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does disclose the output destination, implying a file write, but it doesn't mention whether it overwrites existing files, requires specific permissions, or any side effects. The behavior is partially transparent but has gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that front-loads the core purpose and adds the output path. Every word earns its place, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations and an output schema, the description is too thin. It doesn't explain the process (e.g., that it creates a file, how the AI is invoked, or what the expected result is). Essential context for successful invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description repeats the default output path already documented in the schema, adding no extra semantic value beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool passes user requirements to AI to produce a requirements definition document, and identifies it as the first step of the workflow. This clearly distinguishes it from sibling tools like pass_to_ai_for_design or pass_to_ai_for_implementation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'workflow first step' provides clear context for when to use this tool. However, it does not explicitly mention alternatives or when not to use it, so it's a bit short of a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
ファイルに@spec-implマーカーが配置されているかを検証する。pass_to_ai_for_commentsの実行後に使用して、すべてのファイルにマーカーが正しく追加されているか確認する。
| Name | Required | Description | Default |
|---|---|---|---|
| target_files | Yes | 検証対象のファイルパス配列 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must fully convey behavior. It states the tool verifies/checks markers, implying a read-only operation, but does not explicitly disclose side effects, permission requirements, or output/return format. More could be said about whether it fails on missing markers or what results are produced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and includes a practical usage hint. Every sentence is informative with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one parameter, no output schema), and the description covers what and when. However, it lacks information on the return/exit behavior or how to interpret results, which is important for a verification tool without an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the only parameter (target_files), and the description adds no additional parameter semantics beyond what the schema already states. The baseline of 3 is appropriate since the schema carries the burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'verify whether the @spec-impl marker is placed in files,' using a specific verb (verify) and resource (@spec-impl marker). It distinguishes itself from the sibling 'pass_to_ai_for_*' tools by being a verification tool rather than a generation/passing tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to use 'after executing pass_to_ai_for_comments' and to confirm markers are added to all files. This provides clear when-to-use context, though it does not mention when-not-to-use or alternative tools beyond the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0pass_to_ai_for_commentspass_to_ai_for_designpass_to_ai_for_implementationpass_to_ai_for_requirementsverify_spec_commentsScored across 5 tools
Each tool represents a distinct stage in a clearly defined workflow: requirements, design, comment generation, verification, and implementation. The sequential nature and specific output paths eliminate ambiguity between tools.
Four of the five tools follow the consistent 'pass_to_ai_for_' prefix pattern, while 'verify_spec_comments' deviates slightly. Overall, the naming is snake_case and predictable, with only minor inconsistency.
Five tools is well-scoped for a focused workflow, providing all necessary steps without redundancy. The count is within the ideal range for a single-purpose server.
The tool set covers the full lifecycle from requirements definition to implementation, including a verification step to ensure comments are correctly placed. No obvious gaps in the workflow.
Official DevSpeak MCP server — translate technical text into formal specs from any AI IDE or agent
A MCP server built for developers enabling Git based project management with project and personal…
MCP server for generating rough-draft project plans from natural-language prompts.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
