使用说明

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 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
}

故障排除

常见问题

“未设置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桌面集成