model-context-builder

MCP サーバー評価ガイド

概要

このドキュメントでは、MCP サーバーの包括的な評価を作成する方法を説明します。評価では、提供されたツールのみを使用して、LLM が現実的で複雑な質問に効果的に回答できるかをテストします。

---

クイックリファレンス

評価の要件

• 人が読みやすい質問を10個作成する
• 質問は読み取り専用、独立しており、破壊的でないこと
• 各質問には複数のツール呼び出しが必要（数十回に及ぶ可能性があります）
• 回答は単一の検証可能な値であること
• 回答は安定していること（時間が経っても変わらないこと）

出力形式

<evaluation>
   <qa_pair>
      <question>Your question here</question>
      <answer>Single verifiable answer</answer>
   </qa_pair>
</evaluation>

---

評価の目的

MCP サーバーの品質を測る基準は、サーバーがツールをどれほど適切かつ包括的に実装しているかではありません。ほかのコンテキストを持たず、MCP サーバーのみにアクセスできる LLM が、現実的で難しい質問に回答できるよう、これらの実装（入出力スキーマ、ドキュメント文字列／説明、機能）がどれほど役立つかです。

評価の概要

読み取り専用、独立、非破壊、かつ冪等な操作のみで回答できる、人が読みやすい質問を10個作成します。各質問は次の条件を満たす必要があります。

• 現実的である
• 明確かつ簡潔である
• 曖昧さがない
• 複雑であり、回答には数十回に及ぶ可能性のあるツール呼び出しや手順が必要である
• 事前に特定した、単一の検証可能な値で回答できる

質問のガイドライン

基本要件

1. 質問は独立していなければなりません

   • どの質問も、ほかの質問への回答に依存してはなりません
   • 別の質問の処理で行われた書き込み操作を前提としてはなりません

2. 質問への回答には、非破壊かつ冪等なツールの使用のみが必要でなければなりません

   • 正しい回答にたどり着くために、状態の変更を指示または要求してはなりません

3. 質問は現実的、明確、簡潔、かつ複雑でなければなりません

   • 別の LLM が、複数（数十回に及ぶ可能性のある）のツールや手順を使って回答する必要がなければなりません

複雑さと深さ

4. 質問には深い調査が必要でなければなりません

   • 複数の小問や順次行うツール呼び出しが必要な、複数段階の質問を検討してください
   • それぞれの手順が、前の質問で得られた情報を活用できるようにしてください

5. 質問には広範なページングが必要となる場合があります

   • 複数ページにわたる結果をページングして調べる必要がある場合があります
   • ニッチな情報を見つけるために、古いデータ（1～2年前のもの）を検索する必要がある場合があります
   • 質問は難しいものでなければなりません

6. 質問には深い理解が必要でなければなりません

   • 表面的な知識で答えられるものではなく、深い理解を必要とするものにしてください
   • 証拠を必要とする複雑な内容を、真偽を問う質問として提示してもかまいません
   • LLM が複数の仮説を調べる必要がある多肢選択式にしてもかまいません

7. 質問は、単純なキーワード検索では解けないものでなければなりません

   • 対象コンテンツに含まれる具体的なキーワードを使わないでください
   • 同義語、関連する概念、または言い換えを使用してください
   • 複数回の検索、関連項目の分析、コンテキストの抽出を経て、回答を導き出す必要がある内容にしてください

ツールのテスト

8. 質問では、ツールの戻り値に負荷をかけてください

   • LLM の処理能力を圧倒するほど大きな JSON オブジェクトやリストを返すツールを呼び出すことがあります
   • 次のような複数のデータ形式を理解する必要がある質問にしてください。
     • ID と名前
     • タイムスタンプと日時（月、日、年、秒）
     • ファイル ID、名前、拡張子、MIME タイプ
     • URL、GID など
   • 役立つ形式のデータをすべて返すツールの能力を検証してください

9. 質問の大半は、人間の実際のユースケースを反映したものでなければなりません

   • LLM の支援を受ける人間が知りたいと思うような情報検索タスクにしてください

10. 質問には数十回のツール呼び出しが必要となる場合があります

    • これにより、コンテキストが限られた LLM に負荷をかけます
    • MCP サーバーのツールが返却する情報を減らすよう促します

11. 曖昧な質問を含めてください

    • 曖昧な質問、またはどのツールを呼び出すかの判断が難しい質問でもかまいません
    • LLM が間違いを犯したり、誤解したりする可能性がある内容にしてください
    • ただし、曖昧さがあっても、検証可能な回答が必ず1つに定まるようにしてください

安定性

12. 回答が変わらないように質問を設計する必要があります

    • 動的に変化する「現在の状態」に依存する質問はしないでください
    • たとえば、次の数を数えないでください。
      • 投稿へのリアクション数
      • スレッドへの返信数
      • チャンネルのメンバー数

13. MCP サーバーによって、作成する質問の種類を制限してはいけません

    • 難しく複雑な質問を作成してください
    • 利用可能な MCP サーバーのツールでは解決できない質問も含めてかまいません
    • 質問で特定の出力形式（日付時刻とエポックタイム、JSON と MARKDOWN など）を指定してもかまいません
    • 質問の解決に数十回のツール呼び出しが必要でもかまいません

回答のガイドライン

検証可能性

1. 回答は直接文字列比較で検証できる必要があります
   • 回答がさまざまな形式で書き換えられる場合は、質問で出力形式を明確に指定してください
   • 例：「YYYY/MM/DD 形式を使用してください。」「True または False で回答してください。」「A、B、C、D のいずれかだけで回答してください。」
   • 回答は、次のような検証可能な単一の値にしてください。
     • ユーザー ID、ユーザー名、表示名、名、姓
     • チャンネル ID、チャンネル名
     • メッセージ ID、文字列
     • URL、タイトル
     • 数量
     • タイムスタンプ、日付時刻
     • 真偽値（True/False の質問の場合）
     • メールアドレス、電話番号
     • ファイル ID、ファイル名、ファイル拡張子
     • 選択式の回答
   • 回答に特別な書式や複雑な構造化出力を必要としないでください
   • 回答は直接文字列比較で検証されます

読みやすさ

2. 回答には通常、人が読みやすい形式を優先してください
   • 例：名前、名、姓、日付時刻、ファイル名、メッセージ文字列、URL、yes/no、true/false、a/b/c/d
   • 不透明な ID よりも優先してください（ただし、ID も使用できます）
   • 回答の圧倒的多数は、人が読みやすい形式にしてください

安定性

3. 回答は安定しており、変化しない必要があります

   • 過去の内容（たとえば、終了した会話、公開済みのプロジェクト、回答済みの質問）を参照してください
   • 常に同じ回答が得られる「完了した」概念に基づいて質問を作成してください
   • 変動する回答を避けるため、固定された期間を考慮する質問をしてもかまいません
   • 変化する可能性が低いコンテキストを利用してください
   • 例：論文名を探す場合は、後から発表された論文と混同されないよう、十分に具体的に指定してください

4. 回答は明確で曖昧さがない必要があります

   • 明確な答えが一つだけになるように質問を設計してください
   • 回答は MCP サーバーのツールを使って導き出せる必要があります

多様性

5. 回答には多様性が必要です

   • 回答は、さまざまな形式や種類にわたる、検証可能な単一の値にしてください
   • ユーザーに関する概念：ユーザー ID、ユーザー名、表示名、名、姓、メールアドレス、電話番号
   • チャンネルに関する概念：チャンネル ID、チャンネル名、チャンネルトピック
   • メッセージに関する概念：メッセージ ID、メッセージ文字列、タイムスタンプ、月、日、年

6. 回答は複雑な構造にしてはいけません

   • 値のリストにしないでください
   • 複雑なオブジェクトにしないでください
   • ID や文字列のリストにしないでください
   • 自然言語の文章にしないでください
   • ただし、次の条件を満たす場合を除きます。
     • 直接文字列比較で簡単に検証できる
     • 現実的に再現できる
     • LLM が同じリストを別の順序や形式で返す可能性が低い

評価プロセス

ステップ 1：ドキュメントの確認

対象 API のドキュメントを読み、次の点を把握してください。

• 利用可能なエンドポイントと機能
• 曖昧さがある場合は、ウェブから追加情報を取得してください
• このステップは、可能な限り並列化してください
• 各サブエージェントがファイルシステム上またはウェブ上のドキュメントのみを調査していることを確認してください

ステップ 2：ツールの確認

MCP サーバーで利用できるツールを一覧表示してください。

• MCP サーバーを直接確認してください
• この段階ではツールを呼び出さずに、入力／出力のスキーマ、docstring、説明を把握してください

ステップ 3：理解を深める

十分に理解できるまで、ステップ 1 と 2 を繰り返します。

• 複数回繰り返します
• 作成するタスクの種類を検討します
• 理解を深めます
• どの段階でも、MCP サーバーの実装コードを読んではいけません
• 直感と理解を活用し、妥当で現実的かつ非常に難易度の高いタスクを作成します

ステップ 4：読み取り専用でのコンテンツ調査

API とツールを理解したら、MCP サーバーのツールを使用します。

• 読み取り専用かつ非破壊的な操作のみを使用してコンテンツを調査します
• 目的は、現実的な質問を作成するために特定のコンテンツ（例：ユーザー、チャンネル、メッセージ、プロジェクト、タスク）を特定することです
• 状態を変更するツールは呼び出さないでください
• MCP サーバーの実装コードは読みません
• 独立した調査を行う個々のサブエージェントと並行して、このステップを進めます
• 各サブエージェントが読み取り専用、非破壊的、かつ冪等な操作のみを行うようにします
• 注意してください。一部のツールは大量のデータを返し、コンテキストを使い果たす可能性があります
• 調査では、小規模かつ対象を絞ったツール呼び出しを段階的に行います
• すべてのツール呼び出しリクエストで、結果を制限するためにlimitパラメーターを使用します（10 未満）
• ページネーションを使用します

ステップ 5：タスクの生成

コンテンツを調査した後、人が読みやすい質問を 10 個作成します。

• LLM が MCP サーバーを使って回答できる質問にします
• 上記のすべての質問と回答のガイドラインに従います

出力形式

各 QA ペアは質問と回答で構成されます。出力は、次の構造の XML ファイルにしてください。

<evaluation>
   <qa_pair>
      <question>Find the project created in Q2 2024 with the highest number of completed tasks. What is the project name?</question>
      <answer>Website Redesign</answer>
   </qa_pair>
   <qa_pair>
      <question>Search for issues labeled as "bug" that were closed in March 2024. Which user closed the most issues? Provide their username.</question>
      <answer>sarah_dev</answer>
   </qa_pair>
   <qa_pair>
      <question>Look for pull requests that modified files in the /api directory and were merged between January 1 and January 31, 2024. How many different contributors worked on these PRs?</question>
      <answer>7</answer>
   </qa_pair>
   <qa_pair>
      <question>Find the repository with the most stars that was created before 2023. What is the repository name?</question>
      <answer>data-pipeline</answer>
   </qa_pair>
</evaluation>

評価例

良い質問

例 1：詳細な調査が必要なマルチホップ質問（GitHub MCP）

<qa_pair>
   <question>Find the repository that was archived in Q3 2023 and had previously been the most forked project in the organization. What was the primary programming language used in that repository?</question>
   <answer>Python</answer>
</qa_pair>

この質問が良い理由：

• アーカイブ済みのリポジトリを見つけるために、複数回の検索が必要です
• アーカイブされる前に最も多くのフォークを持っていたリポジトリを特定する必要があります
• リポジトリの詳細を調べ、使用言語を確認する必要があります
• 回答は簡潔で検証可能な値です
• 変化しない過去のデータ（クローズ済み）に基づいています

例 2：キーワード一致に頼らず、文脈の理解が必要な質問（プロジェクト管理 MCP）

<qa_pair>
   <question>Locate the initiative focused on improving customer onboarding that was completed in late 2023. The project lead created a retrospective document after completion. What was the lead's role title at that time?</question>
   <answer>Product Manager</answer>
</qa_pair>

この質問が良い理由：

• 特定のプロジェクト名（「顧客のオンボーディング改善を目的とした取り組み」）を使っていません
• 特定の期間内に完了したプロジェクトを見つける必要があります
• プロジェクトリーダーとその役割を特定する必要があります
• 振り返り資料から文脈を理解する必要があります
• 回答は人が読みやすく、安定しています
• 完了済みの作業（変化しません）に基づいています

例 3：複数の手順が必要な複雑な集計（課題トラッカー MCP）

<qa_pair>
   <question>Among all bugs reported in January 2024 that were marked as critical priority, which assignee resolved the highest percentage of their assigned bugs within 48 hours? Provide the assignee's username.</question>
   <answer>alex_eng</answer>
</qa_pair>

この質問が良い理由：

• 日付、優先度、ステータスでバグを絞り込む必要があります
• 担当者ごとに分類し、解決率を計算する必要があります
• 48 時間の期間を判定するために、タイムスタンプを理解する必要があります
• ページネーションを試す必要があります（処理対象のバグが多数存在する可能性があります）
• 回答は 1 つのユーザー名です
• 特定の期間の過去のデータに基づいています

例 4：複数のデータ種別を横断した統合が必要な質問（CRM MCP）

<qa_pair>
   <question>Find the account that upgraded from the Starter to Enterprise plan in Q4 2023 and had the highest annual contract value. What industry does this account operate in?</question>
   <answer>Healthcare</answer>
</qa_pair>

この質問が良い理由：

• サブスクリプションのティア変更を理解する必要があります
• 特定の期間内のアップグレードイベントを特定する必要があります
• 契約金額を比較する必要があります
• アカウントの業界情報にアクセスする必要があります
• 回答は簡潔で検証可能です
• 完了した過去の取引に基づいています

不適切な質問

例 1：時間の経過とともに回答が変わる

<qa_pair>
   <question>How many open issues are currently assigned to the engineering team?</question>
   <answer>47</answer>
</qa_pair>

この質問が不適切な理由：

• イシューの作成、クローズ、再割り当てに応じて回答が変わります
• 安定したデータに基づいていません
• 動的な「現在の状態」に依存しています

例 2：キーワード検索だけで簡単に解ける

<qa_pair>
   <question>Find the pull request with title "Add authentication feature" and tell me who created it.</question>
   <answer>developer123</answer>
</qa_pair>

この質問が不適切な理由：

• 正確なタイトルをキーワード検索するだけで簡単に解けます
• 深い調査や理解を必要としません
• 情報の統合や分析が不要です

例 3：回答形式が曖昧

<qa_pair>
   <question>List all the repositories that have Python as their primary language.</question>
   <answer>repo1, repo2, repo3, data-pipeline, ml-tools</answer>
</qa_pair>

この質問が不適切な理由：

• 順序を問わず返せるリスト形式の回答です
• 文字列の直接比較では検証が困難です
• LLM によって形式が異なる可能性があります（JSON 配列、カンマ区切り、改行区切りなど）
• 代わりに、特定の集計値（件数）や最上位の項目（スター数が最も多いもの）を尋ねるとよいでしょう

検証プロセス

評価を作成した後は、次の手順に従ってください。

1. XML ファイルを確認する：スキーマを把握します
2. 各タスクの指示を読み込み、MCP サーバーとツールを並行して使用する：タスクを直接解いて正解を特定します
3. WRITE または DESTRUCTIVE 操作を必要とする操作にフラグを付ける
4. 正解をすべて集め、ドキュメント内の誤った回答を置き換える
5. WRITE または DESTRUCTIVE 操作が必要な <qa_pair> を削除する

コンテキストが不足しないよう、タスクを並行して解いてください。その後、回答をすべて集め、最後にファイルを変更します。

品質の高い評価を作成するためのヒント

1. よく考え、事前に計画する：タスクを生成する前に、十分に検討します
2. 可能な箇所は並行処理する：プロセスを高速化し、コンテキストを適切に管理します
3. 現実的なユースケースに焦点を当てる：人が実際に達成したいと考えるタスクを扱います
4. 難易度の高い質問を作成する：MCP サーバーの機能の限界を試します
5. 安定性を確保する：履歴データや確定した概念を使用します
6. 回答を検証する：MCP サーバーのツールを使って質問を解きます
7. 反復して改善する：プロセスから得た知見に基づいて見直します

---

評価の実行

評価ファイルを作成した後、付属の評価ハーネスを使用して MCP サーバーをテストします。

セットアップ

1. 依存関係をインストールする

   pip install -r scripts/requirements.txt
   

   または、手動でインストールします。

   pip install anthropic mcp
   

2. API キーを設定する

   export ANTHROPIC_API_KEY=your_api_key_here
   

評価ファイルの形式

評価ファイルでは、<qa_pair> 要素を含む XML 形式を使用します。

<evaluation>
   <qa_pair>
      <question>Find the project created in Q2 2024 with the highest number of completed tasks. What is the project name?</question>
      <answer>Website Redesign</answer>
   </qa_pair>
   <qa_pair>
      <question>Search for issues labeled as "bug" that were closed in March 2024. Which user closed the most issues? Provide their username.</question>
      <answer>sarah_dev</answer>
   </qa_pair>
</evaluation>

評価の実行

評価スクリプト（scripts/evaluation.py）は、次の 3 種類のトランスポートに対応しています。

重要：

• stdio トランスポート：評価スクリプトが MCP サーバーのプロセスを自動的に起動し、管理します。サーバーを手動で実行しないでください。
• sse/http トランスポート：評価を実行する前に、MCP サーバーを別途起動する必要があります。スクリプトは指定された URL で、すでに実行中のサーバーに接続します。

1. ローカル STDIO サーバー

ローカルで実行する MCP サーバーの場合（スクリプトがサーバーを自動的に起動します）：

python scripts/evaluation.py \
  -t stdio \
  -c python \
  -a my_mcp_server.py \
  evaluation.xml

環境変数を使用する場合：

python scripts/evaluation.py \
  -t stdio \
  -c python \
  -a my_mcp_server.py \
  -e API_KEY=abc123 \
  -e DEBUG=true \
  evaluation.xml

2. Server-Sent Events（SSE）

SSE ベースの MCP サーバーの場合（先にサーバーを起動します）：

python scripts/evaluation.py \
  -t sse \
  -u https://example.com/mcp \
  -H "Authorization: Bearer token123" \
  -H "X-Custom-Header: value" \
  evaluation.xml

3. HTTP（Streamable HTTP）

HTTP ベースの MCP サーバーの場合（先にサーバーを起動します）：

python scripts/evaluation.py \
  -t http \
  -u https://example.com/mcp \
  -H "Authorization: Bearer token123" \
  evaluation.xml

コマンドラインオプション

usage: evaluation.py [-h] [-t {stdio,sse,http}] [-m MODEL] [-c COMMAND]
                     [-a ARGS [ARGS ...]] [-e ENV [ENV ...]] [-u URL]
                     [-H HEADERS [HEADERS ...]] [-o OUTPUT]
                     eval_file

positional arguments:
  eval_file             Path to evaluation XML file

optional arguments:
  -h, --help            Show help message
  -t, --transport       Transport type: stdio, sse, or http (default: stdio)
  -m, --model           Claude model to use (default: claude-3-7-sonnet-20250219)
  -o, --output          Output file for report (default: print to stdout)

stdio options:
  -c, --command         Command to run MCP server (e.g., python, node)
  -a, --args            Arguments for the command (e.g., server.py)
  -e, --env             Environment variables in KEY=VALUE format

sse/http options:
  -u, --url             MCP server URL
  -H, --header          HTTP headers in 'Key: Value' format

出力

評価スクリプトは、次の内容を含む詳細なレポートを生成します。

• 概要統計：

  • 正解率（正解数／合計数）
  • タスクの平均所要時間
  • タスクあたりのツール呼び出しの平均回数
  • ツール呼び出しの合計回数

• タスクごとの結果：

  • プロンプトと期待される回答
  • エージェントからの実際の回答
  • 回答が正解かどうか（✅／❌）
  • 所要時間とツール呼び出しの詳細
  • エージェントによるアプローチの概要
  • ツールに関するエージェントからのフィードバック

レポートをファイルに保存する

python scripts/evaluation.py \
  -t stdio \
  -c python \
  -a my_server.py \
  -o evaluation_report.md \
  evaluation.xml

評価ワークフローの完全な例

評価を作成して実行する一連の例を紹介します。

1. 評価ファイルを作成します（my_evaluation.xml）：

<evaluation>
   <qa_pair>
      <question>Find the user who created the most issues in January 2024. What is their username?</question>
      <answer>alice_developer</answer>
   </qa_pair>
   <qa_pair>
      <question>Among all pull requests merged in Q1 2024, which repository had the highest number? Provide the repository name.</question>
      <answer>backend-api</answer>
   </qa_pair>
   <qa_pair>
      <question>Find the project that was completed in December 2023 and had the longest duration from start to finish. How many days did it take?</question>
      <answer>127</answer>
   </qa_pair>
</evaluation>

2. 依存関係をインストールします：

pip install -r scripts/requirements.txt
export ANTHROPIC_API_KEY=your_api_key

3. 評価を実行します：

python scripts/evaluation.py \
  -t stdio \
  -c python \
  -a github_mcp_server.py \
  -e GITHUB_TOKEN=ghp_xxx \
  -o github_eval_report.md \
  my_evaluation.xml

4. github_eval_report.md のレポートを確認して、以下を行います。
   • 合格した質問と不合格だった質問を確認する
   • ツールに対するエージェントのフィードバックを読む
   • 改善が必要な領域を特定する
   • MCP サーバーの設計を見直す

ローカル MCP サーバーの規約（mcp-* リポジトリ）

MCP サーバーの構築や評価には、次のパターンを使用してください。

• stdio サーバーを実行する mcp サブコマンドを用意します（例：mcp-vector-search mcp、mcp-ticketer mcp --path <repo>、mcp-browser mcp）。
• トークン使用量を抑えるため、コンパクトで統合されたツール構成を優先します。データの一覧表示では、ページネーションとコンパクトモードを使用してください。
• ランタイム依存関係を検証し、クライアントと連携するための setup、install、または doctor コマンドを用意します。
• type: stdio、明示的な command、最小限の env オーバーライドを指定した .mcp.json エントリを優先します。

.mcp.json エントリの例：

{
  "mcpServers": {
    "mcp-vector-search": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "mcp-vector-search", "mcp"],
      "env": {
        "MCP_ENABLE_FILE_WATCHING": "true"
      }
    }
  }
}

運用上の注意：

• アダプターとデータベースのパスには、明示的な環境変数を使用します（例：MCP_TICKETER_ADAPTER、KUZU_MEMORY_DB）。
• HTTP/SSE 版を実行する場合は、ヘルスエンドポイントを公開します。
• ブラウザー連携では、動的なポート割り当てを可能にします（mcp-browser はポート範囲を使用します）。

トラブルシューティング

接続エラー

接続エラーが発生した場合：

• STDIO：コマンドと引数が正しいことを確認します
• SSE/HTTP：URL にアクセスできることと、ヘッダーが正しいことを確認します
• 必要な API キーが環境変数またはヘッダーに設定されていることを確認します

精度が低い場合

多くの評価が失敗する場合：

• 各タスクに対するエージェントのフィードバックを確認します
• ツールの説明が明確で、十分な情報を含んでいるか確認します
• 入力パラメーターが適切に文書化されているか確認します
• ツールが返すデータが多すぎないか、または少なすぎないか検討します
• エラーメッセージが次の対応に役立つ内容になっていることを確認します

タイムアウトの問題

タスクがタイムアウトする場合：

• より高性能なモデル（例：claude-3-7-sonnet-20250219）を使用します
• ツールが返すデータが多すぎないか確認します
• ページネーションが正しく機能しているか確認します
• 複雑な質問の簡略化を検討します