MCP Evals

MCP Evals

LLM ベースのスコアリングを使用して MCP（Model Context Protocol）ツールの実装を評価する、Node.js パッケージおよび GitHub Action です。オブザーバビリティのサポートが組み込まれています。統合されたモニタリングとメトリクスにより、MCP サーバーのツールが正しく動作し、優れたパフォーマンスを発揮し、十分に可観測であることを確認できます。

インストール

Node.js パッケージとして

npm install mcp-evals

GitHub Action として

ワークフローファイルに次の内容を追加します。

name: Run MCP Evaluations
on:
  pull_request:
    types: [opened, synchronize, reopened]
jobs:
  evaluate:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          
      - name: Install dependencies
        run: npm install
        
      - name: Run MCP Evaluations
        uses: mclenhard/[email protected]
        with:
          evals_path: 'src/evals/evals.ts'    # Can also use .yaml files
          server_path: 'src/index.ts'
          openai_api_key: ${{ secrets.OPENAI_API_KEY }}
          model: 'gpt-4'  # Optional, defaults to gpt-4

使い方 -- 評価

1. 評価ファイルを作成する

評価設定は、TypeScript または YAML 形式で作成できます。

オプション A: TypeScript 設定

評価設定をエクスポートするファイル（例: evals.ts）を作成します。

import { EvalConfig } from 'mcp-evals';
import { openai } from "@ai-sdk/openai";
import { grade, EvalFunction} from "mcp-evals";

const weatherEval: EvalFunction = {
    name: 'Weather Tool Evaluation',
    description: 'Evaluates the accuracy and completeness of weather information retrieval',
    run: async () => {
      const result = await grade(openai("gpt-4"), "What is the weather in New York?");
      return JSON.parse(result);
    }
};
const config: EvalConfig = {
    model: openai("gpt-4"),
    evals: [weatherEval]
  };
  
  export default config;
  
  export const evals = [
    weatherEval,
    // add other evals here
]; 

オプション B: YAML 設定

より簡潔に設定するには、YAML 形式（例: evals.yaml）を使用できます。

# Model configuration
model:
  provider: openai     # 'openai' or 'anthropic'
  name: gpt-4o        # Model name
  # api_key: sk-...   # Optional, uses OPENAI_API_KEY env var by default

# List of evaluations to run
evals:
  - name: weather_query_basic
    description: Test basic weather information retrieval
    prompt: "What is the current weather in San Francisco?"
    expected_result: "Should return current weather data for San Francisco including temperature, conditions, etc."

  - name: weather_forecast
    description: Test weather forecast functionality
    prompt: "Can you give me the 3-day weather forecast for Seattle?"
    expected_result: "Should return a multi-day forecast for Seattle"

  - name: invalid_location
    description: Test handling of invalid location requests
    prompt: "What's the weather in Atlantis?"
    expected_result: "Should handle invalid location gracefully with appropriate error message"

2. 評価を実行する

Node.js パッケージとして

TypeScript ファイルまたは YAML ファイルを使って、CLI から評価を実行できます。

# Using TypeScript configuration
npx mcp-eval path/to/your/evals.ts path/to/your/server.ts

# Using YAML configuration
npx mcp-eval path/to/your/evals.yaml path/to/your/server.ts

GitHub Action として

このアクションは次の処理を自動的に行います。

1. 評価を実行する
2. 結果を PR のコメントとして投稿する
3. PR が更新された場合にコメントを更新する

評価結果

各評価は、次の構造を持つオブジェクトを返します。

interface EvalResult {
  accuracy: number;        // Score from 1-5
  completeness: number;    // Score from 1-5
  relevance: number;       // Score from 1-5
  clarity: number;         // Score from 1-5
  reasoning: number;       // Score from 1-5
  overall_comments: string; // Summary of strengths and weaknesses
}

設定

環境変数

• OPENAI_API_KEY: OpenAI API キー（OpenAI モデルで必要）
• ANTHROPIC_API_KEY: Anthropic API キー（Anthropic モデルで必要）

メモ

この GitHub Action をオープンソースソフトウェアで使用している場合は、OpenAI の請求ダッシュボードでデータ共有を有効にすると、1 日あたり 250 万個の無料 GPT-4o mini トークンを利用でき、この Action を実質無料で使用できます。

評価の設定

TypeScript 設定

EvalConfig インターフェースでは、次の項目が必要です。

• model: 評価に使用する言語モデル（例: GPT-4）
• evals: 実行する評価関数の配列

各評価関数は、次の項目を実装する必要があります。

• name: 評価の名前
• description: 評価対象の説明
• run: モデルを受け取り、EvalResult を返す非同期関数

YAML 設定

YAML 設定ファイルでは、次の項目を指定できます。

モデルの設定:

• provider: 'openai' または 'anthropic'
• name: モデル名（例: 'gpt-4o'、'claude-3-opus-20240229'）
• api_key: API キー（省略可能。デフォルトでは環境変数を使用）

評価の設定:

• name: 評価の名前（必須）
• description: 評価対象の説明（必須）
• prompt: MCP サーバーに送信するプロンプト（必須）
• expected_result: 期待される動作の説明（省略可能）

サポートされているファイル拡張子: .yaml、.yml

使い方 -- モニタリング

注: メトリクス機能はまだアルファ版です。機能や API は変更される可能性があり、破壊的変更が生じる場合があります。

1. MCP サーバーを初期化する前に、次の内容をアプリケーションに追加します。

import { metrics } from 'mcp-evals';
metrics.initialize(9090, { enableTracing: true, otelEndpoint: 'http://localhost:4318/v1/traces' });

2. モニタリングスタックを起動します。

docker-compose up -d

3. MCP サーバーを実行すると、モニタリングスタックに自動的に接続されます。

ダッシュボードへのアクセス

• Prometheus: http://localhost:9090
• Grafana: http://localhost:3000（ユーザー名: admin、パスワード: admin）
• Jaeger UI: http://localhost:16686

利用可能なメトリクス

• ツール呼び出し: ツール名ごとのツール呼び出し数
• ツールエラー: ツール名ごとのエラー数
• ツールのレイテンシ: ツール名ごとのレイテンシ時間の分布

ライセンス

MIT