MCP Playbook Server

MCP Playbook Server

ユーザーが指定した対象プロジェクトディレクトリ内で、プロジェクトドキュメントを管理し、会話ログを保存する Model Context Protocol（MCP）サーバーです。

Claude Desktop または MCP クライアントでの使用方法

この MCP サーバーを Claude Desktop で使用するには、Claude Desktop の設定に構成エントリを追加します。正確な command と args は、サーバーの実行方法（例：node から直接実行する、または Docker を使用する）によって異なります。

まず、このプロンプトを cursor rules、cline rules、または windsurf rules に追加してください。

ALWAYS run the `init_playbook` tool before starting to get instructions on how things should be done and documented.

次に、以下の設定を MCP クライアントに追加してください。

{
  "mcpServers": {
    "mcp-playbook": {
      "command": "npx",
      "args": ["-y", "@dwarvesf/mcp-playbook@latest"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your_github_token_here"
      }
    }
  }
}

MCP サーバーの設定方法について詳しくは、Claude Desktop のドキュメントを参照してください。

MCP の内部的な仕組み

MCP Playbook サーバーは、MCP クライアント（Claude Desktop など）からツール呼び出しリクエストを受け取って動作します。これらのリクエストは、サーバーのエントリーポイントである src/index.ts ファイルで処理されます。

graph LR
    A[MCP Client] --> B["CallToolRequestSchema"];
    A --> E["ListToolsRequestSchema"];
    A --> F["ListPromptsRequestSchema"];
    A --> G["GetPromptRequestSchema"];

    subgraph src/index.ts
        B
        E
        F
        G
    end

    B --> C["Switch Case (toolName)"];

    subgraph src/tools/
        C --> C1("init_playbook");
        C --> C2("create_adr");
        C --> C3("search_runbook");
        C --> C4("... ... ...");
    end

    C1 --> D1("handleInitPlaybook");
    C2 --> D2("handleCreateAdr");
    C3 --> D3("handleSearchRunbook");
    C4 --> D4("... ... ...");

    E --> D12("toolDefinitions");
    F --> D13("handleListPrompts");
    G --> D14("handleGetPrompt");

    subgraph src/handlers/
        D1
        D2
        D3
        D4
        D12
        D13
        D14
    end

1. ツール呼び出しリクエスト： MCP クライアントは toolName と必要な arguments を指定して、CallToolRequest をサーバーに送信します。
2. リクエスト処理： src/index.ts ファイルには、server.setRequestHandler(CallToolRequestSchema, async (request: CallToolRequest) => { ... }) を使用して CallToolRequest を処理するリクエストハンドラーが設定されています。
3. ツールのルーティング（switch 文）： リクエストハンドラー内では、toolName に対する switch 文によって、リクエストが適切なハンドラー関数に振り分けられます。
4. ハンドラーの実行： switch 文の各ケースは、src/handlers.ts ファイルにある専用のハンドラー関数（例：handleCreateSpec、handleSearchRunbook、handleSyncPrompt）を呼び出します。これらのハンドラーには、各ツール固有のロジックが含まれています。
5. 結果： ハンドラー関数は要求されたアクションを実行して結果を返します。その結果が MCP クライアントに返されます。

このフローにより、各ツール呼び出しが実行に適したロジックへ確実に振り分けられ、サーバーがさまざまなドキュメント関連タスクやユーティリティタスクを実行できます。

利用可能なツール

ツール名	説明
init_playbook	mcp-playbook サーバーの目的について LLM に指示します。このサーバーは、ローカルプロジェクトのドキュメント作成を支援し、AI を活用したプレイブックのドキュメントとチャットログを部分的に複製できるようにします。
create_spec	対象プロジェクトの docs/specs/ ディレクトリに、新しい仕様ファイル（PRD、RFC、アーキテクチャ計画など）を作成するか、既存のファイルを上書きします。仕様ファイルには、連番付きの spec-name.md 形式の名前が付けられます。
create_adr	対象プロジェクトの docs/adr/ ディレクトリに、新しいアーキテクチャ決定記録（ADR）ファイルを作成するか、既存のファイルを上書きします。ADR ファイルには、連番付きの adr-name.md 形式の名前が付けられます。
create_changelog	対象プロジェクトの docs/changelog/ ディレクトリに、ユーザー向けの詳細な変更履歴エントリファイルを新規作成します。各変更履歴エントリは個別のファイルとなり、連番付きの changelog-entry.md 形式の名前が付けられます。
distill_project_runbook	対象プロジェクト内の中心となる docs/runbook.md ファイルを作成または更新します。LLM は、既存のプロジェクトドキュメント（ADR、仕様書など）と、存在する場合は現在の docs/runbook.md を分析し、その情報を統合して包括的なランブックを作成します。このツールは、LLM が生成した内容を保存し、以前の docs/runbook.md を上書きします。
save_and_upload_chat_log	現在の会話履歴を取得し、対象プロジェクトの .chat/ ディレクトリに Markdown ファイルとして保存して、dwarvesf/prompt-log GitHub リポジトリにアップロードします。整理のためにユーザー ID が必要です。
search_runbook	dwarvesf/runbook GitHub リポジトリ内のキーワードをあいまい検索します。キーワードにスペースが含まれる場合は、完全一致のフレーズまたは個々の単語を検索します。上位 5 件の一致結果を、全内容および総件数とともに返します。
search_prompts	dwarvesf/prompt-db GitHub リポジトリ内のキーワードをあいまい検索します（.synced_prompts/ フォルダーは除外されます）。
suggest_runbook	新しいランブックエントリを含むプルリクエストを dwarvesf/runbook リポジトリに作成または更新します。
sync_prompt	LLM プロンプトを dwarvesf/prompt-db GitHub リポジトリに同期します。
think	何かについて考えるためにこのツールを使用します。新しい情報を取得したり、リポジトリに変更を加えたりはせず、考えた内容を記録するだけです。複雑な推論やブレインストーミングが必要な場合に使用します。

概要

この mcp-playbook サーバーは、Model Context Protocol（MCP）経由でアクセスできる一連のツールを提供する、自己完結型の Node.js/TypeScript アプリケーションです。主な機能は、LLM が指定されたプロジェクトディレクトリ内のドキュメントを構成できるよう支援することと、会話履歴を保存／アップロードすることです。外部の commander や github 環境に依存する可能性のあるツールとは異なり、このサーバーは Node.js の組み込みモジュール（fs、path、https）や node-fetch などのライブラリを直接使用して、ファイルシステム操作と GitHub API とのやり取りを実装しています。

このサーバーは、LLM が指定した target_project_dir を対象とし、その場所のファイルとディレクトリを管理します。ドキュメントやチャットログをサーバー自身のリポジトリ構成内に保存することはありません。

データフローとインタラクション

AI との会話、ファイル探索、LLM、mcp-playbook サーバー、GitHub リポジトリ間のインタラクションを次のように図示できます。

graph TD
    A[LLM] --> B("AI Conversation")
    B --> C{Explore Files}
    C -->|Files with Prompts| D("Prompts in Files")
    C -->|Files without Prompts| B
    B -->|Provides Context| F("MCP Playbook Server")
    D -->|Provides Context| F
    F -->|suggest_runbook| G["dwarvesf/runbook (Practices/Specs)"]
    F -->|save_and_upload_chat_log| H["dwarvesf/prompt-log (Conversation Logs)"]
    F -->|sync_prompt| I["dwarvesf/prompt-db (Synced Prompts)"]

この図は、AI との会話と、ファイル探索中に見つかったプロンプトが MCP Playbook サーバーにコンテキストを提供する仕組みを示しています。その後、サーバーは suggest_runbook、save_and_upload_chat_log、sync_prompt ツールを実行し、それぞれの GitHub リポジトリとやり取りします。

ツールの詳細

init_playbook

mcp-playbook サーバーの目的について LLM に指示を提供します。このサーバーは、ローカルプロジェクトのドキュメント作成を支援し、AI を活用したプレイブックのドキュメントやチャットログを部分的に複製できるようにします。

パラメーター： なし。

戻り値： 指示を含む JSON オブジェクトです。

{
  "instruction": "string" // Instruction for the LLM regarding the purpose of the mcp-playbook.
}

create_spec

対象プロジェクトの docs/specs/ ディレクトリに新しい仕様ファイル（例：PRD、RFC、アーキテクチャ計画）を作成するか、既存のファイルを上書きします。仕様ファイルには、連番付きの spec-name.md 形式の名前が付けられます（例：0001-initial-design.md）。

パラメーター：

• target_project_dir（string、必須）：対象プロジェクトディレクトリのルートへの絶対パスまたは相対パスです。
• spec_name（string、必須）：仕様ファイル名です（連番と .md 拡張子を除く）。基本的なサニタイズが適用されます。
• content（string、必須）：仕様の Markdown コンテンツです。

戻り値： 成功または失敗を示す JSON オブジェクトです。成功した場合はパスも含まれます。

{
  "status": "success" | "error",
  "path": "string" | undefined, // Path to the created file if successful
  "message": "string" // Description of the result or error
}

create_adr

対象プロジェクトの docs/adr/ ディレクトリに新しいアーキテクチャ決定記録（ADR）ファイルを作成するか、既存のファイルを上書きします。ADR ファイルには、連番付きの adr-name.md 形式の名前が付けられます（例：0001-use-react.md）。

パラメーター：

• target_project_dir（string、必須）：対象プロジェクトディレクトリのルートへの絶対パスまたは相対パスです。信頼性を高めるため、絶対パスの使用を強く推奨します。
• adr_name（string、必須）：ADR ファイル名です（連番と .md 拡張子を除く）。基本的なサニタイズが適用されます。
• content（string、必須）：ADR の Markdown コンテンツです。

戻り値： 成功または失敗を示す JSON オブジェクトです。成功した場合はパスも含まれます。

{
  "status": "success" | "error",
  "path": "string" | undefined, // Path to the created file if successful
  "message": "string" // Description of the result or error
}

create_changelog

対象プロジェクトの docs/changelog/ ディレクトリに、ユーザー向けの詳細な変更履歴エントリファイルを新規作成します。各変更履歴エントリは、連番付きの changelog-entry.md 形式の名前（例：0001-added-new-feature.md）を持つ個別のファイルになります。エントリには簡潔な要約ではなく、変更内容や、新機能の使い方、既存の機能への影響など、包括的な情報を記載してください。

パラメーター：

• target_project_dir（string、必須）：対象プロジェクトディレクトリのルートへの絶対パスです。信頼性を高めるため、絶対パスの使用を強く推奨します。
• entry_content（string、必須）：新しい変更履歴エントリの Markdown コンテンツです。
• changelog_name（string、必須）：変更履歴ファイルに付ける名前です（連番と .md 拡張子は含めません）。

戻り値： 成功または失敗を示す JSON オブジェクトです。成功した場合はパスも含まれます。

{
  "status": "success" | "error",
  "path": "string" | undefined, // Path to the updated file if successful
  "message": "string" // Description of the result or error
}

distill_project_runbook

対象プロジェクト内の中央 docs/runbook.md ファイルを作成または更新します。LLM は次の作業を担当します。

1. target_project_dir 内にある、関連するすべてのプロジェクトドキュメント（ADR、仕様書、変更履歴、コードなど）を徹底的に分析します。
2. docs/runbook.md がすでに存在する場合は、その現在の内容も分析対象として確認します。
3. 収集したすべての情報（既存の docs/runbook.md の情報を含む）を統合し、更新後の包括的なプロジェクトランブックを作成します。

このツールは、LLM が生成したコンテンツを受け取り、以前のバージョンを上書きして docs/runbook.md に保存します。フロントマター（title、last_updated、distilled_from）はツールが管理します。

パラメーター：

• target_project_dir（string、必須）：対象プロジェクトディレクトリのルートへの絶対パスです。
• content（string、必須）：LLM が生成・統合した、docs/runbook.md ファイルの完全な Markdown コンテンツです。
• source_document_references（array of strings、任意）：最新の要約・更新で LLM が使用した主要なソースドキュメントへのパス、または説明的な参照の配列です（例：[\'docs/adr/0001-auth-decision.md\', \'src/auth/service.ts\']）。

戻り値： 成功または失敗を示す JSON オブジェクトです。成功した場合は docs/runbook.md へのパスも含まれます。

{
  "status": "success" | "error",
  "path": "string" | undefined, // Path to docs/runbook.md if successful
  "message": "string" // Description of the result or error
}

save_and_upload_chat_log

現在の会話履歴を取得します。MCP クライアントから履歴が直接提供される場合は、それを使用します。そうでない場合は、任意の editorType パラメーターに基づいて、または各パーサーを順に試して、ローカルにインストールされた対応エディター（Cursor、Zed、Cline）のチャットログの解析を試みます。取得または解析した履歴は、対象プロジェクトの .chat/ ディレクトリに一意の名前を付けた Markdown ファイルとして保存した後、GitHub リポジトリ dwarvesf/prompt-log にアップロードされます。ログを整理するには userId が必要です。

パラメーター：

• target_project_dir（string、必須）：アップロード前にチャットログをローカルに保存する対象プロジェクトディレクトリのルートへの絶対パスです。信頼性を高めるため、絶対パスの使用を強く推奨します。
• userId（string、必須）：ユーザーまたは LLM クライアントの一意の ID です（例：GitHub ユーザー名）。
• editorType（string、任意）：クライアントからチャット履歴が直接提供されない場合に、履歴の解析を試みるエディターを指定します（例：'cursor'、'zed'、'cline'）。省略した場合、サーバーは対応するすべてのエディターのログ検出を試みることがあります。

戻り値： 成功または失敗を示す JSON オブジェクトです。成功した場合は、ローカルパス、GitHub パス、および GitHub URL（取得できる場合）が含まれます。

{
  "status": "success" | "error",
  "local_path": "string" | undefined, // Path to the locally saved file
  "github_path": "string" | undefined, // Path within the GitHub repository
  "github_url": "string" | undefined, // URL of the file on GitHub
  "commit_sha": "string" | undefined, // SHA of the commit if successful
  "commit_url": "string" | undefined, // URL of the commit if successful
  "message": "string" // Description of the result or error
}

search_runbook

dwarvesf/runbook GitHub リポジトリ内のキーワードをあいまい検索します。キーワードにスペースが含まれる場合は、完全一致するフレーズまたは個々の単語を検索します。一致したファイルのうち上位 5 件を、ファイルの全文および GitHub が検出した一致件数とともに返します。サーバーの稼働中、同じクエリに対する GitHub API の呼び出しの繰り返しを避けるため、メモリ内キャッシュを備えています。

パラメーター：

• keyword（文字列、必須）：dwarvesf/runbook リポジトリ内で検索するキーワードです。

戻り値： 検索結果を含む JSON オブジェクトです。

{
  "results": [ // An array of search results (limited to top 5)
    {
      "path": "string", // The path to the file in the repository
      "snippet": "string", // A snippet of the content where the keyword was found
      "full_content": "string" | null, // The full decoded content of the file, or null if fetching failed
      "url": "string" // The URL to the file on GitHub
    }
  ],
  "total_count": "number", // The total number of results found by GitHub's search
  "message": "string" // A message describing the result of the search, e.g., "Found and processed 5 results out of 10 total."
}

search_prompts

dwarvesf/prompt-db GitHub リポジトリ内（.synced_prompts/ フォルダーを除く）のキーワードをあいまい検索します。

パラメーター：

• keyword（文字列、必須）：dwarvesf/prompt-db リポジトリ内（.synced_prompts/ フォルダーを除く）で検索するキーワードです。

戻り値： 検索結果を含む JSON オブジェクトです。

{
  "results": [ // An array of search results (limited to top 5)
    {
      "path": "string", // The path to the file in the repository
      "snippet": "string", // A snippet of the content where the keyword was found
      "full_content": "string" | null, // The full decoded content of the file, or null if fetching failed
      "url": "string" // The URL to the file on GitHub
    }
  ],
  "total_count": "number", // The total number of results found by GitHub's search
  "message": "string" // A message describing the result of the search, e.g., "Found and processed 5 results out of 10 total."
}

suggest_runbook

新しいランブックエントリーを追加して、dwarvesf/runbook リポジトリ内の Pull Request を作成または更新します。

パラメーター：

• content（文字列、必須）：ランブックエントリーの Markdown コンテンツです。整理しやすくするため、先頭にフロントマター（--- title: ..., description: ..., date: ..., authors: ..., tags: ... ---）を含めてください。
• target_folder（文字列、必須）：dwarvesf/runbook リポジトリ内の対象フォルダーです。次のいずれかである必要があります：technical-patterns、operational-state-reporting、human-escalation-protocols、diagnostic-and-information-gathering、automations、action-policies-and-constraints。
• filename_slug（文字列、任意）：ファイル名に使用するスラッグです。
• pr_number（数値、任意）：更新する既存の Pull Request の番号です。
• branch_name（文字列、任意）：変更に使用するブランチ名です。提案：説明的な命名規則に従ってください（例：'feat/add-runbook-entry-slug'）。
• commit_message（文字列、任意）：ファイル変更のコミットメッセージです。
• pr_title（文字列、任意）：新しい Pull Request のタイトルです。commitlint の規約に従ってください（例：'feat: add new runbook entry'）。
• pr_body（文字列、任意）：新しい Pull Request の本文です。ランブックエントリーの背景と目的を説明する、包括的で詳細な内容を記述してください。

戻り値： 成功または失敗を示す JSON オブジェクトです。成功した場合は、PR 番号と URL も含まれます。

{
  "status": "success" | "error",
  "pr_number": "number" | undefined, // The number of the created or updated Pull Request.
  "pr_url": "string" | undefined, // The URL of the created or updated Pull Request.
  "message": "string" // Description of the result or error
}

sync_prompt

LLM プロンプトを dwarvesf/prompt-db GitHub リポジトリに同期します。

パラメーター：

• projectName（文字列、必須）：プロンプトが属するプロジェクト名です。
• promptName（文字列、必須）：プロジェクト内でのプロンプトの変数名または論理名です。
• promptContent（文字列、必須）：LLM プロンプトの実際の内容です。

戻り値： 成功または失敗を示す JSON オブジェクトです。成功した場合は、GitHub のパスと URL も含まれます。

{
  "status": "success" | "error",
  "github_path": "string" | undefined, // Path within the GitHub repository
  "github_url": "string" | undefined, // URL of the file on GitHub
  "commit_sha": "string" | undefined, // SHA of the commit if successful
  "commit_url": "string" | undefined, // URL of the commit if successful
  "message": "string" // Description of the result or error
}

think

何かについて考えるためにこのツールを使用します。新しい情報を取得したり、リポジトリに変更を加えたりせず、考えた内容を記録するだけです。複雑な推論やブレインストーミングが必要な場合に使用してください。たとえば、リポジトリを調査してバグの原因を見つけた場合は、このツールを呼び出して、バグを修正する独自の方法をいくつか検討し、どの変更が最も簡単で効果的かを評価できます。また、テスト結果を受け取った場合は、このツールを呼び出して、失敗したテストを修正する方法を検討できます。

パラメーター：

• thought（文字列、必須）：考えた内容です。

戻り値： 処理された考えを含む JSON オブジェクトです。サーバーはハンドラーが返した未加工の文字列をラップします。

{
  "content": [
    {
      "type": "text",
      "text": "\"Your processed thought here\"" // Note: The thought string itself will be JSON stringified
    }
  ]
}

または、エラーが発生した場合：

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "Error: Invalid arguments: Your error message"
    }
  ]
}

セットアップ

ローカル開発

1. リポジトリをクローンします：

   git clone [email protected]:dwarvesf/mcp-playbook.git
   cd mcp-playbook
   

2. 依存関係をインストールします：

   npm install
   

3. プロジェクトをビルドします：

   npm run build # This compiles TypeScript to JavaScript in the 'dist' directory
   

4. GitHub 認証を設定します（下記の設定セクションを参照してください）。
5. コンパイル済みのサーバーを実行します：

   node dist/src/index.js
   

Docker で実行する（任意）

Dockerfile は計画に含まれていますが、ここではまだ完全に実装されていません。完成後、Docker イメージをビルドして実行できます：

1. Docker イメージをビルドします：

   docker build -t mcp-playbook .
   

2. GITHUB_PERSONAL_ACCESS_TOKEN 環境変数が渡されていることを確認して、コンテナを実行します：

   docker run --pull=always -e GITHUB_PERSONAL_ACCESS_TOKEN="your_token" mcp-playbook
   

設定とテスト

save_and_upload_chat_log ツールでファイルを dwarvesf/prompt-log にアップロードするには、repo スコープを持つ GitHub Personal Access Token が必要です。このトークンは、GITHUB_PERSONAL_ACCESS_TOKEN 環境変数を介して指定する必要があります。

ローカル開発では、プロジェクトのルートにある .env ファイルを使用できます：

GITHUB_PERSONAL_ACCESS_TOKEN=your_github_token_here

.env が .gitignore ファイルに追加されていることを確認してください。

テスト

npm run build を実行し、出力先の index.js ファイルを参照するように MCP 設定を更新します。

{
  "mcpServers": {
    "mcp-playbook": {
      "command": "node",
      "args": ["/path/to/your/mcp-playbook/dist/src/index.js"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your_github_token_here"
      }
    }
  }
}

使用例

mcp_mcp-playbook_create_spec(target_project_dir="/Users/monotykamary/VCS/working-remote/my-new-project", spec_name="Initial Design", content="# Initial Design Specification\n\nThis document outlines the initial design of the project...")

トラブルシューティング

• 環境変数が設定されていない：mcp-playbook サーバープロセスが実行されている環境で、GITHUB_PERSONAL_ACCESS_TOKEN 環境変数が正しく設定されていることを確認してください。
• ファイル／ディレクトリが見つからない：サーバーは指定された target_project_dir 内で動作します。指定したパスが存在し、サーバープロセスからアクセスできることを確認してください。ファイルシステムエラー（ENOENT）は、多くの場合、パスが正しくないか、ディレクトリが存在しないことを示します。
• GitHub API エラー：save_and_upload_chat_log が失敗した場合は、githubApi.ts のエラー処理による詳細をサーバーログで確認してください。よくある問題には、トークンの誤り、権限不足、レート制限があります。

別のエンジニアへの引き継ぎガイダンス

• **自己完結型の実装：**このサーバーは、ファイルシステムや GitHub API とのやり取りに Node.js の fs と node-fetch を直接使用しており、環境が提供する外部の commander や github ツールは使用していません。
• **target_project_dir：**ユーザーファイルを操作するすべてのツールは target_project_dir を必須とし、その範囲内で動作します。このパスの入力検証はセキュリティ上重要です。
• **依存関係：**すべての npm 依存関係がインストールされていることを確認してください（npm install）。このプロジェクトでは TypeScript を使用しています。npm run build（または npx tsc）でコンパイルしてください。
• **認証：**GitHub 認証では、src/githubApi.ts の process.env から読み取る GITHUB_PERSONAL_ACCESS_TOKEN 環境変数のみを使用します。
• 会話履歴のプレースホルダー：src/handlers.ts の getConversationHistoryPlaceholder() 関数は ダミー実装 です。save_and_upload_chat_log ツールを正しく動作させるには、サーバーをホストする MCP フレームワークから実際の会話履歴を取得するロジックに 置き換える必要があります。
• MCP フレームワークとの統合：src/handlers.ts のハンドラー関数は、LLM からツール呼び出しを受け取り、ルーティングする外部 MCP フレームワークから呼び出されるように設計されています。src/index.ts ファイルは、この統合における概念上のエントリーポイントです。