build-mcp

MCP サーバー開発ガイド

概要

LLM が外部サービスと効果的にやり取りできる、高品質な MCP（Model Context Protocol）サーバーを作成するには、このスキルを使用してください。MCP サーバーは、LLM が外部サービスや API にアクセスできるツールを提供します。MCP サーバーの品質は、提供するツールを使って LLM が実際のタスクをどれだけうまく達成できるかで測られます。

---

プロセス

🚀 大まかなワークフロー

高品質な MCP サーバーの作成には、主に 4 つのフェーズがあります。

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

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

実装に取りかかる前に、以下の原則を確認して、AI エージェント向けのツール設計について理解しましょう。

API エンドポイントだけでなく、ワークフローに対応する：

• 既存の API エンドポイントをそのままラップするのではなく、よく考えられた、効果の高いワークフローツールを構築します
• 関連する操作を統合します（例：空き状況の確認とイベントの作成を両方行う schedule_event）
• 個々の API 呼び出しだけでなく、タスク全体を完了できるツールに重点を置きます
• エージェントが実際にどのようなワークフローを達成する必要があるかを検討します

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

• エージェントのコンテキストウィンドウには制限があるため、すべてのトークンを有効に使います
• 網羅的なデータのダンプではなく、重要度の高い情報を返します
• 「簡潔」と「詳細」の応答形式を選べるようにします
• 技術的なコードではなく、人が読みやすい識別子をデフォルトにします（ID より名前）
• エージェントのコンテキスト予算は限られたリソースとして扱います

実行に役立つエラーメッセージを設計する：

• エラーメッセージは、エージェントが正しい使い方を選べるように案内する必要があります
• 具体的な次の手順を提案します：「結果を絞り込むには、filter='active_only' を試してください」
• エラーを単なる診断にとどめず、学びにつながるものにします
• 明確なフィードバックを通じて、エージェントがツールの適切な使い方を学べるようにします

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

• ツール名には、人がタスクについて考えるときの表現を反映させます
• 関連するツールを一貫した接頭辞でグループ化し、見つけやすくします
• API の構造だけでなく、自然なワークフローを中心にツールを設計します

評価主導の開発を取り入れる：

• 現実的な評価シナリオを早い段階で作成します
• エージェントからのフィードバックをツールの改善に活用します
• すばやくプロトタイプを作成し、実際のエージェントの性能に基づいて反復します

1.3 MCP プロトコルのドキュメントを確認する

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

WebFetch を使用して、以下を読み込みます：https://modelcontextprotocol.io/llms-full.txt

この包括的なドキュメントには、MCP の仕様とガイドラインがすべて記載されています。

1.4 フレームワークのドキュメントを確認する

以下の参考ファイルを読み込み、内容を確認します：

• MCP のベストプラクティス：📋 ベストプラクティスを見る - すべての MCP サーバーに適用される基本的なガイドライン

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

• Python SDK のドキュメント：WebFetch を使用して https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md を読み込みます
• 🐍 Python 実装ガイド - Python に固有のベストプラクティスと例

Node/TypeScript で実装する場合は、以下も読み込みます：

• TypeScript SDK のドキュメント：WebFetch を使用して https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md を読み込みます
• ⚡ TypeScript 実装ガイド - Node/TypeScript に固有のベストプラクティスと例

1.5 API ドキュメントを網羅的に確認する

サービスを統合するには、利用可能な API ドキュメントをすべて読み込みます。

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

包括的な情報を収集するには、必要に応じてウェブ検索と WebFetch ツールを使用してください。

1.6 包括的な実装計画を作成する

調査結果に基づいて、次の内容を含む詳細な計画を作成します。

ツールの選定：

• 実装する価値が最も高いエンドポイント／操作をリストアップします
• 最も一般的で重要なユースケースを可能にするツールを優先します
• 複雑なワークフローを実現するために、どのツールを組み合わせて使うかを検討します

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

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

入出力の設計：

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

エラー処理の方針：

• 適切なフォールバック動作を計画します
• 次のアクションを促す、明確で実行可能かつ LLM に適した自然言語のエラーメッセージを設計します
• レート制限やタイムアウトが発生した場合を検討します
• 認証エラーと認可エラーに対処します

---

フェーズ 2：実装

包括的な計画ができたら、言語ごとのベストプラクティスに従って実装を開始します。

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

Python の場合：

• .py ファイルを 1 つ作成するか、複雑な場合はモジュールに分割します（🐍 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 の場合：🐍 Python Implementation Guide を読み込み、以下を徹底してください：

• 適切なツール登録で MCP Python SDK を使用する
• model_config を使用した Pydantic v2 モデル
• 全体を通じた型ヒントの使用
• すべての I/O 操作で async/await を使用する
• 適切に整理されたインポート
• モジュールレベルの定数（CHARACTER_LIMIT、API_BASE_URL）

Node/TypeScript の場合：⚡ TypeScript Implementation Guide を読み込み、以下を徹底してください：

• server.registerTool を適切に使用する
• .strict() を使用した Zod スキーマ
• TypeScript の strict モードを有効にする
• any 型を使用せず、適切な型を使う
• Promise<T> の戻り値の型を明示する
• ビルドプロセスを設定する（npm run build）

---

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

初期実装の完了後：

3.1 コード品質レビュー

品質を確保するため、コードをレビューして以下を確認してください：

• DRY 原則：ツール間でコードが重複していない
• 構成可能性：共通ロジックが関数として切り出されている
• 一貫性：類似した操作が類似した形式で結果を返す
• エラー処理：すべての外部呼び出しでエラー処理を行う
• 型安全性：型が全面的にカバーされている（Python の型ヒント、TypeScript の型）
• ドキュメント：すべてのツールに包括的な docstring／説明がある

3.2 テストとビルド

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

サーバーを安全にテストする方法：

• 評価ハーネスを使用する（フェーズ 4 を参照）。推奨される方法です
• tmux でサーバーを実行し、メインプロセスの外で動作させる
• テスト時にタイムアウトを使用する：timeout 5s python server.py

Python の場合：

• Python の構文を検証する：python -m py_compile your_server.py
• ファイルを確認し、インポートが正しく動作することを確認する
• 手動でテストする場合：tmux でサーバーを実行し、メインプロセスで評価ハーネスを使ってテストする
• または評価ハーネスを直接使用する（stdio トランスポート用にサーバーを管理します）

Node/TypeScript の場合：

• npm run build を実行し、エラーなく完了することを確認する
• dist/index.js が作成されたことを確認する
• 手動でテストする場合：tmux でサーバーを実行し、メインプロセスで評価ハーネスを使ってテストする
• または評価ハーネスを直接使用する（stdio トランスポート用にサーバーを管理します）

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 ドキュメント (最初に読み込む)

• MCP プロトコル: https://modelcontextprotocol.io/llms-full.txt から取得 - 完全な MCP 仕様
• 📋 MCP ベストプラクティス - 以下を含む普遍的な MCP ガイドライン:
  • サーバーとツールの命名規則
  • レスポンス形式のガイドライン (JSON 対 Markdown)
  • ページネーションのベストプラクティス
  • 文字数制限と切り詰め戦略
  • ツール開発ガイドライン
  • セキュリティとエラー処理の標準

SDK ドキュメント (フェーズ 1/2 で読み込む)

• Python SDK: https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md から取得
• TypeScript SDK: https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md から取得

言語固有の実装ガイド (フェーズ 2 で読み込む)

• 🐍 Python 実装ガイド - 以下を含む完全な Python/FastMCP ガイド:

  • サーバー初期化パターン
  • Pydantic モデルの例
  • @mcp.tool によるツール登録
  • 完全な動作例
  • 品質チェックリスト

• ⚡ TypeScript 実装ガイド - 以下を含む完全な TypeScript ガイド:

  • プロジェクト構造
  • Zod スキーマパターン
  • server.registerTool によるツール登録
  • 完全な動作例
  • 品質チェックリスト

評価ガイド (フェーズ 4 で読み込む)

• ✅ 評価ガイド - 以下を含む完全な評価作成ガイド:
  • 質問作成のガイドライン
  • 回答検証の戦略
  • XML 形式の仕様
  • 質問と回答の例
  • 提供されたスクリプトを使用した評価の実行