# Test Results MCP Server

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that lets an LLM assistant
(such as Claude Desktop) analyze automated test results, search logs, and file Jira bugs
with steps to reproduce.

![Demo](docs/demo.png)

## Why

Triaging a failed test run usually means jumping between the results report, log files and Jira.
This server exposes those as tools, so an assistant can chain them: find the failures, group them
by cause, look for evidence in the logs, and draft a bug for a human to approve.

## Tools

| Tool | What it does |
|---|---|
| `get_summary` | Total / passed / failed / skipped counts, pass rate, duration |
| `list_failed_tests` | Failed tests with a one-line error each |
| `get_failure_details` | Full error message and stack trace for one test |
| `group_failures_by_error` | Clusters failures by error text (numbers normalised) for first-level root cause analysis |
| `search_logs` | Regex search across log files in a configured folder |
| `create_jira_bug` | Builds a Jira bug (summary, steps to reproduce, expected/actual result, stack trace). **Dry-run by default** |
| `list_jira_issue_types` | Shows which issue types the Jira project accepts (troubleshooting) |

## Quick start

Requires Python 3.10+.

```bash
git clone https://github.com/AnittaSusanThomas/test-results-mcp-server.git
cd test-results-mcp-server
python -m pip install -r requirements.txt

# run the tests
python -m pytest

# try the server in the MCP Inspector
npx @modelcontextprotocol/inspector python test_results_mcp_server.py
```

The server reads `sample/results.xml` and `sample/logs/` by default. Point it at your own
JUnit-style XML and log folder with the `RESULTS_FILE` and `LOG_DIR` environment variables.

## Use it with Claude Desktop

Open **Settings → Developer → Edit Config** and add this to `claude_desktop_config.json`
(use your own absolute paths):

```json
{
  "mcpServers": {
    "test-results": {
      "command": "python",
      "args": ["C:/path/to/test_results_mcp_server.py"],
      "env": {
        "RESULTS_FILE": "C:/path/to/sample/results.xml",
        "LOG_DIR": "C:/path/to/sample/logs"
      }
    }
  }
}
```

Fully quit and reopen Claude Desktop, then try:

> Summarize my latest test run, group the failures by cause, and search the logs for timeouts.

### Optional: Jira

Add these to the same `env` block (see `.env.example`): `JIRA_BASE_URL`, `JIRA_EMAIL`,
`JIRA_API_TOKEN`, `JIRA_PROJECT_KEY`, and optionally `JIRA_ISSUE_TYPE`.
Create an API token at <https://id.atlassian.com/manage-profile/security/api-tokens>.

## Design decisions

- **Dry-run by default.** `create_jira_bug` only previews the ticket unless `dry_run=False` is passed, so
  an assistant cannot create tickets by accident. The client also asks for approval on each tool call.
- **Secrets stay out of code.** Credentials come from environment variables.
- **Restricted log access.** `search_logs` only reads files inside `LOG_DIR`.
- **Jira projects differ.** The tool asks Jira which issue types the project allows and picks a valid one
  (preferred type, then Bug, then Task) instead of hardcoding "Bug".
- **stdio transport.** Suits a local server launched by the client. A shared deployment would use HTTP with authentication.

## Limitations and next steps

- Reads a local JUnit XML file; it is not yet wired to a CI system.
- No duplicate-ticket check before creating a Jira issue.
- Planned: a `run_tests` tool that triggers a Jenkins job, and a `compare_runs` tool that shows new failures versus the previous run.
- Tested with `mcp` 1.x (`mcp[cli]<2`). MCP 2.x renamed `FastMCP` to `MCPServer`.

## Project layout

```
test_results_mcp_server.py   the server
sample/                      dummy results and logs for trying it out
tests/test_server.py         pytest tests
.env.example                 settings reference (no real values)
```

## License

MIT