# OpenHarbor.MCP.Client - 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.Client, following TDD principles and Clean Architecture. ### Goals - Build production-ready MCP client library - Follow Clean Architecture patterns - Maintain >80% test coverage - Enable .NET applications to consume MCP servers --- ## Phase 1: Core Abstractions (2-3 days) ### Goal Establish foundation with interfaces, models, and abstractions. ### Steps #### Step 1.1: Core Models - Create `McpToolInfo` model (tool metadata) - Create `McpToolResult` model (execution results) - Create `McpServerInfo` model (server metadata) - Create `JsonRpcRequest/Response` models - **Tests**: Model validation, serialization #### Step 1.2: Core Interfaces - Define `IMcpClient` interface - Define `IMcpServerConnection` interface - Define `IMcpTransport` interface - Define `IConnectionPool` interface - **Tests**: Interface contracts (using mocks) #### Step 1.3: Configuration Models - Create `McpServerConfig` - Create `TransportConfig` - Create `ConnectionConfig` - **Tests**: Configuration validation ### Exit Criteria - [ ] All core models defined - [ ] All core interfaces defined - [ ] Unit tests passing (target: 20+ tests) - [ ] Zero external dependencies in Core project --- ## Phase 2: Infrastructure - Transport Layer (3-4 days) ### Goal Implement Stdio and HTTP transports. ### Steps #### Step 2.1: Base Transport Infrastructure - Create abstract `TransportBase` class - Implement JSON-RPC serialization/deserialization - Implement timeout handling - **Tests**: Serialization, timeout behavior #### Step 2.2: Stdio Transport - Implement `StdioTransport` - Process lifecycle management (spawn, monitor, dispose) - Stdin/stdout communication - Stderr logging - **Tests**: Process communication, error handling #### Step 2.3: HTTP Transport - Implement `HttpTransport` - HttpClient integration - Header management - HTTPS support - **Tests**: HTTP communication, authentication #### Step 2.4: Transport Factory - Create `TransportFactory` for creating transports by type - Support for custom transports - **Tests**: Factory pattern validation ### Exit Criteria - [ ] HTTP transport functional - [ ] HTTP transport functional - [ ] Unit tests passing (target: 40+ tests) - [ ] Integration tests with mock servers (target: 10+ tests) --- ## Phase 3: Connection Management (2-3 days) ### Goal Implement connection pooling and lifecycle management. ### Steps #### Step 3.1: Server Connection Implementation - Implement `McpServerConnection` - Connection state management - Reconnection logic - **Tests**: Connection lifecycle #### Step 3.2: Connection Pool - Implement `ConnectionPool` - Acquire/release mechanism - Idle connection eviction - Max connections enforcement - **Tests**: Pool behavior, eviction #### Step 3.3: Retry Logic - Implement `RetryPolicy` - Exponential backoff - Configurable retry limits - **Tests**: Retry scenarios ### Exit Criteria - [ ] Connection pooling working - [ ] Retry logic functional - [ ] Unit tests passing (target: 30+ tests) - [ ] No connection leaks --- ## Phase 4: MCP Client Implementation (3-4 days) ### Goal Implement main `McpClient` class. ### Steps #### Step 4.1: Client Core - Implement `McpClient` class - Server registration/discovery - Connection management - **Tests**: Client initialization #### Step 4.2: Tool Discovery - Implement `ListToolsAsync` - Tool caching (optional) - **Tests**: Tool discovery, caching #### Step 4.3: Tool Execution - Implement `CallToolAsync` - Argument validation - Response handling - **Tests**: Tool execution, error handling #### Step 4.4: Health Monitoring - Implement `PingAsync` - Connection health tracking - **Tests**: Health check behavior ### Exit Criteria - [ ] All IMcpClient methods implemented - [ ] Unit tests passing (target: 50+ tests) - [ ] Integration tests with real MCP servers (target: 15+ tests) --- ## Phase 5: ASP.NET Core Integration (2 days) ### Goal Provide dependency injection and configuration support. ### Steps #### Step 5.1: DI Extensions - Create `AddMcpClient` extension method - Service registration - Configuration binding - **Tests**: DI registration #### Step 5.2: Health Checks - Implement MCP health check - ASP.NET Core health check integration - **Tests**: Health check endpoints #### Step 5.3: Hosted Service (Optional) - Background service for auto-connecting to servers - Periodic health monitoring - **Tests**: Hosted service lifecycle ### Exit Criteria - [ ] DI integration complete - [ ] Health checks working - [ ] Unit tests passing (target: 20+ tests) - [ ] Sample ASP.NET Core app working --- ## Phase 6: CLI Tool (1-2 days) ### Goal Provide command-line interface for testing and debugging. ### Steps #### Step 6.1: CLI Commands - `mcp connect ` - Connect to server - `mcp list-tools ` - List available tools - `mcp call-tool ` - Call tool - `mcp ping ` - Health check - **Tests**: CLI command execution #### Step 6.2: Configuration - Support for config file (appsettings.json) - Environment variable support - **Tests**: Configuration loading ### Exit Criteria - [ ] CLI functional for all operations - [ ] Integration tests passing (target: 10+ tests) - [ ] Documentation complete --- ## Phase 7: Sample Application (1-2 days) ### Goal Create CodexMcpClient sample demonstrating usage. ### Steps #### Step 7.1: Sample Project Setup - Create console/web app project - Configure to connect to CODEX MCP Server - **Validation**: Successful connection #### Step 7.2: Sample Services - Implement `CodexSearchService` - Implement `DocumentService` - Implement `TagService` - **Validation**: All services functional #### Step 7.3: Sample Documentation - Usage examples - Configuration guide - Troubleshooting - **Validation**: Clear and complete ### Exit Criteria - [ ] Sample app compiles and runs - [ ] All sample services work - [ ] Documentation complete --- ## Phase 8: Documentation & Polish (1-2 days) ### Goal Finalize documentation and prepare for release. ### Steps #### Step 8.1: API Documentation - XML documentation comments - Generate API reference - **Validation**: Complete coverage #### Step 8.2: User Guides - Getting Started guide - Configuration reference - Troubleshooting guide - **Validation**: User-friendly #### Step 8.3: Code Quality - Run code analysis - Apply code formatting - Review TODOs - **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 ### Integration Tests - **Target**: >70% coverage - **Approach**: Real MCP server connections - **Focus**: End-to-end workflows ### Performance Tests - **Focus**: Connection pooling efficiency - **Metrics**: Requests per second, latency - **Goal**: <100ms average latency --- ## Milestones | Phase | Duration | Test Target | Milestone | |-------|----------|-------------|-----------| | Phase 1 | 2-3 days | 20+ tests | Core abstractions complete | | Phase 2 | 3-4 days | 40+ tests | Transport layer functional | | Phase 3 | 2-3 days | 30+ tests | Connection pooling working | | Phase 4 | 3-4 days | 50+ tests | MCP client fully functional | | Phase 5 | 2 days | 20+ tests | ASP.NET Core integration | | Phase 6 | 1-2 days | 10+ tests | CLI tool complete | | Phase 7 | 1-2 days | N/A | Sample app functional | | Phase 8 | 1-2 days | N/A | Documentation complete | **Total Estimated Time**: 14-22 days --- ## Risk Mitigation ### Risk: MCP Protocol Changes **Mitigation**: - Abstract protocol details behind interfaces - Version protocol implementation - Test against multiple MCP servers ### Risk: Connection Reliability **Mitigation**: - Comprehensive retry logic - Connection health monitoring - Circuit breaker pattern (Phase 9+) ### Risk: Performance Issues **Mitigation**: - Connection pooling from start - Performance testing in Phase 4 - Profiling and optimization phase if needed --- ## Dependencies ### Required - .NET 8.0 SDK - System.Text.Json (built-in) - xUnit, Moq (testing) ### Optional - Microsoft.Extensions.DependencyInjection - Microsoft.Extensions.Http - Microsoft.Extensions.Hosting --- ## 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 --- **Document Version:** 1.0.0 **Status:** Planned **Next Review:** Before Phase 1 start