MCPサーバー開発ガイド
概要
高品質なMCP（Model Context Protocol）サーバーを作成し、LLMが外部サービスと効果的に対話できるようにするには、このスキルを使用します。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リファレンス文書
- 認証と承認の要件
- レート制限とページネーションパターン
- エラーレスポンスとステータスコード
- 利用可能なエンドポイントとそのパラメータ
- データモデルとスキーマ
包括的な情報を収集するには、必要に応じてWeb検索とWebFetchツールを使用してください。
1.6 包括的な実装計画を作成する
調査に基づいて、以下を含む詳細な計画を作成します。
ツールの選択：
- 実装する最も価値のあるエンドポイント/操作をリストアップする
- 最も一般的で重要なユースケースを可能にするツールを優先する
- 複雑なワークフローを可能にするために連携するツールを検討する
共有ユーティリティとヘルパー：
- 共通のAPIリクエストパターンを特定する
- ページネーションヘルパーを計画する
- フィルタリングとフォーマットのユーティリティを設計する
- エラーハンドリング戦略を計画する
入出力設計：
- 入力検証モデルを定義する（PythonではPydantic、TypeScriptではZod）
- 一貫したレスポンス形式（例：JSONまたはMarkdown）と、設定可能な詳細レベル（例：詳細または簡潔）を設計する
- 大規模な使用（数千のユーザー/リソース）に備える
- 文字数制限と切り捨て戦略を実装する（例：25,000トークン）
エラーハンドリング戦略：
- グレースフルな障害モードを計画する
- LLMにとって明確でアクション可能、かつ自然言語によるエラーメッセージを設計し、さらなるアクションを促す
- レート制限とタイムアウトシナリオを考慮する
- 認証と承認のエラーを処理する
フェーズ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/説明を記述する：
- ツールの機能を1行で要約
- 目的と機能の詳細な説明
- 例を含む明示的なパラメータタイプ
- 完全な戻り値の型スキーマ
- 使用例（いつ使用するか、いつ使用しないか）
- 特定のエラーが発生した場合の対処方法を概説したエラーハンドリング文書
ツールロジックを実装する：
- 共有ユーティリティを使用してコードの重複を避ける
- すべてのI/Oにasync/awaitパターンを使用する
- 適切なエラーハンドリングを実装する
- 複数のレスポンス形式（JSONおよびMarkdown）をサポートする
- ページネーションパラメータを尊重する
- 文字数制限をチェックし、適切に切り捨てる
ツールアノテーションを追加する：
readOnlyHint：true（読み取り専用操作の場合）destructiveHint：false（非破壊的操作の場合）idempotentHint：true（同じ効果で繰り返し呼び出せる場合）openWorldHint：true（外部システムと対話する場合）
2.4 言語固有のベストプラクティスに従う
この時点で、適切な言語ガイドを読み込んでください：
Pythonの場合：🐍 Python実装ガイドを読み込み、以下を確認します：
- 適切なツール登録によるMCP Python SDKの使用
model_configを使用したPydantic v2モデル- コード全体での型ヒント
- すべてのI/O操作でのasync/await
- 適切なインポートの整理
- モジュールレベルの定数（CHARACTER_LIMIT、API_BASE_URL）
Node/TypeScriptの場合：⚡ TypeScript実装ガイドを読み込み、以下を確認します：
server.registerToolの適切な使用.strict()を使用したZodスキーマ- TypeScript strictモードの有効化
any型は使用しない - 適切な型を使用する- 明示的なPromise戻り値の型
- ビルドプロセスの設定（
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ガイドの「品質チェックリスト」を参照
- Node/TypeScript：⚡ TypeScriptガイドの「品質チェックリスト」を参照
フェーズ4：評価を作成する
MCPサーバーを実装した後、その効果をテストするための包括的な評価を作成します。
完全な評価ガイドラインについては、✅ 評価ガイドを読み込んでください。
4.1 評価の目的を理解する
評価は、LLMがMCPサーバーを効果的に使用して、現実的で複雑な質問に回答できるかどうかをテストします。
4.2 10個の評価質問を作成する
効果的な評価を作成するには、評価ガイドで概説されているプロセスに従います：
- ツールの調査：利用可能なツールをリストアップし、その機能を理解する
- コンテンツの探索：読み取り専用操作を使用して利用可能なデータを探索する
- 質問の生成：10個の複雑で現実的な質問を作成する
- 回答の検証：各質問を自分で解いて回答を検証する
4.3 評価要件
各質問は以下を満たす必要があります：
- 独立している：他の質問に依存しない
- 読み取り専用：非破壊的操作のみが必要
- 複雑：複数のツール呼び出しと深い探索が必要
- 現実的：人間が気にする実際のユースケースに基づく
- 検証可能：文字列比較で検証できる単一の明確な回答がある
- 安定している：回答が時間とともに変わらない
4.4 出力形式
以下の構造のXMLファイルを作成します：
<evaluation>
<qa_pair>
<question>AIモデルランチについて、動物のコードネームを使用した議論を見つけてください。あるモデルには、ASL-X形式の特定の安全性指定が必要でした。斑点のある野生の猫にちなんで名付けられたモデルに対して決定されたXの番号はいくつですか？</question>
<answer>3</answer>
</qa_pair>
<!-- さらにqa_pairs... -->
</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によるツール登録- 完全な動作例
- 品質チェックリスト