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 软件包

你可以使用 CLI，通过 TypeScript 或 YAML 文件运行评估：

# 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

该 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 账单控制面板中启用数据共享，以便每天领取 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

用法 -- 监控

注意： 指标功能仍处于 alpha 阶段。功能和 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