Metadata-Version: 2.4
Name: bibliocommons-mcp-testrail
Version: 1.0.0
Summary: MCP server for TestRail test case management
Author-email: Cody Lusk <cody.lusk@bibliocommons.com>
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastmcp>=3.2.4
Requires-Dist: requests>=2.33.1
Requires-Dist: fastapi>=0.136.1
Requires-Dist: uvicorn>=0.46.0
Requires-Dist: python-multipart>=0.0.27
Provides-Extra: dev
Requires-Dist: pytest>=9.0.3; extra == "dev"
Requires-Dist: pytest-asyncio>=1.3.0; extra == "dev"
Requires-Dist: pytest-cov>=7.1.0; extra == "dev"
Requires-Dist: httpx>=0.28.1; extra == "dev"

# TestRail MCP Server

MCP server for interacting with TestRail test case management instances.

## Configuration

**Authentication**: TestRail uses HTTP Basic Authentication with your username and an API key (generated under My Settings → API Keys in TestRail). It is recommended to create a dedicated API user account rather than using a personal account.

### Option 1: config.json

```bash
cp config.json.example config.json
# Edit config.json with your API user credentials
```

### Option 2: Environment Variables

```bash
export TESTRAIL_URL="https://example.testrail.io"
export TESTRAIL_USERNAME="api-user@example.com"
export TESTRAIL_API_KEY="your-testrail-api-key"
export TESTRAIL_VERIFY_SSL="true"
```

## Installation

### Option 1: Using uv (Recommended)

[uv](https://github.com/astral-sh/uv) is a fast Python package manager. Install it first:

```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```

No additional installation needed - `uvx` will handle dependencies automatically.

### Option 2: Using pip

```bash
pip install bibliocommons-mcp-testrail
# or for development
pip install -e ".[dev]"
```

## AI Client Setup

### VS Code (with MCP Extension)

1. Install an MCP-compatible extension in VS Code
2. Open VS Code Settings (JSON): `Cmd+Shift+P` → "Preferences: Open User Settings (JSON)"
3. Add the server configuration:

```json
{
  "mcp.servers": {
    "testrail": {
      "command": "uvx",
      "args": ["--from", "/absolute/path/to/testrail", "bibliocommons-mcp-testrail"]
    }
  }
}
```

**Alternative: Using python directly**

```json
{
  "mcp.servers": {
    "testrail": {
      "command": "python",
      "args": ["-m", "bibliocommons_mcp_testrail"]
    }
  }
}
```

### Claude Desktop

1. Open Claude Desktop configuration:
   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`

2. Add the server configuration:

```json
{
  "mcpServers": {
    "testrail": {
      "command": "uvx",
      "args": ["--from", "/absolute/path/to/testrail", "bibliocommons-mcp-testrail"]
    }
  }
}
```

**Alternative: Using python directly**

```json
{
  "mcpServers": {
    "testrail": {
      "command": "python",
      "args": ["-m", "bibliocommons_mcp_testrail"]
    }
  }
}
```

### Kiro IDE

1. Open Kiro IDE settings
2. Navigate to MCP Servers configuration
3. Add the server:

```json
{
  "mcpServers": {
    "testrail": {
      "command": "uvx",
      "args": ["--from", "/absolute/path/to/testrail", "bibliocommons-mcp-testrail"]
    }
  }
}
```

**Alternative: Using python directly**

```json
{
  "mcpServers": {
    "testrail": {
      "command": "python",
      "args": ["-m", "bibliocommons_mcp_testrail"]
    }
  }
}
```

### Kiro CLI

1. Create or edit the MCP configuration file:
   - User level: `~/.kiro/settings/mcp.json`
   - Project level: `<project-root>/.kiro/settings/mcp.json`

2. Add the server configuration:

```json
{
  "mcpServers": {
    "testrail": {
      "command": "uvx",
      "args": ["--from", "/absolute/path/to/testrail", "bibliocommons-mcp-testrail"]
    }
  }
}
```

**Alternative: Using python directly**

```json
{
  "mcpServers": {
    "testrail": {
      "command": "python",
      "args": ["-m", "bibliocommons_mcp_testrail"]
    }
  }
}
```

### Configuration Notes

- Replace `/absolute/path/to/testrail/` with the actual path to your server directory
- **Using `uvx` (default)**: Automatically manages dependencies in isolated environments (like `npx` for Node.js)
- **Using `python` (alternative)**: Requires `pip install bibliocommons-mcp-testrail` first
- After adding the configuration, restart your AI client for changes to take effect

## Docker

```bash
# Pull from Docker Hub (private)
docker pull bibliocommons/mcp-testrail:latest

# Run in stdio mode
docker run -i --rm \
  -v /path/to/config.json:/config.json:ro \
  bibliocommons/mcp-testrail:latest \
  --config /config.json

# Run in HTTP mode
docker run -d --rm \
  -v /path/to/config.json:/config.json:ro \
  -p 8000:8000 \
  bibliocommons/mcp-testrail:latest \
  --config /config.json --transport http --port 8000

# Run in expanded mode
docker run -i --rm \
  -v /path/to/config.json:/config.json:ro \
  bibliocommons/mcp-testrail:latest \
  --config /config.json --expanded
```

## Web UI with Swagger

A REST API with interactive Swagger documentation is available:

```bash
python -m bibliocommons_mcp_testrail.webui
```

Access the Swagger UI at: [http://localhost:8000/docs]

The Web UI provides:

- Interactive API documentation
- Try-it-out functionality for all endpoints
- OpenAPI/Swagger specification
- REST API access to all MCP tools

## Standalone MCP Server

```bash
python -m bibliocommons_mcp_testrail
```

### CLI Flags

| Flag | Env Var | Description |
|------|---------|-------------|
| `--config PATH` | `TESTRAIL_CONFIG` | Path to config.json |
| `--read-only` | `TESTRAIL_READ_ONLY` | Exclude destructive tools (add/update/delete operations) |
| `--expanded` | `TESTRAIL_EXPANDED` | Register all tools individually instead of gateway mode |
| `--transport stdio\|http` | `TESTRAIL_TRANSPORT` | Transport mode (default: stdio) |
| `--port PORT` | `TESTRAIL_PORT` | HTTP port (default: 8000) |
| `--version` | — | Show version and exit |

## Gateway Mode (Default)

By default, the server exposes 2 tools instead of 40+ individual tools:

| Tool | Purpose |
|------|---------|
| `testrail_api` | Execute any TestRail action by name with a params dict |
| `testrail_help` | Search available actions, parameters, and descriptions |

The AI assistant calls `testrail_help` to discover available actions, then calls `testrail_api(action="get_cases", params={"project_id": 1, "suite_id": 5})` to execute them.

To register all individual tools (previous behavior), use `--expanded`:

```bash
python -m bibliocommons_mcp_testrail --expanded
```

## Available Tools

### Projects

- `get_projects` - List all projects
- `get_project` - Get project by ID
- `add_project` - Create a new project
- `update_project` - Update a project
- `delete_project` - Delete a project

### Suites

- `get_suites` - List suites for a project
- `get_suite` - Get suite by ID
- `add_suite` - Create a new suite
- `update_suite` - Update a suite
- `delete_suite` - Delete a suite

### Cases

- `get_case` - Get test case by ID (full details)
- `get_cases` - List test cases for a project with optional filters
- `add_case` - Create a new test case
- `update_case` - Update a test case
- `update_cases` - Bulk update multiple test cases
- `delete_case` - Delete a test case
- `get_case_types` - List available case types
- `get_case_fields` - List available case fields
- `copy_to_section` - Copy test cases to a section
- `move_to_section` - Move test cases to a section
- `get_case_history` - Get change history for a test case
- `get_bdd` - Export BDD test case as .feature file
- `add_bdd` - Import BDD .feature file into a section

### Sections

- `get_section` - Get section by ID
- `get_sections` - List sections for a project
- `add_section` - Create a new section
- `move_section` - Move a section
- `update_section` - Update a section
- `delete_section` - Delete a section

### Runs

- `get_runs` - List test runs for a project
- `get_run` - Get test run by ID
- `add_run` - Create a new test run
- `update_run` - Update a test run
- `close_run` - Close a test run
- `delete_run` - Delete a test run

### Tests

- `get_tests` - List tests in a run
- `get_test` - Get test by ID

### Results

- `get_results` - Get results for a test
- `get_results_for_case` - Get results for a case in a run
- `get_results_for_run` - Get all results for a run
- `add_result_for_case` - Add a result for a case in a run
- `add_results_for_cases` - Bulk add results for multiple cases

### Plans

- `get_plans` - List test plans for a project
- `get_plan` - Get test plan by ID
- `add_plan` - Create a new test plan

### Milestones

- `get_milestones` - List milestones for a project
- `get_milestone` - Get milestone by ID

### Shared Steps

- `get_shared_steps` - List shared steps for a project
- `get_shared_step` - Get shared step by ID
