MCP Evals

🚀 MCP 评测工具

MCP 评测工具是一个 Node.js 包和 GitHub Action，可借助基于大语言模型（LLM）的评分来评估 MCP（模型上下文协议）工具的实现情况，确保您的 MCP 服务器工具能正确且高效地运行。

🚀 快速开始

MCP 评测工具提供了便捷的使用方式，您既可以将其作为 Node.js 包使用，也能通过 GitHub Action 集成到工作流中。

✨ 主要特性

• 多方式集成：支持作为 Node.js 包和 GitHub Action 使用，满足不同场景需求。
• 基于 LLM 评分：利用大语言模型的评分机制，对 MCP 工具实现进行评估。
• 详细评测结果：每个评测返回包含准确性、完整性等多维度评分及综合评价的结果。

📦 安装指南

作为 Node.js 包

在项目中执行以下命令进行安装：

npm install mcp-evals

作为 GitHub Action

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

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'
          server_path: 'src/index.ts'
          openai_api_key: ${{ secrets.OPENAI_API_KEY }}
          model: 'gpt-4'  # 可选，默认为 gpt-4

💻 使用示例

基础用法

1. 创建您的评测文件

创建一个文件（例如 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,
    // 在这里添加其他评测
]; 

2. 运行评测

作为 Node.js 包

您可以使用 CLI 运行评测：

npx mcp-eval path/to/your/evals.ts path/to/your/server.ts

作为 GitHub Action

该操作将自动执行以下步骤：

1. 运行您的评测
2. 在 PR 上发布结果评论
3. 如果 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 密钥（必需）

⚠️ 重要提示

如果您使用此 GitHub Action 进行开源软件开发，请在 OpenAI 账单仪表盘中启用数据共享，以免费声称每天 250 万次的 GPT-4o mini 免费代币，从而使此 Action 实际上免费使用。

评测配置

EvalConfig 接口需要以下内容：

• model：用于评估的语言模型（例如，GPT-4）
• evals：要运行的评测函数数组

每个评测函数必须实现以下内容：

• name：评测名称
• description：评测测试的内容描述
• run：异步函数，接受一个模型并返回一个 EvalResult

📄 许可证

本项目采用 MIT 许可证。