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

Related MCP server: MCPatterns

⚡ 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, 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: "<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

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).

* = 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"

# Run the server
uv run design-pattern-mcp --transport stdio               # for Claude Code / Codex
uv run design-pattern-mcp --transport streamable-http --port 8050   # HTTP
uv run design-pattern-mcp --health                        # offline readiness check (config + catalog + index)

Or use the installed console script (after make install): design-pattern-mcp.

The TEI sidecars are required for full retrieval quality: a dense leg (Qwen3-Embedding-0.6B via the embed sidecar) and a BM25 leg are fused at startup (service_healthy ordering guarantees the embedder is up before the server accepts requests — a failed index warm-up refuses server start). The reranker sidecar (gte-reranker-modernbert-base) reranks candidate patterns. Without reachable sidecars, start with --offline (deterministic lexical-only retrieval, no network).

TEI startup: both sidecar images (docker/Dockerfile.tei-embed, docker/Dockerfile.tei-rerank) ship a self-built TEI router (v1.9.4 + unmerged PR #884) with WARMUP_TOKENS=0 by default — this skips the synthetic warmup pass (measured ~131 s embed / ~78 s rerank) so containers become ready after weight load only. Override per sidecar via TEI_WARMUP_TOKENS / TEI_RERANK_WARMUP_TOKENS (positive N warms with N tokens instead; values > MAX_BATCH_TOKENS are rejected at startup).

GPU TEI: the shipped sidecars are CPU images (cpu-1.9). On a host with a TEI-CUDA-supported NVIDIA GPU (compute capability ≥ 7.5) plus the NVIDIA container toolkit, make docker-build-tei-embed-gpu builds the embed sidecar on the CUDA base (ghcr.io/huggingface/text-embeddings-inference:cuda-1.9) and make docker-up-gpu starts the dev stack with docker/docker-compose.gpu.yml (reserves 1 GPU). The override covers the embed sidecar only — the reranker stays on CPU. On GPU a small positive WARMUP_TOKENS warms kernels at startup instead of skipping the pass.

Already-running embedder/reranker: when embedding and reranking endpoints already run on other servers, point the MCP server at them via EMBEDDER_BASE_URL (OpenAI-compatible route, http://<host>:8080/v1) plus RERANKER_BASE_URL (http://<host>:8080) and skip the sidecars. The embedder forwards EMBEDDER_MODEL (default openai//data/embedding-model) and EMBEDDER_API_KEY through LiteLLM — provider/model syntax is documented in the LiteLLM embedding docs. The reranker is not a LiteLLM client — it POSTs {base_url}/rerank directly (src/patterns/safe_tei_rerank.py), so RERANKER_MODEL (default Alibaba-NLP/gte-reranker-modernbert-base) is a TEI model name, not a LiteLLM model string. A remote embedder serving a different model invalidates the baked dense cache — regenerate it with make embed-cache so vectors match the serving model.

Configuration

config.json

The server reads config/config.json relative to the repo (override with --config-path or CONFIG_PATH). Every value is a {env:VAR:-default} placeholder that expands at load time, so the shipped file doubles as the env-var reference. The schema (abridged):

{
  "logging_level": "{env:LOGGING_LEVEL:-INFO}",
  "transport": "{env:TRANSPORT:-stdio}",
  "host": "{env:HOST:-0.0.0.0}",
  "port": "{env:PORT:-8050}",
  "generator": {
    "provider": "{env:GENERATOR_PROVIDER:-openai}",
    "config": {
      "model": "{env:GENERATOR_MODEL:-gpt-4o-mini}",
      "base_url": "{env:GENERATOR_BASE_URL:-https://api.openai.com/v1}",
      "api_key": "{env:GENERATOR_API_KEY:-}",
      "temperature": "{env:GENERATOR_TEMPERATURE:-0.1}",
      "timeout_seconds": "{env:GENERATOR_TIMEOUT_SECONDS:-120.0}",
      "generation_batch_size": "{env:GENERATOR_GENERATION_BATCH_SIZE:-5}",
      "generation_max_concurrency": "{env:GENERATION_MAX_CONCURRENCY:-2}",
      "circuit_breaker_failure_threshold": "{env:GENERATOR_CIRCUIT_BREAKER_FAILURE_THRESHOLD:-3}",
      "circuit_breaker_cooldown_seconds": "{env:GENERATOR_CIRCUIT_BREAKER_COOLDOWN_SECONDS:-60.0}"
    }
  },
  "embedder":  { "provider": "{env:EMBEDDER_PROVIDER:-tei}", "config": { "base_url": "{env:EMBEDDER_BASE_URL:-http://design-pattern-tei-embed:8080}" } },
  "retrieval": { "bm25_weight": "{env:RETRIEVAL_BM25_WEIGHT:-0.3}", "dense_weight": "{env:RETRIEVAL_DENSE_WEIGHT:-0.7}", "max_concurrent_parts": "{env:RETRIEVAL_MAX_CONCURRENT_PARTS:-1}" },
  "reranker":  { "rerank_text": "{env:RERANK_TEXT:-full}", "rerank_top_n": "{env:RERANK_TOP_N:-10}" },
  "reasoning": { "enabled": "{env:REASONING_ENABLED:-true}", "per_phase": { "analyze": { "enabled": "{env:REASONING_ANALYZE_ENABLED:-true}" }, "weights": { "enabled": "{env:REASONING_WEIGHTS_ENABLED:-true}" }, "generate": { "enabled": "{env:REASONING_GENERATE_ENABLED:-true}" }, "evaluate": { "enabled": "{env:REASONING_EVALUATE_ENABLED:-true}" } }, "max_injected_chars": "{env:REASONING_MAX_INJECTED_CHARS:-}" },
  "validation": { "max_retries": "{env:VALIDATION_MAX_RETRIES:-1}", "retry_on_fail": "{env:VALIDATION_RETRY_ON_FAIL:-true}", "truncation_rerun": "{env:VALIDATION_TRUNCATION_RERUN:-repair}", "truncation_boost_max_completion_tokens": "{env:VALIDATION_TRUNCATION_BOOST_TOKENS:-65536}" },
  "prompts": { "stable_prefix_first": "{env:PROMPT_STABLE_PREFIX:-false}" },
  "loop":  { "max_tries": "{env:LOOP_MAX_TRIES:-2}", "min_quality_score": "{env:LOOP_MIN_QUALITY_SCORE:-50}" },
  "tasks": { "deadline_seconds": "{env:TASKS_DEADLINE_SECONDS:-1800.0}", "heartbeat_enabled": "{env:TASKS_HEARTBEAT_ENABLED:-true}", "heartbeat_interval_seconds": "{env:TASKS_HEARTBEAT_INTERVAL_SECONDS:-30}" },
  "jobs":  { "db_path": "{env:JOBS_DB:-~/.config/design-pattern-mcp/jobs.db}" }
}

Generator LLM (LlamaIndex LiteLLM)

The generator LLM is accessed through the LlamaIndex LiteLLM integration. All provider settings follow LiteLLM's model syntax: <provider>/<model>. The dev stack and benchmark harness default to MiniMax:

Provider list and syntax: LiteLLM Providers documentation. temperature, top_p, top_k, timeout_seconds, and the circuit-breaker knobs map to the corresponding LiteLLM/provider parameters.

Dense embedding cache (restart-durable retrieval)

On by default. The shipped configuration resolves to dense_cache.mode=auto with write=true (Pydantic defaults and config/config.json; both compose stacks set the same values explicitly), and the serving path always passes the cache — the container stacks need no cache configuration at all, and a host run needs exactly one export (DENSE_CACHE_PATH, see the Local Development block). It is switched off only deliberately: DENSE_CACHE_MODE=off (compose stack or host run), mode=off in a config file, the --offline/--health paths (deterministic embedder, no cache), and the benchmark compose override (cold-start measurement). tests/unit/test_config.py::test_dense_cache_defaults and ::test_shipped_config_validates pin the defaults.

The dense retrieval leg is one FAISS index over every catalog record (486 records → 486 document_text embeddings at startup). That matrix is snapshotted to disk next to a manifest and reloaded on the next start, so a restart costs one probe embedding instead of a full corpus pass (~19 min on the CPU TEI sidecar).

• Path: DENSE_CACHE_PATH (/app/data/dense-cache in the image). Contents: manifest.json (the commit marker) + vectors.npy. A directory without a usable manifest is an ordinary miss; mode=require turns a miss into a startup error (ERR_008), mode=off skips the cache read entirely.

• Written immediately after a cold embed (DENSE_CACHE_WRITE=true), so the snapshot is on disk before any later startup step can fail. The vectors file is written before the manifest, so a crash mid-write leaves a directory the next start treats as a miss.

• Containers persist it in a named volume (design-pattern-mcp-dev-dense-cache / design-pattern-mcp-systemd-dense-cache) — the snapshot then survives container recreation, docker compose down and image upgrades. A fresh volume is seeded from the image's baked snapshot; an existing one keeps its own, so after a catalogue- or model-changing rebuild delete it (docker volume rm <name>) before up -d, otherwise the guards force one re-embed (~19 min) and rewrite the volume. A genuinely cold cache needs a cache-less image (make docker-build-nocache) or mode=off — DENSE_CACHE_MODE=off covers both the compose stacks and host runs.

• Rebuilt automatically when the embedding function changes (model string, text instruction, declared model_repo/onnx_variant), when the catalog changes (record count, name order or any document_text — corpus_sha256), when vectors.npy is absent/shape-invalid/off-norm, or when a probe vector shows a different model behind an unchanged configuration (a redeployed TEI sidecar; cosine below dense_cache.probe_min_cosine). Each such change costs exactly one re-embed: the rebuilt snapshot is written back with the new identity, so the next restart hits again (a cache baked by an older release, e.g. without EMBED_MODEL_REPO, misses once for the same reason). Every decision is logged with the directory it used (JSON logger fields in the compose stacks): Dense cache hit (path, records, mode), Dense cache miss (reason, path), Dense cache written (path, records, dimension), Dense cache disabled (mode, path), Dense cache write failed (path, reason) — plus the retriever's summary Dense vectors resolved (source = cache-hit / embedded / disabled, documents).

• Best-effort writes: a read-only or full cache directory logs Dense cache write failed and the run keeps the vectors it just embedded — the cache never fails a start.

• Single writer: no locking. Run one server process per cache directory (dev and systemd stacks use separate volumes; the benchmark harness pins its own disposable data/dense-cache and refuses a cold cache unless mode=off).

• Host runs (uv run python -m src.main) must point DENSE_CACHE_PATH at a writable directory — the shipped default /app/data/dense-cache only exists in the image. Either export DENSE_CACHE_PATH=$PWD/data/dense-cache so a make embed-cache snapshot is reused, or point it at ~/.config/design-pattern-mcp/dense-cache and let the first start write it.

Key environment variables

CLI flags

Structured Reasoning

Before each prompted LLM phase call (analyze / weights / generate / evaluate), the server runs a bounded ThoughtGenerator loop: each step is authored with the generator LLM (one completion per step) and submitted to the shannonthinking and/or code-reasoning MCP servers — structured thinking scratchpads that validate, number, and record each step. The resulting trace is injected into the phase prompt as a <reasoning_context> block. Contract: each thought = 1 LLM completion + 1 MCP tool call, capped by REASONING_MAX_TOTAL_STEPS (default 8). The tools list per phase defaults to both scratchpads; startup health-checks exactly the tools the enabled phases use.

Key properties:

• Embedded in Docker — the image bakes both npm packages into the image; the runtime invokes them directly via node (no network, no npx).

• Auto-fallback to npx outside Docker — missing embedded entry points fall back to npx -y <pkg> (first call downloads).

• Silent per-call degradation — any spawn/timeout/tool failure in an enabled phase logs a WARNING and the phase proceeds with a degraded in-prompt thinking scaffold; a reasoning outage never fails a tool call. A phase disabled via REASONING_<PHASE>_ENABLED=false instead contributes an empty reasoning context — no generator call, no subprocess, no cache entry.

• Loud startup, soft failure — the lifespan health-check reports reasoning health; set REASONING_FAIL_FAST=true to make a broken tool fail startup instead.

• Trace caching — analyze and generate traces are computed once per design request and reused across design-loop attempts; weights and evaluate traces are per-run.

• REASONING_MAX_INJECTED_CHARS — the rendered trace injected downstream can be capped (default uncapped) to cut input tokens on every downstream call.

Latency note: a full run issues 8 reasoning tool calls (2 per phase) as serial subprocesses; reasoning is a material share of end-to-end latency. Measured on the Stage-0 benchmark (MiniMax-M2.7 generator, 18 scenarios, NO_WARMUP=1): shipping config (all phases on) p50 288.4 s / p95 439.6 s; with REASONING_WEIGHTS_ENABLED=false REASONING_EVALUATE_ENABLED=false p50 253.0 s / p95 413.9 s — both arms passed the quality gate (overall hit ≥ baseline Wilson low). The per-phase toggles are the documented way to opt in.

Long-running tools & timeouts

select_design_patterns runs a multi-stage pipeline that takes minutes per call. This is inherent to the workload: the generator LLM processes the fused retrieval candidates, per-part quality weights, and the full output of every previous stage, and produces a large, strictly structured JSON document one token at a time. The design loop repeats generate → evaluate up to LOOP_MAX_TRIES times. If the caller only needs the pattern decisions (the agent writes the code itself), analyze_design runs §1–§8 alone and skips the generate → evaluate loop.

Four bounds govern a run — do not confuse them

The heartbeat defence (applied by default)

Every long-running tool emits progress notifications from a parallel coroutine every 30 seconds (TASKS_HEARTBEAT_INTERVAL_SECONDS). Clients whose idle timers reset on any received data stay alive for the full pipeline duration.

TS-SDK clients (Claude Desktop, Cursor) do not reset their timeout on progress notifications.

The async job trio (for timeout-constrained clients)

submit_design_job(description, language?, ...)  → job_id
get_design_status(job_id)                       → {status, result | error}
cancel_design(job_id)                           → best-effort, next stage boundary

submit_design_job returns a job_id in milliseconds; the pipeline runs in a background task and the store is SQLite (JOBS_DB). Poll every 10–30 seconds. This is the fix that works for TS-SDK clients.

Bypassing client timeouts with a direct HTTP client

examples/design_pattern_client.py is a direct Python HTTP client with no client-side idle timeout — one blocking request, full response regardless of duration:

make docker-up          # Terminal 1
make client-analyze     # Terminal 2: analyze_design only
make client-design      # Terminal 2: select_design_patterns, the long synchronous call

Both targets drive the same direct client (--tool analyze|design). make client-design demonstrates that the server correctly completes long requests — the timeout issue is purely a client-side problem. Host applications that wrap MCP (Claude Desktop, Cursor, …) impose their own timeouts; use the async job trio there.

Benchmarks & Verification

This repo treats selection quality and pipeline latency as measured properties, not claims.

Benchmark harness (tests/benchmark/, make benchmark-*): an 18-scenario corpus with holdout split; make benchmark-live NO_WARMUP=1 OUT=benchmarks/<arm> RUN_ID=<id> runs the full pipeline in-process with per-stage attribution (reasoning., llm., rerank, embed — calls, latency, chars/s, repair counters). make benchmark-analyze runs the same seams and stops after ANALYZE (selection hit/recall/score, no generation); make benchmark-compare accepts an analyze/live pair and reports the hit-rate Newcombe interval, the selection metric deltas and the hit flips, with the p95 latency rule marked inapplicable because the e2e delta is the skipped generation work. make benchmark-selfcheck hand-verifies every metric formula. make benchmark-compare A=<baseline> B=<candidate> applies the preregistered rule — candidate wins iff holdout p95 e2e improves ≥ 15 % AND candidate overall acceptable-primary hit rate ≥ the baseline's overall Wilson lower bound — and exits 1 on candidate-loss. The e2e mode measures the deployed compose stack and is not comparable with the in-process mode.

Reference arms (committed under benchmarks/, all MiniMax-M2.7, 18 scenarios):

The analyze-vs-live pair (2026-10-25, baseline live-20261025, candidate analyze-20261025) measured 12/18 vs 12/18 overall acceptable-primary hits (Newcombe Δ +0.000 [−0.286, +0.286]); holdout 4/6 vs 5/6 (Δ −0.167 [−0.558, +0.295]), recall@5 0.378 vs 0.367. Two scenarios flip in each direction (4 total), so the equal totals are different scenarios; the intervals cover zero on every split. No default was changed on this evidence.

The code levers are shipped as opt-in env configuration, not defaults: the cumulative win claim passed the preregistered gate against base-fresh (holdout p95 410.9 → 297.5 s = 27.6 % ≥ 15 %, overall 13/18 ≥ floor), but the attribution comparison against cfg-reasoning recorded a candidate-loss (+12.5 % < 15 %), so defaults stay behavior-neutral. To opt in:

export VALIDATION_TRUNCATION_RERUN=boost
export REASONING_MAX_INJECTED_CHARS=4000
export PROMPT_STABLE_PREFIX=true

Verification layers (the repo's differentiator):

Every .fizz assertion must kill at least one spec-garden mutant or carry a # spec-explains: justification; a change to a decision module updates the matching .fizz model in the same PR. The normative pipeline spec is docs/implementation-guide.md (§-numbered, mirrored in German as docs/selektions-process-de.md); the wire contract of the tool result is docs/result-schema.json, the catalog record contract is docs/pattern-schema.json.

Troubleshooting

Server starts but tools are not visible

1. Check the agent's MCP connection: Claude Code /mcp, OpenCode opencode mcp list, Codex codex mcp list

2. Verify the server process started and the catalog loaded: uv run design-pattern-mcp --health prints OK plus a JSON readiness report (records, language files, aliases)

3. Confirm the TEI embedder is healthy: docker compose -f docker/docker-compose.yml ps (healthchecks with 120 s embed-model start period)

"Connection refused" or startup failure

Index warm-up refuses server start when the embedder is unreachable (fail-fast rather than breaking your first request):

docker compose -f docker/docker-compose.yml logs design-pattern-tei-embed

Local non-Docker runs must point EMBEDDER_BASE_URL / RERANKER_BASE_URL at reachable endpoints — or start with --offline.

LLM provider errors (502 / 401)

• Confirm GENERATOR_API_KEY (or MINIMAXAI_API_KEY on the dev stack) is set and not expired

• Verify GENERATOR_BASE_URL matches your provider's endpoint

• After 3 consecutive transport failures the circuit opens for 60 s (..._CIRCUIT_BREAKER_* knobs); auth/configuration 4xx never count toward it

ERR_012 / ERR_014

• ERR_012 = cancelled (via cancel_design or a client disconnect at the next stage boundary)

• ERR_014 = whole-run deadline exceeded (TASKS_DEADLINE_SECONDS); raise it explicitly for legitimately longer runs — the in-flight provider coroutine is cancelled, partial results are discarded

Reranker 429s

One full-text rerank request already saturates the CPU TEI sidecar's 16,384-token inference buffer (MAX_BATCH_TOKENS=8192 interacts with request packing; measured 2026-09-25): a cap-2 retrieve_many leg fails outright with HTTP 429 "Model is overloaded". Keep RETRIEVAL_MAX_CONCURRENT_PARTS=1 (shipped default); the server-side invariant also keeps dense_top_k + bm25_top_k ≤ the sidecar's MAX_CLIENT_BATCH_SIZE (48).

Pattern JSON files not loading

• Records are joined from 14 files per pattern (pattern/<name>.generic.json + 13 <language>.json); the generic file is required

• Validate the catalog with ./scripts/verify-patterns.sh (both schemas plus the ajv-inexpressible variant checks; map agreement/orphans are enforced by the startup gate)

• Startup fails on enum drift from the schema (assert_enums_in_sync) — that is intentional; fix the data, not the guard

Building & Development

Common make targets:

Development workflow:

make install               # first-time setup
uv run pre-commit install  # First-time setup: commit hook
make check-all             # before pushing
make test-unit             # behavioral oracle
uv run mypy --strict       # src/ is strict; must exit 0
make docker-up             # after image-affecting changes

Ground rules (from AGENTS.md): src/ is mypy-strict; schema changes change docs/implementation-guide.md + the schema + the code in the same commit; pipeline control-flow changes update the matching FizzBee model in the same PR.

Publishing

All three images are published to two registries simultaneously:

All three images share the same $(DOCKER_TAG) (the version from pyproject.toml). The TEI images are shared with the sibling architecture-pattern-mcp server and change rarely — blob deduplication keeps re-tagging unchanged TEI images cheap, and TEI pushes can be skipped when the sidecars are unchanged.

Bandwidth note: the TEI embedder image is ~5 GB (ONNX fp32 weights baked in). First push to each registry is ~5 GB upload. Subsequent pushes are incremental — only changed layers are transferred.

Prerequisites

Docker Hub — already authenticated locally (docker login).

GitHub Container Registry — requires a classic PAT with write:packages scope. 2FA is not an issue — PATs bypass it. After login the token is discarded; the credential persists in ~/.docker/config.json until you log out.

Publish (one-time setup + per-session)

# 1. Login to GHCR (interactive — paste token at the password prompt)
docker login ghcr.io -u olk

# 2. Build and push all three images (MCP + TEI embedder + TEI reranker)
#    The umbrella target builds the MCP image, tags it, pushes it, creates the git tag,
#    then builds and pushes each TEI image in sequence.
make docker-publish-all

# 3. Logout from GHCR immediately after publishing
#    (removes the ghcr.io credential from ~/.docker/config.json)
docker logout ghcr.io

On subsequent publishes repeat steps 1–3. If your PAT has expired, generate a new one at the link above. make docker-publish pushes only the MCP server image (plus the v$(DOCKER_TAG) git tag and the MCP Registry entry via mcp-publisher); make docker-publish-tei pushes only the two TEI sidecars.

First push — set packages public (GHCR only)

GHCR packages default to private. After the first make docker-publish-all, flip all three packages to public:

Set each to Public and save.

Partial failure recovery

If the push fails mid-way (e.g., GHCR auth was not configured), Docker Hub layers are already uploaded. After fixing auth, re-running make docker-publish-all is safe — each registry reports a cache hit for already-uploaded layers and completes the remaining push. For targeted retries, the TEI sidecars can be pushed with make docker-publish-tei.

systemd Service (Linux)

The server can run as a systemd service on any systemd-based Linux host. It starts the Docker Compose stack automatically at boot. Full agent-runbook install: INSTALL.md (Path B). systemd/ contains:

The production compose is the deployment variant of the dev file: pre-built images only, absolute paths, deployable to /etc/design-pattern-mcp/. The TEI sidecars live in the shared pattern-tei-infra stack; this stack joins its Docker network and reaches them by DNS name. Start the service only after the shared TEI infra is active (running).

# Fast path (see INSTALL.md Path B for the full verified sequence):
VERSION=$(grep -m 1 '^version' pyproject.toml | sed -E 's/.*"([^"]+)".*/\1/')
docker pull "olkowa/design-pattern-mcp:${VERSION}"
docker tag "olkowa/design-pattern-mcp:${VERSION}" design-pattern-mcp:latest
sudo install -d /etc/design-pattern-mcp/config
sudo install -m 644 systemd/docker-compose.yml /etc/design-pattern-mcp/
sudo install -m 644 config/config.json /etc/design-pattern-mcp/config/
sudo install -m 644 systemd/design-pattern-mcp.service /etc/systemd/system/
sudo systemctl daemon-reload && sudo systemctl enable --now design-pattern-mcp

Day-to-day: systemctl start|stop|restart design-pattern-mcp, logs via journalctl -u design-pattern-mcp -f. Full details in systemd/README.md.

License

MIT License. Copyright (c) 2026 Oliver Kowalke. See the license headers in the source files.