Testcollab Mcp Server

TestCollab MCP 服务

将你的 AI 编码助手连接到 TestCollab——直接通过 Claude、Cursor、Windsurf、Codex 或任何兼容 MCP 的客户端管理测试用例、测试计划和测试套件。

快速开始

1. 获取 API 令牌

登录 TestCollab → 我的个人资料设置 → API 令牌选项卡 → 生成新的 API 令牌。

2. 将服务添加到 MCP 客户端

Claude Code — 添加到项目根目录下的 .mcp.json：

{
  "mcpServers": {
    "testcollab": {
      "command": "npx",
      "args": ["-y", "@testcollab/mcp-server"],
      "env": {
        "TC_API_TOKEN": "your-api-token",
        "TC_API_URL": "https://api.testcollab.io",
        "TC_DEFAULT_PROJECT": "16"
      }
    }
  }
}

Claude Desktop — 添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "testcollab": {
      "command": "npx",
      "args": ["-y", "@testcollab/mcp-server"],
      "env": {
        "TC_API_TOKEN": "your-api-token",
        "TC_API_URL": "https://api.testcollab.io",
        "TC_DEFAULT_PROJECT": "16"
      }
    }
  }
}

Codex - 从命令行注册 TestCollab：

codex mcp add testcollab \
  --env TC_API_TOKEN=your-api-token \
  --env TC_API_URL=https://api.testcollab.io \
  --env TC_DEFAULT_PROJECT=16 \
  -- npx -y @testcollab/mcp-server

也可以将服务添加到 ~/.codex/config.toml，供所有项目使用；或者添加到受信任项目中的 .codex/config.toml：

[mcp_servers.testcollab]
command = "npx"
args = ["-y", "@testcollab/mcp-server"]

[mcp_servers.testcollab.env]
TC_API_TOKEN = "your-api-token"
TC_API_URL = "https://api.testcollab.io"
TC_DEFAULT_PROJECT = "16"

运行 codex mcp list，确认服务已配置。有关配置范围和其他选项，请参阅官方 Codex MCP 文档。

Cursor — 添加到项目根目录下的 .cursor/mcp.json：

{
  "mcpServers": {
    "testcollab": {
      "command": "npx",
      "args": ["-y", "@testcollab/mcp-server"],
      "env": {
        "TC_API_TOKEN": "your-api-token",
        "TC_API_URL": "https://api.testcollab.io",
        "TC_DEFAULT_PROJECT": "16"
      }
    }
  }
}

手动测试

TC_API_TOKEN=your-token npm start

可用工具

list_test_cases

列出项目中的测试用例，可选择添加筛选条件。

参数：

名称	类型	必填	说明
project_id	number	否*	项目 ID（*如果未设置 TC_DEFAULT_PROJECT，则为必填）
suite	number|string	否	按套件 ID 或标题筛选
filter	object	否	筛选条件
sort	array	否	排序规则
limit	number	否	最大结果数（1-100，默认值：50）
offset	number	否	跳过的结果数（默认值：0）

3. 验证

重启客户端，然后询问：“TestCollab 有哪些工具？”

你应该会看到列出的 TestCollab 工具。试着询问：“显示所有测试用例”。

配置

变量	必填	默认值	说明
TC_API_TOKEN	是	—	TestCollab 个人资料中的 API 令牌
TC_API_URL	否	https://api.testcollab.io	TestCollab API 基础 URL
TC_DEFAULT_PROJECT	否	—	默认项目 ID（在每次工具调用中，project_id 都将变为可选项）

欧盟区域： 如果你的 TestCollab 账户托管在欧盟，请将 https://api-eu.testcollab.io 用作 TC_API_URL。

可执行的操作

工具	描述
get_project_context	获取套件、标签、自定义字段、需求、测试计划文件夹、发布和用户 — 请先调用此工具
list_test_cases	使用筛选、排序和分页查询测试用例
get_test_case	获取包含完整步骤详情的测试用例
create_test_case	创建包含步骤、标签和自定义字段的测试用例
update_test_case	更新任意测试用例字段
list_test_plans	使用筛选和排序列出测试计划（包括发布 ID／标题筛选条件）
get_test_plan	获取一个测试计划，包含其中的测试用例数量、配置、运行、当前进度状态和发布信息
create_test_plan	通过 ID、选择器或标签 ID／名称选择用例来创建测试计划；除非覆盖，否则保留默认受分配人
get_test_plan_cases	获取某次运行的用例步骤、预期结果、配置状态和已分配的执行 ID
report_test_case_result	记录一次执行，包括状态、评论、毫秒数、步骤结果和证据文件
report_results	提交结构化批次，设置计划自定义字段，并可选择跳过未提交的分配项
update_test_plan	更新测试计划元数据、状态、分配和发布关联
delete_test_plan	删除测试计划
list_suites	列出项目中的所有测试套件（支持 title、parent 和 description 筛选条件）
get_suite	获取套件详情
create_suite	创建新套件
update_suite	更新套件
delete_suite	删除套件
move_suite	将套件移动到其他父级下
reorder_suites	重新排列父级下的套件

示例提示词

"Show me all high-priority test cases in the Login suite"

"Create a test case for verifying password reset with 5 steps"

"List all test plans created this week"

"Create a regression test plan with all test cases tagged 'smoke'"

"Move the Payment suite under the Checkout suite"

详细工作流请参阅使用案例。

通过 MCP 执行计划

使用现有创建流程创建带标签的计划：

{
  "title":"Smoke tests",
  "test_cases":{"tag_name":"Smoke","assignee":"me"},
  "override_assignees":false
}

test_cases.tag_id 改为选择一个数字形式的项目标签。请使用一个标签引用； 标签选择可以包含额外的 selector 筛选条件，并且独立于显式指定的 test_case_ids。 仍可使用现有的用例、配置、分配、发布、文件夹和自定义字段选项。若未提供 override_assignees 或其值为 false，则保留用例默认受分配人，并仅将提供的受分配人 分配给未分配的用例。将其设为 true 可替换默认受分配人。

调用 get_test_plan_cases 并提供 test_plan_id。同时提供 run_id，以获取令牌所有者 被分配的执行 ID 和运行的修订步骤。响应包含 testCases、configurations、带有有效 systemName 值的 statuses，以及 executions。请使用这些内部 ID；TC- 显示编号是不同的 ID。

对于数据驱动的用例，每个用例都包含 datasets，其中有 id、name、 parameters 和 rows（index 加 values）。每个执行都包含其已保存的 datasets 和 datasetResults。运行时请使用执行记录中的快照；之后对 库的编辑可能会更改用例当前的数据集。

使用 report_test_case_result 报告一项已分配的执行：

{
  "run_id":365,
  "executed_test_case_id":53404,
  "status":"passed",
  "comment":"Login succeeded",
  "time_taken":1200,
  "step_results":[{
    "step":"Sign in","expected_result":"Home page appears","status":"passed",
    "attachments":[{"file_name":"step.log","content_base64":"T2sK"}]
  }],
  "attachments":[{"file_name":"run.log","content_base64":"T2sK"}]
}

step_results 会按位置与运行步骤匹配：每个已保存步骤都会保留其 文本和预期结果，并使用你发送的状态和评论。未发送的步骤会采用用例状态。 每个步骤最多发送一个结果。状态使用有效的系统名称，包括自定义状态。time_taken 以 毫秒计（CLI 的 tc reportCase --time-taken 使用秒）。令牌决定执行者； 结果会记录 execution_source: agent（在 Run Mode 列中显示为“Agent”）和 execution_context.tool: tc-mcp-server。TestCollab 将 agent 结果计为机器执行。

每个 step_results 条目都可以接受一个可选的 attachments 列表，格式与顶层列表相同。 步骤文件会显示在对应步骤下，之前保存的步骤文件会保留。顶层文件属于整个结果。 附件在结果、步骤和数据集行中合计每次调用最多可包含 10 个文件。在 stdio 模式下，使用 {"file_path":"/path/to/screenshot.png"} 指定本地常规文件，文件大小上限为 10 MB。 你也可以使用 file_name 和标准填充格式的 content_base64，每个文件解码后大小上限为 1 MB。省略 data URL 前缀。可选的 mime_type 会覆盖基于文件扩展名的检测结果。

对于数据驱动的执行，请发送 dataset_results，而不是 step_results：

{
  "run_id":365,
  "executed_test_case_id":53404,
  "status":"failed",
  "dataset_results":[
    {"dataset_id":7,"dataset_row_index":0,"step_index":0,"status":"passed"},
    {"dataset_id":7,"dataset_row_index":1,"step_index":0,"status":"failed",
     "comment":"This account could not sign in",
     "attachments":[{"file_name":"failure.log","content_base64":"T2sK"}]}
  ]
}

从执行的 datasetResults 中复制 dataset_id、dataset_row_index 和 step_index；索引从零开始。每个提供的条目只会更改对应行和步骤。未报告的条目会保留其状态、备注和文件。新文件会添加到所选条目已有的文件中。10 个文件的限制适用于顶层、步骤和行中的文件总数。用例的 status 在项目状态词汇中的级别必须不低于所有已保存的行状态。在上传或写入前，会拒绝重复或未知的坐标，以及非活动状态。行文件会先上传并关联到执行，然后才会将其 ID 保存到行结果中。如果随后写入结果失败，这些文件仍会关联到执行，且不会添加耗时。

结果写入前会检查证据是否有效。结果保存后发生的错误会指出耗时或证据更新失败；重复执行耗时更新可能导致重复添加。步骤文件会先上传并关联到执行，然后才会将其 ID 保存到步骤中。如果上传或关联失败，则不会更新结果和耗时。

对于 report_results，请传入 test_plan_id 和非空的 results 数组：

{
  "test_plan_id":131,
  "results":[{"test_case_id":1724,"configuration_id":9,"status":"passed","time_taken":1200}],
  "skip_missing":true,
  "custom_fields":[{"id":5,"name":"environment_text","value":"staging","valueLabel":"staging"}]
}

可选的 run_id 用于选择某个运行；否则会使用最新的运行。系统会根据内部用例 ID 和配置 ID 匹配调用方分配的执行。当匹配到多个分配的执行时，必须提供 configuration_id。写入前会拒绝无效和重复的目标。自定义字段使用 API ID、系统名称和带类型的值；未指定的现有值会保留。成功提交提供的结果后，skip_missing 会将调用方遗漏的分配标记为已跳过。响应会列出已确认的结果、已跳过的 ID 和每个执行对应的错误。重试部分失败前请先检查响应。可通过 report_test_case_result 附加批量证据。文件解析、自动创建和构建不属于此执行流程。

请参阅执行架构和验证。

本地开发环境设置

如果你要参与贡献，或想从源代码运行而不是使用 npx：

git clone <repo-url>
cd tc-mcp-server
npm install
npm run build

然后将 MCP 客户端指向构建后的文件：

{
  "mcpServers": {
    "testcollab": {
      "command": "node",
      "args": ["/path/to/tc-mcp-server/dist/index.js"],
      "env": {
        "TC_API_TOKEN": "your-api-token",
        "TC_API_URL": "http://localhost:1337",
        "TC_DEFAULT_PROJECT": "16"
      }
    }
  }
}

开发命令

npm run dev          # Watch mode with hot reload
npm run build        # Compile TypeScript
npm test             # Run tests
npm run typecheck    # Type check
npm run lint         # Lint

故障排除

客户端中未显示服务

• 添加配置后重启客户端
• 确认已安装 Node.js 20+：node --version
• 手动测试：TC_API_TOKEN=your-token npx @testcollab/mcp-server

身份验证错误

• 确认 API 令牌有效且未过期
• 检查 TC_API_URL 是否指向正确的服务

“project_id is required”错误

• 在环境配置中设置 TC_DEFAULT_PROJECT，或
• 在提示词中指定项目：“显示项目 16 中的测试用例”

许可证

MIT