MCP评估服务

Name: MCP评估服务
Author: mclenhard

作者：mclenhard120 星标更新：2025-06-24

安装使用来源：spider==github.com

项目介绍

MCP Evals

一个用于评估基于LLM评分的MCP（模型上下文协议）工具实现的Node.js包和GitHub操作，内置可观测性支持。这有助于确保您的MCP服务器工具运行正确、性能良好，并且可以通过集成监控和指标进行完全观测。

安装

作为Node.js包

npm install mcp-evals

作为GitHub操作

在工作流文件中添加以下内容：

name: 运行MCP评估
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: 设置Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          
      - name: 安装依赖
        run: npm install
        
      - name: 运行MCP评估
        uses: mclenhard/mcp-evals@v1.0.9
        with:
          evals_path: 'src/evals/evals.ts'    # 也可以使用.yaml文件
          server_path: 'src/index.ts'
          openai_api_key: ${{ secrets.OPENAI_API_KEY }}
          model: 'gpt-4'  # 可选，默认为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: '天气工具评估',
    description: '评估天气信息检索的准确性和完整性',
    run: async () => {
      const result = await grade(openai("gpt-4"), "纽约的天气如何？");
      return JSON.parse(result);
    }
};
const config: EvalConfig = {
    model: openai("gpt-4"),
    evals: [weatherEval]
  };
  
  export default config;
  
  export const evals = [
    weatherEval,
    // 在此处添加其他评估
];

选项B：YAML配置

对于更简单的配置，您可以使用YAML格式（例如，evals.yaml）：

# 模型配置
model:
  provider: openai     # 'openai' 或 'anthropic'
  name: gpt-4o        # 模型名称
  # api_key: sk-...   # 可选，默认使用OPENAI_API_KEY环境变量

# 要运行的评估列表
evals:
  - name: weather_query_basic
    description: 测试基本天气信息检索
    prompt: "旧金山当前的天气如何？"
    expected_result: "应返回旧金山当前的天气数据，包括温度、条件等"

  - name: weather_forecast
    description: 测试天气预报功能
    prompt: "你能给我西雅图的三天天气预报吗？"
    expected_result: "应返回西雅图的多日天气预报"

  - name: invalid_location
    description: 测试无效位置请求的处理
    prompt: "亚特兰蒂斯的天气如何？"
    expected_result: "应优雅地处理无效位置并提供适当的错误消息"

2. 运行评估

作为Node.js包

您可以使用CLI运行评估，支持TypeScript或YAML文件：

# 使用TypeScript配置
npx mcp-eval path/to/your/evals.ts path/to/your/server.ts

# 使用YAML配置
npx mcp-eval path/to/your/evals.yaml path/to/your/server.ts

作为GitHub操作

该操作会自动：

运行您的评估
将结果作为评论发布到PR
如果PR更新，则更新评论

评估结果

每个评估返回具有以下结构的对象：

interface EvalResult {
  accuracy: number;        // 从1到5的分数
  completeness: number;    // 从1到5的分数
  relevance: number;       // 从1到5的分数
  clarity: number;         // 从1到5的分数
  reasoning: number;       // 从1到5的分数
  overall_comments: string; // 强项和弱项的总结
}

配置

环境变量

OPENAI_API_KEY: 您的OpenAI API密钥（使用OpenAI模型时需要）
ANTHROPIC_API_KEY: 您的Anthropic API密钥（使用Anthropic模型时需要）

[!NOTE] 如果您使用此GitHub操作与开源软件，启用OpenAI计费仪表板中的数据共享，每天可获得250万免费的GPT-4o迷你代币，使此操作实际上免费使用。

评估配置

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可能会发生变化，可能有破坏性变更。

在初始化MCP服务器之前，在应用程序中添加以下内容。

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

启动监控堆栈：

docker-compose up -d

运行您的MCP服务器，它将自动连接到监控堆栈。

访问仪表盘

Prometheus: http://localhost:9090
Grafana: http://localhost:3000 (用户名：admin, 密码：admin)
Jaeger UI: http://localhost:16686

可用指标

工具调用次数：按工具名称统计的工具调用次数
工具错误次数：按工具名称统计的错误次数
工具延迟分布：按工具名称统计的延迟时间分布

许可证

MIT