Skip to content

Commit e14dd7b

Browse files
AmsterGetAmsterGet
authored
EPMRPP-104321 || Update readme (reportportal#26)
* Temp guide * EPMRPP-104321 || Update readme * EPMRPP-104321 || Add links * Update README.md * Update README.md * EPMRPP-104321 || Update installation guide * EPMRPP-104321 || Add installation section for GitHub Copilot * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md
1 parent bbf6fa6 commit e14dd7b

File tree

1 file changed

+237
-75
lines changed

1 file changed

+237
-75
lines changed

‎README.md

Lines changed: 237 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -4,38 +4,226 @@
44

55
# ReportPortal MCP Server
66

7-
This repository contains a ReportPortal MCP Server.
8-
It allows users to interact with ReportPortal directly from GitHub Copilot / Claude / etc chat to query and analyze test execution results.
7+
## What is the ReportPortal MCP Server?
8+
9+
The ReportPortal MCP Server is a bridge between your ReportPortal instance and AI chat assistants (such as Claude Desktop, GitHub Copilot, Cursor). In simple terms, it lets you ask questions in plain English about your test runs and get answers directly from ReportPortal. It follows the official [MCP](https://modelcontextprotocol.io/overview) guidelines.
10+
11+
For example, instead of logging into the ReportPortal UI, you could ask your AI assistant "What tests failed in the last run?" or "List the 5 most recent test runs," and it will fetch that information from ReportPortal for you. This makes it easy for QA testers and managers to query test results using natural language, speeding up analysis and reporting.
12+
13+
## Why Use It?
14+
15+
- **Quick Test Insights**: Instantly retrieve summaries of test runs, failure counts, or error details without writing code or navigating the UI.
16+
- **Chat-Based Queries**: Use your favourite AI assistant (Claude, Cursor, etc.) to converse with ReportPortal data. It's like having a smart test-reporting helper in your chat window.
17+
- **Integration Flexibility**: Works with any MCP-compatible AI tool. You simply point the tool at this server and it can run ReportPortal queries under the hood.
18+
- **No Custom Scripts Needed**: Common queries (listing runs, getting failures, analysis) are built-in as simple "commands" you invoke via chat.
19+
20+
## Installation
21+
22+
There are two ways to run the latest version of the ReportPortal MCP Server.
23+
Each of this way is suitable for any LLM provider.
24+
25+
### Via Docker (recommended).
26+
27+
The MCP server is available on the official ReportPortal's [DockerHub](https://hub.docker.com/r/reportportal/mcp-server).
28+
29+
Configuration:
30+
```json
31+
{
32+
"reportportal": {
33+
"command": "docker",
34+
"args": [
35+
"run",
36+
"-i",
37+
"--rm",
38+
"-e",
39+
"RP_API_TOKEN",
40+
"-e",
41+
"RP_HOST",
42+
"-e",
43+
"RP_PROJECT",
44+
"reportportal/mcp-server"
45+
],
46+
"env": {
47+
"RP_API_TOKEN": "your-api-token",
48+
"RP_HOST": "https://your-reportportal-instance.com",
49+
"RP_PROJECT": "YourProjectInReportPortal"
50+
}
51+
}
52+
}
53+
```
54+
55+
### Using pre-built binaries.
56+
57+
The OS pre-built binaries can be downloaded from the official releases on [GitHub](https://github.com/reportportal/reportportal-mcp-server/releases).
58+
59+
Configuration:
60+
```json
61+
{
62+
"reportportal": {
63+
"command": "/path/to/reportportal-mcp-server-binary",
64+
"args": ["stdio"],
65+
"env": {
66+
"RP_API_TOKEN": "your-api-token",
67+
"RP_HOST": "https://your-reportportal-instance.com",
68+
"RP_PROJECT": "YourProjectInReportPortal"
69+
}
70+
}
71+
}
72+
```
73+
74+
Choose your favourite AI Tool to connect.
75+
76+
### Claude Desktop
77+
78+
1. Open Claude Desktop, go to **Settings → Developer → Edit Config**.
79+
2. Add a new MCP server entry that runs the ReportPortal MCP Server.
80+
```json
81+
{
82+
"mcpServers": {
83+
"reportportal": {
84+
// choose the Docker or binary configuration from the section above
85+
}
86+
}
87+
}
88+
```
89+
3. Save and restart Claude Desktop.
90+
91+
### Claude Code CLI
92+
93+
1. Open your terminal.
94+
2. Run the following comman.
95+
```bash
96+
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": "your-api-token", "RP_HOST": "https://your-reportportal-instance.com", "RP_PROJECT": "YourProjectInReportPortal"}}'
97+
```
98+
99+
**Configuration Options:**
100+
- Use `-s user` to add the server to your user configuration (available across all projects).
101+
- Use `-s project` to add the server to project-specific configuration (shared via `.mcp.json`).
102+
- Default scope is `local` (available only to you in the current project).
103+
104+
Documentation: [Claude Code guide](https://docs.anthropic.com/en/docs/claude-code/mcp).
105+
106+
### Cursor (AI Code Editor)
107+
108+
1. In Cursor, go to **Settings → Extensions → MCP** and click to add a new global MCP server.
109+
2. Add a new MCP server entry that runs the ReportPortal MCP Server.
110+
```json
111+
{
112+
"mcpServers": {
113+
"reportportal": {
114+
// choose the Docker or binary configuration from the section above
115+
}
116+
}
117+
}
118+
```
119+
Documentation: [Cursor MCP](https://docs.cursor.com/en/tools/developers#example).
120+
121+
### GitHub Copilot (In VS Code and JetBrains IDEs)
122+
123+
#### VS Code
124+
125+
1. Install/update the GitHub Copilot plugin.
126+
2. Type **>mcp** in the search bar and select **MCP: Open User Configuration**.
127+
3. Add configuration:
128+
```json
129+
{
130+
"servers": {
131+
"reportportal": {
132+
// choose the Docker or binary configuration from the section above
133+
}
134+
}
135+
}
136+
```
137+
138+
Documentation: [VS Code Copilot Guide](https://code.visualstudio.com/docs/copilot/chat/mcp-servers).
139+
140+
#### JetBrains IDEs
141+
142+
1. Install/update the GitHub Copilot plugin.
143+
2. Click **GitHub Copilot icon in the status bar → Edit Settings → Model Context Protocol → Configure**.
144+
3. Add configuration:
145+
```json
146+
{
147+
"servers": {
148+
"reportportal": {
149+
// choose the Docker or binary configuration from the section above
150+
}
151+
}
152+
}
153+
```
154+
4. Press `Ctrl + S` or `Command + S` to save, or close the `mcp.json` file. The configuration should take effect immediately and restart all the MCP servers defined. You can restart the IDE if needed.
155+
156+
Documentation: [JetBrains Copilot Guide](https://plugins.jetbrains.com/plugin/17718-github-copilot).
157+
158+
Once connected, your AI assistant will list ReportPortal-related "tools" it can invoke. You can then ask your questions in chat, and the assistant will call those tools on your behalf.
9159

10160
## Features
11161

12162
The ReportPortal MCP server provides a comprehensive set of capabilities for interacting with ReportPortal:
13163

14164
### Launch Management
15-
- List and filter launches with pagination
165+
- Get and filter launches (test runs) with pagination
16166
- Get launch details by name or ID
17-
- Force finish running launches
167+
- Force-finish running launches
18168
- Delete launches
19-
- Run automated analysis on launches (auto analysis, unique error analysis)
169+
- Run automated analysis (auto analysis, unique error analysis) on launches
20170

21171
### Test Item Analysis
22-
- List test items within launches
23-
- Get detailed test item information
172+
- Get test items within by filter
173+
- Get detailed information on each test item
24174
- View test execution statistics and failures
175+
- Retrieve test logs and attachments
25176

26177
### Report Generation
27178
- Analyze launches to get detailed test execution insights
28179
- Generate structured reports with statistics and failure analysis
29180

30-
### Extensibility
31-
- Add custom tools through code extensions
32-
- Define new prompts via YAML files in the `prompts` directory
33-
- Access structured resource data for launches and test items
181+
### Available Tools (commands)
34182

35-
## Installation
183+
| Tool Name | Description | Parameters |
184+
|----------------------------|--------------------------------------------------|---------------------------------------------------------------------------------------------------------------|
185+
| Get Launches by filter | Lists ReportPortal launches with pagination by filter | `name`, `description`, `owner`, `number`, `start_time`, `end_time`, `attributes`, `sort`, `page`, `page-size` (all optional) |
186+
| Get Last Launch by Name | Retrieves the most recent launch by name | `name` |
187+
| Run Auto Analysis | Runs auto analysis on a launch | `launch_id`, `analyzer_mode`, `analyzer_type`, `analyzer_item_modes` |
188+
| Run Unique Error Analysis | Runs unique error analysis on a launch | `launch_id`, `remove_numbers` |
189+
| Force Finish Launch | Forces a launch to finish | `launch_id` |
190+
| Delete Launch | Deletes a specific launch | `launch_id` |
191+
| Get Suites by filter | Lists test suites for a specific launch | `launch-id` (required), `name`, `description`, `start_time_from`, `start_time_to`, `attributes`, `parent_id`, `sort`, `page`, `page-size` (all optional) |
192+
| Get Test Items by filter | Lists test items for a specific launch | `launch-id` (required), `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`, `sort`, `page`, `page-size` (all optional) |
193+
| Get Logs by filter | Lists logs for a specific test item or nested step | `parent-id` (required), `log_level`, `log_content`, `logs_with_attachments`, `status`, `sort`, `page`, `page-size` (all optional) |
194+
| Get Attachment by ID | Retrieves an attachment binary by id | `attachment_id` |
195+
| Run Unique Error Analysis | Runs unique error analysis on a launch | `launch_id`, `remove_numbers` |
196+
| Get Test Item by ID | Retrieves details of a specific test item | `test_item_id` |
36197

37-
### Prerequisites
198+
### Available Prompts
199+
200+
#### Analyze Launch
201+
202+
Analyzes a ReportPortal launch and provides detailed information about test results, failures, and statistics.
203+
204+
Parameters:
205+
- `launch_id`: ID of the launch to analyze
206+
207+
You can follow the [prompt text and structure](https://github.com/reportportal/reportportal-mcp-server/blob/main/internal/reportportal/prompts/launch.yaml) as a reference while working on your own prompts.
208+
209+
### Example Queries (Natural Language)
210+
211+
Here are some real-world examples of what you might ask your AI after setup (the assistant's response will be drawn from ReportPortal data):
38212

213+
- **"List the 5 most recent test launches."** – returns a paginated list of recent test runs with names and statuses.
214+
- **"What tests failed in the latest run?"** – shows failed test items for the most recent launch.
215+
- **"Show me details of launch with number 1234."** – fetches information (ID, name, description, stats) for that specific launch.
216+
- **"Run an analysis on launch ABC."** – triggers the ReportPortal's auto-analysis to summarize results and failures for launch "ABC".
217+
- **"Finish the running launch with ID 4321."** – forces a currently running test launch to stop.
218+
- **"Show me the top five 500-level errors in the last hour"** - lists the top 5 such errors from the recent test results.
219+
220+
Each query above corresponds to a "tool" provided by the MCP server, but you just phrase it naturally.
221+
The AI will invoke the correct command behind the scenes.
222+
These features let you query and manage your test reports in many ways through simple chat interactions.
223+
224+
## For developers
225+
226+
### Prerequisites
39227
- Go 1.24.1 or later
40228
- A ReportPortal instance
41229

@@ -50,89 +238,67 @@ cd reportportal-mcp-server
50238
go build -o reportportal-mcp-server ./cmd/reportportal-mcp-server
51239
```
52240

53-
## Configuration
241+
This creates an executable called `reportportal-mcp-server`.
54242

55-
The server uses environment variables for configuration:
243+
### Configuration
56244

57-
| Variable | Description | Default |
58-
|----------------|------------------------------------------|---------|
59-
| `RP_HOST` | ReportPortal host URL | |
60-
| `RP_API_TOKEN` | ReportPortal API token | |
61-
| `RP_PROJECT` | (optional) ReportPortal project name | |
62-
| `MCP_PORT` | (optional) Port to run the MCP server on | `4389` |
245+
The server needs to know where your ReportPortal is and how to authenticate. Set these environment variables in your shell:
63246

64-
## Usage
247+
| Variable | Description | Required |
248+
|----------|-------------|----------|
249+
| `RP_HOST` | The URL of your ReportPortal (e.g. https://myreportportal.example.com) | Yes |
250+
| `RP_PROJECT` | Your default project name in ReportPortal | Optional |
251+
| `RP_API_TOKEN` | Your ReportPortal API token (for access) | Yes |
252+
| `MCP_PORT` | Port for the MCP server | `4389` |
65253

66-
### Starting the Server
254+
For example:
67255

68256
```bash
69-
# Set required environment variables
70257
export RP_HOST="https://your-reportportal-instance.com"
71-
export RP_PROJECT="your-project"
72-
export RP_TOKEN="your-api-token"
73-
74-
# Run the server
75-
./reportportal-mcp-server
258+
export RP_PROJECT="YourProjectInReportPortal"
259+
export RP_API_TOKEN="your-api-token"
76260
```
77261

78-
### Available Tools
79-
80-
| Tool Name | Description | Parameters |
81-
|----------------------------|--------------------------------------------------|---------------------------------------------------------------------------------------------------------------|
82-
| List Launches | Lists ReportPortal launches with pagination | `page` (optional), `page-size` (optional) |
83-
| Get Last Launch by Name | Retrieves the most recent launch by name | `launch` |
84-
| Force Finish Launch | Forces a launch to finish | `launch_id` |
85-
| Delete Launch | Deletes a specific launch | `launch_id` |
86-
| Get Last Launch by Filter | Retrieves the most recent launch by filters | `name`, `description`, `uuid`, `status`, `start_time`, `end_time`, `attributes`, `mode`, `sort` (all optional)|
87-
| List Test Items by Launch | Lists test items for a specific launch | `launch-id`, `page` (optional), `page-size` (optional) |
88-
| Get Test Item by ID | Retrieves details of a specific test item | `test_item_id` |
89-
| Run Auto Analysis | Runs auto analysis on a launch | `launch_id`, `analyzer_mode`, `analyzer_type`, `analyzer_item_modes` |
90-
| Run Unique Error Analysis | Runs unique error analysis on a launch | `launch_id`, `remove_numbers` |
91-
92-
### Available Prompts
262+
### Starting the Server
93263

94-
#### Analyze Launch
264+
After configuring the env vars as above, simply run:
95265

96-
Analyzes a ReportPortal launch and provides detailed information about test results, failures, and statistics.
97-
98-
Parameters:
99-
- `launch_id`: ID of the launch to analyze
266+
```bash
267+
./reportportal-mcp-server
268+
```
100269

101-
### Available Resources
270+
This will start the MCP server on the configured port.
102271

103-
| Resource Type | Description | Properties |
104-
|---------------|-------------------------------------|------------|
105-
| Launch Resource | Structured access to launch data | • Basic launch info (ID, name, description)<br>• Test execution statistics<br>• Timing information<br>• Status and execution mode |
106-
| Test Item Resource | Structured access to test item data | • Basic test item info (ID, name, description)<br>• Test execution status and type<br>• Parent information and hierarchy position<br>• Issue details (when applicable)<br>• Timing information (start time, end time, duration)<br>• Test attributes and parameters<br>• Path to the test in the test suite hierarchy |
272+
Once running, the MCP server is ready to accept queries from your AI tool.
107273

108-
This table format makes the available resources more scannable while preserving all the key information about each resource type.
274+
### Development
109275

110-
## Development
276+
To set up a development environment or contribute:
111277

112-
### Setting up Development Environment
278+
### Task Tool
279+
Install Go Task v3:
113280
```bash
114-
# Install Task
115281
go install github.com/go-task/task/v3/cmd/task@latest
282+
```
116283

117-
# Install dependencies
284+
### Dependencies
285+
Run task deps to install Go dependencies:
286+
```bash
118287
task deps
119288
```
120289

121-
### Building
290+
### Build
122291
```bash
123-
# Build the server
124292
task build
125293
```
126294

127-
### Running Tests
295+
### Tests
128296
```bash
129-
# Run all tests
130297
task test
131298
```
132299

133-
### Running the MCP Server
300+
### Build with Docker
134301
```bash
135-
# Build Docker Image
136302
task docker:build
137303
```
138304

@@ -153,21 +319,16 @@ task inspector
153319
### Code Quality
154320

155321
```bash
156-
# Run linters
322+
# Lint
157323
task lint
158324

159-
# Format code
325+
# Format
160326
task fmt
161327
```
162328

163-
### Docker
329+
### Extending the Server
164330

165-
```bash
166-
# Build Docker image
167-
task docker:build
168-
```
169-
170-
### Adding New Tools
331+
#### Adding new Tools
171332

172333
To add a new tool, create a new method in the appropriate resource file and add it to the server in the `NewServer` function:
173334

@@ -184,7 +345,8 @@ func NewServer(...) *server.MCPServer {
184345
// ...
185346
}
186347
```
187-
### Adding New Prompts
348+
349+
#### Adding new Prompts
188350

189351
To add a new prompt, simply create a YAML file describing your prompt and place it in the `prompts` folder at the root of the project. The server will automatically read and initialize all prompts from this directory on startup—no code changes are required.
190352

0 commit comments

Comments
 (0)