ComposioHQ/mcp-builder

MCPサーバー開発ガイド

概要

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

---

プロセス

🚀 高レベルのワークフロー

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

フェーズ1: 深い調査と計画

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

実装に入る前に、以下の原則を確認して、AIエージェント向けのツールを設計する方法を理解してください。

ワークフロー向けに構築する（単なるAPIエンドポイントではない）:

• 既存のAPIエンドポイントを単にラップするのではなく、思慮深く影響力の高いワークフローツールを構築する
• 関連する操作を統合する（例: schedule_event は空き状況の確認とイベント作成の両方を行う）
• 個々のAPI呼び出しではなく、完全なタスクを可能にするツールに焦点を当てる
• エージェントが実際に達成する必要があるワークフローを考慮する

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

• エージェントは限られたコンテキストウィンドウを持っているため、すべてのトークンを有効活用する
• 情報を詰め込みすぎず、シグナルの強い情報を返す
• 「簡潔」と「詳細」のレスポンス形式オプションを提供する
• 技術的なコード（ID）よりも人間が読める識別子（名前）をデフォルトで使用する
• エージェントのコンテキスト予算を希少リソースと考える

アクション可能なエラーメッセージを設計する:

• エラーメッセージはエージェントを正しい使用パターンに導くものであるべき
• 具体的な次のステップを提案する: 「フィルター='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 ファイルを作成するか、複雑な場合はモジュールに整理する（🐍 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）を使用する
• 適切な制約（最小/最大長、正規表現パターン、最小/最大値、範囲）を含める
• 明確で説明的なフィールドの説明を提供する
• フィールドの説明に多様な例を含める

包括的なドキュメンテーション文字列/説明を記述する:

• ツールが何を行うかを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<T> 戻り値の型
• ビルドプロセスの設定（npm run build）

---

フェーズ3: レビューと改良

初期実装後:

3.1 コード品質レビュー

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

• DRY原則: ツール間で重複コードがない
• コンポーザビリティ: 共有ロジックが関数に抽出されている
• 一貫性: 同様の操作は同様のフォーマットを返す
• エラーハンドリング: すべての外部呼び出しにエラーハンドリングがある
• 型安全性: 完全な型カバレッジ（Pythonの型ヒント、TypeScriptの型）
• ドキュメンテーション: すべてのツールに包括的なドキュメンテーション文字列/説明がある

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個の評価質問を作成する

効果的な評価を作成するには、評価ガイドで概説されているプロセスに従います:

1. ツールの検査: 利用可能なツールをリストアップし、その機能を理解する
2. コンテンツの探索: 読み取り専用操作を使用して利用可能なデータを探索する
3. 質問の生成: 10個の複雑で現実的な質問を作成する
4. 回答の検証: 各質問を自分で解いて回答を検証する

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