svrnty/svrnty-mcp-client
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
d936ad7856
svrnty-mcp-client/docs/implementation-plan.md
Svrnty d936ad7856 docs: comprehensive AI coding assistant research and MCP-first implementation plan 
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>
2025-10-22 21:00:34 -04:00

8.7 KiB
Raw Blame History

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