svrnty-mcp-server/docs/implementation-plan.md

# OpenHarbor.MCP - Detailed Implementation Plan

**Project:** Standalone, Reusable MCP Library for .NET
**Status:** Planned (Not Yet Started)
**Created:** 2025-10-19
**Version:** 1.0.0
**Estimated Effort:** 3-4 weeks (24-32 hours active work)

---

## Executive Summary

OpenHarbor.MCP is a **standalone .NET library** implementing the Model Context Protocol (MCP) server functionality. It is designed to be:

- **Reusable** across any .NET project
- **Modular** with clean separation of concerns
- **Scalable** with built-in permission and rate limiting
- **Secure** with deny-by-default security model
- **Self-contained** with complete documentation and examples

**First Use Case:** CODEX MCP Gateway (makes CODEX knowledge accessible to all AI agents)

**Future Use Cases:** Any .NET application wanting to expose tools/resources via MCP protocol

---

## Table of Contents

- [Architecture](#architecture)
- [Project Structure](#project-structure)
- [Implementation Phases](#implementation-phases)
- [Test-Driven Development Strategy](#test-driven-development-strategy)
- [AGENT-PRIMER.md Specifications](#agent-primermd-specifications)
- [CODEX Integration](#codex-integration)
- [Technology Stack](#technology-stack)
- [Success Criteria](#success-criteria)

---

## Architecture

### Clean Architecture Layers

```
┌─────────────────────────────────────────────┐
│         OpenHarbor.MCP.Core                 │
│  (Pure Abstractions - Zero Dependencies)    │
│                                             │
│  IMcpServer, IMcpTool, IMcpResource         │
│  IPermissionProvider, IRateLimiter          │
│  McpRequest, McpResponse, McpTool           │
└─────────────────┬───────────────────────────┘
                  │ Depends On
┌─────────────────┴───────────────────────────┐
│    OpenHarbor.MCP.Infrastructure            │
│  (Implementation + Transport)               │
│                                             │
│  McpServer, ToolRegistry, StdioTransport    │
│  PermissionProvider, TokenBucketRateLimiter │
│  McpProtocolHandler, AuditLogger            │
└─────────────────┬───────────────────────────┘
                  │ Depends On
┌─────────────────┴───────────────────────────┐
│     OpenHarbor.MCP.AspNetCore               │
│  (ASP.NET Core Integration)                 │
│                                             │
│  ServiceCollectionExtensions                │
│  McpMiddleware, AuditMiddleware             │
│  McpOptions (Configuration)                 │
└─────────────────────────────────────────────┘

┌─────────────────────────────────────────────┐
│      OpenHarbor.MCP.Cli                     │
│  (Standalone CLI Runner)                    │
│                                             │
│  Program.cs (Entry Point)                   │
│  Configuration Loading                      │
│  Stdio Transport Execution                  │
└─────────────────────────────────────────────┘
```

### Component Responsibilities

**Core (Abstractions):**
- `IMcpServer` - Server lifecycle and tool registration
- `IMcpTool` - Tool interface with execute method
- `IMcpResource` - Resource interface (future)
- `IPermissionProvider` - Permission checking abstraction
- `IRateLimiter` - Rate limiting abstraction
- Models: Request, Response, Tool metadata, Errors

**Infrastructure (Implementation):**
- `McpServer` - Concrete server implementation
- `ToolRegistry` - Dynamic tool registration and discovery
- `McpProtocolHandler` - Protocol message parsing and routing
- `StdioTransport` - Process stdin/stdout communication
- `PermissionProvider` - Permission checking logic
- `TokenBucketRateLimiter` - Rate limiting implementation
- `AuditLogger` - Audit trail for security

**AspNetCore (Integration):**
- `AddMcpServer()` - DI extension method
- `McpMiddleware` - HTTP transport middleware
- `McpOptions` - Configuration model
- `AuditMiddleware` - Audit logging middleware

**Cli (Runtime):**
- `Program.cs` - CLI entry point
- Configuration loading from JSON
- HTTP transport runner

---

## Project Structure

```
/home/svrnty/codex/OpenHarbor.MCP/
├── OpenHarbor.MCP.sln
├── README.md
├── AGENT-PRIMER.md                          # AI-assisted configuration
├── LICENSE                                   # MIT
├── .gitignore
├── .editorconfig
│
├── src/
│   ├── OpenHarbor.MCP.Core/
│   │   ├── Abstractions/
│   │   │   ├── IMcpServer.cs
│   │   │   ├── IMcpTool.cs
│   │   │   ├── IMcpResource.cs
│   │   │   ├── IPermissionProvider.cs
│   │   │   └── IRateLimiter.cs
│   │   ├── Models/
│   │   │   ├── McpRequest.cs
│   │   │   ├── McpResponse.cs
│   │   │   ├── McpTool.cs
│   │   │   ├── McpResource.cs
│   │   │   ├── PermissionScope.cs
│   │   │   └── RateLimitPolicy.cs
│   │   ├── Exceptions/
│   │   │   ├── McpException.cs
│   │   │   ├── PermissionDeniedException.cs
│   │   │   ├── RateLimitExceededException.cs
│   │   │   └── ToolNotFoundException.cs
│   │   └── OpenHarbor.MCP.Core.csproj
│   │
│   ├── OpenHarbor.MCP.Infrastructure/
│   │   ├── Server/
│   │   │   ├── McpServer.cs
│   │   │   ├── ToolRegistry.cs
│   │   │   └── McpProtocolHandler.cs
│   │   ├── Security/
│   │   │   ├── PermissionProvider.cs
│   │   │   ├── TokenBucketRateLimiter.cs
│   │   │   └── AuditLogger.cs
│   │   ├── Transport/
│   │   │   ├── StdioTransport.cs
│   │   │   └── HttpTransport.cs
│   │   └── OpenHarbor.MCP.Infrastructure.csproj
│   │
│   ├── OpenHarbor.MCP.AspNetCore/
│   │   ├── Extensions/
│   │   │   └── ServiceCollectionExtensions.cs
│   │   ├── Middleware/
│   │   │   ├── McpMiddleware.cs
│   │   │   └── AuditMiddleware.cs
│   │   ├── Configuration/
│   │   │   └── McpOptions.cs
│   │   └── OpenHarbor.MCP.AspNetCore.csproj
│   │
│   └── OpenHarbor.MCP.Cli/
│       ├── Program.cs
│       └── OpenHarbor.MCP.Cli.csproj
│
├── tests/
│   ├── OpenHarbor.MCP.Core.Tests/
│   │   ├── Abstractions/
│   │   ├── Models/
│   │   └── Exceptions/
│   ├── OpenHarbor.MCP.Infrastructure.Tests/
│   │   ├── Server/
│   │   ├── Security/
│   │   └── Transport/
│   └── OpenHarbor.MCP.Integration.Tests/
│       ├── EndToEnd/
│       └── Scenarios/
│
├── samples/
│   └── CodexMcpServer/                      # CODEX example
│       ├── Program.cs
│       ├── CodexMcpServer.cs
│       ├── Tools/
│       │   ├── SearchCodexTool.cs
│       │   ├── GetDocumentTool.cs
│       │   ├── ListDocumentsTool.cs
│       │   ├── SearchByTagTool.cs
│       │   ├── GetDocumentSectionsTool.cs
│       │   └── ListTagsTool.cs
│       ├── Permissions/
│       │   └── CodexPermissionProvider.cs
│       ├── codex-mcp-config.json
│       └── CodexMcpServer.csproj
│
├── docs/
│   ├── getting-started.md
│   ├── architecture.md
│   ├── creating-tools.md
│   ├── permission-model.md
│   ├── rate-limiting.md
│   └── deployment.md
│
└── templates/                               # For AGENT-PRIMER.md
    ├── appsettings.json.template
    ├── mcp-config.json.template
    ├── Program.cs.template
    └── sample-tool.cs.template
```

---

## Implementation Phases

### Phase 1: Core Abstractions (Week 1, 6-8 hours)

**Goal:** Define core interfaces and models with zero dependencies

#### Step 1.1: Project Setup (30 minutes)
**TDD:** Not applicable (infrastructure setup)

**Tasks:**
- Create solution: `dotnet new sln -n OpenHarbor.MCP`
- Create Core project: `dotnet new classlib -n OpenHarbor.MCP.Core --framework net8.0`
- Configure: Enable nullable, ImplicitUsings
- Add to solution

**Deliverables:**
- OpenHarbor.MCP.sln
- OpenHarbor.MCP.Core.csproj
- .editorconfig (C# formatting)

#### Step 1.2: Core Interfaces (2 hours)
**TDD:** Write interface tests first (behavior validation via mocks)

**Tests FIRST:**
```csharp
// OpenHarbor.MCP.Core.Tests/Abstractions/IMcpServerTests.cs
[Fact]
public async Task RegisterTool_WithValidTool_AddsToRegistry()
{
    var server = new Mock<IMcpServer>();
    var tool = new Mock<IMcpTool>();

    server.Setup(s => s.RegisterTool(tool.Object))
          .Returns(Task.CompletedTask);

    await server.Object.RegisterTool(tool.Object);

    server.Verify(s => s.RegisterTool(tool.Object), Times.Once);
}
```

**Implementation:**
```csharp
// OpenHarbor.MCP.Core/Abstractions/IMcpServer.cs
public interface IMcpServer
{
    Task RegisterTool(IMcpTool tool);
    Task<IEnumerable<IMcpTool>> GetTools();
    Task<McpResponse> HandleRequest(McpRequest request);
    Task Start(CancellationToken cancellationToken = default);
    Task Stop();
}

// OpenHarbor.MCP.Core/Abstractions/IMcpTool.cs
public interface IMcpTool
{
    string Name { get; }
    string Description { get; }
    McpToolSchema Schema { get; }
    Task<McpResponse> Execute(McpRequest request);
}

// OpenHarbor.MCP.Core/Abstractions/IPermissionProvider.cs
public interface IPermissionProvider
{
    Task<bool> HasPermission(string agentId, string action, string? resource = null);
    Task<IEnumerable<string>> GetPermissions(string agentId);
}

// OpenHarbor.MCP.Core/Abstractions/IRateLimiter.cs
public interface IRateLimiter
{
    Task<bool> TryAcquire(string agentId);
    Task<RateLimitInfo> GetLimitInfo(string agentId);
}
```

**Deliverables:**
- 5 core interfaces
- 10+ interface behavior tests

#### Step 1.3: Core Models (2 hours)
**TDD:** Write model tests first (validation, serialization)

**Tests FIRST:**
```csharp
[Fact]
public void McpRequest_WithValidData_Serializes()
{
    var request = new McpRequest
    {
        Method = "tools/call",
        Params = new { tool = "search", query = "test" }
    };

    var json = JsonSerializer.Serialize(request);
    var deserialized = JsonSerializer.Deserialize<McpRequest>(json);

    Assert.Equal(request.Method, deserialized.Method);
}
```

**Implementation:**
```csharp
// OpenHarbor.MCP.Core/Models/McpRequest.cs
public record McpRequest
{
    public string Method { get; init; } = string.Empty;
    public object? Params { get; init; }
    public string? Id { get; init; }
}

// OpenHarbor.MCP.Core/Models/McpResponse.cs
public record McpResponse
{
    public object? Result { get; init; }
    public McpError? Error { get; init; }
    public string? Id { get; init; }
}

// OpenHarbor.MCP.Core/Models/McpTool.cs
public record McpTool
{
    public string Name { get; init; } = string.Empty;
    public string Description { get; init; } = string.Empty;
    public McpToolSchema Schema { get; init; } = new();
}
```

**Deliverables:**
- 7 core models
- 15+ model tests (validation, serialization)

#### Step 1.4: Exceptions (1 hour)
**TDD:** Write exception tests first

**Tests FIRST:**
```csharp
[Fact]
public void PermissionDeniedException_WithAgentAndAction_ContainsDetails()
{
    var ex = new PermissionDeniedException("agent1", "read", "/docs");

    Assert.Contains("agent1", ex.Message);
    Assert.Contains("read", ex.Message);
    Assert.Equal("agent1", ex.AgentId);
}
```

**Implementation:**
```csharp
public class PermissionDeniedException : McpException
{
    public string AgentId { get; }
    public string Action { get; }
    public string? Resource { get; }

    public PermissionDeniedException(string agentId, string action, string? resource = null)
        : base($"Agent '{agentId}' denied permission to '{action}' on resource '{resource ?? "any"}'")
    {
        AgentId = agentId;
        Action = action;
        Resource = resource;
    }
}
```

**Deliverables:**
- 4 exception classes
- 8+ exception tests

**Phase 1 Checkpoint:**
- Total tests: ~35
- All passing: ✅
- Zero dependencies: ✅
- Code coverage: >90% ✅

---

### Phase 2: Server Implementation (Week 1-2, 8-10 hours)

**Goal:** Implement MCP server with permission, rate limiting, and transport

#### Step 2.1: Infrastructure Project Setup (30 minutes)
- Create Infrastructure project
- Reference Core project
- Configure test project

#### Step 2.2: McpServer Implementation (3 hours)
**TDD:** Write server tests first

**Tests FIRST:**
```csharp
[Fact]
public async Task RegisterTool_WithValidTool_AddsToRegistry()
{
    var server = new McpServer();
    var tool = new MockSearchTool();

    await server.RegisterTool(tool);
    var tools = await server.GetTools();

    Assert.Contains(tools, t => t.Name == tool.Name);
}

[Fact]
public async Task HandleRequest_WithRegisteredTool_ExecutesTool()
{
    var server = new McpServer();
    var tool = new Mock<IMcpTool>();
    tool.Setup(t => t.Name).Returns("test_tool");
    tool.Setup(t => t.Execute(It.IsAny<McpRequest>()))
        .ReturnsAsync(new McpResponse { Result = "success" });

    await server.RegisterTool(tool.Object);
    var request = new McpRequest { Method = "tools/call", Params = new { tool = "test_tool" } };

    var response = await server.HandleRequest(request);

    Assert.NotNull(response.Result);
    tool.Verify(t => t.Execute(It.IsAny<McpRequest>()), Times.Once);
}
```

**Implementation:**
```csharp
public class McpServer : IMcpServer
{
    private readonly IToolRegistry _toolRegistry;
    private readonly IPermissionProvider _permissionProvider;
    private readonly IRateLimiter _rateLimiter;

    public async Task RegisterTool(IMcpTool tool)
    {
        await _toolRegistry.Add(tool);
    }

    public async Task<McpResponse> HandleRequest(McpRequest request)
    {
        // Permission check
        // Rate limit check
        // Route to tool
        // Return response
    }
}
```

**Deliverables:**
- McpServer implementation
- ToolRegistry implementation
- 20+ server tests

#### Step 2.3: Permission Provider (2 hours)
**TDD:** Permission tests first

**Tests FIRST:**
```csharp
[Fact]
public async Task HasPermission_WithAllowedAction_ReturnsTrue()
{
    var config = new PermissionConfig
    {
        Agents = new Dictionary<string, AgentPermissions>
        {
            ["agent1"] = new() { Permissions = new[] { "read", "search" } }
        }
    };
    var provider = new PermissionProvider(config);

    var result = await provider.HasPermission("agent1", "read");

    Assert.True(result);
}
```

**Implementation:**
```csharp
public class PermissionProvider : IPermissionProvider
{
    private readonly PermissionConfig _config;

    public async Task<bool> HasPermission(string agentId, string action, string? resource = null)
    {
        // Check agent permissions
        // Check scopes
        // Return result
    }
}
```

**Deliverables:**
- PermissionProvider implementation
- 15+ permission tests

#### Step 2.4: Rate Limiter (2 hours)
**TDD:** Rate limiter tests first

**Tests:**
- Token bucket algorithm tests
- Concurrent request tests
- Limit exceeded scenarios

**Deliverables:**
- TokenBucketRateLimiter implementation
- 12+ rate limiter tests

#### Step 2.5: Stdio Transport (1.5 hours)
**TDD:** Transport tests first

**Tests:**
- Read from stdin
- Write to stdout
- Handle malformed input

**Deliverables:**
- StdioTransport implementation
- 10+ transport tests

**Phase 2 Checkpoint:**
- Total tests: ~90
- All passing: ✅
- Integration test: MCP server end-to-end ✅

---

### Phase 3: ASP.NET Core Integration (Week 2, 6-8 hours)

**Goal:** Enable MCP server in ASP.NET Core applications

#### Step 3.1: Service Extensions (2 hours)
**TDD:** Extension tests first

**Tests:**
```csharp
[Fact]
public void AddMcpServer_RegistersServices()
{
    var services = new ServiceCollection();

    services.AddMcpServer(options => {
        options.ServerName = "test";
    });

    var provider = services.BuildServiceProvider();
    Assert.NotNull(provider.GetService<IMcpServer>());
}
```

**Implementation:**
```csharp
public static IServiceCollection AddMcpServer(
    this IServiceCollection services,
    Action<McpOptions> configure)
{
    services.Configure(configure);
    services.AddSingleton<IMcpServer, McpServer>();
    services.AddSingleton<IPermissionProvider, PermissionProvider>();
    services.AddSingleton<IRateLimiter, TokenBucketRateLimiter>();
    return services;
}
```

**Deliverables:**
- ServiceCollectionExtensions
- 8+ extension tests

#### Step 3.2: MCP Middleware (3 hours)
**TDD:** Middleware tests first

**Tests:**
- HTTP POST handling
- Permission enforcement
- Rate limiting
- Error responses

**Deliverables:**
- McpMiddleware implementation
- 15+ middleware tests

#### Step 3.3: Configuration (1 hour)
**TDD:** Configuration tests

**Deliverables:**
- McpOptions model
- Configuration validation tests

**Phase 3 Checkpoint:**
- Total tests: ~120
- ASP.NET Core integration working ✅

---

### Phase 4: CLI Runner & Documentation (Week 3, 4-6 hours)

**Goal:** Standalone CLI for HTTP transport + complete documentation

#### Step 4.1: CLI Program (1 hour)
**TDD:** CLI behavior tests

**Deliverables:**
- Program.cs with configuration loading
- HTTP transport runner
- 5+ CLI tests

#### Step 4.2: CODEX Sample (2 hours)
**TDD:** Sample implementation tests

**Deliverables:**
- CodexMcpServer sample
- 6 CODEX tools implemented
- Integration test with CODEX API

#### Step 4.3: Documentation (1.5 hours)
**Not TDD** (documentation doesn't need tests)

**Deliverables:**
- Complete README.md
- Getting started guide
- Architecture documentation
- Tool creation guide
- Deployment guide

**Phase 4 Checkpoint:**
- Total tests: ~140
- Sample working with CODEX ✅
- Documentation complete ✅

---

## Test-Driven Development Strategy

### TDD Principles (CODEX RULE #3)

**Mandatory workflow:**
1. **RED:** Write test that fails
2. **Verify RED:** Run test, confirm failure
3. **GREEN:** Write minimal code to pass
4. **Verify GREEN:** Run test, confirm success
5. **REFACTOR:** Improve code, keep tests green
6. **REPEAT:** Next requirement

### Test Organization

```
tests/
├── OpenHarbor.MCP.Core.Tests/
│   ├── Abstractions/           # Interface behavior tests
│   ├── Models/                 # Model validation tests
│   └── Exceptions/             # Exception tests
├── OpenHarbor.MCP.Infrastructure.Tests/
│   ├── Server/                 # Server logic tests
│   ├── Security/               # Permission & rate limit tests
│   └── Transport/              # Transport tests
└── OpenHarbor.MCP.Integration.Tests/
    └── EndToEnd/               # Full MCP server scenarios
```

### Test Coverage Goals

- **Core:** >95% (pure logic, easy to test)
- **Infrastructure:** >90% (some I/O dependencies)
- **AspNetCore:** >85% (middleware has framework dependencies)
- **Overall:** >90%

### Testing Tools

- **xUnit:** Test framework (CODEX-approved)
- **Moq:** Mocking library (CODEX-approved)
- **FluentAssertions:** Assertion library (optional, check approval)

---

## AGENT-PRIMER.md Specifications

### Purpose

Enable AI agents to automatically configure OpenHarbor.MCP for any target system by:
1. Analyzing the system
2. Generating configuration
3. Creating sample tools
4. Setting up environment

### Structure

```markdown
# OpenHarbor.MCP Agent Primer

**For AI Agents:** This file guides automated setup of OpenHarbor.MCP.

## Step 1: System Analysis

**Commands to run:**
```bash
dotnet --version                              # Check .NET SDK
ls -la [target-project-path]                  # Analyze structure
cat [target-project]/*.csproj                 # Read dependencies
cat [target-project]/appsettings.json         # Check configuration
```

**Detect:**
- .NET SDK version (require 8.0+)
- Project type (Console, ASP.NET Core, Worker)
- Database (PostgreSQL, SQL Server, None)
- Authentication (Keycloak, JWT, None)
- Operating system

## Step 2: Generate Configuration

**Based on analysis, generate:**

### For ASP.NET Core Projects:
- `appsettings.json` MCP section
- `Program.cs` AddMcpServer() call
- Sample controller integration

### For Console Projects:
- `mcp-config.json`
- `Program.cs` standalone server
- HTTP transport setup

**Templates:** See `templates/` folder

## Step 3: Create Sample Tools

**Generate based on detected features:**

**If database detected:**
```csharp
// Tools/QueryDatabaseTool.cs
public class QueryDatabaseTool : IMcpTool
{
    public string Name => "query_database";
    // ... implementation
}
```

**If API detected:**
```csharp
// Tools/CallApiTool.cs
public class CallApiTool : IMcpTool
{
    public string Name => "call_api";
    // ... implementation
}
```

**If git repository detected:**
```csharp
// Tools/SearchRepositoryTool.cs
public class SearchRepositoryTool : IMcpTool
{
    public string Name => "search_repo";
    // ... implementation
}
```

## Step 4: Setup Development Environment

**Generate:**
- `.editorconfig` (if not exists)
- `launchSettings.json` (for debugging)
- `README.md` (project-specific)
- `run-mcp-server.sh` (startup script)

## Step 5: Validation

**Run automated tests:**
```bash
dotnet build                        # Compile
dotnet test                         # Run tests
./run-mcp-server.sh --test         # Test connectivity
```

## Example: CODEX Integration

**Detected:**
- ASP.NET Core 8 project
- PostgreSQL database
- REST API at http://localhost:5050
- Semantic search capability

**Generated:**
- CodexMcpServer.cs
- 6 tools: search_codex, get_document, list_documents, search_by_tag, get_document_sections, list_tags
- codex-mcp-config.json with permission model
- Integration tests

**Output:** `samples/CodexMcpServer/` ready to run
```

### Implementation

The AGENT-PRIMER.md will include:
- Detailed system analysis commands
- Decision trees for configuration generation
- Complete templates for all scenarios
- Validation procedures
- Example outputs for common cases

---

## CODEX Integration

### Integration Approach

**Option 1: NuGet Package (Production)**
```bash
dotnet add package OpenHarbor.MCP.AspNetCore
```

**Option 2: Project Reference (Development)**
```bash
dotnet add reference ../OpenHarbor.MCP/src/OpenHarbor.MCP.AspNetCore/OpenHarbor.MCP.AspNetCore.csproj
```

### CODEX MCP Server Structure

```
src/Codex.Mcp/
├── Program.cs
├── CodexMcpServer.cs
├── Tools/
│   ├── SearchCodexTool.cs
│   ├── GetDocumentTool.cs
│   ├── ListDocumentsTool.cs
│   ├── SearchByTagTool.cs
│   ├── GetDocumentSectionsTool.cs
│   └── ListTagsTool.cs
├── Permissions/
│   └── CodexPermissionProvider.cs
└── codex-mcp-config.json
```

### Sample Tool Implementation

```csharp
using OpenHarbor.MCP.Core.Abstractions;

public class SearchCodexTool : IMcpTool
{
    private readonly HttpClient _httpClient;

    public string Name => "search_codex";
    public string Description => "Search CODEX knowledge base";

    public async Task<McpResponse> Execute(McpRequest request)
    {
        var query = request.Params["query"];
        var limit = request.Params["limit"] ?? 10;

        var response = await _httpClient.PostAsJsonAsync(
            "http://localhost:5050/api/search/hybrid",
            new { query, limit }
        );

        var result = await response.Content.ReadFromJsonAsync<SearchResult>();
        return new McpResponse { Result = result };
    }
}
```

---

## Technology Stack

### Core Dependencies (CODEX-Approved)

- .NET 8.0 SDK
- C# 11
- System.Text.Json (built-in)
- xUnit (testing)
- Moq (mocking)

### New Dependencies (Require Approval via ADR)

- **MCP SDK** (if available for .NET)
  - Alternative: Implement MCP protocol directly
  - License: Verify open source
  - Tier: Core (essential for protocol)

- **FluentAssertions** (optional, testing)
  - License: Apache 2.0
  - Purpose: Better test assertions
  - Tier: Development only

### CODEX RULE #1 Compliance

All new dependencies must be:
1. Documented in ADR
2. Added to CODEX tech stack
3. Approved before use
4. CODEX-approved alternatives used if available

---

## Success Criteria

### Module-Level Criteria

**Functionality:**
- [x] MCP server starts and accepts connections
- [x] Tools can be registered dynamically
- [x] Permission model enforces access control
- [x] Rate limiting prevents abuse
- [x] Audit logging tracks all operations
- [x] HTTP transport works
- [x] HTTP transport works (ASP.NET Core)

**Quality:**
- [x] >90% test coverage
- [x] All tests passing
- [x] Zero compiler warnings
- [x] TDD followed for all code
- [x] Clean Architecture respected

**Usability:**
- [x] Complete README with examples
- [x] API documentation generated
- [x] Sample implementations working
- [x] AGENT-PRIMER.md tested
- [x] Easy to copy to new projects

**Performance:**
- [x] <10ms overhead per request
- [x] Handles 1000+ req/sec
- [x] Rate limiting accurate

### CODEX Integration Criteria

**CODEX MCP Server:**
- [x] All 6 tools implemented
- [x] Integration tests passing
- [x] Permission model configured
- [x] Can be called from Claude Code
- [x] Can be called from Cursor
- [x] Returns valid MCP responses

**Documentation:**
- [x] Updated future-mcp-integration-plan.md
- [x] Completion notes in registry.json
- [x] CODEX_INDEX.md references OpenHarbor.MCP

---

## Timeline & Milestones

### Week 1
- Day 1-2: Phase 1 (Core abstractions)
- Day 3-5: Phase 2 (Server implementation start)

### Week 2
- Day 1-3: Phase 2 (Server implementation complete)
- Day 4-5: Phase 3 (ASP.NET Core integration)

### Week 3
- Day 1-2: Phase 4 (CLI + CODEX sample)
- Day 3-4: Documentation
- Day 5: Testing & validation

### Week 4 (Buffer)
- Refinement
- Additional samples
- NuGet packaging
- Final testing

---

## Next Steps

1. **Get approval for this plan**
2. **Create folder structure:** `/home/svrnty/codex/OpenHarbor.MCP/`
3. **Write AGENT-PRIMER.md**
4. **Begin Phase 1:** Core abstractions with TDD
5. **Track progress:** Use TodoWrite for each phase

---

**Status:** Planned (Awaiting Approval)
**Created:** 2025-10-19
**Version:** 1.0.0
**Related:** scratch/future-mcp-integration-plan.md (Appendix B)