97880406dc
- 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>
400 lines
8.7 KiB
Markdown
400 lines
8.7 KiB
Markdown
# Svrnty.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 Svrnty.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
|
|
|