mcp-builder

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 に配慮した自然言語のエラーメッセージを設計します
• レート制限やタイムアウトの状況を考慮します
• 認証および認可エラーを処理します

---

Phase 2: Implementation

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

2.1 Set Up Project Structure

Python の場合：

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

Node/TypeScript の場合：

• 適切なプロジェクト構造を作成します（⚡ TypeScript Guide を参照）
• 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 実装ガイドを読み込み、以下を確認してください。

• 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<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 ガイドの「Quality Checklist」を参照
• Node/TypeScript：⚡ TypeScript ガイドの「Quality Checklist」を参照

---

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

MCP サーバーを実装した後、その有効性をテストするための包括的な評価を作成してください。

完全な評価ガイドラインについては、✅ 評価ガイドを読み込んでください。

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 形式の仕様
  • 質問と回答の例
  • 提供されたスクリプトを使った評価の実行