Judgmentlabs Mcp Server

JudgmentLabs MCP Server

一个 Model Context Protocol（MCP）服务，可与 Judgment API 无缝集成，用于 AI 评估工作流。此服务让你可以直接在兼容 MCP 的环境（如 Claude Desktop）中管理数据集、运行评估和跟踪追踪记录。

🎥 演示视频

[

🚀 功能

🎯 一键安装

• DXT 安装包：在 Claude Desktop 中以单个 .dxt 文件的形式安装
• 无需依赖项：所有 Python 包均已预先打包
• 自动配置：通过 Claude Desktop 的设置界面轻松完成设置
• 跨平台：支持 Windows、macOS 和 Linux

📊 数据集管理

• 创建和管理数据集：将包含示例和追踪记录的数据集推送到 Judgment API
• 灵活的数据处理：更新数据集时支持追加和覆盖模式
• 数据检索：从 Judgment 项目中拉取现有数据集
• 智能示例转换：自动处理各种输入格式（input/question、expected_output/answer）

项目操作

• 项目创建：在 Judgment API 中创建新项目
• 项目清理：删除项目及其所有关联数据
• 自动创建：推送数据集时，如果项目不存在，则会自动创建

评估与监控

• 运行评估：通过 Judgment API 执行评估运行
• 结果检索：获取详细的评估结果以供分析
• 追踪记录管理：创建、获取和删除单条追踪记录
• 实时监控：跟踪 AI Agent 的性能和行为

开发者体验

• 错误处理：全面的错误处理，并提供实用建议
• 调试日志：内置调试功能，便于排查问题
• 灵活配置：基于环境的配置，并保护敏感数据

📋 前置条件

• Claude Desktop（支持 DXT 的最新版本）
• 拥有 API 访问权限的 JudgmentLabs 账户
• 手动安装时：Python 3.8 或更高版本

🛠️ 安装

方法 1：DXT 扩展（推荐）🎯

通过 Claude Desktop 的 DXT 扩展系统安装此 MCP 服务是最简单的方法：

1. 下载扩展：

   • 从发布页面获取最新的 judgmentlabs-mcp-server.dxt 文件
   • 无需安装 Python！

2. 在 Claude Desktop 中安装：

   • 打开 Claude Desktop
   • 前往 设置 → 扩展
   • 点击 “安装扩展”
   • 选择下载的 .dxt 文件
   • 扩展将自动安装

3. 配置 API 凭据：

   • 在 Claude Desktop 中，前往 设置 → 扩展
   • 找到 “JudgmentLabs MCP” 并点击 配置
   • 输入你的凭据：
     • JUDGMENT_API_KEY：你的 JudgmentLabs Dashboard API 密钥
     • JUDGMENT_ORG_ID：你的 Dashboard 组织 ID

4. 启用并测试：

   • 将扩展切换为 “已启用”
   • 重启 Claude Desktop
   • 通过提问进行测试：“创建一个名为 ‘test-project’ 的新项目”

方法 2：自行构建 DXT 安装包（高级用户）⚙️

适用于想要从源代码构建 DXT 安装包的开发者：

前置条件

• Python 3.8 或更高版本
• Node.js 和 npm

构建步骤

# 1. Clone the repository
git clone https://github.com/suysoftware/judgmentlabs-mcp-server.git

# 2. Install DXT CLI
npm install -g @anthropic-ai/dxt

# 3. Navigate to project directory
cd judgmentlabs-mcp-server

# 4. Install and bundle Python dependencies
pip install -t lib/ judgeval python-dotenv

# 5. Create the DXT package
dxt pack

此操作会在你的项目目录中生成 judgmentlabs-mcp-server.dxt。

安装自行构建的安装包

# Install in Claude Desktop:
# 1. Open Claude Desktop
# 2. Go to Settings → Extensions
# 3. Click "Install Extension"
# 4. Select the generated judgmentlabs-mcp-server.dxt file
# 5. Configure your API credentials
# 6. Restart Claude Desktop
# 7. Your MCP server is ready!

🔧 可用工具

数据集操作

• push_dataset：上传包含示例和追踪记录的数据集
• get_dataset：从项目中检索现有数据集
• delete_dataset：从项目中移除数据集

项目管理

• create_project：创建新项目
• delete_project：删除项目及其所有数据

评估与跟踪记录

• run_evaluation：执行评估运行
• get_evaluation_results：获取评估结果
• get_trace：检索单条跟踪记录
• delete_trace：删除指定的跟踪记录

🔒 安全

• API 密钥：凭据安全地存储在 Claude Desktop 的扩展配置中
• 不在本地存储：使用 DXT 安装时，API 密钥不会存储在纯文本文件中
• 环境隔离：每个扩展都在独立的安全环境中运行
• 数据隐私：所有数据都会安全地传输至 Judgment API

🐛 故障排除

常见问题

扩展无法加载

Extension failed to load

解决方案：

1. 确保使用的是最新版本的 Claude Desktop
2. 检查 .dxt 文件是否已损坏
3. 尝试重新安装扩展

API 密钥配置问题

Error: No API key provided

解决方案：

1. 前往 Claude Desktop 的 Settings → Extensions
2. 找到 “JudgmentLabs MCP” 并点击 Configure
3. 确保已正确设置 JUDGMENT_API_KEY 和 JUDGMENT_ORG_ID
4. 更改配置后重启 Claude Desktop

连接问题

HTTP 500: API server error

解决方案：查看 JudgmentLabs 状态页面，或稍后重试。

Python 路径问题（构建过程）

Command not found: dxt

解决方案：

1. 先安装 Node.js 和 npm
2. 安装 DXT CLI：npm install -g @anthropic-ai/dxt
3. 确保 npm 全局 bin 目录位于 PATH 中

依赖项打包问题

Import error: No module named 'judgeval'

解决方案：

1. 确保已运行：pip install -t lib/ judgeval python-dotenv
2. 检查 lib/ 文件夹是否包含这些包
3. 重新构建 DXT 包：dxt pack

调试模式

检查项目目录中的 debug.log 文件，即可启用调试日志并查看详细错误信息。

📈 性能与限制

• 数据集大小：支持包含数千个示例的数据集
• 批量操作：可高效处理批量操作
• 速率限制：遵守 API 速率限制，并妥善处理错误

🤝 贡献

贡献者指南

1. Fork 此代码库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 进行更改
4. 使用手动安装方法在本地测试
5. 创建新的 DXT 包：

   pip install -t lib/ judgeval python-dotenv
   dxt pack
   

6. 在 Claude Desktop 中测试 .dxt 文件
7. 提交更改（git commit -m 'Add some amazing feature'）
8. 推送到分支（git push origin feature/amazing-feature）
9. 发起 Pull Request

发布流程

1. 更新 manifest.json 中的版本
2. 创建并测试 DXT 包
3. 创建 GitHub 发布版本
4. 将 .dxt 文件附加到该发布版本
5. 按需更新 README

📄 许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

🔗 链接

• JudgmentLabs 网站
• JudgmentLabs 文档
• 模型上下文协议
• Claude Desktop

👨‍💻 作者

Sezer Ufuk Yavuz

• Email：[email protected]
• GitHub：@suysoftware
• Linkedin：@ufukyavuzz
• X：@sezerufukyavuz

🙏 致谢

• 感谢 Anthropic 提供模型上下文协议
• 感谢 JudgmentLabs 提供评估平台
• 感谢开源社区作出的宝贵贡献

---

如需更详细的文档和示例，请访问我们的 GitHub 代码库。