Design Patterns MCP Server

Design Patterns MCP Server 🎯

An intelligent MCP (Model Context Protocol) server that provides design pattern recommendations using semantic search and vector embeddings. This project offers access to a comprehensive catalog of 200+ design patterns through a natural language interface.

📋 Overview

The Design Patterns MCP Server is a specialized server that integrates with AI assistants (like Claude, Cursor) to provide intelligent design pattern recommendations. It uses advanced semantic search technologies to find the most appropriate patterns based on natural language problem descriptions.

✨ Key Features

🔍 Intelligent Semantic Search: Find patterns using natural problem descriptions
📚 Comprehensive Catalog: 200+ patterns organized in 20 categories
🎯 Contextual Recommendations: Suggestions based on programming language and domain
⚡ Vector Search: Uses SQLite with vector extensions for efficient search
🌐 Multi-language: Support for multiple programming languages
🔧 MCP Integration: Compatible with Claude Code, Cursor and other MCP clients

🗂️ Available Pattern Categories

GoF Patterns: Classic patterns (Creational, Structural, Behavioral)
Architectural Patterns: MVC, MVP, MVVM, Clean Architecture
Microservices Patterns: Circuit Breaker, Event Sourcing, CQRS
Cloud Patterns: Auto-scaling, Load Balancing, Service Discovery
AI/ML Patterns: Model Training, Feature Engineering, Pipeline Patterns
Enterprise Patterns: Repository, Unit of Work, Dependency Injection
Security Patterns: Authentication, Authorization, Data Protection
Performance Patterns: Caching, Lazy Loading, Connection Pooling
Concurrency Patterns: Producer-Consumer, Thread Pool, Actor Model
Integration Patterns: Message Queue, Event Bus, API Gateway
Data Access Patterns: Active Record, Data Mapper, Query Object
Testing Patterns: Test Double, Page Object, Builder Pattern for tests
Functional Patterns: Monads, Functors, Higher-Order Functions
Reactive Patterns: Observer, Publisher-Subscriber, Reactive Streams
DDD Patterns: Aggregate, Value Object, Domain Service
Game Development Patterns: State Machine, Component System, Object Pool
Mobile Patterns: Model-View-Intent, Redux-like patterns
IoT Patterns: Device Twin, Telemetry Ingestion
Anti-Patterns: Practices to avoid and their solutions

🏗️ Project Architecture

src/
├── adapters/           # Adapters for external services
├── builders/           # Builders for complex objects
├── cli/               # Command line interface
├── core/              # Core domain logic
├── db/                # Database configuration and migrations
├── factories/         # Factories for object creation
├── lib/               # Auxiliary libraries and MCP utilities
├── models/            # Data models and types
├── repositories/      # Data access layer
├── services/          # Business services and orchestration
├── strategies/        # Specific strategy implementations
├── types/             # TypeScript type definitions
├── utils/             # Utility functions
└── mcp-server.ts      # Main MCP server

data/
├── patterns/          # JSON files with pattern definitions
└── design-patterns.db # SQLite database with embeddings

🔧 Main Components

DatabaseManager: Manages SQLite connections and operations
VectorOperationsService: Vector search operations using sqlite-vec
SemanticSearchService: Implements semantic search with embeddings
PatternMatcher: Pattern matching and ranking logic
LLMBridgeService: Interface for language models (optional)
EmbeddingServiceAdapter: Adapter for embedding services

🚀 Installation and Setup

Prerequisites

Node.js >= 18.0.0
npm >= 8.0.0 or Bun >= 1.0.0

Installation

# Clone the repository
git clone https://github.com/your-org/design-patterns-mcp.git
cd design-patterns-mcp

# Install dependencies
npm install

# Configure environment variables
cp .env.example .env

# Build the project
npm run build

# Setup the database
npm run db:setup

MCP Configuration

Add to your MCP configuration file (.mcp.json):

{
  "mcpServers": {
    "design-patterns": {
      "command": "node",
      "args": ["dist/src/mcp-server.js"],
      "cwd": "/path/to/design-patterns-mcp"
    }
  }
}

📖 Usage

Finding Patterns with Natural Language

Use natural language descriptions to find appropriate design patterns through Claude Code:

For object creation problems:

"I need to create complex objects with many optional configurations"
"How can I create different variations of similar objects?"
"What pattern helps with step-by-step object construction?"

For behavioral problems:

"I need to notify multiple components when data changes"
"How to decouple command execution from the invoker?"
"What pattern helps with state-dependent behavior?"

For architectural problems:

"How to structure a microservices communication system?"
"What pattern helps with distributed system resilience?"
"How to implement clean separation between layers?"

MCP Tool Functions

find_patterns: Semantic search for patterns using problem descriptions
search_patterns: Keyword or semantic search with filtering options
get_pattern_details: Get comprehensive information about specific patterns
count_patterns: Statistics about available patterns by category

🛠️ Available Commands

Development

npm run dev          # Run in development mode with hot reload
npm run dev:debug    # Run with debugging enabled
npm run build:watch  # Build in watch mode

Testing

npm run test                # Run all tests
npm run test:watch         # Run tests in watch mode
npm run test:coverage      # Run tests with coverage
npm run test:unit          # Run unit tests only
npm run test:integration   # Run integration tests
npm run test:performance   # Run performance tests

Code Quality

npm run lint           # Check linting issues
npm run lint:fix       # Fix linting issues automatically
npm run format         # Format code with Prettier
npm run typecheck      # Check TypeScript types

Database

npm run migrate              # Run migrations
npm run seed                # Populate with initial data
npm run generate-embeddings # Generate embeddings for semantic search
npm run db:setup            # Complete database setup
npm run db:reset            # Reset and reconfigure database

🎯 Usage Examples

Problem-Based Pattern Discovery

Distributed Systems:

"I need a pattern for handling service failures gracefully"
"How to implement eventual consistency in distributed data?"
"What pattern helps with service discovery and load balancing?"

Data Validation:

"I need to validate complex business rules on input data"
"How to compose validation rules dynamically?"
"What pattern separates validation logic from business logic?"

Performance Optimization:

"I need to cache expensive computations efficiently"
"How to implement lazy loading for large datasets?"
"What pattern helps with connection pooling?"

Category-Specific Searches

Enterprise Applications:

"Show me enterprise patterns for data access"
"What patterns help with dependency injection?"
"How to implement unit of work pattern?"

Security Implementation:

"I need authentication and authorization patterns"
"What patterns help with secure data handling?"
"How to implement role-based access control?"

🔧 Advanced Configuration

Environment Variables

# Database configuration
DATABASE_PATH=./data/design-patterns.db

# Logging configuration
LOG_LEVEL=info

# Embedding configuration
EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
EMBEDDING_DIMENSION=384

# Search configuration
SIMILARITY_THRESHOLD=0.7
MAX_RESULTS=10

Search Customization

const customConfig = {
  modelName: 'sentence-transformers/all-MiniLM-L6-v2',
  maxResults: 15,
  similarityThreshold: 0.75,
  contextWindow: 512,
  useQueryExpansion: true,
  useReRanking: true,
};

📊 Performance and Scalability

Vector Search: Uses sqlite-vec for efficient search in large volumes
Intelligent Cache: In-memory cache system for frequent queries
Optimized Indexes: Specific indexes for different search types
Pagination: Pagination support for large results
Metrics: Performance and usage metrics collection

🧪 Testing

The project includes a comprehensive test suite:

Unit Tests: Test individual components
Integration Tests: Test interaction between components
Performance Tests: Evaluate search and vectorization performance
Contract Tests: Validate MCP protocol compliance

# Run specific tests
npm run test:unit -- --grep "PatternMatcher"
npm run test:integration -- --grep "database"
npm run test:performance -- --timeout 30000

🤝 Contributing

Fork the project
Create a feature branch (git checkout -b feature/new-functionality)
Commit your changes (git commit -am 'Add new functionality')
Push to the branch (git push origin feature/new-functionality)
Open a Pull Request

Design Patterns MCP Server