MCPサーバー（AI連携）

SpecDownはModel Context Protocol（MCP）サーバーを提供し、 AIアシスタントがドキュメントを読み、検索し、コメントし、更新し、画像を追加し、 同期計画を立てられるようにします。

MCPとは？

Model Context Protocol は、AIモデルが外部システムへ構造化されたツールとして接続するための標準です。 SpecDown MCPを使うと、エージェントはUIを操作せずに仕様を読み、更新し、レビューコメントを追加し、 画像をアップロードし、リモート同期計画を立てられます。

利用可能なツール

読み取りと探索

書き込みとコラボレーション

エージェント向け同期計画

APIキーの取得

1. 設定 → APIキーへ移動します。
2. 新しいキーを生成をクリックします。
3. 名前を付け、アクセス可能なプロジェクトを選択します。
4. キーをコピーします。表示は一度だけです。

2つの接続方法

SpecDown MCPはHTTP hostedとstdio localの両方をサポートします。

HTTP + SSE（リモート）

Endpoint: https://specdown.app/api/mcp
Protocol: JSON-RPC 2.0 over HTTP + Server-Sent Events
Auth: Authorization: Bearer <your-api-key>

Stdio（ローカル）

npx specdown-mcp --api-key <your-api-key>

またはグローバルインストール:

npm install -g specdown-mcp
specdown-mcp --api-key <your-api-key>

Claude Desktopの設定

Claude Desktopのclaude_desktop_config.jsonにSpecDownを追加します:

{
  "mcpServers": {
    "specdown": {
      "command": "npx",
      "args": ["-y", "specdown-mcp"],
      "env": {
        "SPECDOWN_API_KEY": "your-api-key-here"
      }
    }
  }
}

macOSでは、ファイルは ~/Library/Application Support/Claude/claude_desktop_config.json にあります。

典型的なエージェント同期フロー

sync系ツールは、ホスト環境経由でlocal filesystemを読めるエージェント向けです。

1. linked folder内のlocal fileを読む
2. [{ path, hash, documentId? }] にハッシュ化する
3. project_id, remote_prefix, local_files, optional state_files で plan_sync を呼ぶ
4. 返ってきた plan と summary を確認する
5. 承認済みremote mutationを apply_sync_plan operations に変換する
6. 同期成功後に local .specdown/sync-state.json を更新する

プロンプト例

• "認証ドキュメントを読んで、login flowを要約してください。"
• "rate limitingに言及しているドキュメントをすべて検索し、pathを返してください。"
• "/architecture 配下に新しいADRを作り、最初のテンプレートを入れてください。"
• "このdiagramをアップロードし、/guides/authentication.md に入れるMarkdownリンクを返してください。"
• "local linked folderのsync planを作り、apply前にconflictを見せてください。"

セキュリティ

すべてのMCPリクエストはBearer tokenで認証されます。プロジェクトアクセスはサーバー側で強制されるため、 APIキーは発行されたprojectだけにアクセスできます。

update_document、add_comment、upload_image、apply_sync_planのような書き込みツールも同じproject scope内でのみ動作します。

ユースケースとヒント

ライブ仕様に基づく実装

まずSpecDownに仕様を書き、その後AIにライブなsource of truthを読ませて実装させます。

AIレビューとコメント

" /api/authentication.md を読んで、足りないedge caseにレビューコメントを追加してください。"

"新しいbilling docを旧版と比較し、breaking changeが曖昧な箇所にコメントしてください。"

エージェント管理のlocal mirror

"local linked folderを読み、plan_syncを呼んで、push予定を見せてください。"

"承認済みsync planのremote upsertだけを適用し、skipされたファイルを報告してください。"

これはCLIのlinked-folder workflowに対するMCP側の対応です。MCPはremote mutationを計画・適用し、 local fileの読み書きはホストエージェントが担当します。

バックリンクとドキュメントグラフの探索

" /guides/authentication.md にリンクしているドキュメントを全部見せてください。"

" /architecture subtree のグラフを作り、中心的なhub documentを教えてください。"

doc編集前に影響範囲を把握したいときは get_backlinks を、より広い関係性を見たいときは get_doc_graph を使います。

Properties と bases風クエリ

"/prd 配下のすべてのドキュメントについて frontmatter properties を一覧化してください。"

"/roadmap subtree から status = draft かつ tags に agent を含むdocを抽出してください。"

編集計画の前に構造化metadataが必要なら list_properties を、全件走査ではなく絞り込まれた working set が欲しいなら query_view を使います。

docs automation向け画像アップロード

"このPNGを現在のprojectへアップロードし、Markdown image linkを返してください。"

"アップロードした画像を /guides/onboarding.md に追加し、対応するmarkdownでdocを更新してください。"

project attachment automation

"このPDFを /assets/brief.pdf としてアップロードし、[@/assets/brief.pdf] embedを返してください。"

"/assets 配下のproject filesを一覧し、CSV previewを読んで行を要約してください。"

project fileを扱う場合は、list_project_files、read_project_file、upload_project_fileを使います。HTML/HTMは編集可能なdocumentになり、 その他のfileはpreview-only assetのままです。

Cursor / Windsurfでの利用

# .cursor/mcp.json
{
  "mcpServers": {
    "specdown": {
      "command": "npx",
      "args": ["-y", "specdown-mcp"],
      "env": { "SPECDOWN_API_KEY": "your-api-key" }
    }
  }
}

ヒントとトリック

• projectごとにキーを分ける: projectまたは環境ごとに別のAPI keyを作成します。
• まずcontextを取る: 具体的なdocを読む前に read_project_context や list_documents を使います。
• 全文読む前に検索: search_documents でトークン消費を抑えます。
• レビューにはコメントを使う: すぐ書き換えるより add_comment で人間レビューにつなげる方が安全な場面があります。
• apply前にplan: plan_sync を安全な標準ステップとし、apply_sync_plan をcommitステップとして扱います。
• 共有ドキュメントを書き換える前にバックリンクを確認する: 他のガイドへ波及する可能性がある場合は get_backlinks や get_doc_graph を先に使います。
• propertiesで読み込み対象を絞る: 大きなprojectでPRDやADRやrunbookを総当たりする前に list_properties や query_view を使います。
• CLIと併用する: MCPは構造化されたagent判断に強く、CLIはローカルworking copyを維持する最も簡単な方法です。