testio-mcp 1.0.0

Model Context Protocol server for TestIO Customer API integration

TestIO MCP Server

Query TestIO test data through AI tools - no UI required.

---

Quick Start

Get started in 3 steps:

1. Setup (One-time configuration)

uvx testio-mcp setup

Creates ~/.testio-mcp.env with your API credentials and preferences.

Reference docs are copied to ~/.testio-mcp/ including .env.example for all available options.

2. Sync Data

uvx testio-mcp sync

Loads your products, features, and tests into local cache (~30s-2min).

3. Start Server

uvx testio-mcp serve --transport http

Runs at http://127.0.0.1:8080 (keep terminal open).

Next: Configure your AI client → MCP_SETUP.md

Optional: Open http://127.0.0.1:8080/docs for interactive API explorer.

---

Access Methods

Method	Endpoint	Best For
MCP	http://127.0.0.1:8080/mcp	Claude, Cursor, AI assistants
REST	http://127.0.0.1:8080/api/*	Scripts, dashboards, integrations
Swagger	http://127.0.0.1:8080/docs	API exploration, testing

Example: Same Query, Two Ways

# Via AI (MCP)
"What's the status of test 109363?"

# Via REST
curl "http://127.0.0.1:8080/api/tests/109363/summary?customer=canva"

---

Tools (17)

Data Discovery

Tool	Example Query
list_products	"Show all mobile apps"
list_tests	"List running tests for product 598"
list_features	"What features does product 598 have?"
list_users	"Who are our testers?"
list_bugs	"Show critical bugs for test 109363"

Entity Summaries

Tool	Example Query
get_test_summary	"Status of test 109363"
get_product_summary	"Overview of product 598"
get_feature_summary	"Details on feature 1234"
get_user_summary	"Show tester 5678's activity"
get_bug_summary	"Details on bug 91011"

Analytics & Reports

Tool	Example Query
generate_quality_report	"Quality report for products 598, 599"
query_metrics	"Bug counts by severity for product 598"
get_analytics_capabilities	"What metrics can I query?"

See ANALYTICS.md for the full analytics guide with query patterns and examples.

Search & Sync

Tool	Example Query
search	"Find bugs mentioning login"
sync_data	"Refresh data for product 598"

Diagnostics

Tool	Example Query
get_server_diagnostics	"Check server health"
get_problematic_tests	"Which tests failed to sync?"

---

Prompts (2)

Interactive workflows for common tasks:

Prompt	Use Case
analyze-product-quality	Deep-dive quality analysis with artifacts
prep-meeting	Generate meeting materials from analysis

---

Resources (2)

Knowledge bases accessible via testio:// URIs:

Resource	Content
testio://knowledge/playbook	CSM heuristics and templates
testio://knowledge/programmatic-access	REST API discovery guide

---

CLI Reference

# Configuration
uvx testio-mcp setup              # Interactive setup
uvx testio-mcp --version          # Show version

# Customer Management
uvx testio-mcp customer list                          # List configured customers
uvx testio-mcp customer add --name acme --token xxx   # Add a customer
uvx testio-mcp customer remove --name acme            # Remove a customer
uvx testio-mcp customer set-default acme              # Set default customer

# Server
uvx testio-mcp serve --transport http              # HTTP mode (multi-client)
uvx testio-mcp serve --transport http --port 9000  # Custom port
uvx testio-mcp                                     # stdio mode (single client)

# Sync
uvx testio-mcp sync --status                # Check sync status
uvx testio-mcp sync --customer acme         # Sync specific customer
uvx testio-mcp sync --all-customers         # Sync all customers
uvx testio-mcp sync --force                 # Full refresh

---

Data Flow

┌─────────────────────────────────────────┐
│  AI Client (Claude, Cursor)             │
│  or REST Client (curl, scripts)         │
└─────────────┬───────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│  TestIO MCP Server                      │
│  localhost:8080                         │
└─────────────┬───────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│  Local SQLite Cache                     │
│  ~/.testio-mcp/cache.db                 │
│  (queries: ~10ms, auto-sync: 1h)        │
└─────────────┬───────────────────────────┘
              ↓ (read-through cache + sync)
┌─────────────────────────────────────────┐
│  TestIO Customer API                    │
│  https://api.test.io/customer/v2        │
└─────────────────────────────────────────┘

Caching: Background sync refreshes products, features, and discovers new tests every hour for all active customers (not just the default). The SyncScheduler manages per-customer sync loops with staggered startup, exponential backoff on failure, and configurable concurrency (SYNC_MAX_CONCURRENT_CUSTOMERS, default: 2). New customers added via CLI are auto-discovered within 60 seconds; removed customers are evicted from memory. Bug and test metadata use read-through caching—refreshed on-demand when queried if stale (>1 hour). Immutable tests (archived/cancelled) always serve from cache. See CLAUDE.md for details on test mutability and caching logic.

---

Configuration

Multi-Customer Mode (v2.0+)

Manage multiple TestIO customers from a single server. Each customer has independent API credentials (stored in OS keychain), data isolation, and sync.

# Add customers
uvx testio-mcp customer add --name canva --token <token> --customer-id 6668
uvx testio-mcp customer add --name pearson --token <token> --customer-id 4278

# All tools and endpoints require a customer parameter
# MCP: list_products(customer="canva")
# REST: GET /api/products?customer=canva

Auto-migration: If you have an existing ~/.testio-mcp.env with TESTIO_CUSTOMER_API_TOKEN, the server auto-creates a customer entry on first startup. Your token moves to the OS keychain and the env var is cleaned up. No manual steps needed.

Environment Variables

Created by uvx testio-mcp setup at ~/.testio-mcp.env:

Variable	Description
TESTIO_DB_PATH	Database path (default: ~/.testio-mcp/cache.db)
TESTIO_PRODUCT_IDS	Filter to specific products
TESTIO_HTTP_PORT	Server port (default: 8080)
LOG_LEVEL	Logging verbosity (default: INFO)

Customer credentials are managed via customer add (stored in OS keychain), not environment variables. For CI/Docker where keyring is unavailable, set TESTIO_CUSTOMER_API_TOKEN and TESTIO_CUSTOMER_NAME.

Full options: see .env.example (repo root or ~/.testio-mcp/.env.example for uvx users).

---

Client Setup

See MCP_SETUP.md for connecting:

• Claude Desktop
• Claude Code (CLI)
• Cursor
• Gemini Code

---

Troubleshooting

# Server won't start?
curl "http://127.0.0.1:8080/health?customer=default"

# Data seems stale?
uvx testio-mcp sync --status
uvx testio-mcp sync --customer canva --force

# Token issues?
uvx testio-mcp customer list          # Check configured customers
uvx testio-mcp customer add --name X  # Re-add with new token

# "Customer not found" errors?
uvx testio-mcp customer list          # See available names

---

Documentation

• MCP_SETUP.md - Client configuration
• ANALYTICS.md - Analytics engine guide
• CLAUDE.md - Development guide
• CHANGELOG.md - Version history
• docs/architecture/ - Technical architecture

---

License

Proprietary - See LICENSE for terms.