Design Patterns MCP Server

An intelligent MCP (Model Context Protocol) server that provides design pattern recommendations using hybrid search (semantic + keyword + graph augmentation). Access 710 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.

Related MCP server: Acemcp

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

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/              # 710 JSON pattern definitions (see `feature-flag.json`)
└── design-patterns.db     # SQLite database with 710 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

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 the project quickstart for client-specific configuration examples.

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 654 test cases across 77 test files with 100% pass rate (0 failures, 0 skips):

• Contract Tests: MCP protocol compliance validation

• Integration Tests: Component interaction tests against live SQLite DB and embeddings

• 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:

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 (~710 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 the contributing guide.

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

Release Notes

v0.7.2 — Version Bump (2026-08-16)

• Canonical version bumped from 0.7.1 → 0.7.2 across active source and documentation files.

• Files updated: package.json, src/mcp-server.ts (Server registration + runtime info), AGENTS.md, CLAUDE.md (canonical-identity header), README.md (badge, release-notes section, version footer), CHANGELOG.md (new entry). docs/IMPROVEMENTS_03.md and QUICKSTART.md audit-evidence references preserved untouched per state #45.

• Stale version references corrected: AGENTS.md and CLAUDE.md header (version 0.6.0) → (version 0.7.2) (was 7 minor versions behind the actual package.json).

• Runtime self-report now advertises 0.7.2 to MCP clients via Server constructor and /info endpoint.

• No code-level behavioural change: pure release/version-canonicalisation patch.

• Tests: full suite preserved (no test files modified), typecheck clean.

v0.7.1 — Lint + Test Stabilization (2026-08-16)

• Test suite fully validated: 654/654 GREEN, 0 skips, 0 todos (was 651/654 with 3 pre-existing flakes).

• Resolved data/.git leak introduced by db:setup pipeline (data-hygiene test).

• Aligned two outdated tests with the BUG-007 contract: snake_case search_type is silently ignored by validateSearchPatternsArgs and the canonical default hybrid strategy is applied.

  • tests/unit/input-validation.test.ts

  • tests/unit/mcp-server-search.test.ts

• README.md version drift corrected: trailing block now reflects canonical 0.7.0 → 0.7.1 baseline, badge + Production Ready + Testing section aligned with current 654-test suite.

• Lint baseline restored: 0 problems, exit 0 (was 2 errors + 6 warnings).

  • Removed unused HealthStatus import in src/mcp/http-transport.ts.

  • Added targeted eslint-disable for require-await on the synchronous check() in src/health/embedding-coverage-health-check.ts (interface conformance preserved).

  • Refactored ensureBM25() in src/handlers/keyword-search-handler.ts to return BM25Scorer, eliminating 4 non-null assertions at the call sites.

  • Replaced 2 non-null assertions on results.find() in tests/unit/bm25-scorer.test.ts with explicit toBeDefined guards.

• bun run typecheck clean.

v0.7.0 — Catalog Expansion (2026-08-16)

• 24 new design patterns added from docs/01_Agentic_Design_Patterns.md and docs/02_Data_Engineering_Design_Patterns.md:

  • 3 Agentic AI: Multi-Agent Collaboration, Goal Setting and Monitoring, Exception Handling and Recovery.

  • 21 Data Engineering: Aligned Fan-In, Unaligned Fan-In, Bin Pack Orderer, Exclusive Choice, FIFO Orderer, Fine-Grained Accessor for Resources, Fine-Grained Accessor for Tables, Fine-Grained Tracker, In-Place Overwriter, Isolated Sequencer, Metadata Decorator, Metadata Enhancer, Offline Observer, Schema Compatibility Enforcer, Schema Migrator, Secretless Connector, Secrets Pointer, Single Runner, Skew Detector, SLA Misses Detector, Vertical Partitioner.

• Catalog grew from 686 → 710 patterns (Agentic AI: 3→6, Data Engineering: 4→25).

• Integrity check PASS: 710 patterns, 151 valid relationships.

• 654/654 tests pass (100% green, 0 skips, 0 todos).

License

MIT License - see LICENSE for details.

Resources

• Model Context Protocol

• Vector search notes (sql.js vs sqlite-vec) — see contributing guide

• MCP tools surface reference

• Documentation index

• Design Patterns Catalog

Version: 0.7.2 Last Updated: August 2026 Patterns: 710 JSON definitions (highlight: Feature Flag / Feature Toggle) Tests: 654 test cases | 100% pass rate (0 failures, 0 skips)

See also: the latest adversarial quality assurance report (16 findings: 1 critical, 9 high-priority, 6 minor). Findings cover search pipeline correctness, configuration drift, transport security, and documentation sync.