MCP Prompts Server

# ADR-001: Project Rationale and Architecture Decision ## Status **Accepted** - 2025-01-27 ## Context The MCP Prompts Server project needed a clear architectural direction to meet the expectations outlined at [MCPHub](https://mcphub.com/mcp-servers/sparesparrow/mcp-prompts) and [Glama](https://glama.ai/mcp/servers/@sparesparrow/mcp-prompts). The existing codebase showed signs of architectural complexity and needed consolidation. ## Decision We have decided to implement a **Hexagonal Architecture** (Ports & Adapters) pattern for the MCP Prompts Server, with the following key decisions: ### 1. **Architecture Pattern: Hexagonal Architecture** - **Rationale**: Provides clean separation of concerns, testability, and extensibility - **Benefits**: - Isolated domain logic - Easy to add new adapters - Testable without external dependencies - Clear interface boundaries ### 2. **Core Domain Structure** ``` packages/core/ ├── entities/ # Domain entities (Prompt, Template, Category, User) ├── value-objects/ # Immutable value objects (PromptId, Tag, TemplateVariable) ├── ports/ # Interface definitions (IPromptRepository, ITemplatingEngine) ├── use-cases/ # Business logic (addPrompt, getPrompt, validatePrompt) ├── schemas/ # Zod validation schemas ├── errors/ # Custom error classes └── config/ # Configuration management ``` ### 3. **Value Objects Implementation** - **PromptId**: UUID v7 with validation and generation methods - **Tag**: Regex-validated tags with sanitization - **TemplateVariable**: Immutable template variable representation ### 4. **Ports and Adapters** - **Primary Ports**: `IPromptApplication` for driving adapters - **Secondary Ports**: `IPromptRepository`, `ITemplatingEngine`, etc. - **Adapters**: File, PostgreSQL, Memory, MDC storage implementations ### 5. **Validation Strategy** - **Zod Schemas**: Runtime validation for all inputs - **Business Rules**: Domain-specific validation logic - **Security Validation**: Content sanitization and security checks ## Consequences ### Positive Consequences 1. **Maintainability**: Clear separation of concerns makes the codebase easier to maintain 2. **Testability**: Domain logic can be tested in isolation 3. **Extensibility**: New storage backends or templating engines can be added easily 4. **Type Safety**: Strong TypeScript types with Zod validation 5. **Documentation**: Clear architecture that's easy to understand and document ### Negative Consequences 1. **Complexity**: Initial setup requires more boilerplate code 2. **Learning Curve**: Team members need to understand hexagonal architecture 3. **Performance**: Additional abstraction layers may add minimal overhead ### Risks and Mitigation 1. **Over-engineering Risk** - **Risk**: Creating unnecessary abstractions - **Mitigation**: Focus on user value, keep interfaces simple 2. **Performance Risk** - **Risk**: Abstraction layers affecting performance - **Mitigation**: Profile and optimize critical paths 3. **Team Adoption Risk** - **Risk**: Team resistance to new architecture - **Mitigation**: Provide training and clear examples ## Implementation Plan ### Phase 1: Core Domain (Week 1-2) - [x] Create domain entities (Prompt, TemplateVariable, Category, User) - [x] Implement value objects (PromptId, Tag, TemplateVariable) - [x] Define port interfaces - [x] Implement use cases ### Phase 2: Adapters (Week 3-4) - [ ] Implement file storage adapter - [ ] Implement PostgreSQL adapter - [ ] Implement memory adapter - [ ] Implement MDC adapter ### Phase 3: Integration (Week 5-6) - [ ] MCP protocol adapter - [ ] REST API adapter - [ ] CLI adapter - [ ] Integration testing ### Phase 4: Production (Week 7-8) - [ ] Performance optimization - [ ] Security hardening - [ ] Documentation completion - [ ] Production deployment ## Alternatives Considered ### 1. **Monolithic Architecture** - **Pros**: Simpler initial implementation - **Cons**: Harder to test, maintain, and extend - **Decision**: Rejected due to long-term maintainability concerns ### 2. **Layered Architecture** - **Pros**: Familiar pattern for most developers - **Cons**: Tight coupling between layers - **Decision**: Rejected in favor of hexagonal architecture ### 3. **Event-Driven Architecture** - **Pros**: Loose coupling, scalability - **Cons**: Increased complexity, harder to debug - **Decision**: Rejected as overkill for current requirements ## Success Metrics ### Technical Metrics - **Build Time**: <5 minutes for full build - **Test Coverage**: >90% for core packages - **Type Safety**: 100% TypeScript strict mode compliance - **Performance**: <100ms response time for basic operations ### Development Metrics - **Time to First Contribution**: <30 minutes from git clone - **CI/CD Pipeline Duration**: <10 minutes - **Documentation Completeness**: 100% API coverage ### Quality Metrics - **Zero Critical Security Vulnerabilities** - **MCP Protocol Compliance**: 100% - **Cross-Platform Compatibility**: Linux, macOS, Windows ## References - [Hexagonal Architecture (Alistair Cockburn)](https://alistair.cockburn.us/hexagonal-architecture/) - [Model Context Protocol Specification](https://modelcontextprotocol.io/specification/draft) - [Clean Architecture (Robert C. Martin)](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html) - [Domain-Driven Design (Eric Evans)](https://domainlanguage.com/ddd/) ## Review Schedule This ADR will be reviewed: - **Monthly**: During architecture review meetings - **Quarterly**: During planning sessions - **Annually**: During major version planning ## Approval - **Architecture Team**: ✅ Approved - **Development Team**: ✅ Approved - **Product Owner**: ✅ Approved - **Security Team**: ✅ Approved --- *This ADR represents a significant architectural decision for the MCP Prompts Server project and should be carefully considered before making any changes to the established patterns.*