ReportPortal MCP Server

ReportPortal MCP Server

文档说明： 本 README 反映当前开发分支。如需查看最新的可用工具与功能列表，请参阅 main 分支的 README。

什么是 ReportPortal MCP Server？

ReportPortal MCP Server 是 ReportPortal 实例与 AI 聊天助手（如 Claude Desktop、GitHub Copilot、Cursor）之间的桥梁。简单来说，它让你可以用自然语言询问测试运行相关的问题，并直接从 ReportPortal 获得答案。它遵循官方 MCP 指南。

从 2.x 版本开始，该服务还集成了 ReportPortal 测试用例管理系统（TMS）——测试用例、文件夹、里程碑和测试计划——因此你可以通过同一个聊天界面浏览和管理测试设计数据。

例如，无需登录 ReportPortal UI，你可以直接问 AI 助手"最近一次运行中有哪些测试失败？"或"列出最近的 5 次测试运行"，它就会为你从 ReportPortal 获取这些信息。
借助 TMS 支持，你还可以问"列出 Smoke 文件夹中的测试用例"或"为当前冲刺里程碑创建测试计划"之类的问题。这让 QA 测试人员和管理者可以轻松使用自然语言管理测试用例、查询测试结果和测试资产，从而加快规划、分析和报告的速度。

为什么使用它？

• 快速获取测试洞察：无需编写代码或浏览 UI，即可即时获取测试运行摘要、失败数量或错误详情。
• 在聊天中使用 TMS：无需离开 AI 助手，即可在 ReportPortal TMS 中浏览、创建和更新测试用例、文件夹、里程碑和测试计划。
• 基于聊天的查询：使用你喜欢的 AI 助手（Claude、Cursor 等）与 ReportPortal 数据对话。就像在聊天窗口中拥有一个智能的测试报告助手。
• 集成灵活：可与任何兼容 MCP 的 AI 工具配合使用。你只需将工具指向此服务，它就能在后台运行 ReportPortal 查询。
• 无需自定义脚本：常见查询（列出运行、获取失败、分析、TMS 查找）已内置为简单的"命令"，可通过聊天调用。

前提条件

在设置 MCP 服务之前，你需要从 ReportPortal 实例获取以下信息：

ReportPortal 主机 URL（RP_HOST）

你的 ReportPortal 实例 URL：

• 示例：https://reportportal.example.com
• 本地环境：http://localhost:8080

项目 Key（RP_PROJECT）— 可选

此值是可选的。设置后，它将定义所有请求使用的默认项目 key。仅当上下文中没有可用项目时（即 stdio 模式下的 RP_PROJECT 环境变量，或 HTTP 模式下的 X-Project HTTP 请求头），才会将 projectKey 工具参数作为回退使用。

项目 key 是 ReportPortal 实例内的唯一项目标识符，请勿将项目显示名称用作项目 key。可在 ReportPortal 的常规设置页面找到它：

https://your-rp-instance.com/ui/#organizations/{your-organization}/projects/{your_project}/settings/general

API Token（RP_API_TOKEN）

你可以从 ReportPortal 个人资料中获取 API token，或生成一个新的。 安全提示： 切勿将 token 提交到版本控制系统或公开分享。

服务器模式（MCP_MODE）

MCP_MODE 是一个系统环境变量，用于控制 MCP 服务的传输模式：

值	描述
stdio	（默认） 标准输入/输出 – 用于本地 AI 工具集成（Claude Desktop、Cursor、VS Code Copilot 等）
http	HTTP/SSE 流式传输 – 暴露一个 HTTP 端点，供远程或多客户端访问

仅当你想以 HTTP 模式运行服务时，才需要此变量。对于本地 AI 工具集成，使用默认的 stdio 模式，无需额外配置。

重要： http 模式适用于服务部署。MCP 服务必须先以 MCP_MODE=http 部署并运行，任何 AI 工具才能远程连接到它。部署说明请参阅面向开发者部分。

安装

连接到 ReportPortal MCP 服务有两种方式：

1. 本地 - 通过 Docker（推荐）或使用预构建二进制文件。
2. 连接到远程 MCP 服务（当服务已部署时）

这些方法均适用于任何大模型提供商。

本地安装

以下配置使用默认的 stdio 模式（MCP_MODE=stdio），这是所有本地 AI 工具集成的正确选择。若要以 HTTP 模式运行服务，请在 env 块中添加 MCP_MODE=http（详情请参阅面向开发者部分）。

通过 Docker（推荐）

MCP 服务可在 ReportPortal 官方 DockerHub 上获取。

配置：

{
  "reportportal": {
    "command": "docker",
    "args": [
      "run",
      "-i",
      "--rm",
      "-e",
      "RP_API_TOKEN",
      "-e",
      "RP_HOST",
      "-e",
      "RP_PROJECT",
      "reportportal/mcp-server"
    ],
    "env": {
      "RP_API_TOKEN": "your-api-token",
      "RP_HOST": "https://your-reportportal-instance.com",
      "RP_PROJECT": "YourProjectKeyFromReportPortal"
    }
  }
}

使用预构建二进制文件

各操作系统的预构建二进制文件可从 GitHub 上的官方发行版下载。

配置：

{
  "reportportal": {
    "command": "/path/to/reportportal-mcp-server-binary",
    "args": ["stdio"],
    "env": {
      "RP_API_TOKEN": "your-api-token",
      "RP_HOST": "https://your-reportportal-instance.com",
      "RP_PROJECT": "YourProjectKeyFromReportPortal"
    }
  }
}

连接到远程 MCP 服务

如果 ReportPortal MCP 服务已经部署并可通过 HTTP 访问，你无需在本地运行它即可远程连接。当服务集中托管或位于共享环境中时，这非常有用。

注意： 远程服务必须以 HTTP 模式（系统环境变量 MCP_MODE=http）部署并运行，任何 AI 工具才能连接到它。部署和配置详情请参阅面向开发者部分。

远程服务配置：

{
  "reportportal": {
    "url": "http://your-mcp-server-host:port/mcp",
    "headers": {
      "Authorization": "Bearer ${RP_API_TOKEN}",
      "X-Project": "YourProjectKeyFromReportPortal"
    }
  }
}

配置参数：

• url：远程 MCP 服务的 HTTP 端点 URL（使用 /mcp 或 /api/mcp）
• headers.Authorization：用于身份验证的 Bearer token（必需）
• headers.X-Project：ReportPortal 项目键 — 唯一的项目标识符，而非显示名称（可选）

AI 工具设置

选择你喜欢的 AI 工具进行连接。

Cursor（AI 代码编辑器）

只需点击

或按照以下步骤操作：

1. 在 Cursor 中，转到 Settings，然后 Tools & MCP，点击 Add Custom MCP。
2. 这将打开 mcp.json 文件，你需要在其中添加一个新的 MCP 服务条目，用于运行 ReportPortal MCP 服务：

对于本地安装（Docker 或二进制文件）：

从安装部分选择你偏好的配置，并将其粘贴到 reportportal 块内。

{
  "mcpServers": {
    "reportportal": {
      // paste your chosen configuration here
    }
  }
}

对于远程服务：

注意： 远程服务必须在连接前以 HTTP 模式部署并运行。

{
  "mcpServers": {
    "reportportal": {
      "url": "http://your-mcp-server-host:port/mcp/",
      "headers": {
        "Authorization": "Bearer ${RP_API_TOKEN}",
        "X-Project": "YourProjectKeyFromReportPortal"
      }
    }
  }
}

文档：Cursor MCP。

GitHub Copilot（在 VS Code 和 JetBrains IDE 中）

VS Code

1. 安装/更新 GitHub Copilot 插件。
2. 按下 Ctrl+P，在搜索栏中输入 >mcp，然后选择 MCP: Open User Configuration。
3. 这会打开文件 mcp.json，你需要在其中添加一个新的 MCP 服务条目，用于运行 ReportPortal MCP 服务：

对于本地安装（Docker 或二进制文件）：

从安装部分中选择你偏好的配置，并将其粘贴到 reportportal 块内。

{
  "servers": {
    "reportportal": {
      // paste your chosen configuration here
    }
  }
}

对于远程服务：

注意： 远程服务在连接前必须已以 HTTP 模式部署并运行。

{
  "servers": {
    "reportportal": {
      "url": "http://your-mcp-server-host:port/mcp/",
      "requestInit": {
        "headers": {
          "Authorization": "Bearer ${RP_API_TOKEN}",
          "X-Project": "YourProjectKeyFromReportPortal"
        }
      }
    }
  }
}

文档：VS Code Copilot 指南。

JetBrains IDE

1. 安装/更新 GitHub Copilot 插件。
2. 点击 状态栏中的 GitHub Copilot 图标 → Edit Settings → Model Context Protocol → Configure。
3. 添加配置：

对于本地安装（Docker 或二进制文件）：

从安装部分中选择你偏好的配置，并将其粘贴到 reportportal 块内。

{
  "servers": {
    "reportportal": {
      // paste your chosen configuration here
    }
  }
}

对于远程服务：

注意： 远程服务在连接前必须已以 HTTP 模式部署并运行。

{
  "servers": {
    "reportportal": {
      "url": "http://your-mcp-server-host:port/mcp/",
      "requestInit": {
        "headers": {
          "Authorization": "Bearer ${RP_API_TOKEN}",
          "X-Project": "YourProjectKeyFromReportPortal"
        }
      }
    }
  }
}

4. 按下 Ctrl + S 或 Command + S 保存，或关闭 mcp.json 文件。配置应立即生效，并重启所有已定义的 MCP 服务。如有需要，你可以重启 IDE。

文档：JetBrains Copilot 指南。

Claude Desktop

1. 打开 Claude Desktop，前往 Settings → Developer → Edit Config。
2. 添加一个新的 MCP 服务条目，用于运行 ReportPortal MCP 服务。

对于本地安装（Docker 或二进制文件）：

从安装部分中选择你偏好的配置，并将其粘贴到 reportportal 块内。

{
  "mcpServers": {
    "reportportal": {
      // paste your chosen configuration here
    }
  }
}

3. 保存并重启 Claude Desktop。

对于远程服务：

Claude Desktop 原生不支持为远程 Model Context Protocol (MCP) 服务直接使用 Server-Sent Events (SSE) 传输，因为它主要设计为通过本地标准 I/O (stdio) 进行通信。若要连接到远程 SSE 服务，你必须在 claude_desktop_config.json 中使用本地包装脚本或桥接工具（例如 mcp-remote、npx）来将 stdio 桥接到 SSE。

Claude Code CLI

1. 打开你的终端。
2. 运行以下命令之一。

对于本地安装（Docker）：

claude mcp add-json reportportal '{"command": "docker", "args": ["run", "-i", "--rm", "-e", "RP_API_TOKEN", "-e", "RP_HOST", "-e", "RP_PROJECT", "reportportal/mcp-server"], "env": {"RP_API_TOKEN": "${RP_API_TOKEN}", "RP_HOST": "https://your-reportportal-instance.com", "RP_PROJECT": "YourProjectKeyFromReportPortal"}}'

对于远程服务：

注意： 远程服务在连接前必须已以 HTTP 模式部署并运行。

claude mcp add-json reportportal '{"url": "http://your-mcp-server-host:port/mcp/", "headers": {"Authorization": "Bearer ${RP_API_TOKEN}", "X-Project": "YourProjectKeyFromReportPortal"}}'

配置选项：

• 使用 -s user 将服务添加到你的用户配置中（在所有项目中可用）。
• 使用 -s project 将服务添加到项目特定配置中（通过 .mcp.json 共享）。
• 默认作用域为 local（仅你在当前项目中可用）。

文档：Claude Code 指南。

其他编码 Agent

ReportPortal MCP 服务与任何兼容 MCP 的编码 Agent 兼容。虽然确切的配置格式可能有所不同，但大多数 Agent 支持以下任一方式：

本地安装（stdio 模式）：

{
  "reportportal": {
    "command": "docker",
    "args": ["run", "-i", "--rm", "-e", "RP_API_TOKEN", "-e", "RP_HOST", "-e", "RP_PROJECT", "reportportal/mcp-server"],
    "env": {
      "RP_API_TOKEN": "your-api-token",
      "RP_HOST": "https://your-reportportal-instance.com",
      "RP_PROJECT": "YourProjectKeyFromReportPortal"
    }
  }
}

远程服务（HTTP 模式）：

注意： 远程服务在连接前必须已以 HTTP 模式部署并运行。

{
  "reportportal": {
    "url": "http://your-mcp-server-host:port/mcp/",
    "headers": {
      "Authorization": "Bearer your-api-token",
      "X-Project": "YourProjectKeyFromReportPortal"
    }
  }
}

请参阅你的编码 Agent 的文档，了解确切的配置格式以及配置文件的放置位置。

连接后，你的 AI 助手将列出它可以调用的 ReportPortal 相关“工具”。然后你可以在聊天中提问，助手将代表你调用这些工具。

注意： 完成设置后，请参阅验证你的设置部分，了解如何测试你的配置。

ReportPortal 兼容性

强烈建议使用 ReportPortal 的最新版本。

本 MCP 服务的 1.x 版本支持 25.1 及以上的 ReportPortal 产品版本（其中 API 服务版本不低于 5.14.0）。
与旧版本的兼容性未经测试，可能导致 MCP 服务工作异常。

2.x 版本（目前正在开发中）新增了 ReportPortal TMS 工具，并要求 ReportPortal 产品版本为 26.1+，该版本中提供了测试用例管理 API。

功能

ReportPortal MCP 服务提供了一整套与 ReportPortal 交互的功能：

启动管理

• 获取并筛选启动（测试运行），支持分页
• 按名称或 ID 获取启动详情
• 强制结束正在运行的启动
• 删除启动
• 对启动运行自动化分析（自动分析、唯一错误分析、质量门禁）
• 使用 ReportPortal 导入插件从文件导入启动（支持的格式取决于你的 ReportPortal 实例上安装的插件——通常为 XML 报告和 ZIP 归档，例如 JUnit XML、Allure ZIP）

测试项分析

• 按启动或已保存的筛选器获取测试项，支持可选筛选条件（包括缺陷/问题类型）
• 获取每个测试项的详细信息
• 查看测试执行统计和失败情况
• 获取测试日志和附件
• 通过更新测试项的缺陷类型对测试结果作出判定
• 获取测试项跨多次启动的历史执行数据

报告生成

• 分析启动以获取详细的测试执行洞察
• 生成包含统计信息和失败分析的结构化报告

测试用例管理 (TMS)

从 MCP 服务 2.x 版本起可用（需要 ReportPortal 26.1+）。

• 浏览里程碑、测试文件夹和测试用例，支持可选筛选条件和 limit/offset 分页
• 按 ID 获取特定测试计划
• 创建和组织测试文件夹（包括嵌套子文件夹）
• 以任一支持的格式创建、更新和删除手动测试用例：text 场景（说明和预期结果）或 steps 场景（有序步骤列表）
• 创建里程碑和测试计划，然后在计划中添加或移除测试用例
• 获取与特定测试计划关联的测试用例，支持可选 limit/offset 分页
• 一步创建包含测试计划测试用例的手动启动
• 按筛选条件（名称、项状态、完成状态、时间范围、测试计划、属性）列出手动启动，支持分页
• 按筛选条件（名称、优先级、标签）列出手动启动的测试用例执行，支持分页
• 批量将测试用例添加到现有的手动启动
• 更新手动启动中测试用例执行的状态和评论

Note: TMS 写入工具（create_*、update_*、delete_*、add_test_cases_to_test_plan、delete_test_cases_from_test_plan、add_test_cases_to_manual_launch、update_manual_launch_execution）会修改 ReportPortal 中的数据。在生产项目中请谨慎使用。

可用工具（命令）

Tools. Test results

工具名称	描述	参数
Get Launches by filter	按过滤器分页列出 ReportPortal 启动项	name、description、owner、number、start_time、end_time、attributes、sort、page、page-size（均为可选）
Get Last Launch by Name	按名称检索最近的启动项	launch（必填）
Get Launch by ID	直接按其 ID 检索特定启动项	project（可选，字符串）、launch_id（必填，字符串）
Run Quality Gate	对启动项运行质量门禁分析	launch_id（必填）、project（可选）
Run Auto Analysis	对启动项运行自动分析	launch_id（必填）、analyzer_mode（可选）、analyzer_type（可选）、analyzer_item_modes（可选）
Run Unique Error Analysis	对启动项运行唯一错误分析	launch_id（必填）、remove_numbers（可选）
Update Launch	更新启动项的描述和/或属性	launch_id（必填）、description（可选，替换现有值）、attributes（可选，由 {key, value} 对象组成的数组——替换所有现有属性）
Force Finish Launch	强制启动项结束	launch_id（必填）
Delete Launch	删除特定启动项	launch_id（必填）
Import Launch from File	使用 ReportPortal 导入插件从文件导入启动项。支持的文件格式取决于服务器上安装的插件（例如 JUnit XML、Allure ZIP）。可通过 GET /api/v1/plugin 发现可用插件及其接受的 MIME 类型（按 groupType: "IMPORT" 过滤）。该处理程序默认对解码后的上传内容强制实施最高 50 MiB 的限制，当所选插件声明的 details.maxFileSize 更小时，可能会应用更低的上限；base64 编码的上传内容在解码后进行计量。超过有效限制的导入将被拒绝——请在导入前拆分文件或预先压缩。	plugin_name（必填）、file_name（必填，例如 results.xml）、file_content（必填，文本格式使用原始文本，二进制格式使用 base64）、content_encoding（可选，"none"（默认）或 "base64"）、project（可选）
Get Suites by filter	列出特定启动项的测试套件	launch-id（必填）、name、description、start_time_from、start_time_to、attributes、parent_id、sort、page、page-size（均为可选）
Get Test Items by filter	列出特定启动项或已保存过滤器的测试项	launch-id 或 filter-name（必须提供一个）、include-before-after-hooks、name、description、status、has_retries、start_time_from、start_time_to、attributes、parent_id、defect_comment、auto_analyzed、ignored_in_aa、pattern_name、ticket_id、filter-eq-defect-type（可选，来自 get_project_defect_types 的缺陷/问题类型定位符）、sort、page、page-size（均为可选）
Get Logs by filter	列出特定测试项或嵌套步骤的日志	parent-item-id（必填）、log_level、log_content、logs_with_attachments、status、sort、page、page-size（均为可选）
Get Attachment by ID	按 id 检索附件二进制内容	attachment-content-id（必填）
Get Test Item by ID	检索特定测试项的详细信息	test_item_id（必填）
Get Project Defect Types	检索特定项目的可用缺陷类型	无
Update defect types by item ids	为多个测试项更新缺陷类型	test_items_ids（必填）、defect_type_id（必填）、defect_type_comment（可选）
Get Test Items History	检索特定启动项或父套件的测试项执行历史	filter-eq-launchId 或 filter-eq-parentId（必须提供一个）、historyDepth、type、name、description、status、start_time_from、start_time_to、attributes、has_retries、defect_comment、auto_analyzed、ignored_in_aa、ticket_id、pattern_name、page、page-size、page-sort（均为可选）

工具。测试用例管理

自 MCP 服务 2.x 版本起可用。需要启用 TMS 的 ReportPortal 26.1+。

工具名称	描述	参数
按筛选条件获取里程碑	列出项目的 TMS 里程碑，可选按名称或 ID 筛选。支持 limit/offset 分页。	filter-cnt-name（可选）、filter-id（可选）、limit（可选，整数 ≥ 1，默认 50）、offset（可选，整数 ≥ 0，默认 0）
按 ID 获取测试计划	按 ID 获取 TMS 测试计划	id（必填）
获取测试计划的测试用例	列出分配给某个 TMS 测试计划的测试用例。支持 limit/offset 分页。	test-plan-id（必填）、limit（可选，整数 ≥ 1，默认 50）、offset（可选，整数 ≥ 0，默认 0）
按筛选条件获取测试文件夹	列出项目的 TMS 测试文件夹。所有筛选和分页参数均为可选。	filter-eq-id（可选，整数 ≥ 1）、filter-eq-parentId（可选，整数 ≥ 1）、filter-cnt-name（可选）、limit（可选，整数 ≥ 1，默认 50）、offset（可选，整数 ≥ 0，默认 0）
按筛选条件获取测试用例	列出项目的 TMS 测试用例。所有筛选和分页参数均为可选。	filter-eq-id（可选，整数 ≥ 1）、filter-eq-testFolderId（可选，整数 ≥ 1）、filter-cnt-name（可选）、filter-has-attributeKey（可选，用于筛选的标签键列表，以逗号分隔，例如 smoke,regression,login）、filter-in-priority（可选，枚举数组：BLOCKER | CRITICAL | HIGH | LOW | MEDIUM | UNSPECIFIED）、limit（可选，整数 ≥ 1，默认 50）、offset（可选，整数 ≥ 0，默认 0）
创建文件夹	在 TMS 中创建新的测试文件夹（或子文件夹）。会修改 TMS 数据。	name（必填）、description（可选）、parent-test-folder-id（可选，整数 ≥ 1）
删除文件夹	按 ID 从 TMS 中删除测试文件夹。会修改 TMS 数据。不可逆。	folderId（必填，整数 ≥ 1）
创建测试用例	创建新的测试用例。使用 test-case-type 选择手动场景。附件（{ id, fileName, fileType, fileSize, content }，与更新手动启动执行的附件结构相同——提供预上传的 id 或内联 base64 content 以自动上传）可在 text 类型的整个场景级别关联，也可为 steps 类型按步骤及前置条件关联。会修改 TMS 数据。	name（必填）、test-folder-id（必填，整数 ≥ 1——放置测试用例的文件夹 ID）、description（可选）、priority（可选，枚举：LOW | MEDIUM | HIGH | CRITICAL | BLOCKER | UNSPECIFIED）、test-case-type（可选，枚举：text（默认）| steps）、instructions（可选，用于 text 类型）、expected-result（可选，用于 text 类型）、steps（可选，{ instructions, expected-result, attachments } 数组，用于 steps 类型——每个步骤的 attachments 仅关联到该步骤）、preconditions（可选）、preconditions-attachments（可选，前置条件的附件数组；仅当 test-case-type 为 steps 且提供了 preconditions 时有效）、requirements（可选，值字符串数组；每条自动生成唯一 ID）、attachments（可选，整个场景的附件数组；仅当 test-case-type 为 text 时有效）、attributes（可选，{ key } 对象数组——要附加的标签；匹配键的现有项目属性将被复用，缺少的会自动创建）
更新测试用例	更新现有测试用例；仅更改提供的字段。会修改 TMS 数据。	testCaseId（必填，整数 ≥ 1）、name（可选）、description（可选）、priority（可选，枚举：LOW | MEDIUM | HIGH | CRITICAL | BLOCKER | UNSPECIFIED）、test-folder-id（可选，整数 ≥ 1）、test-case-type（可选，枚举：text | steps；如果提供了 instructions、expected-result、preconditions、requirements、steps、attachments 或 preconditions-attachments 中的任意一项，则为必填）、instructions（可选，用于 text 类型）、expected-result（可选，用于 text 类型）、steps（可选，{ instructions, expected-result, attachments } 数组，用于 steps 类型）、preconditions（可选）、preconditions-attachments（可选，前置条件的附件数组；仅当 test-case-type 为 steps 且提供了 preconditions 时有效）、requirements（可选，值字符串数组；每条自动生成唯一 ID）、attachments（可选，整个场景的附件数组；仅当 test-case-type 为 text 时有效）、attributes（可选，{ key } 对象数组——要附加的标签；传入 [] 可清除所有现有标签；省略则保持不变）
删除测试用例	按 ID 从 TMS 中删除测试用例。会修改 TMS 数据。不可逆。	testCaseId（必填，整数 ≥ 1）
创建里程碑	在 TMS 中创建新的里程碑。会修改 TMS 数据。 日期必须为 RFC3339 格式（例如 2026-01-01T00:00:00Z）；end-date 不得早于 start-date。	name（必填）、type（必填，枚举：RELEASE | SPRINT | PLAN | FEATURE | OTHER）、start-date（必填，RFC3339）、end-date（必填，RFC3339）、status（可选，枚举：SCHEDULED | TESTING | COMPLETED）
创建测试计划	创建链接到现有里程碑的新测试计划。会修改 TMS 数据。	name（必填）、milestone-id（必填，整数 ≥ 1）、description（可选）
向测试计划添加测试用例	向现有 TMS 测试计划添加一个或多个测试用例。会修改 TMS 数据。	test-plan-id（必填，整数 ≥ 1）、test-case-ids（必填，非空的整数 ≥ 1 数组）
从测试计划删除测试用例	从现有 TMS 测试计划中移除一个或多个测试用例。会修改 TMS 数据。	test-plan-id（必填，整数 ≥ 1）、test-case-ids（必填，非空的整数 ≥ 1 数组）
创建手动启动	在 TMS 中创建新的手动启动，并使用测试计划中的测试用例填充。会修改 TMS 数据。	name（必填）、startTime（必填，ISO-8601，例如 2026-07-29T11:59:04.221Z）、test-plan-id（必填，整数 ≥ 1）、test-case-ids（必填，非空的整数 ≥ 1 数组）、description（可选）、attributes（可选，{ key, value } 对象数组——每个属性都必须提供 value）
获取手动启动	从 TMS 中列出项目的手动启动，可按名称、执行状态、完成状态、时间范围、测试计划或属性筛选。支持 limit/offset 分页。	filter-cnt-name（可选）、filter-in-itemStatus（可选，数组：PASSED | FAILED | SKIPPED | IN_PROGRESS）、filter-eq-completion（可选，枚举：has_not_executed | done；省略表示全部）、filter-gt-startTime（可选，RFC3339 或 Unix 时间戳）、filter-lt-endTime（可选，RFC3339 或 Unix 时间戳）、filter-eq-testPlanId（可选，整数 ≥ 1）、filter-has-compositeAttribute（可选，格式：key1:value1,key2:value2）、limit（可选，整数 ≥ 1）、offset（可选，整数 ≥ 0）
获取手动启动执行	从 TMS 中列出特定手动启动的测试用例执行。所有筛选和分页参数均为可选。	launchId（必填，整数 ≥ 1）、filter-cnt-name（可选）、filter-in-priority（可选，数组：BLOCKER | CRITICAL | HIGH | LOW | MEDIUM | UNSPECIFIED）、filter-in-attributeKey（可选，格式：tag1,tag2,tag3）、limit（可选，整数 ≥ 1）、offset（可选，整数 ≥ 0）
向手动启动添加测试用例	向现有 TMS 手动启动添加一个或多个测试用例。会修改 TMS 数据。	launchId（必填，整数 ≥ 1）、test-case-ids（必填，非空的整数 ≥ 1 数组）
更新手动启动执行	更新 TMS 手动启动中测试用例执行的状态（并可选添加带附件的评论）。每个附件要么引用已通过 POST /project/{projectKey}/tms/attachment/upload 上传的文件（通过 id/fileName/fileType/fileSize），要么以内联 base64 提供原始文件内容（fileName + content），此时工具会自动将其上传到该端点并将生成的附件关联到该执行。处理程序对每个内联附件强制实施 52,428,800 字节（50 MiB）的解码后上传限制；base64 编码内容按解码后测量。超出此限制的附件将被拒绝。会修改 TMS 数据。	launchId（必填，整数 ≥ 1）、testCaseExecutionId（必填，整数 ≥ 1）、status（必填，枚举：IN_PROGRESS | PASSED | FAILED | SKIPPED）、executionComment（可选，对象：comment（可选，字符串）、attachments（可选，{ id, fileName, fileType, fileSize, content } 数组——提供 id（预上传的附件；fileType/fileSize 必填）或 content（要自动上传的 base64 编码字节；fileType/fileSize 可选且会自动推断），另外 fileName 始终必填））

可用提示词

分析启动

分析 ReportPortal 启动，并提供测试结果、失败项和统计数据的详细信息。

参数：

• launch_id：要分析的启动 ID

编写自己的提示词时，可以参考提示词文本和结构。

示例查询（自然语言）

完成设置后，你可以向 AI 提出以下真实场景中的问题（助手的回复将基于 ReportPortal 数据）：

• “列出最近的 5 次测试启动。” – 返回最近测试运行的分页列表，包括名称和状态。
• “最近一次运行中哪些测试失败了？” – 显示最近一次启动中失败的测试项。
• “显示 ID 为 119000 的启动详情。” – 通过 ID 直接检索指定启动，不进行分页。
• “显示编号为 1234 的启动详情。” – 获取该指定启动的信息（ID、名称、描述、统计数据）。
• “对启动 12345 执行质量门禁检查。” – 执行质量门禁分析，验证该启动是否符合设定的质量标准。
• “分析启动 ABC。” – 触发 ReportPortal 的自动分析，总结启动“ABC”的结果和失败项。
• “结束 ID 为 4321 的运行中启动。” – 强制停止当前正在运行的测试启动。
• “显示过去一小时内排名前五的 500 级错误” - 列出最近测试结果中排名前 5 的此类错误。
• “使用 junit 插件将此 JUnit XML 报告导入项目‘my_project’。” – 将提供的报告文件上传到 ReportPortal，并据此创建新的启动。

以上每个查询都对应 MCP 服务提供的一个“工具”，你只需用自然语言表达即可。 AI 会在后台调用正确的命令。 这些功能让你可以通过简单的聊天交互，以多种方式查询和管理测试报告。

面向开发者

前提条件

• Go 1.24.4 或更高版本
• 一个 ReportPortal 实例

从源码构建

# Clone the repository
git clone https://github.com/reportportal/reportportal-mcp-server.git
cd reportportal-mcp-server

# Build the binary
go build -o reportportal-mcp-server ./cmd/reportportal-mcp-server

这将创建一个名为 reportportal-mcp-server 的可执行文件。

配置

服务需要知道 ReportPortal 的地址以及身份验证方式。在 shell 中设置以下环境变量：

stdio 模式（默认）：

变量	描述	必需
RP_HOST	ReportPortal 安装实例的 URL（例如 https://myreportportal.example.com）	是
RP_PROJECT	ReportPortal 中的默认项目密钥（ReportPortal 实例内唯一的项目标识符，例如 myorganization_myproject）	否
RP_API_TOKEN	ReportPortal API 令牌（用于访问）	是

HTTP 模式：

设置 MCP_MODE=http 并配置以下内容：

• RP_HOST：必需 - ReportPortal 的 URL
• RP_PROJECT：HTTP 模式下不使用此变量——即使已设置也会忽略。每次请求都应通过 X-Project 请求头传递。
• MCP_SERVER_PORT：可选 - HTTP 服务端口（默认值：8080）
• MCP_SERVER_HOST：可选 - HTTP 绑定主机（默认值：空）
• 身份验证令牌必须通过每次请求中的 Authorization: Bearer <token> 请求头传递
• HTTP 模式下不使用 RP_API_TOKEN 环境变量

stdio 模式示例：

export RP_HOST="https://your-reportportal-instance.com"
export RP_PROJECT="YourProjectKeyFromReportPortal"
export RP_API_TOKEN="your-api-token"
./reportportal-mcp-server

HTTP 模式示例：

export MCP_MODE=http
export RP_HOST="https://your-reportportal-instance.com"
export MCP_SERVER_PORT=8080
./reportportal-mcp-server
# Tokens and project key are passed per-request via HTTP headers:
#   Authorization: Bearer <token>
#   X-Project: <projectKey>

HTTP API 端点

在 HTTP 模式（MCP_MODE=http）下运行时，服务会公开以下端点：

MCP 端点（用于工具调用和 MCP 协议）

• POST /mcp - 用于 JSON-RPC 请求的主要 MCP 端点
• POST /api/mcp - 备用 MCP 端点（功能相同）
• GET /mcp - MCP 协议的 SSE（服务器发送事件）流端点
• GET /api/mcp - 备用 SSE 流端点

重要： POST 请求必须发送到 /mcp 或 /api/mcp，而不是根端点 /。

请求格式：

所有 MCP 请求都必须遵循 JSON-RPC 2.0 规范：

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 1,
  "params": {
    "name": "get_launches",
    "arguments": {
      "filter-cnt-name": "test",
      "page": 1,
      "page-size": 10
    }
  }
}

请求示例：

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-reportportal-token" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "id": 1,
    "params": {
      "name": "get_launches",
      "arguments": {
        "page": 1,
        "page-size": 10
      }
    }
  }'

信息端点（仅支持 GET）

• GET / - 根端点，返回服务信息和可用端点
• GET /health - 健康检查端点
• GET /info - 服务信息和配置
• GET /api/status - 服务状态（与 /info 相同）
• GET /metrics - 分析指标（如果已启用分析功能）

注意： 根端点 / 仅接受 GET 请求。向 / 发送 POST 请求会返回 404 错误。MCP 协议请求请使用 /mcp 或 /api/mcp。

启动服务

服务将以 MCP_MODE 环境变量指定的模式启动（默认：stdio）。

启动后，MCP 服务即可接受来自 AI 工具的查询。

开发

如需设置开发环境或参与贡献：

Task 工具

安装 Go Task v3：

go install github.com/go-task/task/v3/cmd/task@latest

依赖项

运行 task deps 以安装 Go 依赖项：

task deps

构建

task build

测试

task test

使用 Docker 构建

task docker:build

使用 MCP Inspector 调试

modelcontextprotocol/inspector 工具适用于在本地测试和调试 MCP 服务：

npx @modelcontextprotocol/inspector docker run -i --rm -e "RP_API_TOKEN=$RP_API_TOKEN" -e "RP_PROJECT=$RP_PROJECT" -e "RP_HOST=$RP_HOST" reportportal-mcp-server

或者，也可以使用 Task 命令：

# Run inspector against your local server
task inspector

代码质量

# Lint
task lint

# Format
task fmt

项目文档

如需深入了解本 README 之外的内容，请参阅 docs/ 中的文档：

• 架构与限制 — 进程布局、请求生命周期、软件包映射，以及已知的设计限制和注意事项。
• 开发与风格指南 — 环境设置、编码规范，以及配置、验证、分析和测试方面的既定方法。
• 发布工作流 — 分支模型、CI/CD 流水线，以及发布正式版本的步骤。

扩展服务

添加新工具

要添加新工具，请在相应的资源文件中创建新方法，并在 NewServer 函数中将其添加到服务：

// In your resource file (e.g., launches.go)
func (lr *LaunchResources) toolNewFeature() (tool mcp.Tool, handler server.ToolHandlerFunc) {
    // Implement your tool
}

// In server.go
func NewServer(...) *server.MCPServer {
    // ...
    s.AddTool(launches.toolNewFeature())
    // ...
}

添加新提示词

要添加新提示词，只需创建一个描述提示词的 YAML 文件，并将其放在项目根目录下的 prompts 文件夹中。服务启动时会自动读取并初始化该目录中的所有提示词，无需修改代码。

示例：

1. 在 prompts 文件夹中使用现有文件，或创建一个新文件，例如 my_custom_prompt.yaml。
2. 使用 YAML 格式定义提示词逻辑和参数。
3. 重新构建服务以加载新提示词。

这种方式让你无需修改代码库，即可快速使用自定义提示词扩展服务功能。

验证设置

1. 验证 ReportPortal 是否可访问

测试 MCP 服务之前，请确保 ReportPortal 实例可以访问：

通过浏览器：

1. 在 Web 浏览器中打开你的 ReportPortal URL（RP_HOST）
2. 应该会看到 ReportPortal 登录页面或仪表板
3. 确认可以使用你的凭据登录

通过命令行（curl）：

# Test basic connectivity
curl -I https://your-reportportal-instance.com

# Test API access with your token
curl -H "Authorization: Bearer your-api-token" \
     https://your-reportportal-instance.com/api/v1/YourProjectKey/launch

通过 PowerShell：

# Test basic connectivity
Invoke-WebRequest -Uri "https://your-reportportal-instance.com" -Method Head

# Test API access
$headers = @{
    "Authorization" = "Bearer your-api-token"
}
Invoke-RestMethod -Uri "https://your-reportportal-instance.com/api/v1/YourProjectKey/launch" -Headers $headers

预期结果：

• HTTP 200 OK 响应
• 有效的 JSON 响应，其中包含启动数据（如果项目存在启动记录）
• 没有身份验证错误（401）或禁止访问错误（403）

2. 验证远程 MCP 服务（如果使用远程部署）

如果连接到远程 MCP 服务，请验证其是否可访问：

通过浏览器：

http://your-mcp-server-host:port/

应返回服务器信息和可用端点。

通过 curl（GET 请求）：

# Check server health
curl http://your-mcp-server-host:port/health

# Check server info
curl http://your-mcp-server-host:port/info

通过 curl（MCP 协议测试）：

# Test MCP endpoint with JSON-RPC request
curl -X POST http://your-mcp-server-host:port/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-token" \
  -H "X-Project: YourProjectKey" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

通过 PowerShell：

# Check server health
Invoke-RestMethod -Uri "http://your-mcp-server-host:port/health"

# Test MCP endpoint
$headers = @{
    "Content-Type" = "application/json"
    "Authorization" = "Bearer your-api-token"
    "X-Project" = "YourProjectKey"
}
$body = @{
    jsonrpc = "2.0"
    method = "tools/list"
    id = 1
} | ConvertTo-Json

Invoke-RestMethod -Uri "http://your-mcp-server-host:port/mcp" -Method Post -Headers $headers -Body $body

通过 ping（仅测试网络连通性）：

ping your-mcp-server-host

预期结果：

• 服务器响应健康检查
• /info 返回服务器配置
• MCP 端点返回可用工具列表
• 没有连接被拒绝或超时错误

3. 验证 MCP 服务集成

完成配置后，验证 AI 助手能否与 MCP 服务通信：

步骤 1：检查可用工具

向 AI 助手提问：

"What ReportPortal tools are available?"

预期响应：包含 37 个工具的列表，包括启动、测试项、分析工具、TMS 工具等。

步骤 2：测试基本查询

尝试一个简单查询：

"List the 5 most recent test launches"

预期响应：格式化的近期启动列表，包含名称、状态和时间戳。

步骤 3：检查服务器日志

监控日志，确认请求正在得到处理：

Docker：

# View logs
docker logs <container-name>

# Follow logs in real-time
docker logs -f <container-name>

# View last 50 lines
docker logs --tail 50 <container-name>

二进制文件（stdio 模式）： 检查服务器运行所在终端的输出。每个请求都应显示相应的日志条目。

二进制文件（HTTP 模式）：

# If redirecting to file
./reportportal-mcp-server > server.log 2>&1

# Then view logs
tail -f server.log

预期日志输出：

INFO: MCP server started
INFO: Received request: tools/list
INFO: Processing tool call: get_launches
DEBUG: Calling ReportPortal API: /api/v1/projectKey/launch

4. 常见验证问题

问题	原因	解决方案
AI 未显示 ReportPortal 工具	MCP 服务未连接	检查配置文件语法，然后重启 AI 助手
“Connection refused” 错误	服务器未运行或端口错误	确认服务器正在运行：docker ps，或检查进程
“401 Unauthorized”	API 令牌无效	在 ReportPortal 个人资料中重新生成令牌
“403 Forbidden”	令牌有效，但没有项目访问权限	检查 RP_PROJECT 键（必须与 Project KEY 匹配，而不是显示名称），并确认用户有访问权限
“404 Not Found”	端点 URL 错误	确保远程 URL 以 /mcp/ 结尾
查询结果为空	ReportPortal 中没有数据	先运行一些测试以填充数据
超时错误	网络问题或 ReportPortal 响应缓慢	检查网络连通性和 ReportPortal 性能

故障排除

连接问题

问题：无法连接到 ReportPortal

症状：

• 出现“Connection refused”错误
• 出现“Could not resolve host”错误
• 出现超时错误

解决方案：

1. 确认 RP_HOST 正确，并包含协议（https:// 或 http://）
2. 检查网络连通性：ping your-reportportal-host
3. 确认 ReportPortal 正在运行且可访问
4. 检查防火墙规则是否允许连接到 ReportPortal
5. 对于 HTTPS，确认 SSL 证书有效

问题：无法连接到远程 MCP 服务

症状：

• MCP 服务出现“Connection refused”
• 出现“No route to host”错误

解决方案：

1. 确认 MCP 服务正在运行：使用 curl http://host:port/health 检查
2. 确认服务器已设置 MCP_MODE=http
3. 确认端口正确（默认值：8080）
4. 检查防火墙/安全组是否允许访问该端口
5. 确保服务器绑定到正确的网络接口（MCP_SERVER_HOST）

身份验证问题

问题：401 Unauthorized 错误

解决方案：

1. 确认 API 令牌正确且未过期
2. 在 ReportPortal 中重新生成令牌：个人资料 → API 密钥 → 生成新令牌
3. 检查令牌是否已正确设置在环境变量或配置中
4. 对于远程服务，确认已发送 Authorization: Bearer <token> 标头
5. 确保令牌值前后没有多余的空格或引号

问题：403 Forbidden 错误

解决方案：

1. 确认用户有权访问指定项目
2. 检查项目键（RP_PROJECT）是否完全匹配（区分大小写，必须是 Project Key，而不是显示名称）
3. 确认用户角色拥有足够的权限
4. 对于远程服务，检查 X-Project 标头是否设置正确

Docker 问题

问题：Docker 容器立即退出

解决方案：

1. 检查容器日志：docker logs <container-name>
2. 确认已设置所有必需的环境变量
3. 确保环境变量值不存在语法错误
4. 检查 Docker 是否有权访问网络

问题："docker: command not found"

解决方案：

1. 为你的操作系统安装 Docker Desktop
2. 确认 Docker 正在运行：docker --version
3. 对于 Linux，将用户添加到 docker 组：sudo usermod -aG docker $USER

AI 助手集成问题

问题：AI 助手无法识别 MCP 服务

解决方案：

1. 确认配置文件语法是有效的 JSON
2. 检查配置文件是否位于正确位置
3. 更改配置后重启 AI 助手
4. 对于 Cursor/VS Code，检查 MCP 扩展是否已安装并启用
5. 查看 AI 助手日志中的错误消息

问题：工具列表为空

解决方案：

1. 确认 MCP 服务正在运行且可访问
2. 检查服务日志中的启动错误
3. 确保服务模式与客户端配置一致（stdio 或 HTTP）
4. 对于远程服务，确认 URL 以 /mcp/ 结尾

性能问题

问题：响应缓慢或超时

解决方案：

1. 检查 ReportPortal API 性能（使用 curl 测试）
2. 减小查询中的页面大小（page-size 参数）
3. 使用筛选条件限制数据检索范围
4. 检查服务与 ReportPortal 之间的网络延迟
5. 监控服务资源（CPU、内存）

问题：内存使用量过高

解决方案：

1. 减少并发请求
2. 使用分页限制结果集大小
3. 定期重启 MCP 服务
4. 检查日志中是否存在内存泄漏

配置问题

问题："Environment variable not set"

解决方案：

1. 确认变量名称正确：RP_HOST、RP_PROJECT、RP_API_TOKEN
2. 对于 Docker，检查 -e 标志是否指定正确
3. 对于二进制文件，在同一个 Shell 会话中导出变量
4. 使用 echo $VAR_NAME（Linux/Mac）或 $env:VAR_NAME（PowerShell）进行验证

问题："Invalid JSON" 配置错误

解决方案：

1. 使用 JSON 验证器检查 JSON 语法
2. 删除 JSON 对象中的尾随逗号
3. 确保所有字符串都正确使用引号
4. 检查是否包含注释（JSON 不支持注释）
5. 检查路径中的转义字符（Windows 路径中使用 \\）

获取帮助

如果问题仍然存在：

1. 检查日志：启用调试日志记录并查看详细错误消息
2. 测试组件：分别验证每个组件（ReportPortal → MCP 服务 → AI 助手）
3. GitHub Issues：在 reportportal-mcp-server 搜索或创建问题
4. 文档：查看 MCP 规范 和 ReportPortal API 文档
5. 社区：加入 ReportPortal 社区获取支持

许可证

本项目基于 Apache 2.0 许可证 授权。