mcp-builder

MCP サーバー開発ガイド

プロセス

契約

入力：

• 要求された統合、対象リポジトリ、API ドキュメント、および承認済みのサービス範囲

出力：

• MCP サーバーの実装、ツールの契約、および範囲を限定した検証エビデンス

作成／変更対象：

• 要求されたサーバーに必要なソース、テスト、および評価フィクスチャ

外部への副作用：

• ドキュメントの参照。プロバイダーへの呼び出しや有料評価は、承認された場合に限ります

確認が必要な操作：

• 認証情報を使ったサービスへの書き込み、有料評価の実行、公開、または要求された範囲外でのエージェント設定の前
• スキルを読み込んでも権限は追加されません。既存の明示的な承認は、同じ対象および操作にのみ適用されます。報告のみという制限を維持してください。

委任先：

• なし

全体的なワークフロー

MCP サーバーは、次の4つのフェーズで構築します。

フェーズ 1：徹底的な調査と計画

1.1 エージェント中心の設計原則を理解する

実装の前に、エージェントのワークフローを中心にツールを設計します。

API エンドポイントではなく、ワークフローを中心に構築する：

• 既定ですべての API エンドポイントをそのまま反映するのは避けてください。1つのユーザータスクで複数の API 呼び出しが必要な場合は、エンドポイントをワークフローツールにまとめます。
• 関連する操作を統合します（例：空き状況の確認とイベントの作成を行う schedule_event）。
• 主なユーザーワークフローを列挙し、各ツールを1つのワークフローに対応付けます。

限られたコンテキストに最適化する：

• 既定では、タスクに必要なフィールドのみを返します。
• 網羅的なデータではなく、重要度の高い情報を返します。
• 「簡潔」と「詳細」の応答形式を選べるようにします。
• 技術的なコードよりも、人が読みやすい識別子を既定で使用します（ID より名前）。
• 大きな応答には、ページネーション、フィールド選択、または切り詰めを追加します。

実行可能なエラーメッセージを設計する：

• エラーメッセージには、失敗したフィールドまたは操作、原因、および次に実行できる操作を含めます。
• 具体的な次の手順を提案します：「結果を絞り込むには、filter='active_only' を使用してみてください」
• ツールレベルの説明を付けずに、プロバイダーの生のエラーを返してはいけません。

自然なタスクの区分に従う：

• ツール名は、人がタスクをどう考えるかを反映する必要があります。
• 関連するツールには一貫性のある接頭辞を付け、見つけやすくします。
• API の構造だけではなく、自然なワークフローを中心にツールを設計します。

評価主導の開発を行う：

• 現実的な評価シナリオを早期に作成します。
• エージェントからのフィードバックをツールの改善に反映します。
• すばやくプロトタイプを作成し、実際のエージェントのパフォーマンスに基づいて反復します。

1.2 MCP プロトコルのドキュメントを調査する

MCP プロトコルのドキュメントを取得します：

取得先：https://modelcontextprotocol.io/llms-full.txt

このドキュメントには、MCP の仕様全体が含まれています。注：仕様の進化に伴い、URL が変更される場合があります。取得に失敗した場合は、現在の MCP ドキュメントの URL を検索してください。

1.3 フレームワークのドキュメントを調査する

次のリファレンスファイルを読み込み、内容を確認します：

• MCP のベストプラクティス：📋 ベストプラクティスを表示 - すべての MCP サーバーに共通する基本ガイドライン

Python 実装の場合は、以下も読み込みます：

• Python SDK ドキュメント：https://py.sdk.modelcontextprotocol.io/ を取得します
• 🐍 Python 実装ガイド - Python 固有のベストプラクティスと例

Node／TypeScript 実装の場合は、以下も読み込みます：

• TypeScript SDK ドキュメント：https://ts.sdk.modelcontextprotocol.io/ を取得します
• ⚡ TypeScript 実装ガイド - Node／TypeScript 固有のベストプラクティスと例

1.4 API ドキュメントを調べる

サービスを統合するには、選択したワークフローに関する API ドキュメントを読みます。 エンドポイントとパラメーターの確認範囲はそれらのワークフローに限定します。ただし、 横断的な事項（認証、レート制限、エラー処理、データモデル）は、公開するすべての ツールに適用されるため、すべて確認してください。

• 公式 API リファレンスドキュメント
• 認証と認可の要件
• レート制限とページネーションのパターン
• エラーレスポンスとステータスコード
• 利用可能なエンドポイントとそのパラメーター
• データモデルとスキーマ

選択したワークフローを妨げる未解決の問題がある場合にのみ、ドキュメントを検索または取得してください。

1.5 実装計画を作成する

次のセクションを含む計画を作成します。

ツールの選定：

• 実装する価値が最も高いエンドポイント／操作を列挙します
• 最も一般的で重要なユースケースを可能にするツールを優先します
• 複雑なワークフローを実現するために、どのツールが連携して使えるかを検討します

共通ユーティリティとヘルパー：

• 共通する API リクエストのパターンを特定します
• ページネーションヘルパーを計画します
• フィルタリングとフォーマット用のユーティリティを設計します
• エラー処理の戦略を計画します

入力／出力の設計：

• 入力検証モデルを定義します（Python では Pydantic、TypeScript では Zod）
• 一貫したレスポンス形式（例：JSON または Markdown）と、設定可能な詳細度（例：詳細または簡潔）を設計します
• 大規模な利用（数千人のユーザー／リソース）に備えます
• 文字数制限と切り捨ての方法（例：25,000 トークン）を実装します

エラー処理戦略：

• 適切に処理される失敗時の動作を計画します
• 各エラーの形式として、エラーコード、人が読んで分かる原因、再試行の可否、 次に実行できる操作を定義します。
• レート制限とタイムアウトの状況を考慮します
• 認証および認可エラーを処理します

---

フェーズ 2：実装

計画を作成したら、個々のツールを実装する前に共通インフラストラクチャを実装します。

2.1 プロジェクト構成を設定する

Python の場合：

• 単一の .py ファイルを作成するか、複雑な場合はモジュールに整理します（🐍 Python ガイドを参照）
• ツールの登録には MCP Python SDK を使用します
• 入力検証用の Pydantic モデルを定義します

Node／TypeScript の場合：

• ⚡ TypeScript ガイドに従ってプロジェクト構成を作成します
• package.json と tsconfig.json を設定します
• MCP TypeScript SDK を使用します
• 入力検証用の Zod スキーマを定義します

2.2 まずコアインフラストラクチャを実装する

実装を始めるには、ツールを実装する前に共通ユーティリティを作成します。

• API リクエスト用ヘルパー関数
• エラー処理ユーティリティ
• レスポンスのフォーマット関数（JSON と Markdown）
• ページネーションヘルパー
• 認証／トークン管理

2.3 ツールを体系的に実装する

計画に含まれる各ツールについて、次の手順に従います。

入力スキーマを定義する：

• 検証には Pydantic（Python）または Zod（TypeScript）を使用します
• 制約（最小／最大の長さ、正規表現パターン、最小／最大の値、範囲）を含めます
• フィールドの目的、受け付ける値、デフォルト値を説明します
• フィールドの説明には多様な例を含めます

ツールの docstring／説明を書く：

• ツールの機能を一文で要約します
• 目的と機能
• 例を含む明示的なパラメーター型
• 戻り値の型スキーマ
• 使用例（使用する状況と使用しない状況）
• 特定のエラーが発生した場合の対処方法を示すエラー処理の説明

ツールのロジックを実装する：

• コードの重複を避けるため、共通ユーティリティを使用します
• すべての I/O で async/await パターンに従います
• 計画したエラー形式を実装します
• 複数のレスポンス形式（JSON と Markdown）に対応します
• ページネーションパラメーターを尊重します
• 文字数制限を確認し、適切に切り詰めます

ツールアノテーションを追加する：

• readOnlyHint: true（読み取り専用操作の場合）
• destructiveHint: false（破壊的でない操作の場合）
• idempotentHint: true（呼び出しを繰り返しても同じ効果が得られる場合）
• openWorldHint: true（外部システムと連携する場合）

2.4 言語固有のベストプラクティスに従う

実装を完了する前に、該当するガイド（🐍 Python Implementation Guide または ⚡ TypeScript Implementation Guide）を読み込み、そのパターンに従ってください。適切な SDK ツール登録（@mcp.tool / server.registerTool）、厳格な入力検証（Pydantic v2 model_config / Zod .strict()）、any を使わない完全な型カバレッジ、すべての I/O に対する async/await、共有値のモジュールレベル定数（例：CHARACTER_LIMIT、API_BASE_URL）、さらに TypeScript の場合は動作する bun run build が含まれます。

---

フェーズ 3：レビューと改善

初期実装の後に、以下を行います。

3.1 コード品質のレビュー

次の点についてコードをレビューします。

• DRY 原則：ツール間でコードを重複させない
• コンポーザビリティ：共有ロジックを関数に切り出す
• 一貫性：類似する操作では類似した形式を返す
• エラー処理：すべての外部呼び出しでエラーを処理する
• 型安全性：完全な型カバレッジ（Python の型ヒント、TypeScript の型）
• ドキュメント：各ツールに概要、パラメーター、戻り値の形式、使用例、 エラー時の動作を記載する

3.2 テストとビルド

重要： MCP サーバーは、stdio/stdin または sse/http 経由のリクエストを待つ長時間実行プロセスです。メインプロセスで直接実行すると（例：python server.py または node dist/index.js）、メインプロセスが無期限に停止します。

安全にテストする方法：メインプロセスとは別に実行できるよう tmux でサーバーを起動する、タイムアウトを使用する（timeout 5s python server.py）、または stdio トランスポートの場合は評価ハーネス（フェーズ 4）にサーバーのサブプロセスを直接管理させます。

• Python： python -m py_compile your_server.py で構文を確認し、インポートをレビューします。
• Node/TypeScript： bun run build を実行し、エラーなく完了することを確認して、dist/index.js が作成されたことを確認します。

3.3 品質チェックリストを使用する

実装の品質を確認するには、言語固有のガイドから該当するチェックリストを読み込みます。

• Python：🐍 Python Guide の「Quality Checklist」を参照
• Node/TypeScript：⚡ TypeScript Guide の「Quality Checklist」を参照

---

フェーズ 4：評価を作成する

MCP サーバーを実装した後、エージェントがツールを使って現実的な質問に回答できるかをテストする評価を作成します。

評価ガイドラインの詳細は、✅ Evaluation Guide を読み込んでください。

4.1 評価の目的を理解する

評価では、LLM が MCP サーバーを効果的に使用して、現実的で複雑な質問に回答できるかをテストします。

4.2 評価用の質問を 10 個作成する

評価ガイドに記載された手順に従います。

1. ツールの確認：利用可能なツールを一覧表示し、その機能を理解する
2. コンテンツの探索：読み取り専用の操作で利用可能なデータを探索する
3. 質問の作成：複雑で現実的な質問を 10 個作成する
4. 回答の検証：各質問を自分で解いて回答を検証する

4.3 評価要件

各質問は、次の要件を満たす必要があります。

• 独立性：他の質問に依存しない
• 読み取り専用：破壊的でない操作のみが必要
• 複雑性：複数のツール呼び出しと詳細な探索が必要
• 現実性：人々が関心を持つ現実のユースケースに基づいている
• 検証可能性：文字列比較で検証できる、明確で一意の回答がある
• 安定性：時間が経っても回答が変わらない

4.4 出力形式

次の構造の XML ファイルを作成します。

<evaluation>
  <qa_pair>
    <question>Find discussions about AI model launches with animal codenames. One model needed a specific safety designation that uses the format ASL-X. What number X was being determined for the model named after a spotted wild cat?</question>
    <answer>3</answer>
  </qa_pair>

</evaluation>

---

注意点

• サーバーを直接実行すると、プロセスが終了しません。 MCP サーバーは、リクエストを待つ間、stdio/stdin をブロックし続けます。メインプロセスで python server.py や node dist/index.js を実行しないでください。tmux を使ってサーバーをバックグラウンドで実行するか、サーバーのサブプロセスを管理する評価ハーネスを使用してください。
• 最新の URL 参照先は変更されている可能性があります。 MCP プロトコルのドキュメント URL（modelcontextprotocol.io/llms-full.txt）や GitHub SDK の README URL は、バージョン間で移動する場合があります。取得に失敗した場合は、スキルのパスが正しいと決めつけず、現在の URL を検索してください。
• TypeScript のソースを変更したら、必ずビルドを再実行してください。 MCP ランタイムが読み込む成果物は dist/index.js です。.ts ファイルを編集した後に bun run build を実行しないと、ランタイムでは古いバージョンが実行されます。
• ツールのアノテーションはヒントであり、強制される契約ではありません。 readOnlyHint: true を設定しても、ツールによるデータの書き込みは防止されません。これは LLM に意図を伝えるだけです。安全性はツールの実装自体で確保してください。

---

リファレンスファイル

実装言語とフェーズに必要なリソースのみを読み込んでください。

ファイル	読み込むタイミング	内容
references/mcp_best_practices.md	フェーズ 1.3（最初に読み込む）	命名規則、レスポンス形式（JSON と Markdown）、ページネーション、文字数制限／切り捨て、セキュリティとエラー処理の標準
references/python_mcp_server.md	フェーズ 2（Python）	サーバーの初期化、Pydantic モデル、@mcp.tool による登録、実用例、品質チェックリスト
references/node_mcp_server.md	フェーズ 2（TypeScript）	プロジェクト構成、Zod スキーマ、server.registerTool、実用例、品質チェックリスト
references/evaluation.md	フェーズ 4	質問の作成と回答の検証に関するガイドライン、XML 形式、Q&A の例、評価の実行

必要に応じて、最新のプロトコル／SDK ドキュメントも取得してください。MCP プロトコル仕様（https://modelcontextprotocol.io/llms-full.txt）、Python SDK（https://py.sdk.modelcontextprotocol.io/）、TypeScript SDK（https://ts.sdk.modelcontextprotocol.io/）。