apolosan/design_patterns_mcp

Design Patterns MCP Server

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
bun install

# Build and setup database
bun run db:setup

# Start the server
bun run dev

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

Features

Available Pattern Categories

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

Installation

Prerequisites

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

Setup

# Install dependencies
bun install

# Build project
bun run build

# Complete database setup (migrate + seed + embeddings + relationships)
bun run db:setup

# Or run steps individually
bun run migrate
bun run seed
bun run generate-embeddings
bun run setup-relationships

MCP Configuration

Add to your .mcp.json or Claude Desktop configuration:

{
  "mcpServers": {
    "design-patterns": {
      "command": "node",
      "args": ["dist/src/mcp-server.js"],
      "cwd": "/path/to/design-patterns-mcp",
      "env": {
        "LOG_LEVEL": "info",
        "DATABASE_PATH": "./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"
      }
    }
  }
}

Environment Variables

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

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:

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 for details.

Resources

• Model Context Protocol
• sqlite-vec
• Design Patterns Catalog

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