svrnty/svrnty-mcp-gateway
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
7fe275f348
svrnty-mcp-gateway/docs/implementation-plan.md
Svrnty 19ef79362e refactor: rename OpenHarbor.MCP to Svrnty.MCP across all libraries 
- 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>
2025-10-22 21:04:17 -04:00

9.8 KiB
Raw Blame History

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