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 許可證。