# 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)**
```xml
<PackageReference Include="OpenHarbor.MCP.AspNetCore" Version="1.0.0" />
```

**Option 2: Local Project Reference (Development)**
```xml
<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](../README.md) - Project overview and quick start
- [AGENT-PRIMER.md](../AGENT-PRIMER.md) - AI-automated configuration guide
- [Implementation Plan](implementation-plan.md) - 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