mcp-builder

MCP サーバー開発ガイド

概要

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

大まかなワークフロー

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

フェーズ 1：詳細な調査と計画

エージェント中心の設計原則

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

• 既存の API エンドポイントを単にラップするのではなく、よく考えられた、影響力の大きいワークフローツールを構築します
• 関連する操作を統合します（例：空き状況の確認とイベントの作成を両方行う schedule_event）
• 個々の API 呼び出しだけでなく、タスク全体を完了できるツールに重点を置きます

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

• エージェントのコンテキストウィンドウには制限があるため、すべてのトークンを有効活用します
• 網羅的なデータの羅列ではなく、重要度の高い情報を返します
• 「簡潔」と「詳細」のレスポンス形式を選べるようにします
• 技術的なコードより、人が読みやすい識別子をデフォルトで使用します

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

• エラーメッセージは、エージェントを正しい使い方へ導くようにします
• 具体的な次の手順を提案します：「結果を絞り込むには filter='active_only' を使用してみてください」
• エラーは単なる診断ではなく、学びにつながるものにします

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

最新の MCP プロトコルドキュメントを取得します： WebFetch を使用して、次を読み込みます：https://modelcontextprotocol.io/llms-full.txt

Python の実装の場合：

• Python SDK：https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md

Node/TypeScript の実装の場合：

• TypeScript SDK：https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md

フェーズ 2：実装

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

Python の場合：

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

Node/TypeScript の場合：

• 適切なプロジェクト構成を作成します
• package.json と tsconfig.json を設定します
• MCP TypeScript SDK を使用します
• 入力検証用の Zod スキーマを定義します

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

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

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

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

各ツールについて：

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

• 検証には Pydantic（Python）または Zod（TypeScript）を使用します
• 適切な制約（最小／最大文字数、正規表現パターンなど）を設定します
• 明確で説明的なフィールドの説明を記述します

包括的な docstring を記述する：

• ツールの機能を1行で要約します
• 目的と機能を詳しく説明します
• 例を含む、明示的なパラメーター型を記載します
• 戻り値の型スキーマを完全に記載します
• 使用例を記載します

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

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

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

コード品質のレビュー

次の点についてコードを確認します：

• DRY 原則：ツール間でコードを重複させない
• 合成可能性：共通ロジックを関数に抽出する
• 一貫性：類似した操作は類似した形式で結果を返す
• エラー処理：すべての外部呼び出しにエラー処理を実装する
• 型安全性：すべてのコードで型を網羅する
• ドキュメント：すべてのツールに包括的な docstring を用意する

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

MCP サーバーの有効性をテストするために、包括的な評価を作成します。

各評価の質問は、次の条件を満たす必要があります：

• 独立している：ほかの質問に依存しない
• 読み取り専用である：破壊的でない操作のみを必要とする
• 複雑である：複数のツール呼び出しと詳細な調査を必要とする
• 現実的である：実際のユースケースに基づいている
• 検証可能である：検証できる、明確で一意な回答がある

ベストプラクティスのまとめ

1. API エンドポイントだけでなく、ワークフローに合わせて構築します
2. 限られたコンテキストウィンドウに合わせて最適化します
3. 対処方法が分かるエラーメッセージを設計します
4. 自然なタスクの区分に従います
5. 評価主導の開発を行います
6. フレームワークのドキュメントを十分に調べます
7. まずコアインフラストラクチャを実装します
8. 適切なツールアノテーションを追加します
9. 現実的なシナリオでテストします