Deepeval MCP Bridge

关键词

模型上下文协议深度评估FastAPI 服务ASGI 集成容器化部署

使用说明内容（Markdown 格式）

项目简介

Deepeval MCP Bridge 是一个基于 MCP（模型上下文协议）的服务器实现。它在本地嵌入 deepeval-wrapper 的评估逻辑，通过 MCP 风格的 API 向 MCP 客户端提供上下文信息与评估功能，并在同一进程中暴露 wrapper 的全部端点以便直接访问，避免额外的网络开销。

主要功能点

  • MCP API 接口（包装为 MCP 结果 envelope）：
    • POST /mcp/evaluate：将评估请求转发给 deepeval-wrapper，并返回符合 MCP 规范的结果 envelope。
    • GET /mcp/metrics：获取可用的评估指标，并以 MCP 结果格式封装返回。
    • GET /mcp/metrics/categories：按分类获取指标信息，返回 MCP 风格的封装。
    • GET /mcp/metrics/{metric_type}：获取特定指标的详细信息，并以 MCP envelope 返回。
  • 直接访问 wrapper 功能：
    • /wrapper/*：暴露 deepeval-wrapper 的完整 API，便于开发和调试。
  • 无缝的 in-process ASGI 通信：
    • 将 wrapper 作为本地嵌入的 FastAPI 应用，通过 ASGITransport 在同一进程内通信，避免网络开销。
  • 身份验证与安全性：
    • 通过 API_KEYS 控制对 /mcp/* 与 /wrapper/* 的访问（可选，未配置时公开）。
  • 健康与发现端点：
    • /health、/healthz、根路径 / 提供 API 概览，方便健康检查和文档查看。
  • 容器化就绪：
    • 支持 Docker 构建与部署，方便在本地或云端运行。

安装步骤

  1. 安装 Docker（建议 24.x 及以上）。
  2. 获取代码并进入仓库根目录。
  3. 构建镜像：
    • docker build -t deepeval-mcp .
  4. 配置环境变量：
    • 复制并编辑 .env.example 为 .env，填入所需的 LLM API Key（OPENAI_API_KEY / ANTHROPIC_API_KEY / GOOGLE_API_KEY 中至少一个）。
    • 如需开启认证，请在 .env 中设置 API_KEYS（如 "key1,key2"）。
    • 其他可选设置包括 DEEPEVAL_WRAPPER_IMPORT_PATH、DEEPEVAL_WRAPPER_ASGI_TARGET、DEEPEVAL_HTTP_TIMEOUT。
  5. 运行服务：
    • docker run --env-file .env -p 8000:8000 deepeval-mcp

服务器将对外暴露在 http://localhost:8000。

服务器配置（MCP 客户端启动连接所需信息说明）

MCP 服务器本身需要一个对接配置以便 MCP 客户端知道如何启动和连接服务器。以下为可参考的配置信息描述（JSON 格式，包含 server name、command、args 等字段；用于 MCP 客户端在本地启动并连接 MCP 服务器的参数说明，实际启动请由客户端读取并执行）： { "server_name": "deepeval-mcp", "command": "uvicorn", "args": ["src.main:app", "--host", "0.0.0.0", "--port", "8000"] }

  • server_name 表示 MCP 服务器的标识名称，便于管理和日志追踪。
  • command 为启动服务器的可执行程序，这里使用 uvicorn。
  • args 是一个字符串列表，表示启动命令的参数，例如绑定地址、端口以及加载的应用入口。

说明：

  • MCP 客户端在启动时会读取该配置并根据 command 与 args 启动 MCP 服务器实例。
  • 实际连接时，客户端不需要此配置的具体实现细节，但通过该字段可以了解服务器启动的预期方式和端口号。
  • 上述配置对应当前仓库的实现逻辑：FastAPI 应用作为 MCP 服务器，入口点为一个可通过 uvicorn 启动的应用对象。

基本使用方法

  • 启动后测试 MCP 接口：
    • 调用 /mcp/evaluate，传入包含 test_case 的数据结构，服务会返回一个 MCP 风格的 envelope。
    • 访问 /mcp/metrics 获取可用指标信息，/mcp/metrics/categories 获取分类信息，/mcp/metrics/{metric_type} 获取单一指标详细信息。
  • 直接使用 wrapper 的全部能力：
    • 访问 /wrapper/* 路径可直接调用 deepeval-wrapper 的所有端点。
  • 安全性与鉴权：
    • 如果配置了 API_KEYS，将需要在请求头中携带 X-API-Key 以通过鉴权。
    • 未配置 API_KEYS 时，认证将禁用，公开访问。
  • 部署与维护：
    • 服务器在启动时会初始化 wrapper 客户端，若未能成功加载 wrapper 端应用，将返回 503 服务不可用，并通过日志提示。
    • 支持健康检查端点与日志详细输出，便于运维监控。

服务器信息

访问项目