monomind 1.6.0 → 1.6.1

package/.claude/skills/v3-mcp-optimization/SKILL.md

@@ -1,816 +0,0 @@
----
-name: "v1 MCP Optimization"
-description: "MCP server optimization and transport layer enhancement for monomind v1. Implements connection pooling, load balancing, tool registry optimization, and performance monitoring for sub-100ms response times."
----
-
-# MCP Optimization
-
-## What This Skill Does
-
-Optimizes monomind v1 MCP (Model Context Protocol) server implementation with advanced transport layer optimizations, connection pooling, load balancing, and comprehensive performance monitoring to achieve sub-100ms response times.
-
-## Quick Start
-
-```bash
-# Initialize MCP optimization analysis
-Task("MCP architecture", "Analyze current MCP server performance and bottlenecks", "mcp-specialist")
-
-# Optimization implementation (parallel)
-Task("Connection pooling", "Implement MCP connection pooling and reuse", "mcp-specialist")
-Task("Load balancing", "Add dynamic load balancing for MCP tools", "mcp-specialist")
-Task("Transport optimization", "Optimize transport layer performance", "mcp-specialist")
-```
-
-## MCP Performance Architecture
-
-### Current State Analysis
-
-```
-Current MCP Issues:
-├── Cold Start Latency: ~1.8s MCP server init
-├── Connection Overhead: New connection per request
-├── Tool Registry: Linear search O(n) for 213+ tools
-├── Transport Layer: No connection reuse
-└── Memory Usage: No cleanup of idle connections
-
-Target Performance:
-├── Startup Time: <400ms (4.5x improvement)
-├── Tool Lookup: <5ms (O(1) hash table)
-├── Connection Reuse: 90%+ connection pool hits
-├── Response Time: <100ms p95
-└── Memory Efficiency: 50% reduction
-```
-
-### MCP Server Architecture
-
-```typescript
-// src/core/mcp/mcp-server.ts
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-
-interface OptimizedMCPConfig {
-  // Connection pooling
-  maxConnections: number;
-  idleTimeoutMs: number;
-  connectionReuseEnabled: boolean;
-
-  // Tool registry
-  toolCacheEnabled: boolean;
-  toolIndexType: "hash" | "trie";
-
-  // Performance
-  requestTimeoutMs: number;
-  batchingEnabled: boolean;
-  compressionEnabled: boolean;
-
-  // Monitoring
-  metricsEnabled: boolean;
-  healthCheckIntervalMs: number;
-}
-
-export class OptimizedMCPServer {
-  private server: Server;
-  private connectionPool: ConnectionPool;
-  private toolRegistry: FastToolRegistry;
-  private loadBalancer: MCPLoadBalancer;
-  private metrics: MCPMetrics;
-
-  constructor(config: OptimizedMCPConfig) {
-    this.server = new Server(
-      {
-        name: "monomind-v1",
-        version: "3.0.0",
-      },
-      {
-        capabilities: {
-          tools: { listChanged: true },
-          resources: { subscribe: true, listChanged: true },
-          prompts: { listChanged: true },
-        },
-      },
-    );
-
-    this.connectionPool = new ConnectionPool(config);
-    this.toolRegistry = new FastToolRegistry(config.toolIndexType);
-    this.loadBalancer = new MCPLoadBalancer();
-    this.metrics = new MCPMetrics(config.metricsEnabled);
-  }
-
-  async start(): Promise<void> {
-    // Pre-warm connection pool
-    await this.connectionPool.preWarm();
-
-    // Pre-build tool index
-    await this.toolRegistry.buildIndex();
-
-    // Setup request handlers with optimizations
-    this.setupOptimizedHandlers();
-
-    // Start health monitoring
-    this.startHealthMonitoring();
-
-    // Start server
-    const transport = new StdioServerTransport();
-    await this.server.connect(transport);
-
-    this.metrics.recordStartup();
-  }
-}
-```
-
-## Connection Pool Implementation
-
-### Advanced Connection Pooling
-
-```typescript
-// src/core/mcp/connection-pool.ts
-interface PooledConnection {
-  id: string;
-  connection: MCPConnection;
-  lastUsed: number;
-  usageCount: number;
-  isHealthy: boolean;
-}
-
-export class ConnectionPool {
-  private pool: Map<string, PooledConnection> = new Map();
-  private readonly config: ConnectionPoolConfig;
-  private healthChecker: HealthChecker;
-
-  constructor(config: ConnectionPoolConfig) {
-    this.config = {
-      maxConnections: 50,
-      minConnections: 5,
-      idleTimeoutMs: 300000, // 5 minutes
-      maxUsageCount: 1000,
-      healthCheckIntervalMs: 30000,
-      ...config,
-    };
-
-    this.healthChecker = new HealthChecker(this.config.healthCheckIntervalMs);
-  }
-
-  async getConnection(endpoint: string): Promise<MCPConnection> {
-    const start = performance.now();
-
-    // Try to get from pool first
-    const pooled = this.findAvailableConnection(endpoint);
-    if (pooled) {
-      pooled.lastUsed = Date.now();
-      pooled.usageCount++;
-
-      this.recordMetric("pool_hit", performance.now() - start);
-      return pooled.connection;
-    }
-
-    // Check pool capacity
-    if (this.pool.size >= this.config.maxConnections) {
-      await this.evictLeastUsedConnection();
-    }
-
-    // Create new connection
-    const connection = await this.createConnection(endpoint);
-    const pooledConn: PooledConnection = {
-      id: this.generateConnectionId(),
-      connection,
-      lastUsed: Date.now(),
-      usageCount: 1,
-      isHealthy: true,
-    };
-
-    this.pool.set(pooledConn.id, pooledConn);
-    this.recordMetric("pool_miss", performance.now() - start);
-
-    return connection;
-  }
-
-  async releaseConnection(connection: MCPConnection): Promise<void> {
-    // Mark connection as available for reuse
-    const pooled = this.findConnectionById(connection.id);
-    if (pooled) {
-      // Check if connection should be retired
-      if (pooled.usageCount >= this.config.maxUsageCount) {
-        await this.removeConnection(pooled.id);
-      }
-    }
-  }
-
-  async preWarm(): Promise<void> {
-    const connections: Promise<MCPConnection>[] = [];
-
-    for (let i = 0; i < this.config.minConnections; i++) {
-      connections.push(this.createConnection("default"));
-    }
-
-    await Promise.all(connections);
-  }
-
-  private async evictLeastUsedConnection(): Promise<void> {
-    let oldestConn: PooledConnection | null = null;
-    let oldestTime = Date.now();
-
-    for (const conn of this.pool.values()) {
-      if (conn.lastUsed < oldestTime) {
-        oldestTime = conn.lastUsed;
-        oldestConn = conn;
-      }
-    }
-
-    if (oldestConn) {
-      await this.removeConnection(oldestConn.id);
-    }
-  }
-
-  private findAvailableConnection(endpoint: string): PooledConnection | null {
-    for (const conn of this.pool.values()) {
-      if (
-        conn.isHealthy &&
-        conn.connection.endpoint === endpoint &&
-        Date.now() - conn.lastUsed < this.config.idleTimeoutMs
-      ) {
-        return conn;
-      }
-    }
-    return null;
-  }
-}
-```
-
-## Fast Tool Registry
-
-### O(1) Tool Lookup Implementation
-
-```typescript
-// src/core/mcp/fast-tool-registry.ts
-interface ToolIndexEntry {
-  name: string;
-  handler: ToolHandler;
-  metadata: ToolMetadata;
-  usageCount: number;
-  avgLatencyMs: number;
-}
-
-export class FastToolRegistry {
-  private toolIndex: Map<string, ToolIndexEntry> = new Map();
-  private categoryIndex: Map<string, string[]> = new Map();
-  private fuzzyMatcher: FuzzyMatcher;
-  private cache: LRUCache<string, ToolIndexEntry>;
-
-  constructor(indexType: "hash" | "trie" = "hash") {
-    this.fuzzyMatcher = new FuzzyMatcher();
-    this.cache = new LRUCache<string, ToolIndexEntry>(1000); // Cache 1000 most used tools
-  }
-
-  async buildIndex(): Promise<void> {
-    const start = performance.now();
-
-    // Load all available tools
-    const tools = await this.loadAllTools();
-
-    // Build hash index for O(1) lookup
-    for (const tool of tools) {
-      const entry: ToolIndexEntry = {
-        name: tool.name,
-        handler: tool.handler,
-        metadata: tool.metadata,
-        usageCount: 0,
-        avgLatencyMs: 0,
-      };
-
-      this.toolIndex.set(tool.name, entry);
-
-      // Build category index
-      const category = tool.metadata.category || "general";
-      if (!this.categoryIndex.has(category)) {
-        this.categoryIndex.set(category, []);
-      }
-      this.categoryIndex.get(category)!.push(tool.name);
-    }
-
-    // Build fuzzy search index
-    await this.fuzzyMatcher.buildIndex(tools.map((t) => t.name));
-
-    console.log(
-      `Tool index built in ${(performance.now() - start).toFixed(2)}ms for ${tools.length} tools`,
-    );
-  }
-
-  findTool(name: string): ToolIndexEntry | null {
-    // Try cache first
-    const cached = this.cache.get(name);
-    if (cached) return cached;
-
-    // Try exact match
-    const exact = this.toolIndex.get(name);
-    if (exact) {
-      this.cache.set(name, exact);
-      return exact;
-    }
-
-    // Try fuzzy match
-    const fuzzyMatches = this.fuzzyMatcher.search(name, 1);
-    if (fuzzyMatches.length > 0) {
-      const match = this.toolIndex.get(fuzzyMatches[0]);
-      if (match) {
-        this.cache.set(name, match);
-        return match;
-      }
-    }
-
-    return null;
-  }
-
-  findToolsByCategory(category: string): ToolIndexEntry[] {
-    const toolNames = this.categoryIndex.get(category) || [];
-    return toolNames
-      .map((name) => this.toolIndex.get(name))
-      .filter((entry) => entry !== undefined) as ToolIndexEntry[];
-  }
-
-  getMostUsedTools(limit: number = 10): ToolIndexEntry[] {
-    return Array.from(this.toolIndex.values())
-      .sort((a, b) => b.usageCount - a.usageCount)
-      .slice(0, limit);
-  }
-
-  recordToolUsage(toolName: string, latencyMs: number): void {
-    const entry = this.toolIndex.get(toolName);
-    if (entry) {
-      entry.usageCount++;
-      // Moving average for latency
-      entry.avgLatencyMs = (entry.avgLatencyMs + latencyMs) / 2;
-    }
-  }
-}
-```
-
-## Load Balancing & Request Distribution
-
-### Intelligent Load Balancer
-
-```typescript
-// src/core/mcp/load-balancer.ts
-interface ServerInstance {
-  id: string;
-  endpoint: string;
-  load: number;
-  responseTime: number;
-  isHealthy: boolean;
-  maxConnections: number;
-  currentConnections: number;
-}
-
-export class MCPLoadBalancer {
-  private servers: Map<string, ServerInstance> = new Map();
-  private routingStrategy: RoutingStrategy = "least-connections";
-
-  addServer(server: ServerInstance): void {
-    this.servers.set(server.id, server);
-  }
-
-  selectServer(toolCategory?: string): ServerInstance | null {
-    const healthyServers = Array.from(this.servers.values()).filter(
-      (server) => server.isHealthy,
-    );
-
-    if (healthyServers.length === 0) return null;
-
-    switch (this.routingStrategy) {
-      case "round-robin":
-        return this.roundRobinSelection(healthyServers);
-
-      case "least-connections":
-        return this.leastConnectionsSelection(healthyServers);
-
-      case "response-time":
-        return this.responseTimeSelection(healthyServers);
-
-      case "weighted":
-        return this.weightedSelection(healthyServers, toolCategory);
-
-      default:
-        return healthyServers[0];
-    }
-  }
-
-  private leastConnectionsSelection(servers: ServerInstance[]): ServerInstance {
-    return servers.reduce((least, current) =>
-      current.currentConnections < least.currentConnections ? current : least,
-    );
-  }
-
-  private responseTimeSelection(servers: ServerInstance[]): ServerInstance {
-    return servers.reduce((fastest, current) =>
-      current.responseTime < fastest.responseTime ? current : fastest,
-    );
-  }
-
-  private weightedSelection(
-    servers: ServerInstance[],
-    category?: string,
-  ): ServerInstance {
-    // Prefer servers with lower load and better response time
-    const scored = servers.map((server) => ({
-      server,
-      score: this.calculateServerScore(server, category),
-    }));
-
-    scored.sort((a, b) => b.score - a.score);
-    return scored[0].server;
-  }
-
-  private calculateServerScore(
-    server: ServerInstance,
-    category?: string,
-  ): number {
-    const loadFactor = 1 - server.currentConnections / server.maxConnections;
-    const responseFactor = 1 / (server.responseTime + 1);
-    const categoryBonus = this.getCategoryBonus(server, category);
-
-    return loadFactor * 0.4 + responseFactor * 0.4 + categoryBonus * 0.2;
-  }
-
-  updateServerMetrics(
-    serverId: string,
-    metrics: Partial<ServerInstance>,
-  ): void {
-    const server = this.servers.get(serverId);
-    if (server) {
-      Object.assign(server, metrics);
-    }
-  }
-}
-```
-
-## Transport Layer Optimization
-
-### High-Performance Transport
-
-```typescript
-// src/core/mcp/optimized-transport.ts
-export class OptimizedTransport {
-  private compression: boolean = true;
-  private batching: boolean = true;
-  private batchBuffer: MCPMessage[] = [];
-  private batchTimeout: NodeJS.Timeout | null = null;
-
-  constructor(private config: TransportConfig) {}
-
-  async send(message: MCPMessage): Promise<void> {
-    if (this.batching && this.canBatch(message)) {
-      this.addToBatch(message);
-      return;
-    }
-
-    await this.sendImmediate(message);
-  }
-
-  private async sendImmediate(message: MCPMessage): Promise<void> {
-    const start = performance.now();
-
-    // Compress if enabled
-    const payload = this.compression ? await this.compress(message) : message;
-
-    // Send through transport
-    await this.transport.send(payload);
-
-    // Record metrics
-    this.recordLatency(performance.now() - start);
-  }
-
-  private addToBatch(message: MCPMessage): void {
-    this.batchBuffer.push(message);
-
-    // Start batch timeout if not already running
-    if (!this.batchTimeout) {
-      this.batchTimeout = setTimeout(
-        () => this.flushBatch(),
-        this.config.batchTimeoutMs || 10,
-      );
-    }
-
-    // Flush if batch is full
-    if (this.batchBuffer.length >= this.config.maxBatchSize) {
-      this.flushBatch();
-    }
-  }
-
-  private async flushBatch(): Promise<void> {
-    if (this.batchBuffer.length === 0) return;
-
-    const batch = this.batchBuffer.splice(0);
-    this.batchTimeout = null;
-
-    // Send as single batched message
-    await this.sendImmediate({
-      type: "batch",
-      messages: batch,
-    });
-  }
-
-  private canBatch(message: MCPMessage): boolean {
-    // Don't batch urgent messages or responses
-    return (
-      message.type !== "response" &&
-      message.priority !== "high" &&
-      message.type !== "error"
-    );
-  }
-
-  private async compress(data: any): Promise<Buffer> {
-    // Use fast compression for smaller messages
-    return gzipSync(JSON.stringify(data));
-  }
-}
-```
-
-## Performance Monitoring
-
-### Real-time MCP Metrics
-
-```typescript
-// src/core/mcp/metrics.ts
-interface MCPMetrics {
-  requestCount: number;
-  errorCount: number;
-  avgResponseTime: number;
-  p95ResponseTime: number;
-  connectionPoolHits: number;
-  connectionPoolMisses: number;
-  toolLookupTime: number;
-  startupTime: number;
-}
-
-export class MCPMetricsCollector {
-  private metrics: MCPMetrics;
-  private responseTimeBuffer: number[] = [];
-  private readonly bufferSize = 1000;
-
-  constructor() {
-    this.metrics = this.createInitialMetrics();
-  }
-
-  recordRequest(latencyMs: number): void {
-    this.metrics.requestCount++;
-    this.updateResponseTimes(latencyMs);
-  }
-
-  recordError(): void {
-    this.metrics.errorCount++;
-  }
-
-  recordConnectionPoolHit(): void {
-    this.metrics.connectionPoolHits++;
-  }
-
-  recordConnectionPoolMiss(): void {
-    this.metrics.connectionPoolMisses++;
-  }
-
-  recordToolLookup(latencyMs: number): void {
-    this.metrics.toolLookupTime = this.updateMovingAverage(
-      this.metrics.toolLookupTime,
-      latencyMs,
-    );
-  }
-
-  recordStartup(latencyMs: number): void {
-    this.metrics.startupTime = latencyMs;
-  }
-
-  getMetrics(): MCPMetrics {
-    return { ...this.metrics };
-  }
-
-  getHealthStatus(): HealthStatus {
-    const errorRate = this.metrics.errorCount / this.metrics.requestCount;
-    const poolHitRate =
-      this.metrics.connectionPoolHits /
-      (this.metrics.connectionPoolHits + this.metrics.connectionPoolMisses);
-
-    return {
-      status: this.determineHealthStatus(errorRate, poolHitRate),
-      errorRate,
-      poolHitRate,
-      avgResponseTime: this.metrics.avgResponseTime,
-      p95ResponseTime: this.metrics.p95ResponseTime,
-    };
-  }
-
-  private updateResponseTimes(latency: number): void {
-    this.responseTimeBuffer.push(latency);
-
-    if (this.responseTimeBuffer.length > this.bufferSize) {
-      this.responseTimeBuffer.shift();
-    }
-
-    this.metrics.avgResponseTime = this.calculateAverage(
-      this.responseTimeBuffer,
-    );
-    this.metrics.p95ResponseTime = this.calculatePercentile(
-      this.responseTimeBuffer,
-      95,
-    );
-  }
-
-  private calculatePercentile(arr: number[], percentile: number): number {
-    const sorted = arr.slice().sort((a, b) => a - b);
-    const index = Math.ceil((percentile / 100) * sorted.length) - 1;
-    return sorted[index] || 0;
-  }
-
-  private determineHealthStatus(
-    errorRate: number,
-    poolHitRate: number,
-  ): "healthy" | "warning" | "critical" {
-    if (errorRate > 0.1 || poolHitRate < 0.5) return "critical";
-    if (errorRate > 0.05 || poolHitRate < 0.7) return "warning";
-    return "healthy";
-  }
-}
-```
-
-## Tool Registry Optimization
-
-### Pre-compiled Tool Index
-
-```typescript
-// src/core/mcp/tool-precompiler.ts
-export class ToolPrecompiler {
-  async precompileTools(): Promise<CompiledToolRegistry> {
-    const tools = await this.loadAllTools();
-
-    // Create optimized lookup structures
-    const nameIndex = new Map<string, Tool>();
-    const categoryIndex = new Map<string, Tool[]>();
-    const fuzzyIndex = new Map<string, string[]>();
-
-    for (const tool of tools) {
-      // Exact name index
-      nameIndex.set(tool.name, tool);
-
-      // Category index
-      const category = tool.metadata.category || "general";
-      if (!categoryIndex.has(category)) {
-        categoryIndex.set(category, []);
-      }
-      categoryIndex.get(category)!.push(tool);
-
-      // Pre-compute fuzzy variations
-      const variations = this.generateFuzzyVariations(tool.name);
-      for (const variation of variations) {
-        if (!fuzzyIndex.has(variation)) {
-          fuzzyIndex.set(variation, []);
-        }
-        fuzzyIndex.get(variation)!.push(tool.name);
-      }
-    }
-
-    return {
-      nameIndex,
-      categoryIndex,
-      fuzzyIndex,
-      totalTools: tools.length,
-      compiledAt: new Date(),
-    };
-  }
-
-  private generateFuzzyVariations(name: string): string[] {
-    const variations: string[] = [];
-
-    // Common typos and abbreviations
-    variations.push(name.toLowerCase());
-    variations.push(name.replace(/[-_]/g, ""));
-    variations.push(name.replace(/[aeiou]/gi, "")); // Consonants only
-
-    // Add more fuzzy matching logic as needed
-
-    return variations;
-  }
-}
-```
-
-## Advanced Caching Strategy
-
-### Multi-Level Caching
-
-```typescript
-// src/core/mcp/multi-level-cache.ts
-export class MultiLevelCache {
-  private l1Cache: Map<string, any> = new Map(); // In-memory, fastest
-  private l2Cache: LRUCache<string, any>; // LRU cache, larger capacity
-  private l3Cache: DiskCache; // Persistent disk cache
-
-  constructor(config: CacheConfig) {
-    this.l2Cache = new LRUCache<string, any>({
-      max: config.l2MaxEntries || 10000,
-      ttl: config.l2TTL || 300000, // 5 minutes
-    });
-
-    this.l3Cache = new DiskCache(config.l3Path || "./.cache/mcp");
-  }
-
-  async get(key: string): Promise<any | null> {
-    // Try L1 cache first (fastest)
-    if (this.l1Cache.has(key)) {
-      return this.l1Cache.get(key);
-    }
-
-    // Try L2 cache
-    const l2Value = this.l2Cache.get(key);
-    if (l2Value) {
-      // Promote to L1
-      this.l1Cache.set(key, l2Value);
-      return l2Value;
-    }
-
-    // Try L3 cache (disk)
-    const l3Value = await this.l3Cache.get(key);
-    if (l3Value) {
-      // Promote to L2 and L1
-      this.l2Cache.set(key, l3Value);
-      this.l1Cache.set(key, l3Value);
-      return l3Value;
-    }
-
-    return null;
-  }
-
-  async set(key: string, value: any, options?: CacheOptions): Promise<void> {
-    // Set in all levels
-    this.l1Cache.set(key, value);
-    this.l2Cache.set(key, value);
-
-    if (options?.persistent) {
-      await this.l3Cache.set(key, value);
-    }
-
-    // Manage L1 cache size
-    if (this.l1Cache.size > 1000) {
-      const firstKey = this.l1Cache.keys().next().value;
-      this.l1Cache.delete(firstKey);
-    }
-  }
-}
-```
-
-## Success Metrics
-
-### Performance Targets
-
-- [ ] **Startup Time**: <400ms MCP server initialization (4.5x improvement)
-- [ ] **Response Time**: <100ms p95 for tool execution
-- [ ] **Tool Lookup**: <5ms average lookup time
-- [ ] **Connection Pool**: >90% hit rate
-- [ ] **Memory Usage**: 50% reduction in idle memory
-- [ ] **Error Rate**: <1% failed requests
-- [ ] **Throughput**: >1000 requests/second
-
-### Monitoring Dashboards
-
-```typescript
-const mcpDashboard = {
-  metrics: [
-    "Request latency (p50, p95, p99)",
-    "Error rate by tool category",
-    "Connection pool utilization",
-    "Tool lookup performance",
-    "Memory usage trends",
-    "Cache hit rates (L1, L2, L3)",
-  ],
-
-  alerts: [
-    "Response time >200ms for 5 minutes",
-    "Error rate >5% for 1 minute",
-    "Pool hit rate <70% for 10 minutes",
-    "Memory usage >500MB for 5 minutes",
-  ],
-};
-```
-
-## Related v1 Skills
-
-- `v1-core-implementation` - Core domain integration with MCP
-- `v1-performance-optimization` - Overall performance optimization
-- `v1-swarm-coordination` - MCP integration with swarm coordination
-- `v1-memory-unification` - Memory sharing via MCP tools
-
-## Usage Examples
-
-### Complete MCP Optimization
-
-```bash
-# Full MCP server optimization
-Task("MCP optimization implementation",
-     "Implement all MCP performance optimizations with monitoring",
-     "mcp-specialist")
-```
-
-### Specific Optimization
-
-```bash
-# Connection pool optimization
-Task("MCP connection pooling",
-     "Implement advanced connection pooling with health monitoring",
-     "mcp-specialist")
-```