svrnty/svrnty-mcp-server
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
516e1479c6
svrnty-mcp-server/docs/module-design.md
Svrnty 516e1479c6 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

274 lines
8.0 KiB
Markdown
Raw Blame History

# 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
Reference in New Issue View Git Blame Copy Permalink