# TestIO MCP Server

**AI-first Model Context Protocol server for TestIO Customer API**

[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![FastMCP](https://img.shields.io/badge/FastMCP-2.12+-green.svg)](https://github.com/jlowin/fastmcp)
[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
[![Type checked: mypy](https://img.shields.io/badge/type%20checked-mypy-blue.svg)](http://mypy-lang.org/)
[![License: Proprietary](https://img.shields.io/badge/license-Proprietary-red.svg)](LICENSE)

Query TestIO test status, bugs, and activity metrics through AI tools like Claude and Cursor—no UI required.

> **⚠️ Disclaimer:** This software is provided "AS IS" with no warranty or support obligations. See [License & Disclaimer](#license--disclaimer) for details.

---

## What Is This?

TestIO MCP Server is a [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that provides read-only access to the TestIO Customer API. It enables non-developer stakeholders (CSMs, PMs, QA leads) to query test information using natural language through AI assistants like Claude Desktop or Cursor.

**Key Features:**
- 🔍 **8 MCP Tools** - Health check, test status, bug reporting, database management, sync monitoring
- 💾 **Local Data Store** - SQLite-based persistent cache with incremental sync, background refresh, and query interface
- 🏗️ **Service Layer Architecture** - Framework-agnostic business logic, reusable across transports
- 🔒 **Security-First** - Token sanitization, strict input validation, comprehensive secret scanning
- ⚡ **Performance** - Local queries (~10ms), incremental sync, WAL mode for concurrent reads
- 📊 **Strict Type Safety** - mypy --strict enforced, Pydantic v2 validation throughout

**Use Cases:**
- **CSMs:** "What's the status of test 109363?" → Get comprehensive test details in seconds
- **TLs:** "Show me critical functional bugs for test 109363" → Filter bugs by type, severity, status
- **CSMs:** "Generate a status report for tests 109363, 109364" → Export markdown/text/json summaries

---

## Quick Start

### Installation

```bash
# 1. Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Run interactive setup
uvx testio-mcp setup

# 3. Start server (config auto-loads from ~/.testio-mcp.env)
uvx testio-mcp serve --transport http
```

**Setup command features:**
- Interactive prompts for:
  - TestIO subdomain and API token
  - Customer ID (default: 1)
  - Log format (text/JSON) and level (INFO/DEBUG/WARNING)
  - Optional product filtering (reduce sync scope)
- API token validation with retry/force-save options
- Automatic backup of existing configuration
- Secure file permissions (user read/write only)
- Clear next steps after completion

> **📁 Configuration Auto-Loading:**
> - **Production/Users:** `~/.testio-mcp.env` (created by setup, auto-loaded)
> - **Development:** `.env` in repo root (for testing, local dev)
> - **Custom:** Use `--env-file /path/to/custom.env` to override
>
> No `--env-file` flag needed for normal usage!

**Access your data three ways:**
- **MCP Protocol:** `http://localhost:8080/mcp` (Claude, Cursor)
- **REST API:** `http://localhost:8080/api/*` (curl, web apps)
- **Swagger Docs:** `http://localhost:8080/docs` (interactive API explorer)

See [.env.example](.env.example) for configuration options.

### Alternative: stdio mode (Single Client)

For using only one MCP client at a time:

```bash
# Add to Claude Code
claude mcp add testio-mcp -- uvx testio-mcp
```

See [MCP_SETUP.md](MCP_SETUP.md) for detailed client configuration.

---

## API Access

TestIO MCP Server provides **three ways** to access your data:

### 1. MCP Protocol (AI Clients)

Connect Claude Code, Cursor, or other MCP clients to `http://localhost:8080/mcp`

**Best for:** Natural language queries through AI assistants

### 2. REST API (Web Apps, curl)

Standard REST endpoints at `http://localhost:8080/api/*`:
- `GET /api/tests/{test_id}` - Get test details
- `GET /api/tests?product_id=123` - List tests
- `GET /api/products` - List products
- `POST /api/reports/ebr` - Generate executive bug reports

**Best for:** Web applications, scripts, integrations

### 3. Interactive Swagger Docs

Open `http://localhost:8080/docs` in your browser to:
- Browse all available endpoints
- Test API calls interactively
- View request/response schemas
- Generate client code

**Best for:** API exploration, testing, documentation

**Recommended:** Run in hybrid mode (`--api-mode hybrid`) to enable all three access methods simultaneously.

---

## CLI Usage

Basic commands:

```bash
# Show version
uvx testio-mcp --version

# Start HTTP mode (supports multiple clients)
uvx testio-mcp serve --transport http

# Check database sync status
uvx testio-mcp sync --status
```

See [CLAUDE.md](CLAUDE.md) for complete CLI reference and advanced usage.


### Database Sync

**Automatic Sync:**
- **Initial sync** on server startup (non-blocking, server remains available)
- **Background refresh** every 15 minutes (configurable via `TESTIO_REFRESH_INTERVAL_SECONDS`)
- **Incremental updates** - Only fetches new and mutable tests (status not "archived")

**Manual Control:**

```bash
# Check sync status
uvx testio-mcp sync --status

# Sync recent data
uvx testio-mcp sync --since yesterday

# Force full refresh
uvx testio-mcp sync --force
```

See [CLAUDE.md](CLAUDE.md) for advanced sync patterns and troubleshooting.

### MCP Client Configuration

**stdio mode (Single Client):**
```bash
claude mcp add testio-mcp -- uvx testio-mcp
```

**HTTP mode (Multiple Clients):**
```json
{
  "mcpServers": {
    "testio-mcp": {
      "url": "http://127.0.0.1:8080/mcp"
    }
  }
}
```

**For REST API usage:** Open `http://localhost:8080/docs` for interactive Swagger documentation.

See [MCP_SETUP.md](MCP_SETUP.md) for detailed client configuration.

---

## Features

- **Hybrid MCP + REST API** - Access via MCP protocol, REST endpoints, or interactive Swagger docs
- **SQLite Local Cache** - Fast local queries (~10ms), automatic sync, incremental updates
- **8 MCP Tools** - Also available via REST API (see `/docs` for complete list)
- **Type-Safe** - mypy --strict, Pydantic v2 validation throughout
- **HTTP Transport** - Multi-client support, background sync, health monitoring

---

## Architecture

```
┌─────────────────────────────────────────┐
│  MCP Tools / REST Endpoints             │
│  (Transport Layer)                      │
└─────────────┬───────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│  Transformers (Anti-Corruption Layer)   │
│  - Converts service dicts to API models │
│  - Maps 'id' → 'test_id' (semantic)    │
└─────────────┬───────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│  Service Layer (Business Logic)         │
│  - TestService, ProductService, etc.    │
└─────────────┬───────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│  Infrastructure (HTTP & SQLite)         │
│  - TestIOClient, PersistentCache        │
└─────────────────────────────────────────┘
```

See [docs/architecture/ARCHITECTURE.md](docs/architecture/ARCHITECTURE.md) for details.

---

## Documentation

- [CLAUDE.md](CLAUDE.md) - Development guide (testing, CLI reference, adding tools)
- [MCP_SETUP.md](MCP_SETUP.md) - Client configuration by platform
- [docs/architecture/](docs/architecture/) - Architecture, ADRs, security, performance
- [CHANGELOG.md](CHANGELOG.md) - Version history and migration guides

---

## Configuration

See [.env.example](.env.example) for all configuration options including:
- API credentials
- Database settings (path, refresh interval, date filtering)
- HTTP & concurrency limits
- Logging configuration
- Tool enable/disable

---

## License

**Proprietary License** - See [LICENSE](LICENSE) for terms.

This software is provided "AS IS" without warranty. Free to use, no modification/redistribution permitted.

---
