svrnty/svrnty-mcp-gateway
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
a4a1dd2e38
svrnty-mcp-gateway/docs/implementation-plan.md
Svrnty a4a1dd2e38 docs: comprehensive AI coding assistant research and MCP-first implementation plan 
Research conducted on modern AI coding assistants (Cursor, GitHub Copilot, Cline,
Aider, Windsurf, Replit Agent) to understand architecture patterns, context management,
code editing workflows, and tool use protocols.

Key Decision: Pivoted from building full CLI (40-50h) to validation-driven MCP-first
approach (10-15h). Build 5 core CODEX MCP tools that work with ANY coding assistant,
validate adoption over 2-4 weeks, then decide on full CLI if demand proven.

Files:
- research/ai-systems/modern-coding-assistants-architecture.md (comprehensive research)
- research/ai-systems/codex-coding-assistant-implementation-plan.md (original CLI plan, preserved)
- research/ai-systems/codex-mcp-tools-implementation-plan.md (approved MCP-first plan)
- ideas/registry.json (updated with approved MCP tools proposal)

Architech Validation: APPROVED with pivot to MCP-first approach
Human Decision: Approved (pragmatic validation-driven development)

Next: Begin Phase 1 implementation (10-15 hours, 5 core MCP tools)

🤖 Generated with CODEX Research System

Co-Authored-By: The Archivist <archivist@codex.svrnty.io>
Co-Authored-By: The Architech <architech@codex.svrnty.io>
Co-Authored-By: Mathias Beaulieu-Duncan <mat@svrnty.io>
2025-10-22 21:00:34 -04:00

9.8 KiB
Raw Blame History

OpenHarbor.MCP.Gateway - Implementation Plan

Document Type: Implementation Roadmap Status: Planned Version: 1.0.0 Last Updated: 2025-10-19

Overview

This document outlines the phased implementation plan for OpenHarbor.MCP.Gateway, following TDD principles and Clean Architecture.

Goals

  • Build production-ready MCP gateway library
  • Follow Clean Architecture patterns
  • Maintain >80% test coverage
  • Enable centralized routing and management of MCP traffic

Phase 1: Core Abstractions (2-3 days)

Goal

Establish foundation with interfaces, models, and abstractions.

Steps

Step 1.1: Core Models

  • Create ServerInfo model (server metadata)
  • Create ServerConfig model (server configuration)
  • Create RoutingContext model (routing metadata)
  • Create McpRequest/Response models
  • Create ServerHealthStatus model
  • Tests: Model validation, serialization

Step 1.2: Core Interfaces

  • Define IGatewayRouter interface
  • Define IRoutingStrategy interface
  • Define IAuthProvider interface
  • Define ICircuitBreaker interface
  • Define IServerConnection interface
  • Tests: Interface contracts (using mocks)

Step 1.3: Configuration Models

  • Create GatewayConfig
  • Create RoutingConfig
  • Create SecurityConfig
  • Create RateLimitConfig
  • Tests: Configuration validation

Exit Criteria

  • All core models defined
  • All core interfaces defined
  • Unit tests passing (target: 25+ tests)
  • Zero external dependencies in Core project

Phase 2: Infrastructure - Server Connections (3-4 days)

Goal

Implement connections to backend MCP servers.

Steps

Step 2.1: Transport Layer

  • Implement StdioServerTransport
  • Implement HttpServerTransport
  • Process lifecycle management
  • HTTP client configuration
  • Tests: Transport communication

Step 2.2: Server Connection

  • Implement ServerConnection class
  • Connection state management
  • Request/response handling
  • Timeout handling
  • Tests: Connection lifecycle

Step 2.3: Connection Pool

  • Implement ServerConnectionPool
  • Connection pooling per server
  • Idle connection eviction
  • Max connections enforcement
  • Tests: Pool behavior

Exit Criteria

  • Server connections functional
  • Connection pooling working
  • Unit tests passing (target: 40+ tests)
  • Integration tests with mock servers (target: 10+ tests)

Phase 3: Routing Implementation (3-4 days)

Goal

Implement routing strategies and gateway router.

Steps

Step 3.1: Routing Strategies

  • Implement RoundRobinStrategy
  • Implement ToolBasedStrategy
  • Implement ClientBasedStrategy
  • Implement WeightedStrategy (optional)
  • Tests: Strategy selection logic

Step 3.2: Gateway Router

  • Implement GatewayRouter class
  • Server registration/discovery
  • Route request to selected server
  • Response handling
  • Tests: Routing behavior

Step 3.3: Strategy Configuration

  • Strategy factory
  • Configuration-based strategy selection
  • Custom strategy registration
  • Tests: Strategy configuration

Exit Criteria

  • All routing strategies implemented
  • Gateway router functional
  • Unit tests passing (target: 50+ tests)
  • Integration tests with real servers (target: 15+ tests)

Phase 4: Health Monitoring (2-3 days)

Goal

Implement health checks and monitoring.

Steps

Step 4.1: Health Check Implementation

  • Implement ServerHealthChecker
  • Periodic health checks
  • Health status tracking
  • Tests: Health check behavior

Step 4.2: Circuit Breaker

  • Implement CircuitBreaker class
  • Failure tracking
  • Circuit state management
  • Half-open state handling
  • Tests: Circuit breaker state transitions

Step 4.3: Health Dashboard

  • ASP.NET Core health check integration
  • Health status endpoints
  • Metrics collection
  • Tests: Health endpoint behavior

Exit Criteria

  • Health monitoring functional
  • Circuit breaker working
  • Unit tests passing (target: 30+ tests)
  • Health endpoints operational

Phase 5: Security Layer (2-3 days)

Goal

Implement authentication, authorization, and rate limiting.

Steps

Step 5.1: Authentication

  • Implement ApiKeyAuthProvider
  • API key validation
  • Client identification
  • Tests: Authentication flows

Step 5.2: Authorization

  • Implement authorization rules
  • Role-based access control
  • Server-level permissions
  • Tool-level permissions
  • Tests: Authorization logic

Step 5.3: Rate Limiting

  • Implement rate limiter
  • Per-client rate limits
  • Global rate limits
  • Burst handling
  • Tests: Rate limit enforcement

Exit Criteria

  • Authentication working
  • Authorization functional
  • Rate limiting operational
  • Unit tests passing (target: 40+ tests)

Phase 6: ASP.NET Core Integration (2 days)

Goal

Provide HTTP endpoints and dependency injection support.

Steps

Step 6.1: DI Extensions

  • Create AddMcpGateway extension method
  • Service registration
  • Configuration binding
  • Tests: DI registration

Step 6.2: HTTP Endpoints

  • Implement gateway endpoint
  • Implement health endpoints
  • Implement management endpoints
  • Tests: Endpoint behavior

Step 6.3: Middleware

  • Authentication middleware
  • Rate limiting middleware
  • Audit logging middleware
  • Tests: Middleware integration

Exit Criteria

  • DI integration complete
  • HTTP endpoints working
  • Unit tests passing (target: 25+ tests)
  • Sample ASP.NET Core app working

Phase 7: CLI Tool (1-2 days)

Goal

Provide command-line interface for management.

Steps

Step 7.1: CLI Commands

  • gateway list-servers - List registered servers
  • gateway add-server <config> - Register server
  • gateway remove-server <id> - Unregister server
  • gateway health - Check server health
  • gateway route-test <tool> - Test routing
  • Tests: CLI command execution

Step 7.2: Configuration

  • Support for config file
  • Environment variable support
  • Interactive mode
  • Tests: Configuration loading

Exit Criteria

  • CLI functional for all operations
  • Integration tests passing (target: 10+ tests)
  • Documentation complete

Phase 8: Sample Application (1-2 days)

Goal

Create CodexMcpGateway sample demonstrating usage.

Steps

Step 8.1: Sample Project Setup

  • Create ASP.NET Core project
  • Configure to route to multiple servers
  • Validation: Successful routing

Step 8.2: Sample Routing Strategies

  • Implement custom routing strategy
  • Demonstrate tool-based routing
  • Demonstrate client-based routing
  • Validation: All strategies functional

Step 8.3: Sample Documentation

  • Usage examples
  • Configuration guide
  • Troubleshooting
  • Validation: Clear and complete

Exit Criteria

  • Sample app compiles and runs
  • All routing strategies demonstrated
  • Documentation complete

Phase 9: Documentation & Polish (1-2 days)

Goal

Finalize documentation and prepare for release.

Steps

Step 9.1: API Documentation

  • XML documentation comments
  • Generate API reference
  • Validation: Complete coverage

Step 9.2: User Guides

  • Getting Started guide
  • Configuration reference
  • Routing strategies guide
  • Security guide
  • Troubleshooting guide
  • Validation: User-friendly

Step 9.3: Code Quality

  • Run code analysis
  • Apply code formatting
  • Validation: Clean codebase

Exit Criteria

  • All documentation complete
  • Code analysis passes
  • Ready for use

Test Strategy

Unit Tests

  • Target: >80% coverage
  • Framework: xUnit + Moq
  • Pattern: AAA (Arrange-Act-Assert)
  • Focus: Core logic, edge cases, routing strategies

Integration Tests

  • Target: >70% coverage
  • Approach: Real MCP server connections
  • Focus: End-to-end routing, health checks, authentication

Load Tests

  • Focus: Gateway throughput and latency
  • Metrics: Requests per second, p95/p99 latency
  • Goal: <50ms average latency for routing decisions

Milestones

Phase Duration Test Target Milestone
Phase 1 2-3 days 25+ tests Core abstractions complete
Phase 2 3-4 days 40+ tests Server connections functional
Phase 3 3-4 days 50+ tests Routing strategies working
Phase 4 2-3 days 30+ tests Health monitoring operational
Phase 5 2-3 days 40+ tests Security layer complete
Phase 6 2 days 25+ tests ASP.NET Core integration
Phase 7 1-2 days 10+ tests CLI tool complete
Phase 8 1-2 days N/A Sample app functional
Phase 9 1-2 days N/A Documentation complete

Total Estimated Time: 17-26 days

Risk Mitigation

Risk: Server Failures

Mitigation:

  • Circuit breaker pattern implementation
  • Health monitoring with automatic failover
  • Retry logic with exponential backoff

Risk: Performance Bottlenecks

Mitigation:

  • Connection pooling from start
  • Performance testing in Phase 3
  • Caching of health check results

Risk: Security Vulnerabilities

Mitigation:

  • Input validation throughout
  • Rate limiting implementation
  • Audit logging of all requests
  • Regular security reviews

Dependencies

Required

  • .NET 8.0 SDK
  • System.Text.Json (built-in)
  • xUnit, Moq (testing)

Optional

  • Microsoft.Extensions.DependencyInjection
  • Microsoft.Extensions.Http
  • Microsoft.Extensions.Diagnostics.HealthChecks
  • Microsoft.AspNetCore.RateLimiting

Success Criteria

  • All phases complete
  • >80% test coverage (Core, Infrastructure)
  • >70% test coverage (AspNetCore)
  • Sample application working
  • Documentation complete
  • Zero critical bugs
  • Performance targets met (<50ms routing latency)
  • Security audit passed

Document Version: 1.0.0 Status: Planned Next Review: Before Phase 1 start