zephyr-scale-mcp

zephyr-scale-mcp

适用于自托管 Jira Server / Data Center 的 Zephyr Scale MCP 服务（原名 TM4J）。它通过 {JIRA_BASE_URL}/rest/atm/1.0 上的 Zephyr Scale REST API v1，为 AI Agent 提供 54 个测试管理工具，可供 Claude Code、Claude Desktop、Cursor 以及任何 MCP 客户端使用，涵盖测试用例、文件夹、测试周期、执行、测试计划、附件和自动化导入。

npm：zephyr-scale-mcp · MCP Registry：io.github.vilaabo/zephyr-scale-mcp · 俄语版本 →

⚠️ 适用范围：仅限 Server / Data Center。 Zephyr Scale Cloud（API v2）和 Zephyr Squad 使用不同的 API，不在适用范围内——此服务无法用于它们。

为什么要开发这个项目

大多数 Zephyr MCP 服务面向 Cloud API。如果你的 Jira 部署在本地，你使用的就是 v1 API，而 v1 有不少棘手之处：测试运行创建后不可修改、无法列出文件夹、状态是区分大小写的内部名称、BDD 脚本不接受 Feature: 标头，而且较旧的插件版本缺少整类端点。此服务将这些知识内置其中，不必让 Agent 一次次碰到 400 错误才发现问题。

• 54 个工具（42 个公开工具 + 12 个可选的内部 API 工具），每个工具的说明都会列出端点、调用者无法自行猜出的限制，以及确切的响应结构。
• 弥补 API 盲区的组合工具——add_test_steps 按 ID 合并步骤（读取 → 合并 → 写入），避免内容被静默删除；recreate_test_run_with_items 可绕过测试运行的不可变限制，并可保留上次的结果；get_issue_test_coverage、get_test_run_summary、clone_test_case、move_test_cases_to_folder。
• 兼容较旧版本——分页结果端点不可用时自动回退，批量创建端点故障时则逐项回退。这两种情况都来自真实的旧版实例，而非变更日志。
• 可靠的底层机制——严格的 zod 输入验证、支持 Retry-After 的指数退避重试、附带可行提示的错误消息、只读模式，以及确保密钥不会出现在日志和工具输出中。
• 1181 个单元测试和契约测试（使用 vitest + msw，不访问网络），另有一个需手动启用、针对真实实例的端到端场景。

快速开始

要求：Node.js >= 20、安装了 Zephyr Scale 插件的 Jira Server/DC，以及 Personal Access Token（Jira 8.14+）或用户名/密码组合。

无需克隆——该软件包已发布到 npm。Claude Code：

claude mcp add zephyr-scale \
  --env JIRA_BASE_URL=https://jira.example.com \
  --env JIRA_PAT=<personal access token> \
  --env ZEPHYR_DEFAULT_PROJECT_KEY=PROJ \
  --env ZEPHYR_ALLOW_INTERNAL_API=true \
  -- npx -y zephyr-scale-mcp

Claude Desktop / 任意 MCP 客户端（claude_desktop_config.json、.mcp.json）：

{
  "mcpServers": {
    "zephyr-scale": {
      "command": "npx",
      "args": ["-y", "zephyr-scale-mcp"],
      "env": {
        "JIRA_BASE_URL": "https://jira.example.com",
        "JIRA_PAT": "<personal access token>",
        "ZEPHYR_DEFAULT_PROJECT_KEY": "PROJ",
        "ZEPHYR_ALLOW_INTERNAL_API": "true"
      }
    }
  }
}

git clone https://github.com/vilaabo/zephyr-scale-mcp.git
cd zephyr-scale-mcp
npm install
npm run build        # -> dist/index.js

ZEPHYR_ALLOW_INTERNAL_API=true 是可选项，建议启用。 它会注册 12 个额外工具，可执行公共 API 完全无法完成的操作：直接编辑测试运行——重命名或移动测试运行（update_test_run），以及在不更改其键的情况下添加或移除用例（add_test_cases_to_run、remove_test_cases_from_run）；此外，还能列出文件夹树（get_folder_tree）、删除文件夹（delete_folder）、编辑较早的执行记录（update_test_result_by_id），以及读取 API 默认要求的确切状态名称（get_status_options）。这些工具调用 Jira 界面本身使用的相同未公开 /rest/tests/1.0 端点；供应商不提供支持，而且这些端点在其他 Zephyr Scale 版本中可能不同或不存在。如果无法接受这种权衡，请关闭此标志——其他 42 个工具不受影响。

然后让 Agent 运行 health_check。该工具通过 GET /rest/api/2/myself 验证连接和凭据；如果设置了 ZEPHYR_DEFAULT_PROJECT_KEY，还会验证 Zephyr 插件是否能在 /rest/atm/1.0 上响应。

可以让 Agent 执行的操作

• “创建文件夹 /Regression/Payments，并根据本文档中描述的结账流程添加分步测试用例。”
• “找出 /Regression 中所有 Draft 用例，检查它们，并将已准备好的用例设为 Approved。”
• “为 sprint 42 创建一个周期，加入所有冒烟用例，然后根据此报告记录结果——如果脚本包含步骤，就逐步记录。”
• “哪些测试用例涵盖 PROJ-123？它们各自最近一次通过是什么时候？”——从问题追溯到相关用例及其最新执行记录。
• “将这个包含 Cucumber JSON 报告的 ZIP 导入，并在 PROJ 中发布为新周期。”——自动化导入；系统会根据用例的 @TestCaseKey=PROJ-T1 标签，将场景与 BDD 用例匹配。
• “在 PROJ-T55 的步骤 3 后添加两个步骤。”——现有步骤及其 ID 会保留。
• “重建周期 PROJ-R7，增加三个用例，保留结果，然后删除原周期。”

配置

测试涵盖了两项保证：JIRA_PAT 和 JIRA_PASSWORD 永远不会出现在日志、工具输出或错误消息中——无论它们在输出时采用何种编码：原始形式、JSON 转义形式或 base64 基本身份验证令牌（错误文本仅包含方法和路径——绝不包含可能含有数据的查询字符串）；并且 stdout 专用于 MCP 协议，所有日志行都会写入 stderr。一个有意保留的例外：少于 6 个字符的密钥会原样保留，因为对其进行脱敏会在无法保护任何内容的同时破坏无关输出；服务会在启动时对此发出警告。

配置会在启动时验证：所有问题都会一次性报告，进程会以非零代码退出，而不是在配置不完整的情况下启动。

工具

共有 54 个工具。42 个公开工具始终会注册；最后一组中的 12 个工具仅在 ZEPHYR_ALLOW_INTERNAL_API=true 时注册。

以下是服务器所遵循的约束。每个工具的说明都会重复与其相关的约束，因此 Agent 在调用工具时可以看到。

1. 测试运行不可变。 没有 PUT /testrun：测试运行无法重命名或移动，也无法添加或移除用例。测试运行中的项目在创建时便已固定，运行状态根据项目状态推导。可用的变通方式：recreate_test_run_with_items（公开接口，会生成一个新键），或内部接口 update_test_run / add_test_cases_to_run / remove_test_cases_from_run（沿用同一个键）。
2. 不会隐式创建文件夹。 在未知文件夹中调用 create_test_case、create_test_run 和 create_test_plan 会失败并返回 400。也无法通过公开 API 列出文件夹；重命名文件夹需要使用 create_folder 返回的数字 ID，或在启用内部 API 后使用 get_folder_tree。
3. owner / executedBy / assignedTo 接受 Jira 用户键（JIRAUSER10000），不接受用户名或电子邮件。使用 find_jira_user 进行解析。
4. TQL 语法严格：运算符两侧必须有空格，字符串值必须用双引号括起，连接符只能使用 AND（不能使用 OR），文件夹路径必须以 / 开头。测试运行只能按 projectKey 和 folder 搜索。对于单选和多选自定义字段，= 不起作用——请使用 IN。
5. 状态、优先级和环境均使用区分大小写的内部名称。 内置状态在 UI 中会以本地化名称显示（你看到的 Draft 标签可能是其翻译），自定义状态则显示其字面名称——get_status_options 会显示 API 实际接受的名称。公开 API 会静默忽略错误的执行状态。
6. BDD 脚本只包含场景正文——直接使用 Given / When / Then / And / But 行。包含 Feature: / Scenario: 包装内容的文本会被拒绝，并返回 400 Invalid BDD Script；导出时会自动生成包装内容。
7. STEP_BY_STEP 步骤在 PUT 时按 ID 同步：没有 ID 的步骤会被创建，带 ID 的步骤会被更新，列表中缺失的所有已存储步骤都会被删除。务必发送完整的最终列表，并沿用从 get_test_case 获取的 ID——或者让 add_test_steps 执行读取、合并和写入。
8. 不接受已弃用的字段：使用 issueLinks 代替 issueKey，使用 actualEndDate 代替 executionDate，使用 executedBy 代替 userKey。

旧版插件构建的特殊情况

以下情况均在真实的旧版 Zephyr Scale Server 实例上现场观察到，并已纳入测试。

• 周期键可能使用 -C 前缀（PROJ-C34），而不是 -R。所有运行键参数都按原样接收键值，因此请传入实例显示的键。
• GET /testrun/{key}/testresults/page 可能不存在。 get_test_run_results 和 get_test_run_summary 会回退到已弃用的扁平端点，并在客户端进行分页，同时在响应中添加 note。确实不存在的运行仍会返回 404。
• 同时发送 scriptResults 时，整体 status 会被忽略。 请先发送步骤结果，再使用 update_last_test_result 设置整体状态。
• POST /testcase/link-issues 可能返回 500。 请改用带有 issueLinks 的 update_test_case 来关联问题。
• 对于任何负载，POST /testcase/bulk 都可能返回 HTTP 500 和空响应正文，即使单条创建可以正常工作。create_test_cases_bulk 会回退为逐条创建用例——遇到任何 5xx，以及 JSON 格式的 404（这表示“此构建中没有此端点”，不同于 Jira 在插件不存在时返回的 HTML 格式 404）时都会回退——并报告哪些创建成功了（#1）。其他所有 4xx 都属于负载错误，不会重试。
• 在此构建中，为不属于运行项目的用例提交结果会将其静默添加到运行中；其他构建则会以 400/404 拒绝此调用。结果工具对此两种情况都有说明。
• 自定义自动化结果格式会经过严格验证。 {"version": 1, "executions": [{"source", "result", "testCase": {"key"}}]} 可正常使用；每次执行中额外的字段（例如 executionTime）会被拒绝，并报错 Invalid Custom Format JSON file。只要场景带有 @TestCaseKey=PROJ-T1，Cucumber JSON 报告就能直接使用。
• download_feature_files 需要 tql 查询参数——没有该参数时，API 会拒绝此调用。
• 无法删除运行项目的最后一次执行记录。 delete_test_results 会拒绝此操作；请改为移除项目。
• 自定义字段可能完全不存在——此时定义端点会返回 []。

开发

npm run typecheck    # tsc --noEmit, strict
npm test             # 1181 unit + contract tests (vitest + msw), no network
npm run build        # tsup -> dist/index.js
npm run smoke        # 13 end-to-end tests, ZEPHYR_E2E=1, real instance required

只有在 ZEPHYR_E2E=1 时才会运行冒烟测试场景。该场景需要真实的 JIRA_BASE_URL、凭据，以及一个专用的 ZEPHYR_DEFAULT_PROJECT_KEY——它会创建和删除真实实体，并留下 /mcp-smoke-* 文件夹，因为公共 API 无法删除文件夹。

src/
├── index.ts             # bootstrap: config, tool registration, stdio transport
├── config.ts            # environment validation
├── http.ts              # fetch wrapper: auth, timeouts, retries, error normalization,
│                        #   multipart and binary bodies
├── schemas.ts           # shared parameter schemas, field shapes, recurring description constants
├── toolkit.ts           # defineTool(): strict zod input, read-only guard,
│                        #   JSON / isError response shaping, shared helpers
├── internal.ts          # the UNOFFICIAL /rest/tests/1.0 layer: key -> id resolution,
│                        #   run-item plumbing, status resolution, error hints
├── runResults.ts        # paged run results with the legacy fallback
├── log.ts               # leveled logger, stderr only
└── tools/               # one module per tool family: testCases, testRuns, testResults,
                         #   testPlans, folders, attachments, automation, misc,
                         #   runMaintenance, resultsMaintenance, internalRefs
test/                    # one test module per source module + negative contract tests
                         #   and the gated smoke scenario

版本管理与变更日志

版本为 1.0.0。从此版本起，工具名称、参数名称和响应结构均为公开契约，只会在主版本中更改。请参阅 CHANGELOG.md。

许可证

MIT