d936ad7856
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>
400 lines
8.7 KiB
Markdown
400 lines
8.7 KiB
Markdown
# 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 <server>` - Connect to server
|
|
- `mcp list-tools <server>` - List available tools
|
|
- `mcp call-tool <server> <tool> <args>` - Call tool
|
|
- `mcp ping <server>` - 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
|
|
|