# ADR-039: V3 QE MCP Optimization

**Status**: Proposed
**Date**: 2026-01-11
**Author**: Claude Code

## Context

The existing `v3-qe-mcp` skill provides basic MCP tool definitions but lacks the performance optimizations from `v3-mcp-optimization`. Current issues include:

1. No connection pooling - new connections per request
2. Linear O(n) tool lookup across 20+ QE tools
3. No load balancing for fleet operations
4. High response latency (often >200ms)
5. No performance monitoring

## Decision

Create an enhanced `v3-qe-mcp-optimization` skill that implements:

1. **Connection Pooling**
   - Pre-warmed connection pool
   - Connection reuse for QE tools
   - Health-checked connections

2. **O(1) Tool Lookup**
   - Hash-indexed tool registry
   - LRU cache for hot tools
   - Fuzzy matching for typos

3. **Load Balancing**
   - Least-connections routing
   - Response-time weighted selection
   - Agent capacity awareness

4. **Performance Targets**
   - <100ms p95 response time
   - >90% connection pool hit rate
   - <5ms tool lookup time

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                V3 QE MCP Optimized Server                    │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌─────────────────────────────────────────────────────┐    │
│  │               Connection Pool                        │    │
│  │  • 50 max connections                               │    │
│  │  • 5 min pre-warmed                                 │    │
│  │  • 300s idle timeout                                │    │
│  │  • Health checks every 30s                          │    │
│  └─────────────────────────────────────────────────────┘    │
│                         │                                    │
│  ┌──────────────────────┼──────────────────────────────┐    │
│  │               Fast Tool Registry                     │    │
│  │  • Hash index: O(1) lookup                          │    │
│  │  • Category index: domain grouping                  │    │
│  │  • LRU cache: 1000 entries                          │    │
│  │  • Fuzzy matcher: typo tolerance                    │    │
│  └─────────────────────────────────────────────────────┘    │
│                         │                                    │
│  ┌──────────────────────┼──────────────────────────────┐    │
│  │               Load Balancer                          │    │
│  │  • Least-connections strategy                       │    │
│  │  • Response-time weighted                           │    │
│  │  • Agent capacity aware                             │    │
│  └─────────────────────────────────────────────────────┘    │
│                                                              │
└─────────────────────────────────────────────────────────────┘
```

## QE MCP Tools (Optimized)

| Tool | Category | Target Latency |
|------|----------|----------------|
| qe_test_generate | test-generation | <500ms |
| qe_coverage_analyze | coverage-analysis | <200ms |
| qe_coverage_gaps | coverage-analysis | <100ms |
| qe_quality_gate | quality-assessment | <100ms |
| qe_quality_metrics | quality-assessment | <50ms |
| qe_fleet_init | coordination | <200ms |
| qe_fleet_status | coordination | <50ms |
| qe_agent_spawn | coordination | <100ms |
| qe_task_orchestrate | coordination | <150ms |
| qe_memory_store | memory | <20ms |
| qe_memory_retrieve | memory | <10ms |
| qe_memory_search | memory | <50ms |
| qe_learn_pattern | learning | <100ms |
| qe_learn_status | learning | <30ms |

## Performance Configuration

```typescript
const QE_MCP_CONFIG: OptimizedMCPConfig = {
  // Connection pooling
  maxConnections: 50,
  minConnections: 5,
  idleTimeoutMs: 300000, // 5 minutes
  connectionReuseEnabled: true,

  // Tool registry
  toolCacheEnabled: true,
  toolCacheSize: 1000,
  toolIndexType: 'hash',

  // Performance
  requestTimeoutMs: 5000,
  batchingEnabled: true,
  batchSize: 10,
  batchTimeoutMs: 10,

  // Monitoring
  metricsEnabled: true,
  healthCheckIntervalMs: 30000,
  performanceTargets: {
    p95ResponseTime: 100, // ms
    poolHitRate: 0.9,
    toolLookupTime: 5 // ms
  }
};
```

## Performance Targets

| Metric | Current | Target | Improvement |
|--------|---------|--------|-------------|
| p95 Response Time | ~250ms | <100ms | 2.5x |
| Tool Lookup | ~15ms (linear) | <5ms (hash) | 3x |
| Pool Hit Rate | 0% (no pool) | >90% | ∞ |
| Startup Time | ~1.8s | <400ms | 4.5x |
| Memory Usage | ~150MB | ~75MB | 50% |

## Monitoring Dashboard

```typescript
const qeMCPDashboard = {
  metrics: [
    'qe_mcp_request_latency_p50',
    'qe_mcp_request_latency_p95',
    'qe_mcp_request_latency_p99',
    'qe_mcp_pool_hit_rate',
    'qe_mcp_pool_utilization',
    'qe_mcp_tool_lookup_time',
    'qe_mcp_error_rate',
    'qe_mcp_requests_per_second'
  ],
  alerts: [
    { metric: 'p95_response_time', threshold: 200, window: '5m' },
    { metric: 'error_rate', threshold: 0.05, window: '1m' },
    { metric: 'pool_hit_rate', threshold: 0.7, window: '10m' }
  ]
};
```

## Consequences

### Positive
- 2.5x faster p95 response times
- Reduced server load via connection reuse
- Better fleet operation throughput
- Real-time performance visibility

### Negative
- Additional complexity in MCP server
- Memory overhead for connection pool
- Monitoring infrastructure required

### Mitigation
- Graceful degradation to single connections
- Configurable pool sizes
- Lightweight metrics collection

## Related ADRs

- ADR-037: V3 QE Agent Naming
- ADR-038: V3 QE Memory Unification
- v3-mcp-optimization (claude-flow)