Design Patterns MCP Server

An intelligent MCP (Model Context Protocol) server that provides design pattern recommendations using hybrid search (semantic + keyword + graph augmentation). Access 686 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/cli/migrate.js
node dist/cli/seed.js
node dist/cli/generate-embeddings.js
node dist/cli/setup-relationships.js

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

Tooling and build hygiene

Use Bun as the canonical package manager for this repository (bun install only). The lockfile is bun.lock.
Never copy a .git directory into dist/data (or ship it inside dist/). That path must remain a plain data directory to avoid multi‑gigabyte images and metadata leakage.

Features

Feature	Description
Hybrid Search Engine	Blended RAG combining semantic, keyword (BM25), and graph-augmented retrieval
686 Patterns	Comprehensive catalog across 90+ categories including Feature Flag / Feature Toggle for progressive delivery and experimentation
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	543 test cases across 67 test files with 88% pass rate (21 pre-existing integration test failures unrelated to core search functionality)

Available Pattern Categories

Category	Count	Examples
Classic GoF Patterns	34	Factory, Builder, Observer, Strategy, Command
Architectural Patterns	56	MVC, Clean Architecture, Hexagonal, DDD, Feature Flag
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/              # 686 JSON pattern definitions (see `feature-flag.json`)
└── design-patterns.db     # SQLite database with 686 patterns and 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/cli/migrate.js
node dist/cli/seed.js
node dist/cli/generate-embeddings.js
node dist/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/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 543 test cases across 67 test files with 88% pass rate:

Contract Tests: MCP protocol compliance validation
Integration Tests: Component interaction tests (21 pre-existing failures due to DB setup requirements)
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`

Vector search (runtime honesty)

The server uses sql.js (SQLite WASM) with in-memory cosine similarity over stored embeddings. Native sqlite-vec (vec0 virtual tables) is not available in this runtime. Semantic search works for the current catalog size (~700 patterns) but does not use indexed native vector tables.

Enable LLM enrichment only when you have a real provider integration — built-in LLM bridge providers return placeholders unless extended.

Contributing

Contributions are welcome! See docs/CONTRIBUTING.md.

Fork the repository
Create a feature branch
Make changes following SOLID principles
Run tests and linting
Submit a pull request

License

MIT License - see LICENSE for details.

Resources

Model Context Protocol
Vector search notes (sql.js vs sqlite-vec)
MCP tools surface
Documentation index
Design Patterns Catalog

Version: 0.6.0
Last Updated: August 2026 Patterns: 686 JSON definitions (highlight: Feature Flag / Feature Toggle) Tests: 543 test cases | 88% pass rate

Name		Name	Last commit message	Last commit date
Latest commit History 41 Commits
data/patterns		data/patterns
migrations		migrations
scripts		scripts
src		src
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.prettierrc		.prettierrc
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
LICENSE		LICENSE
QUICKSTART.md		QUICKSTART.md
README.md		README.md
bun.lock		bun.lock
docker-compose.yml		docker-compose.yml
entrypoint.sh		entrypoint.sh
package.json		package.json
test-mcp-http.js		test-mcp-http.js
test-mcp-stdio.js		test-mcp-stdio.js
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Navigation Menu

Repository files navigation

Design Patterns MCP Server

Quick Start

Tooling and build hygiene

Features

Available Pattern Categories

Architecture

Usage

Finding Patterns

MCP Tools

Installation

Prerequisites

Setup with Bun

Setup with npm

MCP Configuration

Environment Variables

Docker Deployment

Quick Start

Docker Compose

Environment Variables

Endpoints (HTTP mode)

Commands

Testing

Architecture Patterns

Vector search (runtime honesty)

Contributing

License

Resources

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

Design Patterns MCP Server

Quick Start

Tooling and build hygiene

Features

Available Pattern Categories

Architecture

Usage

Finding Patterns

MCP Tools

Installation

Prerequisites

Setup with Bun

Setup with npm

MCP Configuration

Environment Variables

Docker Deployment

Quick Start

Docker Compose

Environment Variables

Endpoints (HTTP mode)

Commands

Testing

Architecture Patterns

Vector search (runtime honesty)

Contributing

License

Resources

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages