svrnty-mcp-server/docs/module-design.md

OpenHarbor.MCP - Reusable Module Design

Document Type: Architecture and Design Specification Created: 2025-10-19 Purpose: Extract MCP server functionality into standalone, reusable .NET library Version: 1.0.0

---

Overview

OpenHarbor.MCP is a standalone, modular, scalable MCP library that can be extracted and reused across multiple projects. While CODEX will be the first implementation, the module is designed for general-purpose use.

Key Design Principles:

• Zero CODEX dependencies - Pure .NET library
• Self-contained - All instructions and examples included
• Reusable - Copy folder to any project
• Automated setup - AGENT-PRIMER.md for AI-assisted configuration
• Clean Architecture - Core → Infrastructure → Integration layers

---

Project Location

Standalone folder (NOT in CODEX codebase):

/home/svrnty/codex/OpenHarbor.MCP/          # Separate from CODEX
├── README.md                                # Usage documentation
├── AGENT-PRIMER.md                          # AI-automated configuration
├── LICENSE                                  # MIT license
├── OpenHarbor.MCP.sln                       # Solution file
├── src/                                     # Source code
├── tests/                                   # Unit + integration tests
├── samples/CodexMcpServer/                  # CODEX example
└── docs/                                    # Architecture & guides

Benefits:

• No contamination of CODEX codebase
• Can copy entire folder to new projects
• CODEX references it via NuGet or project reference
• Independent versioning and release

---

Module Architecture

Clean Architecture Layers:

1. OpenHarbor.MCP.Core - Pure Abstractions

• IMcpServer - Server interface
• IMcpTool - Tool interface
• IPermissionProvider - Permission abstraction
• IRateLimiter - Rate limiting abstraction
• Zero dependencies

2. OpenHarbor.MCP.Infrastructure - Implementation

• McpServer - Server implementation
• ToolRegistry - Dynamic tool registration
• StdioTransport - Process communication
• PermissionProvider - Access control
• TokenBucketRateLimiter - Rate limiting

3. OpenHarbor.MCP.AspNetCore - Integration

• ServiceCollectionExtensions - DI
• McpMiddleware - HTTP transport
• McpOptions - Configuration

4. OpenHarbor.MCP.Cli - CLI Runner

• HTTP transport runner
• Configuration loading

---

AGENT-PRIMER.md - Automated Configuration

Purpose: AI agents read this file and automatically:

1. Analyze target system - Detect .NET version, project type, dependencies
2. Generate configuration - Create appsettings.json, mcp-config.json, Program.cs
3. Create sample tools - Based on detected system (database, API, git)
4. Setup environment - Generate .editorconfig, launchSettings.json, scripts
5. Validate - Run tests and verify MCP connectivity

AI Agent Workflow:

User: "Copy OpenHarbor.MCP to my project"
  ↓
AI reads AGENT-PRIMER.md
  ↓
AI analyzes target system automatically
  ↓
AI generates all configuration files
  ↓
AI creates sample implementations
  ↓
User validates and runs

Example for CODEX:

• Detects: ASP.NET Core API at http://localhost:5050
• Generates: CodexMcpServer with 6 tools
• Configures: Permission model with agent scopes
• Output: samples/CodexMcpServer/ ready to use

---

CODEX Integration Strategy

Option 1: NuGet Package (Production)

<PackageReference Include="OpenHarbor.MCP.AspNetCore" Version="1.0.0" />

Option 2: Local Project Reference (Development)

<ProjectReference Include="../OpenHarbor.MCP/src/OpenHarbor.MCP.AspNetCore/OpenHarbor.MCP.AspNetCore.csproj" />

CODEX MCP Server Location:

src/Codex.Mcp/                       # Uses OpenHarbor.MCP library
├── Program.cs                       # CLI entry point
├── CodexMcpServer.cs                # Server configuration
├── Tools/
│   ├── SearchCodexTool.cs           # search_codex implementation
│   ├── GetDocumentTool.cs           # get_document implementation
│   └── ... (4 more tools)
├── Permissions/
│   └── CodexPermissionProvider.cs   # CODEX-specific permissions
└── codex-mcp-config.json            # Agent configuration

---

Implementation Phases

Phase 1: Core Module Development (Week 1-2, 6-8 hours)

• Location: /home/svrnty/codex/OpenHarbor.MCP/src/
• Deliverables:
  • Core abstractions (Core project)
  • Server implementation (Infrastructure project)
  • ASP.NET integration (AspNetCore project)
  • CLI runner (Cli project)
  • AGENT-PRIMER.md
  • Configuration templates
• Testing: TDD approach (tests first, all phases)

Phase 2: CODEX Integration Example (Week 2-3, 4-6 hours)

• Location: /home/svrnty/codex/OpenHarbor.MCP/samples/CodexMcpServer/
• Deliverables:
  • Sample implementation with 6 CODEX tools
  • Permission configuration
  • Rate limiting setup
  • Integration tests with CODEX API

Phase 3: Documentation & Reusability (Week 3, 4-6 hours)

• Location: /home/svrnty/codex/OpenHarbor.MCP/docs/
• Deliverables:
  • Complete README.md
  • Architecture documentation
  • Tool creation guide
  • Deployment guide
  • Migration guide (copy to new projects)

Phase 4: CODEX Production Integration (Week 3-4, 2-4 hours)

• Location: CODEX references OpenHarbor.MCP
• Deliverables:
  • Update CODEX to use library
  • Production deployment configuration
  • Update future features registry
  • Mark CODEX MCP implementation complete

---

Technology Stack

Same as CODEX (approved):

• .NET 8.0 (C# 11)
• ASP.NET Core 8
• xUnit (testing)
• Moq (mocking)
• System.Text.Json (serialization)

New dependencies (require approval):

• MCP SDK: @modelcontextprotocol/sdk (TypeScript) OR .NET MCP library
  • Tier: Core (essential for MCP protocol)
  • License: Open source (verify)
  • Purpose: MCP protocol implementation

---

Reusability Features

1. Folder Portability

• Copy /home/svrnty/codex/OpenHarbor.MCP/ to any project
• Self-contained with all documentation
• No external CODEX dependencies

2. AI-Assisted Setup

• AGENT-PRIMER.md guides automated configuration
• System analysis detects project specifics
• Configuration generation based on analysis

3. Extensibility

• Implement IMcpTool for custom tools
• Implement IPermissionProvider for custom auth
• Implement IRateLimiter for custom rate limiting

4. NuGet Distribution

• Publish to NuGet when mature
• Other teams use via package manager
• Versioned independently from CODEX

---

Security Considerations

Built-in security:

• Permission-based access control
• Rate limiting per agent
• Audit logging for all operations
• Deny-by-default security model

CODEX-specific security:

• Agent scopes (all, documentation, public)
• Rate limits per agent type
• Read-only by default
• Write operations require explicit approval

---

Success Criteria

Module-level:

• Reusable across projects (not CODEX-specific)
• Clean Architecture respected
• Full test coverage (>90%)
• Documentation complete
• NuGet package ready

CODEX integration:

• CODEX MCP server operational
• All 6 tools working
• Permission enforcement validated
• Rate limiting tested

---

Related Documentation

OpenHarbor.MCP Documentation:

• README.md - Project overview and quick start
• AGENT-PRIMER.md - AI-automated configuration guide
• Implementation Plan - Detailed TDD implementation strategy

CODEX Documentation:

• CODEX/scratch/future-mcp-integration-plan.md - Strategic context and CODEX use case
• CODEX/.codex/future-features/registry.json - Trigger tracking
• CODEX/docs/architecture/claude-code-mcp-integration.md - ADR (planned)

---

Revision History

Version	Date	Changes
1.0.0	2025-10-19	Initial module design extracted from CODEX future features documentation

---

Status: Designed - Ready for Implementation Next Steps: Begin Phase 1 when Phase 4 of CODEX is complete Last Updated: 2025-10-19