Metadata-Version: 2.4
Name: testio-mcp
Version: 0.2.2
Summary: Model Context Protocol server for TestIO Customer API integration
Author: TestIO MCP Team
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://github.com/test-IO/customer-mcp
Project-URL: Documentation, https://github.com/test-IO/customer-mcp#readme
Project-URL: Repository, https://github.com/test-IO/customer-mcp
Project-URL: Issues, https://github.com/test-IO/customer-mcp/issues
Keywords: mcp,testio,api,ai,llm,model-context-protocol
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp>=2.12.0
Requires-Dist: pydantic>=2.12.0
Requires-Dist: pydantic-settings>=2.11.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: python-dateutil>=2.8.0
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: rich>=13.7.0
Requires-Dist: dateparser>=1.2.0
Requires-Dist: filelock>=3.13.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: fastapi>=0.109.0
Requires-Dist: uvicorn[standard]>=0.27.0
Provides-Extra: dev
Requires-Dist: pytest>=8.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
Requires-Dist: pytest-cov>=7.0.0; extra == "dev"
Requires-Dist: pytest-httpx>=0.30.0; extra == "dev"
Requires-Dist: ruff>=0.8.4; extra == "dev"
Requires-Dist: mypy>=1.13.0; extra == "dev"
Requires-Dist: pre-commit>=4.0.0; extra == "dev"
Requires-Dist: detect-secrets; extra == "dev"
Requires-Dist: pip-audit>=2.8.0; extra == "dev"
Requires-Dist: freezegun>=1.5.0; extra == "dev"
Requires-Dist: types-python-dateutil>=2.8.0; extra == "dev"
Requires-Dist: types-dateparser>=1.2.0; extra == "dev"
Requires-Dist: types-psutil>=5.9.0; extra == "dev"
Requires-Dist: bump-my-version>=0.28.0; extra == "dev"
Dynamic: license-file

# 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.

---
