19ef79362e
- Renamed all directories: OpenHarbor.MCP.* → Svrnty.MCP.* - Updated all namespaces in 179 C# files - Renamed 20 .csproj files and 3 .sln files - Updated 193 documentation references - Updated 33 references in main CODEX codebase - Updated Codex.sln with new paths - Build verified: 0 errors Preparing for extraction to standalone repositories. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
443 lines
9.8 KiB
Markdown
443 lines
9.8 KiB
Markdown
# Svrnty.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 Svrnty.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
|