0c27de4162
- 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>
274 lines
8.0 KiB
Markdown
274 lines
8.0 KiB
Markdown
# Svrnty.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
|
|
|
|
Svrnty.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/Svrnty.MCP/ # Separate from CODEX
|
|
├── README.md # Usage documentation
|
|
├── AGENT-PRIMER.md # AI-automated configuration
|
|
├── LICENSE # MIT license
|
|
├── Svrnty.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. Svrnty.MCP.Core - Pure Abstractions
|
|
- `IMcpServer` - Server interface
|
|
- `IMcpTool` - Tool interface
|
|
- `IPermissionProvider` - Permission abstraction
|
|
- `IRateLimiter` - Rate limiting abstraction
|
|
- Zero dependencies
|
|
|
|
### 2. Svrnty.MCP.Infrastructure - Implementation
|
|
- `McpServer` - Server implementation
|
|
- `ToolRegistry` - Dynamic tool registration
|
|
- `StdioTransport` - Process communication
|
|
- `PermissionProvider` - Access control
|
|
- `TokenBucketRateLimiter` - Rate limiting
|
|
|
|
### 3. Svrnty.MCP.AspNetCore - Integration
|
|
- ServiceCollectionExtensions - DI
|
|
- McpMiddleware - HTTP transport
|
|
- McpOptions - Configuration
|
|
|
|
### 4. Svrnty.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 Svrnty.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="Svrnty.MCP.AspNetCore" Version="1.0.0" />
|
|
```
|
|
|
|
**Option 2: Local Project Reference (Development)**
|
|
```xml
|
|
<ProjectReference Include="../Svrnty.MCP/src/Svrnty.MCP.AspNetCore/Svrnty.MCP.AspNetCore.csproj" />
|
|
```
|
|
|
|
**CODEX MCP Server Location:**
|
|
```
|
|
src/Codex.Mcp/ # Uses Svrnty.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/Svrnty.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/Svrnty.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/Svrnty.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 Svrnty.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/Svrnty.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
|
|
|
|
**Svrnty.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
|