testlink-mcp

testlink-mcp

面向 AI、以安全为先的 TestLink 1.9.20 模型上下文协议服务。它通过 stdio 提供规范化的发现与分析工具、有界游标分页、结构化输出，以及先预览再应用的写入操作。

本仓库基于 TestLink 的公开 XML-RPC 接口和公开 MCP SDK 实现，不依赖私有 TestLink 软件包或私有源代码树。

亮点

• 无需凭据即可启动，方便 MCP 客户端发现所有工具、资源和提示词。
• 提供明确、确定性的演示模式，便于评估和入门。
• 支持 structuredContent、outputSchema、工具注释、游标分页和稳定的错误代码。
• 仅提供附件元数据；附件内容和 base64 负载均会移除。
• 默认禁用写入；不提供删除工具。
• 每次应用都必须提供 confirm: true、未过期且只能使用一次的 10 分钟预览，以及未发生变化的服务端快照。
• 副作用调用绝不自动重试；应用尝试会记录到经过脱敏的操作日志中。
• 运行时保护机制会阻止使用不受支持或已 EOL 的 Node 奇数版本，以及低于声明下限的安全补丁级别。

安全写入演示

演示仅使用合成数据，展示了必要的安全边界： 先预览拟议的更改，再检查有界差异，随后使用确切的预览 ID 和 confirm: true 调用应用操作。预览期间不会发生任何写入。 可编辑的源帧位于 docs/assets/testlink-safety。

要求

• Node.js ^22.23.2 || ^24.18.1 || ^26.5.1
• 已启用 XML-RPC API 的 TestLink 1.9.20

开发和容器基线版本为 Node 24.19.0 LTS。CI 也会运行 Node 22.23.2 和 26.7.0。

快速开始

nvm use
npm ci
npm run build
TESTLINK_DEMO_MODE=true node dist/cli.js

发布后使用 npm 调用：

npx -y [email protected]

MCP 客户端配置：

{
  "mcpServers": {
    "testlink": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": {
        "TESTLINK_URL": "https://testlink.example.com/testlink",
        "TESTLINK_DEV_KEY": "your-testlink-dev-key"
      }
    }
  }
}

不要将真实凭据放入受版本控制的文件中。将 .env.example 复制为已忽略的 .env，或通过 MCP 客户端／密钥管理器注入环境变量。

工具

工作流	工具	用途
启动	testlink_get_server_capabilities	检查配置、兼容性、演示模式和写入策略
探索	testlink_list_projects	列出项目
探索	testlink_list_test_plans	列出项目中的计划
探索	testlink_list_builds	列出计划中的构建
探索	testlink_list_test_suites	遍历一层测试套件
分析	testlink_search_test_cases	在有界的项目／套件范围内搜索用例
分析	testlink_get_test_case	获取一个规范化用例
分析	testlink_list_test_case_attachments	获取安全的附件元数据
分析	testlink_get_traceability	检查需求链接，以及用例是否属于一个必需的测试计划
分析	testlink_get_execution_history	检查近期执行证据
验证	testlink_validate_test_case	查找内容不完整或含糊的用例
预览	testlink_preview_test_case_sync	预览创建／更新操作和计划成员关系
应用	testlink_apply_test_case_sync	应用未更改且已确认的同步预览
预览	testlink_preview_execution_result	预览通过／失败／阻塞结果的报告
应用	testlink_apply_execution_result	应用未更改且已确认的结果预览

所有工具均返回：

{
  "ok": true,
  "data": {},
  "meta": {
    "source": "testlink",
    "requestId": "..."
  }
}

失败时会返回 ok: false 和 { code, message, retryable, details? }。使用方应根据 error.code 分支处理，而不是根据消息文本。

安全写入工作流

1. 搜索现有用例并获取其当前版本。
2. 验证所需的测试用例。
3. 调用相关的预览工具。
4. 创建用例时，提供 TestLink authorLogin；TestLink 1.9.20 还要求提供 desiredCase.suiteId、summary 和 steps。
5. 向用户展示 proposedChanges 并取得明确确认。
6. 在 10 分钟内使用预览 ID 和 confirm: true 调用 apply。
7. 确认后的 apply 会在产生任何副作用前消耗其预览。无论成功、冲突还是失败，再次尝试前都要创建并审查新的预览。
8. 如果 apply 返回 OUTCOME_UNKNOWN，请勿重试。远程写入可能已成功；请先核对 TestLink 用例、计划成员关系或执行结果。

仅在应执行写入操作的服务器进程中启用写入：

TESTLINK_WRITE_ENABLED=true npx -y [email protected]

默认账本路径为 ~/.local/state/testlink-mcp/operations.jsonl。使用 TESTLINK_LEDGER_PATH 覆盖该路径。远程写入前，服务器会持久化一条 attempted 记录；随后记录 applied 或 outcome_unknown。账本包含哈希和已脱敏的结果，不包含开发者密钥。

配置

变量	默认值	含义
TESTLINK_URL	未设置	TestLink 基础 URL 或完整的 XML-RPC 端点
TESTLINK_DEV_KEY	未设置	个人 TestLink API 密钥
TESTLINK_DEMO_MODE	false	使用确定性的本地演示数据
TESTLINK_WRITE_ENABLED	false	允许使用已确认的 apply 工具
TESTLINK_REQUEST_TIMEOUT_MS	30000	请求超时时间，100–300000 ms
TESTLINK_MAX_RESPONSE_BYTES	5242880	XML 响应大小上限
TESTLINK_LEDGER_PATH	用户状态目录	已脱敏的 JSONL 操作账本
NODE_EXTRA_CA_CERTS	未设置	可选的额外 CA 证书包；仍会启用 TLS 验证

演示模式需显式启用，且优先于远程配置：

TESTLINK_DEMO_MODE=true TESTLINK_WRITE_ENABLED=true node dist/cli.js

开发

npm ci
npm run check
npm test
npm run eval
npm run build
npm audit --omit=dev --audit-level=high
npm pack --dry-run

离线工具选择评估会检查常见用户意图是否能分别选择搜索、验证、预览和 apply 工具。该评估结果确定性，不会向外部模型发送数据。

Docker

镜像以非 root 用户身份运行，并使用 Node 24.19.0。构建但不推送：

docker buildx build --platform linux/amd64,linux/arm64 --tag testlink-mcp:local --output type=oci,dest=testlink-mcp.oci.tar .

批准并发布后使用的镜像名称：ghcr.io/eason0in/testlink-mcp:1.0.8。

发布政策

版本 1.0.8 已准备好发布，但发布仍需显式执行。受保护的发布工作流要求使用签名版本标签，重新运行完整的测试／评估／审计／SBOM／打包检查，通过来源证明发布 npm，发布带有 SBOM 和来源证明的多架构 GHCR 镜像，创建 GitHub Release，最后发布经过验证的 MCP Registry 条目。

单独的受保护实时冒烟测试工作流会通过只读调用，使用真实的 TestLink 1.9.20 实例验证已安装的软件包。其 URL 和开发者密钥必须存储为环境机密，且绝不会写入日志。

软件包清单和 server.json 使用相同的 MCP 名称 io.github.Eason0in/testlink-mcp。无需发布即可运行注册表验证：

mcp-publisher validate server.json

npm、MCP Registry、Glama 和 MCP.so 的账户端设置及提交数据记录在市场提交清单中。

公共参考资料

• TestLink 1.9.20 源代码和发布分支
• Model Context Protocol TypeScript SDK
• 官方 MCP Registry 发布者命令

许可证

MIT