使用说明（Markdown 格式）

项目简介

这是一个基于 MCP（Model Context Protocol）的服务端实现，旨在让 AI 助手（如 Claude、Cursor、Windsurf 等）通过标准化接口访问 TestRail 的资源、执行工具和模板。
服务器负责接收 MCP 客户端发送的请求，调用 TestRail 的 API，并将结果以 JSON-RPC 风格的响应返回给客户端。

主要功能点

资源管理能力：暴露 TestRail 数据（如项目、分区、模板、字段等）作为可访问的资源，以支持 LLM 的上下文生成和任务编排。
工具注册与执行：实现多组工具（get_projects、get_case、get_cases、create_case、update_case、add_run、get_statuses、get_templates、get_sections、get_tests、add_results、add_attachment_to_run 等），LLM 客户端可以通过统一接口调用这些工具并获取结果。
数据清洗与兼容：对返回的数据进行清洗与结构化（使用 sanitize、映射自定义字段、字段校验等）。
传输协议与会话：通过 StdioServerTransport 提供 STDIO 传输，便于在 CLI/桌面场景中与 LLM 客户端交互，遵循 MCP 的会话与能力声明模型。
安全与错误处理：在工具执行阶段对错误进行封装与返回，确保客户端能得到明确的响应与错误信息。

安装步骤

先准备环境：Node.js 18 及以上、npm。
克隆仓库并安装依赖：在项目根目录执行 npm install。
构建与运行：执行 npm run build（如仓库提供）后，直接运行 server（含 shebang 的入口文件 index.ts 已实现 CLI 启动）即可启动 MCP 服务器。

服务器配置（供 MCP 客户端使用的配置信息，示例为 JSON 格式，包含 server name、command、args 等）

服务器名称：TestRail MCP Server
启动命令及参数示例（与客户端配置的结构一致，实际运行时请替换为你自己的 TestRail 实例信息）： { "mcpServers": { "testrail": { "command": "npx", "args": ["-y", "@uarlouski/testrail-mcp-server@latest"], "env": { "TESTRAIL_INSTANCE_URL": "https://your-instance.testrail.io", "TESTRAIL_USERNAME": "[email protected]", "TESTRAIL_API_KEY": "your-api-key" } } } } 说明：
server name 对应仓库中 MCP 服务器的名称（TestRail MCP Server）。
command 与 args 指明如何启动 MCP 服务器（本实现使用 npx 调起服务器包的最新版本）。
env 部分为连接 TestRail 所需的认证信息，请替换为真实的实例、账户和 API key。
MCP 客户端无需关心服务器实现细节，只需要按照上述结构配置即可建立连接。

基本使用方法

启动后，MCP 客户端通过 MCP 标准的 JSON-RPC 请求与服务器交互，查询资源、执行工具、获取模板等。
常见操作包括：
- 查询可用项目、分组、模板等资源
- 调用工具执行 TestRail 相关操作（如创建测试用例、更新用例、添加测试结果等）
- 获取并应用字段模板与自定义字段映射以生成结构化输出
客户端在接收到响应后，需对返回的 JSON 进行解析与后续处理。服务器会对输出进行空值清理，避免将无用字段带入后续流程。

使用时注意事项

MCP 客户端需要具备与服务器对接的能力（command、args、环境变量配置），本仓库提供的示例配置适用于主流 MCP 客户端（Claude、Cursor、Windsurf 等）。
服务器端的错误会以结构化的文本返回给客户端，便于调试和错误排查。
如需扩展工具集，只需要在服务器端 RegisterTools 的流程中添加新的工具定义即可，客户端将能通过相同的接口访问。

关键词 TestRail, AI 助手, 流程自动化, 测试管理, 云端协作

分类ID 6

TestRail MCP Server