mcp-builder

MCP サーバー開発ガイド

概要

LLM が適切に設計されたツールを通じて外部サービスとやり取りできるようにする、MCP（Model Context Protocol）サーバーを作成します。MCP サーバーの品質は、LLM が実際のタスクをどれだけうまく達成できるかによって評価されます。

---

プロセス

🚀 大まかなワークフロー

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

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

1.1 最新の MCP 設計を理解する

API の網羅性とワークフローツール： API エンドポイントを幅広く網羅することと、特定のワークフローに特化したツールのバランスを取ります。ワークフローツールは特定のタスクでより便利な場合があり、API を幅広く網羅すると、エージェントが柔軟に操作を組み合わせられます。パフォーマンスはクライアントによって異なります。基本的なツールを組み合わせるコード実行が役立つクライアントもあれば、高レベルのワークフローのほうが適しているクライアントもあります。判断に迷った場合は、API を幅広く網羅することを優先してください。

ツールの命名と見つけやすさ： 明確で説明的なツール名を付けると、エージェントが適切なツールをすばやく見つけやすくなります。一貫したプレフィックス（例：github_create_issue、github_list_repos）を使用し、アクションが伝わる名前を付けてください。

コンテキスト管理： 簡潔なツールの説明と、結果をフィルタリングしたりページ分割したりできる機能は、エージェントにとって役立ちます。焦点を絞った関連データを返すツールを設計してください。一部のクライアントはコード実行に対応しており、エージェントが効率的にデータをフィルタリングして処理するのに役立ちます。

実行可能なエラーメッセージ： エラーメッセージには、具体的な提案と次の手順を示し、エージェントが解決策を見つけられるようにしてください。

1.2 MCP プロトコルのドキュメントを調べる

MCP 仕様を確認する：

サイトマップから関連するページを探してください：https://modelcontextprotocol.io/sitemap.xml

次に、Markdown 形式で特定のページを取得するには、.md サフィックスを付けてください（例：https://modelcontextprotocol.io/specification/draft.md）。

確認すべき主なページ：

• 仕様の概要とアーキテクチャ
• トランスポート方式（ストリーミング可能な HTTP、stdio）
• ツール、リソース、プロンプトの定義

1.3 フレームワークのドキュメントを調べる

推奨スタック：

• 言語：TypeScript（高品質な SDK サポートがあり、多くの実行環境（例：MCPB）で優れた互換性があります。また、AI モデルは TypeScript コードの生成が得意です。広く使われており、静的型付けに対応し、優れたリンターツールが利用できるためです）
• トランスポート：リモートサーバーにはステートレス JSON を使用するストリーミング可能な HTTP（ステートフルなセッションやストリーミングレスポンスに比べ、スケーリングと保守が容易です）。ローカルサーバーには stdio を使用します。

フレームワークのドキュメントを読み込む：

• MCP のベストプラクティス：ベストプラクティスを見る - 基本的なガイドライン

TypeScript の場合（推奨）：

• TypeScript SDK：WebFetch を使って https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md を読み込みます
• ⚡ TypeScript ガイド - TypeScript のパターンと例

Python の場合：

• Python SDK：WebFetch を使って https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md を読み込みます
• 🐍 Python ガイド - Python のパターンと例

1.4 実装を計画する

API を理解する： サービスの API ドキュメントを確認し、主要なエンドポイント、認証要件、データモデルを特定します。必要に応じて、ウェブ検索と WebFetch を使用してください。

ツールの選定： API を幅広く網羅することを優先します。最も一般的な操作から順に、実装するエンドポイントを列挙してください。

---

フェーズ2：実装

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

プロジェクトの設定については、言語別のガイドを参照してください。

• ⚡ TypeScript ガイド - プロジェクト構成、package.json、tsconfig.json
• 🐍 Python ガイド - モジュール構成、依存関係

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

共通ユーティリティを作成します。

• 認証機能を備えた API クライアント
• エラーハンドリング用ヘルパー
• レスポンスの整形（JSON/Markdown）
• ページネーションのサポート

2.3 ツールの実装

各ツールについて:

入力スキーマ:

• Zod(TypeScript)または Pydantic(Python)を使用する
• 制約と明確な説明を含める
• フィールドの説明に例を追加する

出力スキーマ:

• 構造化データには、可能な限り outputSchema を定義する
• ツールの応答で structuredContent を使用する(TypeScript SDK の機能)
• クライアントがツールの出力を理解し処理しやすくなる

ツールの説明:

• 機能の簡潔な要約
• パラメータの説明
• 戻り値の型スキーマ

実装:

• I/O 操作には async/await を使用する
• 実行可能なメッセージを伴う適切なエラー処理
• 該当する場合はページネーションをサポートする
• 最新の SDK を使用する場合は、テキストコンテンツと構造化データの両方を返す

アノテーション:

• readOnlyHint: true/false
• destructiveHint: true/false
• idempotentHint: true/false
• openWorldHint: true/false

---

フェーズ 3: レビューとテスト

3.1 コード品質

以下についてレビューします:

• コードの重複がないこと(DRY 原則)
• 一貫したエラー処理
• 完全な型カバレッジ
• 明確なツールの説明

3.2 ビルドとテスト

TypeScript:

• npm run build を実行してコンパイルを検証する
• MCP Inspector でテストする: npx @modelcontextprotocol/inspector

Python:

• 構文を検証する: python -m py_compile your_server.py
• MCP Inspector でテストする

詳細なテスト手法と品質チェックリストについては、言語別のガイドを参照してください。

---

フェーズ 4: 評価の作成

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

評価ガイドを読み込んで、完全な評価ガイドラインを確認してください。

4.1 評価の目的を理解する

評価を使用して、LLM があなたの MCP サーバーを効果的に使用して現実的で複雑な質問に答えられるかどうかをテストします。

4.2 10 個の評価質問を作成する

効果的な評価を作成するには、評価ガイドに記載されているプロセスに従ってください:

1. ツールの調査: 利用可能なツールをリストアップし、その機能を理解する
2. コンテンツの探索: READ-ONLY 操作を使用して利用可能なデータを探索する
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/sitemap.xml のサイトマップから始め、その後 .md サフィックスを付けて特定のページを取得する
• MCP ベストプラクティス - 以下を含む普遍的な MCP ガイドライン:
  • サーバーとツールの命名規則
  • 応答形式のガイドライン(JSON 対 Markdown)
  • ページネーションのベストプラクティス
  • トランスポートの選択(ストリーミング可能な HTTP 対 stdio)
  • セキュリティとエラー処理の標準

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