testio-mcp 0.2.1

Model Context Protocol server for TestIO Customer API integration

TestIO MCP Server

AI-first Model Context Protocol server for TestIO Customer API

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 for details.

---

What Is This?

TestIO MCP Server is a Model Context Protocol (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

# 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 for configuration options.

Alternative: stdio mode (Single Client)

For using only one MCP client at a time:

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

See 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:

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

# 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 for advanced sync patterns and troubleshooting.

MCP Client Configuration

stdio mode (Single Client):

claude mcp add testio-mcp -- uvx testio-mcp

HTTP mode (Multiple Clients):

{
  "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 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 for details.

---

Documentation

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

---

Configuration

See .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 for terms.

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

---