MCP评估
一个Node.js包和GitHub Action，用于使用基于LLM的评分来评估MCP（模型上下文协议）工具实现， 内置可观测性支持这有助于确保您的MCP服务器的工具正常工作，性能良好，并且可以通过集成监控和指标完全观察到。
安装
作为Node.js包
npm install mcp-evals作为GitHub行动
将以下内容添加到工作流文件中：
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/mcp-evals@v1.0.9
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行动
该操作将自动：
- 运行您的评估
- 将结果作为评论发布在PR上
- 如果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密钥（Anthroptic模型需要）
\[！注意\] 如果您将此GitHub Action与开源软件一起使用，请在OpenAI计费仪表板中启用数据共享，每天免费领取250万个GPT-40迷你代币，使此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可能会发生变化，也可能发生重大变化。
- 在启动MCP服务器之前，将以下内容添加到您的应用程序中。
import { metrics } from 'mcp-evals';
metrics.initialize(9090, { enableTracing: true, otelEndpoint: 'http://localhost:4318/v1/traces' });- 启动监控堆栈：
docker-compose up -d- 运行MCP服务器，它将自动连接到监控堆栈。
访问仪表板
- 普罗米修斯: http://localhost:9090
- 格拉法纳: http://localhost:3000（用户名：admin，密码：admin）
- Jaeger用户界面: http://localhost:16686
可用指标
- 工具调用：按工具名称列出的工具调用次数
- 工具错误：按工具名称列出的错误数
- 工具延迟：按工具名称列出的延迟时间分布
许可证
麻省理工学院