Design Pattern MCP

design-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
• Claude Code
• OpenCode
• Codex CLI
• 🧑🏫 SKILL for AI Agents
• 🧪 Use the Tools
• 🛠️ Tools at a Glance
• 💬 Prompts
• 📖 Pattern Catalog
• Working Together with architecture-pattern-mcp
• Install Alternatives
• Docker (manual)
• Local Development (uv)
• 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](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, needs sudo. Uses the shared pattern-tei-infra TEI 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_design when the agent writes the code itself (decisions and rationale, no generated design), the full pipeline when the caller wants the design
• That job_id is the only durable handle — persist it (SQLite job store, JOBS_DB)
• How to phrase description (component names + responsibilities + constraints), and language, paradigm, focus as 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: " "

→ 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          # Termina