Zephyr Scale MCP Server

Zephyr Scale MCP服务器

用于SmartBear Zephyr Scale测试管理平台的综合模型上下文协议（MCP）服务器。该服务器提供与Zephyr Scale的REST API的无缝集成，通过Claude和其他兼容MCP的工具实现自动化测试管理工作流程。

目录

• 特性
• 编码结构
• 先决条件
• 安装
• 配置
• 使用Claude Desktop进行设置
• 可用工具
• 使用示例
• 错误处理
• 贡献
• 许可证

特性

• 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令牌

安装

1. 初始化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

1. 使用UV安装依赖项

   uv add fastmcp python-dotenv httpx

1. 你的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"

配置

1. 生成Zephyr规模的API令牌

- 登录您的Jira实例 - 点击您的个人资料图片（左下角） - 选择“Zephyr API密钥” - 生成新的API密钥 - 复制令牌以进行配置

1. 创建环境文件

创建一个 .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

1. 测试配置

   uv run python zephyr_mcp_server.py

使用Claude Desktop进行设置

1. 找到Claude桌面配置

- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - 视窗: %APPDATA%\Claude\claude_desktop_config.json

1. 添加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"
         }
       }
     }
   }

1. 替代方案：使用.env文件（推荐）

   {
     "mcpServers": {
       "zephyr-scale": {
         "command": "uv",
         "args": ["run", "python", "zephyr_mcp_server.py"],
         "cwd": "/path/to/your/zephyr-scale-mcp"
       }
     }
   }

1. 重新启动克劳德桌面

- 完全关闭克劳德桌面 - 重新启动应用程序 - 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 executions

4.将测试链接到问题

Link test case DEMO-T123 to Jira issue DEMO-456

5.管理测试环境

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 results

7.批量操作

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
}

故障排除

常见问题

1. “未设置API令牌”错误

- 确保 ZEPHYR_API_TOKEN 已设置 .env 文件 - 验证令牌是否有效且未过期

1. “连接超时”错误

- 检查网络连接 - 验证API基本URL（全球与欧盟地区）

1. “找不到项目”错误

- 确保项目密钥存在且可访问 - 检查Jira/Zephyr Scale中的用户权限

1. 工具未出现在Claude中

- 验证 claude_desktop_config.json 语法 - 检查文件路径是否为绝对路径 - 配置更改后重新启动Claude Desktop

调试模式

通过修改服务器启用调试日志记录：

logging.basicConfig(level=logging.DEBUG)

API费率限制

Zephyr Scale有速率限制。服务器优雅地处理这些问题：

• 自动重试速率限制错误
• 指数退避策略
• 超出限制时清除错误消息

安全考虑

• 将API令牌安全地存储在环境变量中
• 使用 .env 仅用于本地开发的文件
• 考虑在生产中使用机密管理
• 定期轮换API代币
• 监控API使用和访问日志

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 如果适用，添加测试
5. 提交拉取请求

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

支持

关于以下问题：

• 此MCP服务器：在此存储库中创建问题
• Zephyr规模API：联系SmartBear支持
• 克劳德桌面：联系Anthropic支持

更新日志

v1.0.0

• API全面覆盖的首次发布
• 支持所有主要的Zephyr Scale端点
• 全面的错误处理
• 区域支持（全球/欧盟）
• Claude桌面集成