svrnty/svrnty-mcp-client
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
0e74b22c5b
svrnty-mcp-client/docs/implementation-plan.md
Svrnty 97880406dc 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

8.7 KiB
Raw Blame History

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