a4a1dd2e38
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>
443 lines
9.8 KiB
Markdown
443 lines
9.8 KiB
Markdown
# 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
|