AI导哈

TestRail MCP服务器

一个基于Spring Boot的MCP服务器，使AI助手能够与TestRail交互，提供可搜索的TestRail操作工具集，同时确保本地机器上的凭证安全。

  • by maheshyaddanapudi
  • Java
  • 本地部署
  • 更新于
在 GitHub 查看 maheshyaddanapudi/testrail-mcp-server

使用说明

TestRail MCP服务器

Spring Boot MCP（模型上下文协议）服务器，使Cursor等AI助手能够与TestRail交互。该服务器采用Java 17和Spring AI构建，为TestRail操作提供了一个强大的、可搜索的工具集，同时确保您的凭据在本地计算机上的安全。

目录

文档

有关综合Mermaid图的详细文档，请参阅 docs/ 文件夹：

文档 描述
建筑 具有类图、组件图和数据流的详细架构
工具参考 所有101个内部工具的完整参考，包括参数和示例
安全 安全架构、威胁模型和凭证管理
集成指南 一步一步Cursor IDE集成和故障排除

特性

  • 101测试轨道工具：全面覆盖TestRail API操作，可通过4工具网关访问。
  • 双重发现路径：通过自然语言搜索查找工具(search_tools)或者浏览结构化目录(get_categories, get_tools_by_category).
  • 可搜索工具：强大 search_tools 该方法允许LLM使用自然语言为作业找到合适的工具。
  • 设计安全：API凭据永远不会离开本地计算机。
  • 权限控制：游标在执行每个工具之前要求确认。
  • 丰富的工具元数据：所有内部工具都附有详细的描述、类别、关键字和示例，以便更好地理解LLM。
  • 90%测试覆盖率：具有JaCoCo强制执行功能的全面测试套件。

建筑

高级体系结构

flowchart TB
    subgraph IDE["Cursor IDE"]
        UP[User Prompt]
        LLM[Claude LLM]
        UP --> LLM
    end

    subgraph MCP["MCP Server - Local Machine"]
        direction TB
        STDIO[STDIO Transport]
        McpExposed[4-Tool Gateway]
        Lucene[LuceneToolIndexService]
        Registry[InternalToolRegistry]

        subgraph Tools["Internal Tools (101)"]
            CT[Cases Tools]
            PT[Projects Tools]
            RT[Runs Tools]
            RST[Results Tools]
            ST[Sections Tools]
        end

        TC[TestRail API Client]

        STDIO --> McpExposed
        McpExposed --> Lucene
        McpExposed --> Registry
        Registry --> Tools
        Tools --> TC
    end

    subgraph Config["Local Configuration"]
        ENV[Environment Variables]
        CREDS["TESTRAIL_URL<br/>TESTRAIL_USERNAME<br/>TESTRAIL_API_KEY"]
        ENV --> CREDS
    end

    subgraph TR["TestRail Instance"]
        API[TestRail API v2]
    end

    LLM <-->|MCP Protocol| STDIO
    TC <-->|HTTPS + Basic Auth| API
    CREDS -.->|Loaded at startup| TC

    style CREDS fill:#ff6b6b,color:#fff
    style LLM fill:#a29bfe,color:#fff
    style API fill:#74b9ff,color:#fff

组件架构

flowchart LR
    subgraph SpringBoot["Spring Boot Application"]
        direction TB

        subgraph Config["Configuration Layer"]
            TP[TestrailProperties]
            TCC[TestrailClientConfig]
            MCC[McpToolConfig]
        end

        subgraph Client["API Client Layer"]
            TAC[TestrailApiClient]
            WC[WebClient]
        end

        subgraph RegistryLayer["Tool Registry & Search"]
            Registry[InternalToolRegistry]
            Lucene[LuceneToolIndexService]
        end

        subgraph McpLayer["MCP Gateway"]
            McpExposed[4-Tool Gateway]
        end

        subgraph ToolsLayer["Internal Tools Layer (101)"]
            direction LR
            CT[CasesTools]
            PT[ProjectsTools]
            RT[RunsTools]
            RST[ResultsTools]
            ST[SectionsTools]
        end

        Config --> Client
        RegistryLayer --> ToolsLayer
        McpLayer --> RegistryLayer
        ToolsLayer --> Client
    end

    ENV[Environment] --> Config
    TAC --> API[TestRail API]
    McpLayer <--> Cursor[Cursor IDE]

安全

您的TestRail证书 永远不要离开你的本地机器 并且是 从未被送往法学硕士该架构旨在仅向LLM公开一个4工具网关，确保101个内部工具实现和您的凭据安全。

先决条件

  • Java 17 或更高
  • Gradle 8.x （或使用附带的包装）
  • TestRail实例 启用API访问
  • TestRail API密钥
  • 光标IDE 支持MCP

安装

  1. 克隆仓库

    git clone https://github.com/yourusername/testrail-mcp-server.git
cd testrail-mcp-server

  2. 构建项目

    ./gradlew build

配置

在运行服务器之前设置以下环境变量：

export TESTRAIL_URL="https://yourcompany.testrail.io"
export TESTRAIL_USERNAME="your.email@company.com"
export TESTRAIL_API_KEY="your-api-key-here"

光标集成

创建或编辑 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "testrail": {
      "command": "java",
      "args": [
        "-jar",
        "/absolute/path/to/testrail-mcp-server.jar"
      ],
      "env": {
        "TESTRAIL_URL": "https://yourcompany.testrail.io",
        "TESTRAIL_USERNAME": "your.email@company.com",
        "TESTRAIL_API_KEY": "your-api-key"
      }
    }
  }
}

4-Tool网关

此服务器向LLM公开了一个4工具网关，为101个内部工具提供了两条发现路径：

  • 搜索路径
    • search_tools(query: string)：模糊搜索所有101个内部工具，并返回匹配的排名列表。
  • 浏览路径
    • get_categories()：返回所有19个工具类别的列表（例如。， test-cases, projects).
    • get_tools_by_category(category: string)：返回特定类别中的所有工具。
  • 执行
    • execute_tool(toolName: string, parameters: map)：按名称执行特定的内部工具。

示例用例

基于搜索的发现

用户： “在‘移动应用程序’项目的‘用户身份验证’套件中查找所有测试用例。”

  1. LLM电话 search_tools("find test cases in suite")
  2. 服务器返回 get_cases 作为首选结果，带有参数 projectId, suiteId等等。
  3. LLM电话 execute_tool("get_project_by_name", {name: "Mobile App"}) 获取项目ID。
  4. LLM电话 execute_tool("get_suite_by_name", {projectId: 1, name: "User Authentication"}) 获取套房ID。
  5. LLM电话 execute_tool("get_cases", {projectId: 1, suiteId: 5}) 获取测试用例。

基于浏览的发现

用户： “我需要管理试运行。我该怎么办？”

  1. LLM电话 get_categories() 看看有什么可用的。
  2. 服务器返回一个类别列表，包括 test-runs.
  3. LLM电话 get_tools_by_category("test-runs") 查看该类别中的工具。
  4. 服务器返回 get_run, get_runs, add_run, update_run, close_run, delete_run.
  5. LLM电话 execute_tool("get_runs", {projectId: 1}) 获取项目的所有测试运行。

发展

该系统的核心是 @InternalTool 注释，用于装饰所有101个内部TestRail工具方法。这 InternalToolRegistry 在启动时扫描这些注释以构建运行时注册表。这 LuceneToolIndexService 然后对该注册表进行索引，以便进行快速的语义搜索。

测试

运行带有覆盖率验证的完整测试套件：

./gradlew clean build

相关 MCP