MCP Zephyr

MCP Zephyr服务器

Zephyr Scale Cloud API的全面模型上下文协议（MCP）服务器，可实现与测试管理工作流程的无缝集成。

🚀 特性

核心能力

• 项目管理：列出并检索项目详细信息
• 文件夹组织：创建和管理分层文件夹结构
• 测试用例管理：为测试用例创建、读取和更新操作
• 测试步骤管理：获取并附加测试步骤（注意：没有单独的步骤更新/删除）
• 测试脚本管理：创建和管理BDD/Gherkin测试脚本（与步骤互斥）
• 参考数据：测试用例配置的访问状态和优先级

🛠️ 可用工具

项目工具

• list_projects -获取所有Zephyr集成Jira项目
• get_project -检索详细的项目信息

文件夹工具

• list_folders -列出具有项目/文件夹筛选功能的文件夹
• get_folder -获取详细的文件夹信息
• create_folder -创建具有可选父层次结构的新文件夹

测试用例工具

• list_test_cases -列出带有筛选功能的测试用例（项目、文件夹）
• get_test_case -检索详细的测试用例信息
• create_test_case -创建具有完整配置的新测试用例
• update_test_case -更新现有测试用例

测试步骤工具

• get_test_steps -获取测试步骤（分页，最多100个项目）
• get_all_test_steps -获取所有测试步骤（自动分页）
• append_test_steps -在现有序列中添加新步骤（每个请求最多100个）

测试脚本工具

• get_test_script -获取BDD/Gherkin测试脚本
• create_test_script -创建/更新测试脚本（删除现有步骤）
• create_bdd_test_script -BDD脚本创建和验证的助手

参考数据工具

• list_statuses -获取所有可用状态（草稿、就绪、已批准等）
• list_priorities -获取所有可用优先级（高、中、低等）
• get_reference_data -在一次通话中获取状态和优先级

📋 先决条件

• Node.js 18.0.0或更高版本
• 具有API访问权限的Zephyr Scale云帐户
• 启用Zephyr集成的Jira项目

🔧 安装

1. 克隆或下载此存储库

1. 安装依赖项:

   npm install

1. 设置环境变量:

   cp .env.example .env

编辑 .env 并添加您的Zephyr API令牌：

   ZEPHYR_API_TOKEN=your_bearer_token_here
   ZEPHYR_REGION=us

🔑 获取您的API代币

1. 登录您的Jira Cloud实例
2. 点击左下角的个人资料图片
3. 选择“Zephyr API密钥”
4. 生成新的API令牌
5. 将令牌复制到您的 .env 文件

🚀 运行服务器

发展模式

npm run dev

生产模式

npm start

使用MCP客户端

# Start the server
npm start

# In another terminal, use with your MCP client
# Configuration will be automatically discovered

🔌 使用此MCP服务器

此软件包是一个通过stdio进行通信的MCP服务器。它被设计为由MCP客户端（例如，VS Code MCP扩展或Claude Desktop）启动。如果直接运行它，它将显示为“空闲”，因为它在stdin上等待MCP协议消息。

VS代码MCP扩展

创建或更新您的MCP配置文件（例如.vcode/MCP.json）以包含此服务器：

{
  "servers": {
    "zephyr": {
      "type": "stdio",
      "command": "mcp-zephyr",
      "env": {
        "ZEPHYR_API_TOKEN": "YOUR_TOKEN_HERE",
        "ZEPHYR_REGION": "us"
      }
    }
  },
  "inputs": []
}

然后从MCP扩展UI启动服务器。它应该保持在运行状态，并准备好接收工具调用。

克劳德桌面（MCP）

在Claude Desktop MCP设置中添加服务器条目：

{
  "mcpServers": {
    "zephyr": {
      "command": "mcp-zephyr",
      "env": {
        "ZEPHYR_API_TOKEN": "YOUR_TOKEN_HERE",
        "ZEPHYR_REGION": "us"
      }
    }
  }
}

保存后，重新启动Claude Desktop。服务器将可用于聊天中的工具使用。

本地CLI（用于调试）

如果要查看日志，请在stderr可见的情况下运行：

mcp-zephyr 2> server.log

服务器日志被写入stderr，以避免干扰stdout上的MCP协议消息。

🧰 测试单个工具

对于开发和调试，您可以使用 test-tools.js 脚本：

列出可用工具

node test-tools.js --list

测试工具

# Simple tool without arguments
node test-tools.js list_projects

# Tool with arguments (pass JSON)
node test-tools.js list_projects '{"maxResults": 10}'

# Get specific project
node test-tools.js get_project '{"projectId": "PROJ1"}'

# Create a test case
node test-tools.js create_test_case '{"name": "Login Test", "projectKey": "PROJ"}'

# List test cases with filtering
node test-tools.js list_test_cases '{"projectKey": "PROJ", "maxResults": 5}'

# Get reference data
node test-tools.js get_reference_data

备注：确保你的 .env 文件配置为 ZEPHYR_API_TOKEN 在运行测试工具之前。

📝 用法示例

基本项目操作

// List all projects
{
  "tool": "list_projects",
  "arguments": {
    "maxResults": 50
  }
}

// Get specific project
{
  "tool": "get_project",
  "arguments": {
    "projectId": "PROJ"
  }
}

文件夹管理

// Create a folder
{
  "tool": "create_folder",
  "arguments": {
    "name": "Smoke Tests",
    "projectKey": "PROJ",
    "parentFolderId": "123"
  }
}

测试用例创建

// Create a comprehensive test case
{
  "tool": "create_test_case",
  "arguments": {
    "name": "User Login Test",
    "projectKey": "PROJ",
    "description": "Verify user can log in with valid credentials",
    "priorityName": "High",
    "statusName": "Ready",
    "folderId": "123",
    "component": "Authentication",
    "labels": ["smoke", "regression"],
    "objective": "Verify login functionality",
    "precondition": "User exists in system",
    "estimatedTime": 5
  }
}

测试步骤管理

// Append test steps
{
  "tool": "append_test_steps",
  "arguments": {
    "testCaseKey": "PROJ-T1",
    "steps": [
      {
        "description": "Navigate to login page",
        "expectedResult": "Login page is displayed"
      },
      {
        "description": "Enter valid username and password",
        "expectedResult": "Credentials are accepted"
      },
      {
        "description": "Click login button",
        "expectedResult": "User is logged in and redirected to dashboard"
      }
    ]
  }
}

BDD测试脚本创建

// Create BDD script with helper
{
  "tool": "create_bdd_test_script",
  "arguments": {
    "testCaseKey": "PROJ-T2",
    "feature": "User Authentication",
    "scenario": "Successful login with valid credentials",
    "steps": [
      "Given I am on the login page",
      "And I have valid user credentials",
      "When I enter my username and password",
      "And I click the login button",
      "Then I should be redirected to the dashboard",
      "And I should see my username displayed"
    ]
  }
}

获取参考数据

// Get all statuses and priorities
{
  "tool": "get_reference_data"
}

⚠️ 重要说明

测试步骤与测试脚本

• 互斥：一个测试用例可以有测试步骤或测试脚本，而不是两者都有
• 脚本创建警告：创建测试脚本会自动删除现有的测试步骤
• 步骤限制：单个测试步骤不能更新或删除，只能批量附加

API约束

• 分页：大多数端点支持分页（每个请求最多1000个项目）
• 步骤限制：每个请求最多可以添加100个测试步骤
• 速率限制：遵守Zephyr Cloud API费率限制
• 区域支持：通过配置支持美国和欧盟地区

数据格式

• 测试用例密钥：格式 [A-Z]+-T[0-9]+ （例如。， PROJ-T1)
• 项目密钥：格式 [A-Z][A-Z_0-9]+ （例如。， PROJ, PROJ123)
• 文件夹ID：数字字符串（例如。， "123")
• 测试脚本：Gherkin格式用于BDD，纯文本用于简单脚本

🧪 测试

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run with coverage
npm test -- --coverage

🔍 代码质量

# Run linter
npm run lint

# Fix linting issues
npm run lint:fix

🏗️ 项目结构

mcp-zephyr/
├── src/
│   ├── config.js              # Configuration management
│   ├── zephyr-client.js       # API client with error handling
│   ├── index.js               # Main MCP server entry point
│   └── tools/                 # MCP tool implementations
│       ├── project-tools.js
│       ├── folder-tools.js
│       ├── test-case-tools.js
│       ├── test-steps-tools.js
│       ├── test-script-tools.js
│       └── reference-data-tools.js
├── tests/                     # Unit tests
│   ├── setup.js
│   ├── config.test.js
│   ├── zephyr-client.test.js
│   └── tools/
│       └── project-tools.test.js
├── .env.example               # Environment template
├── package.json               # Dependencies and scripts
├── eslint.config.js           # ESLint configuration
├── jest.config.js             # Jest test configuration
└── README.md                  # This file

🔌 MCP集成

此服务器实现了模型上下文协议规范：

• 工具发现：通过自动工具列表 ListToolsRequestSchema
• 工具执行：通过标准化工具调用 CallToolRequestSchema
• 错误处理：所有操作的一致错误响应
• JSON 模式：所有工具参数的输入验证

🐛 故障排除

常见问题

1. “ZEPHYR_API_TOKEN环境变量是必需的”

- 确保您已创建 .env 带有有效API令牌的文件 - 检查令牌是否未过期

1. “testCaseKey格式无效”

- 测试用例密钥必须与模式匹配 [A-Z]+-T[0-9]+ - 示例： PROJ-T1, PROJECT123-T456

1. “请求超时”

- 检查您的互联网连接 - 尝试减少 maxResults 用于大型请求的参数

1. “未找到测试用例”

- 验证Zephyr实例中是否存在测试用例密钥 - 确保您拥有适当的项目权限

调试模式

通过设置环境变量启用调试日志记录：

DEBUG=* npm start

📄 许可证

MIT许可证-有关详细信息，请参阅许可证文件。

🤝 贡献

1. 克隆该仓库
2. 创建要素分支
3. 进行更改
4. 添加新功能的测试
5. 运行测试套件
6. 提交拉取请求

🆘 支持

• Zephyr文档: Zephyr Scale Cloud API文档
• MCP规范: 模型上下文协议
• 问题：通过GitHub Issues报告bug