Provides design-pattern selection expertise to AI coding agents by analyzing system descriptions and retrieving matching patterns across multiple languages.
Also known as olk/design-pattern-mcp, design-pattern-mcp
- Stars
- 0
- Tools
- 9
- Downloads, 30 days
- —
- Latest version
- 1.0.1
- Last commit
- Nov 15, 2026
- License
- MIT
What is Design Pattern MCP?
Design Pattern provides design-pattern selection expertise to AI coding agents by analyzing system descriptions and retrieving matching patterns across multiple languages. It exposes 9 tools, such as select_design_patterns, analyze_design, generate_design.
Summary generated from the project's README
About Design Pattern MCP server
Design Pattern MCP provides specialized design-pattern selection expertise to AI coding agents. It functions by analyzing free-text system descriptions to retrieve matching patterns from a catalog of 486 built-in patterns. Each pattern is realized across 13 concrete languages plus a generic binding. The server can generate complete designs including primary and supporting patterns, participants, interactions, and implementation steps, while evaluating them against eight quality axes such as testability, scalability, and security.
Developers can deploy this server locally using Docker or via uv for local development. It supports multiple transport methods including stdio for Claude Code and Codex CLI, or streamable-http for OpenCode. Users must provide a generator API key, such as a Minimax AI key, to power the reasoning engine. For long-running design tasks that might exceed client timeouts, the server offers an asynchronous job pattern using submit_design_job and get_design_status to manage background processing.
What you can do with it
- 1Automated design pattern selectionAn AI agent can analyze a natural language description of a system to find the most appropriate design patterns.
- 2Generating implementation blueprintsA developer can request a full design that includes specific implementation steps and language-bound variants.
- 3Evaluating architectural qualityThe server can assess a proposed design against specific metrics like maintainability and performance.
- 4Managing long-running design tasksUsers can submit complex design requests as background jobs to avoid connection timeouts.
Written from the project's README. Every use case is checked against a quote from it.
How to install Design Pattern MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Design Pattern MCP in Claude Code
$ claude mcp add --env 'DESIGN_PATTERN_GENERATOR_API_KEY=<YOUR_DESIGN_PATTERN_GENERATOR_API_KEY>' --env 'DESIGN_PATTERN_EMBEDDER_BASE_URL=<DESIGN_PATTERN_EMBEDDER_BASE_URL>' --env 'DESIGN_PATTERN_RERANKER_BASE_URL=<DESIGN_PATTERN_RERANKER_BASE_URL>' --env 'DESIGN_PATTERN_EMBEDDER_API_KEY=<YOUR_DESIGN_PATTERN_EMBEDDER_API_KEY>' design-pattern-mcp -- docker run -i --rm docker.io/olkowa/design-pattern-mcp:1.0.1Install Design Pattern MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"design-pattern-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"docker.io/olkowa/design-pattern-mcp:1.0.1"
],
"env": {
"DESIGN_PATTERN_GENERATOR_API_KEY": "<YOUR_DESIGN_PATTERN_GENERATOR_API_KEY>",
"DESIGN_PATTERN_EMBEDDER_BASE_URL": "<DESIGN_PATTERN_EMBEDDER_BASE_URL>",
"DESIGN_PATTERN_RERANKER_BASE_URL": "<DESIGN_PATTERN_RERANKER_BASE_URL>",
"DESIGN_PATTERN_EMBEDDER_API_KEY": "<YOUR_DESIGN_PATTERN_EMBEDDER_API_KEY>"
}
}
}
}Install Design Pattern MCP in VS Code
.vscode/mcp.json
{
"servers": {
"design-pattern-mcp": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"docker.io/olkowa/design-pattern-mcp:1.0.1"
],
"env": {
"DESIGN_PATTERN_GENERATOR_API_KEY": "<YOUR_DESIGN_PATTERN_GENERATOR_API_KEY>",
"DESIGN_PATTERN_EMBEDDER_BASE_URL": "<DESIGN_PATTERN_EMBEDDER_BASE_URL>",
"DESIGN_PATTERN_RERANKER_BASE_URL": "<DESIGN_PATTERN_RERANKER_BASE_URL>",
"DESIGN_PATTERN_EMBEDDER_API_KEY": "<YOUR_DESIGN_PATTERN_EMBEDDER_API_KEY>"
}
}
}
}Install Design Pattern MCP in VS Code CLI
$ code --add-mcp '{"name":"design-pattern-mcp","type":"stdio","command":"docker","args":["run","-i","--rm","docker.io/olkowa/design-pattern-mcp:1.0.1"],"env":{"DESIGN_PATTERN_GENERATOR_API_KEY":"<YOUR_DESIGN_PATTERN_GENERATOR_API_KEY>","DESIGN_PATTERN_EMBEDDER_BASE_URL":"<DESIGN_PATTERN_EMBEDDER_BASE_URL>","DESIGN_PATTERN_RERANKER_BASE_URL":"<DESIGN_PATTERN_RERANKER_BASE_URL>","DESIGN_PATTERN_EMBEDDER_API_KEY":"<YOUR_DESIGN_PATTERN_EMBEDDER_API_KEY>"}}'Install Design Pattern MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"design-pattern-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"docker.io/olkowa/design-pattern-mcp:1.0.1"
],
"env": {
"DESIGN_PATTERN_GENERATOR_API_KEY": "<YOUR_DESIGN_PATTERN_GENERATOR_API_KEY>",
"DESIGN_PATTERN_EMBEDDER_BASE_URL": "<DESIGN_PATTERN_EMBEDDER_BASE_URL>",
"DESIGN_PATTERN_RERANKER_BASE_URL": "<DESIGN_PATTERN_RERANKER_BASE_URL>",
"DESIGN_PATTERN_EMBEDDER_API_KEY": "<YOUR_DESIGN_PATTERN_EMBEDDER_API_KEY>"
}
}
}
}Install Design Pattern MCP in Codex
$ codex mcp add design-pattern-mcp --env 'DESIGN_PATTERN_GENERATOR_API_KEY=<YOUR_DESIGN_PATTERN_GENERATOR_API_KEY>' --env 'DESIGN_PATTERN_EMBEDDER_BASE_URL=<DESIGN_PATTERN_EMBEDDER_BASE_URL>' --env 'DESIGN_PATTERN_RERANKER_BASE_URL=<DESIGN_PATTERN_RERANKER_BASE_URL>' --env 'DESIGN_PATTERN_EMBEDDER_API_KEY=<YOUR_DESIGN_PATTERN_EMBEDDER_API_KEY>' -- docker run -i --rm docker.io/olkowa/design-pattern-mcp:1.0.1Install Design Pattern MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.design-pattern-mcp] command = "docker" args = ["run", "-i", "--rm", "docker.io/olkowa/design-pattern-mcp:1.0.1"] [mcp_servers.design-pattern-mcp.env] DESIGN_PATTERN_GENERATOR_API_KEY = "<YOUR_DESIGN_PATTERN_GENERATOR_API_KEY>" DESIGN_PATTERN_EMBEDDER_BASE_URL = "<DESIGN_PATTERN_EMBEDDER_BASE_URL>" DESIGN_PATTERN_RERANKER_BASE_URL = "<DESIGN_PATTERN_RERANKER_BASE_URL>" DESIGN_PATTERN_EMBEDDER_API_KEY = "<YOUR_DESIGN_PATTERN_EMBEDDER_API_KEY>"
Install Design Pattern MCP in Gemini CLI
$ gemini mcp add -s user -e 'DESIGN_PATTERN_GENERATOR_API_KEY=<YOUR_DESIGN_PATTERN_GENERATOR_API_KEY>' -e 'DESIGN_PATTERN_EMBEDDER_BASE_URL=<DESIGN_PATTERN_EMBEDDER_BASE_URL>' -e 'DESIGN_PATTERN_RERANKER_BASE_URL=<DESIGN_PATTERN_RERANKER_BASE_URL>' -e 'DESIGN_PATTERN_EMBEDDER_API_KEY=<YOUR_DESIGN_PATTERN_EMBEDDER_API_KEY>' design-pattern-mcp docker -- run -i --rm docker.io/olkowa/design-pattern-mcp:1.0.1Install Design Pattern MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"design-pattern-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"docker.io/olkowa/design-pattern-mcp:1.0.1"
],
"env": {
"DESIGN_PATTERN_GENERATOR_API_KEY": "<YOUR_DESIGN_PATTERN_GENERATOR_API_KEY>",
"DESIGN_PATTERN_EMBEDDER_BASE_URL": "<DESIGN_PATTERN_EMBEDDER_BASE_URL>",
"DESIGN_PATTERN_RERANKER_BASE_URL": "<DESIGN_PATTERN_RERANKER_BASE_URL>",
"DESIGN_PATTERN_EMBEDDER_API_KEY": "<YOUR_DESIGN_PATTERN_EMBEDDER_API_KEY>"
}
}
}
}Needs a key before it starts
Started on 16 Nov 2026 with no keys, it stopped and asked for one, so a client sees no tools until you set the variables above.
Design Pattern MCP tools 9
Detected from the READMEselect_design_patternsanalyze_designgenerate_designevaluate_designsubmit_design_jobget_design_statuscancel_designlist_design_patternsget_design_pattern
Configuration
DESIGN_PATTERN_GENERATOR_API_KEYRequiredSecretAPI key for the generator LLM (LiteLLM provider).
DESIGN_PATTERN_EMBEDDER_BASE_URLRequiredRequired: the dense retrieval leg embeds the 438-record catalogue during startup warmup and the server refuses to start when the endpoint is unreachable. TEI embeddings endpoint: on the Docker host use http://host.docker.internal:8080 (add --add-host=host.docker.internal:host-gateway on Linux); on a shared Docker network use http://design-pattern-tei-embed:8080.
DESIGN_PATTERN_RERANKER_BASE_URLRequiredRequired: retrieval runs a mandatory TEI cross-encoder rerank whenever the fused pool has more than one candidate. On the Docker host use http://host.docker.internal:8080; on a shared Docker network use http://design-pattern-tei-rerank:8080.
DESIGN_PATTERN_EMBEDDER_API_KEYSecretAPI key for the embedder. Keyless TEI accepts any non-empty value; use 'not-needed' there.
DENSE_CACHE_PATHDESIGN_PATTERN_GENERATOR_BASE_URLOpenAI-compatible base URL (LiteLLM api_base).
DESIGN_PATTERN_GENERATOR_MODELModel name, combined as <provider>/<model> via LiteLLM.
DESIGN_PATTERN_GENERATOR_PROVIDERLiteLLM provider prefix, e.g. openai, anthropic, openrouter.
DESIGN_PATTERN_PATTERN_DIRECTORYDirectory with the catalog records (*.json main records plus per-language files). The image bakes the 438-record catalogue at /app/pattern.
GENERATOR_API_KEYGENERATOR_BASE_URLGENERATOR_MODELGENERATOR_PROVIDERMINIMAXAI_API_KEYPROMPT_STABLE_PREFIXREASONING_MAX_INJECTED_CHARSVALIDATION_TRUNCATION_RERUN
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packageNot checked
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledPass
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesNot checked
README
View on GitHubdesign-pattern-mcp
An MCP (Model Context Protocol) server that provides design-pattern selection expertise to AI coding agents. Given a free-text description of a system, it analyses the problem, retrieves matching design patterns (from 486 built-in patterns, each realized in 13 concrete languages plus a generic binding), generates a concrete design with a primary pattern, supporting patterns, participants, interactions, implementation steps, and language-bound variants, and evaluates it against eight design-level quality axes (testability, extensibility, maintainability, simplicity, performance, reliability, security, scalability). The pipeline (analyze → weights ∥ retrieval → generate → evaluate → bounded refine) and its wire contract are specified in docs/implementation-guide.md.
Table of Contents
- ⚡ Quickstart
- Install via AI Agent
- 🔌 Connect Your Agent
- 🧑🏫 SKILL for AI Agents
- 🧪 Use the Tools
- 🛠️ Tools at a Glance
- 💬 Prompts
- 📖 Pattern Catalog
- Working Together with architecture-pattern-mcp
- Install Alternatives
- Configuration
- Structured Reasoning
- Long-running tools & timeouts
- Benchmarks & Verification
- Troubleshooting
- Building & Development
- Publishing
- systemd Service (Linux)
- License
⚡ Quickstart
# 1. Clone
git clone https://git.odvlh.xyz/olli/design-pattern-mcp.git && cd design-pattern-mcp
# 2. Add your API key
export MINIMAXAI_API_KEY=your_key_here
# 3. Build + start (three images: MCP server + TEI embed + TEI rerank)
make docker-build-all
make docker-up
# 4. Demo (analyze-only: fast. For the full design: make client-design)
make client-analyze
make client-async # full design via the background job trio
Server starts on streamable-http at http://localhost:8822/mcp (dev compose maps host 8822 → container 8050). make client-analyze / make client-design target http://localhost:8822/mcp; override with CLIENT_URL.
Install via AI Agent
To have an AI coding agent install the Docker stack from prebuilt images (no local build), point it at INSTALL.md — the non-interactive agent runbook (copy-paste commands, expected outputs, verification probes).
Clone this repo, then follow INSTALL.md Path A (compose stack, port 8822).
My generator API key is: sk-...
Pick one path in INSTALL.md:
- Path A — Compose stack (
:8822): evaluating / developing, no sudo needed. Own TEI sidecar copies. - Path B — systemd stack (
:8812): persistent host service, starts at boot, needssudo. Uses the sharedpattern-tei-infraTEI stack.
The agent needs a repo clone, Docker ≥ v2.20 with group membership, ~8 GB free, a MINIMAXAI_API_KEY (or another provider per INSTALL.md#switching-the-generator-llm), and linux/amd64 (on arm64 it builds locally via make docker-build-all). Dev and systemd stacks run concurrently on their default host ports (8822 vs 8812). After install, continue with Connect Your Agent below.
🔌 Connect Your Agent
Claude Code
# Install (one-time)
uv pip install -e .
# Run as stdio subprocess — pass the API key via env
claude mcp add design-patterns \
-e GENERATOR_PROVIDER=minimax \
-e GENERATOR_MODEL=minimax/MiniMax-M2.7 \
-e GENERATOR_BASE_URL=https://api.minimax.io/v1 \
-e GENERATOR_API_KEY=your_key \
-- design-pattern-mcp --transport stdio
Stdio mode needs the TEI endpoints reachable (default http://design-pattern-tei-embed:8080 and the reranker URL from config/config.json) — either run the compose stack's sidecars or set EMBEDDER_BASE_URL / RERANKER_BASE_URL to your own. For a no-network smoke run, start with --offline (deterministic lexical-only retrieval instead of TEI).
OpenCode
OpenCode uses HTTP transport. Start the server first, then configure opencode:
# Terminal 1: start the server
make docker-up
# or locally:
uv run design-pattern-mcp --transport streamable-http --port 8050
# Terminal 2: add to ~/.config/opencode/opencode.json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"design-patterns": {
"type": "remote",
"url": "http://localhost:8822/mcp"
}
}
}
Note: the generator API key is read by the server from its config file (
config/config.json,{env:...}placeholders), not from opencode's environment.
Codex CLI
# Install (one-time)
uv pip install -e .
Add to ~/.codex/config.toml:
[mcp_servers.design-patterns]
command = "design-pattern-mcp"
args = ["--transport", "stdio"]
[mcp_servers.design-patterns.env]
GENERATOR_PROVIDER = "minimax"
GENERATOR_MODEL = "minimax/MiniMax-M2.7"
GENERATOR_BASE_URL = "https://api.minimax.io/v1"
GENERATOR_API_KEY = "your_key"
Or via CLI:
codex mcp add design-patterns \
-e GENERATOR_API_KEY=your_key \
-- design-pattern-mcp --transport stdio
🧑🏫 SKILL for AI Agents
The SKILL in skills/design-pattern-mcp/ is written for Oh My Pi (OMP), where this server's tools are reached as xd://mcp__design_pattern_local_* devices and every MCP request is bounded by a deadline (OMP_MCP_TIMEOUT_MS → per-server timeout → 30 s). It teaches the agent which entry point fits that deadline, how to read the results, and the full workflow recipes.
skills/design-pattern-mcp/
├── SKILL.md # OMP constraints, entry-point decision guide, device quick reference
└── references/
├── tools.md # 9 tool signatures, arg shapes, status codes
└── workflows.md # workflow recipes, result interpretation, troubleshooting
Install for OMP — copy the skill directory into OMP's user skills root:
cp -r skills/design-pattern-mcp ~/.omp/agent/skills/
The skill then tells the agent:
- Which entry point fits OMP's 30 s deadline: the async job trio by default;
select_design_patterns(full pipeline) takes 2–10 min - Which path fits the job:
analyze_designwhen the agent writes the code itself (decisions and rationale, no generated design), the full pipeline when the caller wants the design - That
job_idis the only durable handle — persist it (SQLite job store,JOBS_DB) - How to phrase
description(component names + responsibilities + constraints), andlanguage,paradigm,focusas separate structured arguments - How to interpret
overview.score(0–100),findings[], and per-part selections
The tool schemas in references/ are client-agnostic; only the deadline/device guidance is OMP-specific.
🧪 Use the Tools
All pipeline tools take a free-text description as the primary argument. The examples below show the exact tool call shape so you can use them in any MCP client or API consumer.
Design your first selection
In Claude Code (or any MCP client), paste the natural-language instruction:
We're building the ingestion path of an IoT platform: a Kafka consumer
service parses 10k events/sec, an enricher adds geolocation from Redis,
and a writer persists to InfluxDB and S3. Components: consumer, parser,
enricher, sink. Constraints: at-least-once delivery, backpressure, Python.
Your agent calls select_design_patterns internally. The server returns the DesignResult: overview (primary pattern, supporting patterns, principles, score, reasoning), applications[] (participants, interactions, implementation_steps, code_sketch, language_binding with the bound variant), interactions[], quality_attributes, test_strategy, and risks[].
Coding agents that write the code themselves should call analyze_design instead. It runs the same ANALYZE phase (§1–§8: brief repair → decision parts → per-part retrieval → quality weights → selection) and stops there: you get the repaired brief, the decision parts and one selection per part (primary, supporting patterns, ranked alternatives, veto ledger, weights) with no generated applications and no evaluation. The selection names what to apply per part, not how — participants, implementation steps,
code sketches and language bindings are materialized by generate_design from that payload (or
read via get_design_pattern per pattern); implement from the applications, never from the
bare pattern names. select_design_patterns remains the design path — it continues through GENERATE → EVALUATE, where the bulk of a full run's wall clock goes. Either way, the decisions come from the same ANALYZE stage — a fresh LLM analysis per call, so neither path is idempotent; pass the analyze_design payload to generate_design if you later want the materialized applications.
Or call tools directly from your agent:
Call select_design_patterns with:
description: "IoT ingestion path: Kafka consumer (10k events/sec) → JSON parse
→ Redis geo-enrich → InfluxDB + S3 sink. At-least-once, backpressure."
language: "python"
Call list_design_patterns() # all 486 patterns
Call list_design_patterns(category="workflow-messaging")
Call get_design_pattern(name="process-manager")
Async job pattern: submit_design_job + get_design_status
For clients with short request timeouts. submit_design_job returns a job_id immediately; poll get_design_status until done:
# Step 1: start the job
Call submit_design_job with:
description: "IoT ingestion path: Kafka consumer → parse → Redis enrich → InfluxDB + S3"
# Step 2: poll every 10-30 seconds
Call get_design_status with:
job_id: "<job_id from step 1>"
# → status is "pending" | "running" | "completed" | "failed" | "cancelled"
# When status is "completed", the full DesignResult is in result
# When status is "failed", the error is in error
In Python (via the MCP client API — see examples/design_pattern_client_async.py):
import asyncio
from fastmcp import Client
SERVER = "http://localhost:8822/mcp"
POLL_EVERY = 15 # seconds
async def main():
client = Client(SERVER)
async with client:
# Step 1: start the job
result = await client.call_tool(
"submit_design_job",
{"description": "IoT ingestion: Kafka → parse → enrich → sink"},
)
job_id = result.data["job_id"]
print(f"Job started: {job_id}")
# Step 2: poll until terminal state
while True:
await asyncio.sleep(POLL_EVERY)
status = await client.call_tool("get_design_status", {"job_id": job_id})
data = status.data
print(f" status={data['status']}")
if data["status"] in ("completed", "failed", "cancelled"):
break
print(data.get("result", data)) # full DesignResult when completed
asyncio.run(main())
See examples/design_pattern_client_async.py for the complete runnable example. Run it with:
make docker-up # Terminal 1
make client-async # Terminal 2
🛠️ Tools at a Glance
| Tool | Description |
|---|---|
select_design_patterns |
Design path for callers that want the generated design: full pipeline (analyze → weights ∥ retrieval → generate → evaluate → refine, LOOP_MAX_TRIES attempts), returning applications with participants, implementation steps, bound variants, quality attributes, a test strategy and risks. Long-running (2–10 min). Heartbeat-defended. |
analyze_design |
Analysis-only path for coding agents that write the code themselves: requirements → brief, decision parts and per-part selection (primary, supporting, alternatives, vetoes, weights) with no generated design. Follow with generate_design (same payload) for participants, steps and language bindings before coding. Long-running (~1 min). |
generate_design |
Materialize applications from a prior analyze_design payload or explicitly named patterns. Long-running (~1 min). |
evaluate_design |
Score an existing design JSON against the eight quality axes. Long-running (~30 s). |
submit_design_job |
Start a background selection job and return a job_id immediately (SQLite-backed, survives server restart). For short-timeout clients. |
get_design_status |
Poll job status; returns the full DesignResult when completed. |
cancel_design |
Cancel a running job (best-effort; takes effect at the next pipeline stage boundary). |
list_design_patterns |
List patterns with name/category/description; filter by category and/or language. |
get_design_pattern |
Full pattern JSON for one name (loader-resolvable, alias-aware). |
Description, language, paradigm, focus are structured parameters — pass them as separate tool arguments, not embedded in the description text. Variant selection is signal-based: there is no catalog-wide variant_id enum (variant ids are per-(pattern, language) and change with catalog edits; valid ids are discoverable via the design-patterns://variants resource and previous runs' bound_variant).
💬 Prompts
This server also exposes four user-invoked workflow prompts (slash commands in MCP clients). Unlike tools, the LLM does not autonomously invoke prompts — the user selects one and fills in its arguments. Each prompt encodes a tested tool-orchestration recipe, and none hardcode pattern names (category guidance quotes the live catalog's own structure).
| Prompt | Args | What it does |
|---|---|---|
/select_design_patterns_workflow |
description*, language, architecture_style, paradigm, focus | Guided end-to-end selection workflow |
/explore_pattern_catalog |
category |
Live catalog discovery via the design-patterns://variants resource + decision probes |
/evaluate_my_design |
description* | Compare the catalog's selection against an existing design |
/compare_pattern_candidates |
decision*, candidates* | Two or three named patterns side-by-side for one decision; one selection run per candidate |
* = required argument
Tool-only clients
Clients that only support the tools protocol (no native prompts/list or prompts/get) can access all four workflow prompts via the generated list_prompts and get_prompt tools, which route through the server's middleware chain exactly as native prompt calls do.
📖 Pattern Catalog
Via MCP tools (recommended — works in all clients)
list_design_patterns() # all 486 patterns
list_design_patterns(category="concurrency-resilience") # filter by category
get_design_pattern(name="acceptor-connector") # full pattern JSON
Valid category values (the nine decision groups, catalog sections 1–9): domain-modeling, construction-composition, behavior-selection, interaction-boundary, workflow-messaging, persistence-state, concurrency-resilience, security-verification, specialized-components.
Via MCP resources
mcp_read_resource(uri="design-patterns://variants")
Groups every pattern's language realizations by language, then pattern — the realization vocabulary for language/paradigm/focus hints and variant selection.
What one pattern record contains
The loader (src/patterns/loader.py) joins each record from 14 files: one generic entry plus one per concrete language (13 languages: C, C++, C#, Go, Java, JavaScript, Kotlin, Python, Ruby, Rust, Scala, Swift, TypeScript). Each language binding carries support (native / idiomatic / discouraged), idiom_name, implementation_notes, an optional code_sketch, pitfalls, and — for discouraged support — a required alternative. Language bindings can declare variants[] (per-language realizations, 4,953 across the catalog) with a default_variant. Each record also declares related_patterns (loader-resolvable canonical names only) and related_patterns_notes (per-link prose distinctions).
Alias resolution is built in: the loader turns 993 raw alias entries → 978 distinct after case-folding → 966 indexed alias mappings, dropping ambiguous aliases (an alias that is itself another record's name or claimed by two records; the ambiguous_aliases health field lists them), so get_design_pattern(name="circuit-breaker") and its alias spellings resolve to the same record. Startup fails fast when the catalog's enums drift from docs/pattern-schema.json (assert_enums_in_sync).
Working Together with architecture-pattern-mcp
This server answers how each unit is coded (design patterns); the sibling architecture-pattern-mcp answers which system shape to build (architecture). An architecture pattern structures the whole system — its components, their relationships, and its API/data/event contracts (e.g. event-driven, pipe-and-filter, microservices, chosen from the sibling's 40-pattern catalog). A design pattern solves one recurring implementation problem inside a single component — its participants, interactions, and language-bound code (e.g. observer, process-manager, circuit-breaker, chosen from the 486-pattern catalog above with 13 language bindings each).
Recommended order — macro first, micro second:
1. Call the sibling's design_architecture with:
requirements: "ETL pipeline for IoT: Kafka → JSON → Redis geo-enrich → InfluxDB + S3"
domain: "data-processing"
# → components (Kafka source, parser filter, enricher, sinks),
# relationships, API contracts, data models, event contracts
# Keep design_architecture for callers that want the design: the sibling's LLM
# generates the architecture artifact (5–10 min) rather than only advising.
2. For each component with non-trivial internal logic, ask for the pattern decisions:
- coding agent writes the code itself → analyze_design with:
description: "<component name + responsibilities + constraints from step 1>"
language: "python"
# → decision parts + per-part selection with rationale; no generated applications
- caller wants the generated pattern design → select_design_patterns with:
description: "<component name + responsibilities + constraints from step 1>"
language: "python"
# → primary + supporting patterns, participants, implementation_steps,
# code_sketch with the bound language variant
Both pattern calls run the same ANALYZE stage (§1–§8); analyze_design stops there, before generation and evaluation. Each call runs its own LLM analysis (neither tool is idempotent), so two calls can select differently on the same description.
Concrete handoff on the IoT example: the sibling emits the pipe-and-filter architecture (Kafka source → JSON parser filter → geolocation enricher → InfluxDB/S3 sinks, with at-least-once delivery and backpressure in the contracts). The geolocation enricher's cache-miss path then comes here: analyze_design returns the circuit-breaker + retry decision with its rationale when your agent writes the enricher, while select_design_patterns additionally materializes the applications (participants, implementation_steps, a Python code_sketch) when the caller wants the generated design — internals the architecture-level component contract references but never implements.
On the analyze_design path, run generate_design on the returned payload (or
get_design_pattern("circuit-breaker") for the Python binding and pitfalls) before writing
the enricher code.
Run both servers side by side (dev host ports :8060 architecture, :8822 design-pattern; systemd :8050 / :8812). They are independent — either order works for exploration — but architecture-first keeps component boundaries stable while this server fills in the internals.
Install Alternatives
Docker (manual)
# Build the three images (dense vector cache generated and baked in)
make docker-build-all
# Run with your API key
MINIMAXAI_API_KEY=your_key make docker-up
First docker-build-all generates the FAISS dense cache (data/dense-cache/) via the TEI embed sidecar and bakes it into the server image; make docker-build-nocache skips that (first startup then embeds the corpus, ~19 min).
Both compose stacks back that cache directory with a named Docker volume
(design-pattern-mcp-dev-dense-cache / design-pattern-mcp-systemd-dense-cache,
mounted at /app/data/dense-cache). A fresh volume is seeded from the image's baked
snapshot, and every later write-back lands in the volume — so a restarted or recreated
container reloads the vectors instead of re-embedding the catalog (one probe embedding
instead of ~486 document embeddings). docker compose down keeps the volume.
Two operational consequences: an existing volume shadows a newer baked snapshot
after an image rebuild, and the fingerprint guards then force exactly one re-embed — so
after a catalogue- or model-changing rebuild delete the volume first
(docker volume rm design-pattern-mcp-dev-dense-cache) and let up -d re-seed it.
And DENSE_CACHE_MODE=off disables the cache entirely — the compose stacks forward the
host value into the container, and a host run reads it directly. Details:
Dense embedding cache.
Local Development (uv)
Prerequisites: Python 3.12+, uv
# Install
make install
# Configure — the shipped wire config with {env:...} placeholders
export GENERATOR_PROVIDER=minimax
export GENERATOR_MODEL=minimax/MiniMax-M2.7
export GENERATOR_BASE_URL=https://api.minimax.io/v1
export GENERATOR_API_KEY=your_key
# Dense cache (host runs): the image default /app/data/dense-cache does not exist
# on a workstation, so point it at the gitignored repo snapshot. `make embed-cache`
# fills it; otherwise the first start embeds once and writes it (later starts warm).
export DENSE_CACHE_PATH="$PWD/data/dense-cache"
Design Pattern MCP questions
How do I add Design Pattern MCP to Claude Code?
Run claude mcp add --env 'DESIGN_PATTERN_GENERATOR_API_KEY=<YOUR_DESIGN_PATTERN_GENERATOR_API_KEY>' --env 'DESIGN_PATTERN_EMBEDDER_BASE_URL=<DESIGN_PATTERN_EMBEDDER_BASE_URL>' --env 'DESIGN_PATTERN_RERANKER_BASE_URL=<DESIGN_PATTERN_RERANKER_BASE_URL>' --env 'DESIGN_PATTERN_EMBEDDER_API_KEY=<YOUR_DESIGN_PATTERN_EMBEDDER_API_KEY>' design-pattern-mcp -- docker run -i --rm docker.io/olkowa/design-pattern-mcp:1.0.1 in your terminal. Add --scope user to make it available in every project.
How do I add Design Pattern MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Design Pattern MCP provide?
It exposes 9 tools, including select_design_patterns, analyze_design, generate_design, evaluate_design, submit_design_job.
What kind of design patterns does the server provide?
The server includes 486 built-in patterns, each realized in 13 concrete languages plus a generic binding.
How can I use the server if my AI client has short request timeouts?
You can use the async job pattern by calling submit_design_job to get a job_id, then polling get_design_status until the process is complete.
What quality metrics are used to evaluate a design?
Designs are evaluated against eight design-level quality axes: testability, extensibility, maintainability, simplicity, performance, reliability, security, and scalability.