Zephyr Scale MCP服务器
用于SmartBear Zephyr Scale测试管理平台的综合模型上下文协议（MCP）服务器。该服务器提供与Zephyr Scale的REST API的无缝集成，通过Claude和其他兼容MCP的工具实现自动化测试管理工作流程。
目录
特性
- API全面覆盖：所有主要的Zephyr Scale终点
- 区域支持：全球和欧盟地区API
- 全面的错误处理：详细的错误消息和状态代码
- 类型安全：正确的类型提示和枚举
- 分页支持：高效处理大型数据集
- 灵活的身份验证：基于JWT令牌的身份验证
- 日志记录：用于调试的全面日志记录
编码结构
zephyr-scale-mcp/
├── .venv/ # UV virtual environment
├── zephyr_mcp_server.py # Main MCP server implementation
├── .env # Environment variables (create this)
├── pyproject.toml # UV project configuration
├── uv.lock # UV lock file
├── .gitignore # Git ignore file
└── README.md # This file核心组件
# Main server initialization
mcp = FastMCP("zephyr-scale")
# HTTP client with error handling
async def make_zephyr_request(method, url, data=None, params=None)
# Tool categories:
# - Test Cases (13 tools)
# - Folders (3 tools)
# - Test Cycles (4 tools)
# - Test Executions (4 tools)
# - Projects (2 tools)
# - Priorities (4 tools)
# - Statuses (4 tools)
# - Environments (4 tools)
# - Links (1 tool)
# - Issue Links (4 tools)
# - Utilities (2 tools)先决条件
- Python 3.8+
- 具有API访问权限的Zephyr Scale帐户
- Jira实例已连接到Zephyr Scale
- 有效的Zephyr Scale API令牌
安装
- 初始化UV项目
# Create project directory
mkdir zephyr-scale-mcp
cd zephyr-scale-mcp
# Initialize uv project
uv init
# Save the zephyr_mcp_server.py file in this directory- 使用UV安装依赖项
uv add fastmcp python-dotenv httpx- 你的pyproject.toml应该看起来像
[project]
name = "zephyr-scale-mcp"
version = "0.1.0"
description = "Zephyr Scale MCP Server"
dependencies = [
"fastmcp>=0.1.0",
"dotenv>=1.0.0",
"httpx>=0.25.0",
]
requires-python = ">=3.8"配置
- 生成Zephyr规模的API令牌
- 登录您的Jira实例 - 点击您的个人资料图片（左下角） - 选择“Zephyr API密钥” - 生成新的API密钥 - 复制令牌以进行配置
- 创建环境文件
创建一个 .env 项目目录中的文件：
# Required: Your Zephyr Scale API token
ZEPHYR_API_TOKEN=your_jwt_token_here
# Optional: Set to true for EU region (default: false)
ZEPHYR_USE_EU_REGION=false- 测试配置
uv run python zephyr_mcp_server.py使用Claude Desktop进行设置
- 找到Claude桌面配置
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - 视窗: %APPDATA%\Claude\claude_desktop_config.json
- 添加MCP服务器配置
{
"mcpServers": {
"zephyr-scale": {
"command": "uv",
"args": ["run", "python", "app.py"],
"cwd": "/path/to/your/zephyr-scale-mcp",
"env": {
"ZEPHYR_API_TOKEN": "your_jwt_token_here",
"ZEPHYR_USE_EU_REGION": "false"
}
}
}
}- 替代方案：使用.env文件（推荐）
{
"mcpServers": {
"zephyr-scale": {
"command": "uv",
"args": ["run", "python", "zephyr_mcp_server.py"],
"cwd": "/path/to/your/zephyr-scale-mcp"
}
}
}- 重新启动克劳德桌面
- 完全关闭克劳德桌面 - 重新启动应用程序 - Zephyr Scale工具现在应该可用了
可用工具
📝 测试用例（13个工具）
get_test_cases-列出带有筛选功能的测试用例get_test_case-获取特定测试用例详细信息create_test_case-创建新的测试用例update_test_case-更新现有测试用例get_test_case_links-获取测试用例的所有链接create_test_case_issue_link-将测试用例链接到Jira问题create_test_case_web_link-为测试用例创建web链接get_test_case_versions-获取测试用例的所有版本get_test_case_version-获取特定版本get_test_case_script-获取测试脚本内容create_test_case_script-创建/更新测试脚本get_test_case_steps-获取测试步骤create_test_case_steps-创建测试步骤
📁 文件夹（3个工具）
get_folders-列出具有筛选功能的文件夹get_folder-获取特定文件夹的详细信息create_folder-创建新文件夹
🔄 测试周期（4个工具）
get_test_cycles-列出测试周期get_test_cycle-获取特定的测试周期create_test_cycle-创建新的测试周期update_test_cycle-更新现有测试周期
▶️ 测试执行（4个工具）
get_test_executions-列出测试执行情况get_test_execution-获得具体执行create_test_execution-创建新执行update_test_execution-更新执行结果
🏗️ 项目（2个工具）
get_projects-列出所有项目get_project-获取具体项目详细信息
🔺 优先级（4种工具）
get_priorities-列出优先级get_priority-获得特定优先级create_priority-创建新优先级update_priority-更新现有优先级
📊 状态（4个工具）
get_statuses-列出状态get_status-获取特定状态create_status-创建新状态update_status-更新现有状态
🌍 环境（4个工具）
get_environments-列出环境get_environment-获取特定环境create_environment-创建新环境update_environment-更新现有环境
🔗 链接（1个工具）
delete_link-按ID删除任何链接
🎯 问题链接（4个工具）
get_issue_link_test_cases-获取与Jira问题关联的测试用例get_issue_link_test_cycles-获取与Jira问题关联的测试周期get_issue_link_test_plans-获取与Jira问题关联的测试计划get_issue_link_test_executions-获取与Jira问题关联的执行
🛠️ 实用程序（2个工具）
health_check-检查API运行状况get_api_info-获取服务器配置信息
使用示例
1.创建测试用例
Create a test case named "User Login Validation" for project "DEMO" with high priority and objective "Validate user authentication flow"2.使用文件夹组织测试
Create a folder structure for organizing regression tests in project "DEMO"3.执行测试循环
Create a test cycle for Sprint 1 testing in project "DEMO" and show me all test executions4.将测试链接到问题
Link test case DEMO-T123 to Jira issue DEMO-4565.管理测试环境
Create testing environments for Chrome, Firefox, and Safari browsers in project "DEMO"6.生成测试报告
Get all test executions for project "DEMO" from the last 7 days and summarize the results7.批量操作
Get all test cases in folder ID 100 and update their priority to "High"8.集成工作流程
For each failed test execution, create a Jira issue and link it to the test case错误处理
服务器包括全面的错误处理：
- HTTP错误：详细的状态代码和消息
- 身份验证错误：明确令牌验证反馈
- 验证错误：参数验证，并显示有用消息
- 网络错误：超时和连接错误处理
- JSON解析：妥善处理格式错误的回复
错误响应示例：
{
"error": "HTTP 401: Unauthorized - Invalid API token",
"status_code": 401
}故障排除
常见问题
- “未设置API令牌”错误
- 确保 ZEPHYR_API_TOKEN 已设置 .env 文件 - 验证令牌是否有效且未过期
- “连接超时”错误
- 检查网络连接 - 验证API基本URL（全球与欧盟地区）
- “找不到项目”错误
- 确保项目密钥存在且可访问 - 检查Jira/Zephyr Scale中的用户权限
- 工具未出现在Claude中
- 验证 claude_desktop_config.json 语法 - 检查文件路径是否为绝对路径 - 配置更改后重新启动Claude Desktop
调试模式
通过修改服务器启用调试日志记录：
logging.basicConfig(level=logging.DEBUG)API费率限制
Zephyr Scale有速率限制。服务器优雅地处理这些问题：
- 自动重试速率限制错误
- 指数退避策略
- 超出限制时清除错误消息
安全考虑
- 将API令牌安全地存储在环境变量中
- 使用
.env仅用于本地开发的文件 - 考虑在生产中使用机密管理
- 定期轮换API代币
- 监控API使用和访问日志
贡献
- 分叉存储库
- 创建要素分支
- 进行更改
- 如果适用，添加测试
- 提交拉取请求
许可证
此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。
支持
关于以下问题：
- 此MCP服务器：在此存储库中创建问题
- Zephyr规模API：联系SmartBear支持
- 克劳德桌面：联系Anthropic支持
更新日志
v1.0.0
- API全面覆盖的首次发布
- 支持所有主要的Zephyr Scale端点
- 全面的错误处理
- 区域支持（全球/欧盟）
- Claude桌面集成