Skip to content

apolosan/design_patterns_mcp

BranchesTags

Repository files navigation

Design Patterns MCP Server

Version License: MIT Test Status Patterns TypeScript

An intelligent MCP (Model Context Protocol) server that provides design pattern recommendations using hybrid search (semantic + keyword + graph augmentation). Access 685+ design patterns across 90+ categories through a natural language interface with advanced blended RAG architecture.

Quick Start

# Clone and setup
git clone https://github.com/apolosan/design_patterns_mcp.git
cd design_patterns_mcp

# Install dependencies and build (using bun)
bun install
bun run db:setup

# Or using npm (if bun is not installed)
npm install --ignore-scripts
npx tsc
node dist/src/cli/migrate.js
node dist/src/cli/seed.js
node dist/src/cli/generate-embeddings.js
node dist/src/cli/setup-relationships.js

Configure in your MCP client (Claude Desktop, Cursor, etc.) and start discovering patterns through natural language queries.

Features

Feature Description
Hybrid Search Engine Blended RAG combining semantic, keyword (TF-IDF), and graph-augmented retrieval
685+ Patterns Comprehensive catalog across 12 major categories
MCP Integration Seamless integration with Claude, Cursor, and other MCP clients
Multi-Level Caching L1 in-memory + L3 SQLite cache with 95%+ hit rate
Event Bus System Decoupled service communication via pub/sub
Telemetry & Health Real-time performance metrics and system monitoring
SOLID Architecture Clean, maintainable codebase following best practices
Production Ready 464 test cases with 100% pass rate

Available Pattern Categories

Category Count Examples
Classic GoF Patterns 34 Factory, Builder, Observer, Strategy, Command
Architectural Patterns 56 MVC, Clean Architecture, Hexagonal, DDD
Microservices & Cloud 39 Circuit Breaker, Saga, Service Mesh
Data Engineering 54 Repository, CQRS, Event Sourcing
AI/ML & MLOps 46 RAG, Fine-Tuning, Model Compression
React Patterns 27 Hooks, Server Components, Performance
Blockchain & Web3 115 DeFi, NFTs, Smart Contracts, MEV
Concurrency & Reactive 45 Producer-Consumer, Actor Model
Security 21 OAuth, RBAC, Zero Trust
Functional Programming 26 Monads, Functors, Higher-Order Functions

Architecture

src/
├── adapters/              # External service adapters (LLM, embeddings)
├── cli/                   # CLI commands (migrate, seed, embeddings, setup-relationships)
├── core/                  # DI Container, configuration builder
├── db/                    # Database migrations
├── events/                # Event bus system
├── handlers/              # MCP request handlers (hybrid search, recommendations)
├── health/                # Health check services
├── repositories/          # Data access layer
├── search/                # Hybrid search engine
├── services/              # Business services (cache, telemetry, pattern service)
├── strategies/            # Strategy pattern implementations
├── types/                 # TypeScript type definitions
└── mcp-server.ts          # MCP server entry point

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

Usage

Finding Patterns

Ask natural language questions through your MCP client:

"I need to create complex objects with many optional configurations"
→ Builder, Abstract Factory, Factory Method

"How to handle service failures gracefully in distributed systems?"
→ Circuit Breaker, Bulkhead, Retry, Fallback

"What pattern helps with state-dependent behavior in React?"
→ State Machine, Observer, useReducer

"How to implement secure authentication and authorization?"
→ OAuth 2.0, RBAC, JWT, Zero Trust

MCP Tools

Tool Description
find_patterns Hybrid search for patterns using problem descriptions
search_patterns Keyword or semantic search with filtering
get_pattern_details Comprehensive pattern information with code examples
count_patterns Statistics about available patterns
get_health_status System health and service status

Installation

Prerequisites

  • Node.js >= 18.0.0
  • Bun >= 1.0.0 (recommended) or npm >= 8.0.0

Setup with Bun

bun install
bun run build
bun run db:setup

Setup with npm

The prepare script in package.json requires bun. If you don't have bun installed, use --ignore-scripts to skip it and build manually:

npm install --ignore-scripts
npx tsc

# Setup database
node dist/src/cli/migrate.js
node dist/src/cli/seed.js
node dist/src/cli/generate-embeddings.js
node dist/src/cli/setup-relationships.js

MCP Configuration

Add to your MCP client configuration (Claude Desktop, Cursor, etc.):

{
  "mcpServers": {
    "design-patterns": {
      "command": "node",
      "args": ["/absolute/path/to/design-patterns-mcp/dist/src/mcp-server.js"],
      "env": {
        "LOG_LEVEL": "info",
        "DATABASE_PATH": "/absolute/path/to/design-patterns-mcp/data/design-patterns.db",
        "ENABLE_HYBRID_SEARCH": "true",
        "ENABLE_GRAPH_AUGMENTATION": "true",
        "EMBEDDING_COMPRESSION": "true",
        "ENABLE_FUZZY_LOGIC": "true",
        "ENABLE_TELEMETRY": "true",
        "ENABLE_MULTI_LEVEL_CACHE": "true"
      }
    }
  }
}

Important: Use absolute paths for both args and DATABASE_PATH. MCP clients like Cursor do not reliably support the cwd field, so relative paths resolve against the user's home directory rather than the project directory. See QUICKSTART.md for client-specific configuration examples.

Environment Variables

Variable Default Description
LOG_LEVEL info Logging level (debug, info, warn, error)
DATABASE_PATH ./data/design-patterns.db SQLite database path
ENABLE_HYBRID_SEARCH true Enable blended RAG search
ENABLE_GRAPH_AUGMENTATION true Enable pattern relationship traversal
EMBEDDING_COMPRESSION true Dimensionality reduction
ENABLE_FUZZY_LOGIC true Fuzzy logic result refinement
ENABLE_TELEMETRY true Performance metrics
ENABLE_MULTI_LEVEL_CACHE true L1 + L3 caching
MAX_CONCURRENT_REQUESTS 10 Request concurrency limit
CACHE_MAX_SIZE 1000 Cache size limit
CACHE_TTL 3600000 Cache TTL in milliseconds
TRANSPORT_MODE stdio Transport mode (stdio/http)
HTTP_PORT 3000 HTTP port (http mode)
MCP_ENDPOINT /mcp MCP endpoint path
HEALTH_CHECK_PATH /health Health check path
SKIP_DB_SETUP false Skip database setup

Docker Deployment

Quick Start

# Build
docker build -t design-patterns-mcp .

# Run HTTP mode
docker run -p 3000:3000 -e TRANSPORT_MODE=http design-patterns-mcp

# Run stdio mode (default)
docker run design-patterns-mcp

Docker Compose

docker compose up --build -d

Environment Variables

Variable Default Description
TRANSPORT_MODE stdio Transport mode (stdio/http)
HTTP_PORT 3000 HTTP port (http mode)
MCP_ENDPOINT /mcp MCP endpoint path
HEALTH_CHECK_PATH /health Health check path
DATABASE_PATH /app/data/design-patterns.db SQLite database path
LOG_LEVEL info Logging level
SKIP_DB_SETUP false Skip database setup

Endpoints (HTTP mode)

  • GET /health - Health check
  • POST /mcp - MCP JSON-RPC endpoint

Commands

# Development
bun run build        # Compile TypeScript
bun run dev          # Development with hot reload
bun run start        # Build and start production server

# Database
bun run db:setup     # Complete database setup
bun run migrate      # Run migrations
bun run seed         # Seed pattern data
bun run generate-embeddings  # Generate semantic embeddings
bun run setup-relationships  # Setup pattern relationships

# Quality
bun run test         # Run all tests
bun run lint         # Check code quality
bun run lint:fix     # Auto-fix linting issues
bun run typecheck    # TypeScript type checking

Testing

The project includes 464 test cases across 41 test files with 100% pass rate:

  • Contract Tests: MCP protocol compliance validation
  • Integration Tests: Component interaction tests
  • Performance Tests: Search and vectorization benchmarks
  • Unit Tests: Individual component tests
# Run all tests
bun run test

# Run specific test suites
bun run test:unit -- --grep "PatternService"
bun run test:integration -- --grep "database"
bun run test:performance -- --timeout 30000

Architecture Patterns

This project implements the patterns it documents:

Pattern Implementation
Repository repositories/pattern-repository.ts
Service Layer services/pattern-service.ts
Object Pool services/statement-pool.ts
Dependency Injection core/container.ts
Strategy strategies/search-strategy.ts
Event Bus events/event-bus.ts
Multi-Level Cache services/multi-level-cache.ts
Builder core/config-builder.ts

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

  1. Fork the repository
  2. Create a feature branch
  3. Make changes following SOLID principles
  4. Run tests and linting
  5. Submit a pull request

License

MIT License - see LICENSE for details.

Resources

Version: 0.4.4
Last Updated: February 2026
Patterns: 685+ (750+ JSON files)
Tests: 464 test cases | 100% pass rate

About

MCP Server for suggestion of Design Patterns - Provides semantic search and recommendations for software design patterns

Resources

Readme

License

MIT license
Activity

Stars

23 stars

Watchers

0 watching

Forks

7 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages