agent-pattern-mcp

An MCP (Model Context Protocol) server that provides agent system design expertise to AI coding agents. Given a requirements string and a domain, it analyses the problem, selects matching agent patterns (from 68 built-in patterns), generates a concrete agent system design with agents, relationships, tool contracts, state models, and message contracts, and evaluates it against quality attributes (reliability, cost efficiency, latency, output quality, observability, safety, simplicity). Coding agents that write the implementation themselves can call analyze_agent_system for topology and scored-pattern guidance without generating a design.

Table of Contents

• ⚡ Quickstart

• Install via AI Agent

• 🔌 Connect Your Agent

  • Claude Code

  • OpenCode

  • Codex CLI

• 🧑‍🏫 SKILL for AI Agents

• 🧪 Use the Tools

  • Design your first agent system

  • Explore the pattern catalog

• 🛠️ Tools at a Glance

• 📖 Pattern Catalog

• Install Alternatives

  • Docker (manual)

  • Local Development (uv)

• Configuration

• Structured Reasoning (shannonthinking / code-reasoning)

• Extending with Custom Patterns

• Long-running tools & timeouts

• Troubleshooting

• Building & Development

• Publishing

• systemd Service (Linux)

• License

Related MCP server: Senior Code MCP

⚡ Quickstart

# 1. Clone
git clone https://github.com/olk/agent-pattern-mcp.git && cd agent-pattern-mcp

# 2. Add your API key (the dev compose reads MINIMAXAI_API_KEY and pins
#    GENERATOR_PROVIDER=minimax)
export MINIMAXAI_API_KEY=sk-...

# 3. Start (needs images: `make docker-build-all` once, or prebuilt pulls
#    per INSTALL.md Path A)
docker compose -f docker/docker-compose.yml up -d

# 4. Demo (analyze-only: fast. For the full design: make client-design)
make client-analyze

Server starts on streamable-http at http://localhost:8821/mcp (dev compose host port; systemd uses 8811). Then connect your agent below.

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 8821).
My generator API key is: sk-...

Pick one path in INSTALL.md:

• Path A — Compose stack (:8821): evaluating / developing, no sudo needed. Own TEI sidecar copies.

• Path B — systemd stack (:8811): 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, ~5 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). 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 API key via env
claude mcp add agent-pattern \
  -e GENERATOR_API_KEY=your_key \
  -e GENERATOR_PROVIDER=openai \
  -- agent-pattern-mcp --transport stdio

Or add to your project for the whole team:

claude mcp add --scope project agent-pattern \
  -e GENERATOR_API_KEY=your_key \
  -- agent-pattern-mcp --transport stdio

OpenCode

OpenCode uses HTTP transport. Start the server first, then configure opencode:

# Terminal 1: start the server
docker compose -f docker/docker-compose.yml up --build   # serves :8821
# or locally on the same port:
uv run python -m src.main --port 8821

# Terminal 2: add to ~/.config/opencode/opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "agent-pattern": {
      "type": "remote",
      "url": "http://localhost:8821/mcp"
    }
  }
}

Note: GENERATOR_API_KEY is read from the server's config file (~/.config/agent-pattern-mcp/config.json), not from opencode's environment.

Codex CLI

# Install (one-time)
uv pip install -e .

Add to ~/.codex/config.toml:

[mcp_servers.agent-pattern]
command = "agent-pattern-mcp"
args = ["--transport", "stdio"]

[mcp_servers.agent-pattern.env]
GENERATOR_API_KEY = "your_key"
GENERATOR_PROVIDER = "openai"

Or via CLI:

codex mcp add agent-pattern \
  -e GENERATOR_API_KEY=your_key \
  -- agent-pattern-mcp --transport stdio

🧑‍🏫 SKILL for AI Agents

The SKILL in skills/agent-pattern-mcp/ is written for Oh My Pi (OMP), where this server's tools are reached as xd://mcp__agent_pattern_* 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/agent-pattern-mcp/
├── SKILL.md                 # OMP constraints, entry-point decision guide, device quick reference
└── references/
    ├── tools.md             # 9 tool signatures, output schemas, error codes, design-dict shape
    └── workflows.md         # recipes, result interpretation, OMP troubleshooting

Install for OMP — copy the skill directory into the user skills root, or point skills.customDirectories at this repository's skills/ directory in OMP's config:

cp -r skills/agent-pattern-mcp ~/.omp/agent/skills/

The skill then tells the agent:

• Which entry point fits OMP's deadline: the async job trio by default, one-shot design_agent_system only after raising the server's timeout (every LLM tool aborts under the 30 s default — submit_agent_design_job answers in ~0.05 s)

• That analyze_agent_system is the analysis-only path for coding agents that write the code themselves — topology, scored patterns, quality metrics, no design generated — while design_agent_system is for callers that want the design artifact

• How to phrase requirements, domain, and topology as separate structured arguments

• How to interpret final_quality_score, attempts > 1, and evaluation.recommendations

• That read mcp://pattern://… is ambiguous while the sibling architecture-pattern server is connected, so the tool route (get_agent_pattern) is authoritative

The tool schemas, error codes and design-dict shape in references/ are client-agnostic; only the deadline/device guidance is OMP-specific.

🧪 Use the Tools

All tools accept requirements (free text) and domain (e.g. tool-use-tasks, data-processing, customer-support) as arguments. The examples below show the exact tool call shape so you can use them in any MCP client or API consumer.

Design your first agent system

In Claude Code (or any MCP client), paste the natural-language instruction:

Build a research assistant agent that answers multi-hop questions by combining
web search results with sandboxed Python computation, iterating until it can
synthesise a final cited answer.

Your agent calls design_agent_system internally. The server returns a full agent system design: agents (planner, searcher, coder, synthesizer), quality attribute scores (reliability: 8.0, output_quality: 8.5, …), and specific recommendations.

That is the design path: the server's LLM generates the design artifact for you, which is why a call takes minutes. If your agent writes the implementation itself and only needs the pattern expertise, call analyze_agent_system instead — it returns the recommended topology, the selected patterns with scores, quality_metrics (per-attribute 0–10), and matched domains without generating a design, so the generate and evaluate phases never run. Measured basis: a single live analyze_agent_system call on this host returned in 23.3 s, while the committed full-pipeline corpus measured p50 ≈ 304 s and p95 ≈ 375 s over 20 scenarios (benchmarks/base/summary.json).

Or call tools directly from your agent:

Call analyze_agent_system with:
  requirements: "Research assistant combining web search with sandboxed code execution for multi-hop questions"
  domain: "tool-use-tasks"

Call generate_agent_system with:
  requirements: "Research assistant: decompose into sub-questions, search or code per sub-question, synthesise cited answer"
  domain: "tool-use-tasks"
  selected_patterns: ["react"]

Call evaluate_agent_system with:
  agent_system: { ... paste a design dict here ... }
  criteria: "reliability, safety"

Call list_agent_patterns()  # all 68 patterns
Call list_agent_patterns(category="multi_agent")  # filter by category
Call get_agent_pattern(name="supervisor-worker")   # full pattern JSON

Async job pattern: submit_agent_design_job + get_agent_design_status

ONLY for clients with short request timeouts (Cursor, Claude Desktop, TS-SDK). The default design path is design_agent_system with heartbeat defence. submit_agent_design_job returns a job_id immediately; poll get_agent_design_status until done:

# Step 1: start the job
Call submit_agent_design_job with:
  requirements: "Research assistant combining web search with sandboxed code execution for multi-hop questions"
  domain: "tool-use-tasks"

# Step 2: poll every 10-30 seconds
Call get_agent_design_status with:
  job_id: "<job_id from step 1>"

# → status is "pending" | "running" | "completed" | "failed" | "cancelled"
# When status is "completed", the full design is in result.design
# When status is "failed", the error is in result.error

In Python (via the MCP HTTP API directly — see examples/agent_client_async.py):

import asyncio
from fastmcp import Client

SERVER = "http://localhost:8821/mcp"
POLL_EVERY = 15  # seconds

async def main():
    async with Client(SERVER) as client:
        # Start
        started = await client.call_tool("submit_agent_design_job", {
            "requirements": "Research assistant: web search + sandboxed code for multi-hop questions",
            "domain": "tool-use-tasks",
        })
        job_id = started.data["job_id"]
        print(f"Job started: {job_id}")

        # Poll
        while True:
            await asyncio.sleep(POLL_EVERY)
            status = await client.call_tool("get_agent_design_status", {"job_id": job_id})
            data = status.data
            print(f"  status={data['status']}  message={data['message']}")
            if data["status"] in ("completed", "failed", "cancelled"):
                break

        print(data.get("result", data))  # full design when completed

See examples/agent_client_async.py for the complete runnable example. Run it with:

docker compose -f docker/docker-compose.yml up --build   # Terminal 1
make client-async                                      # Terminal 2

Explore the pattern catalog

Call list_agent_patterns() with no filters to see all patterns.

Or get details on a specific pattern:

Show me details about the react agent pattern.

🛠️ Tools at a Glance

Domain and Topology are structured parameters — pass them as separate tool arguments, not embedded in the requirements text.

Example prompts:

Build a research assistant that answers multi-hop questions by combining
web search with sandboxed code execution, with full audit logging.

Design an agent system for customer-support automation handling 1M
conversations/day. Domain: customer-support. Topology: hierarchical.

Show me details about the reflexion pattern.

Call design_agent_system with:
  requirements: "Research assistant combining web search with sandboxed code execution for multi-hop questions"
  domain: "tool-use-tasks"

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

* = 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_agent_patterns()                                  # all 68 patterns
list_agent_patterns(category="multi_agent")            # filter by category
list_agent_patterns(domain="tool-use-tasks")           # filter by domain
get_agent_pattern(name="supervisor-worker")            # full pattern JSON

Valid category values: reasoning, tool_use, planning, reflection, research_synthesis, multi_agent, memory, retrieval, safety_control, observability.

Via MCP resources

pattern://                    → list of all patterns
pattern://{name}              → full pattern JSON
template://{name}             → curated design templates (react, supervisor-worker, multi-agent-debate, agentic-rag)
component://{type}            → component blueprints derived from pattern data

Note: on hosts where the sibling architecture-pattern-mcp server is also connected, pattern://{name} is ambiguous (both servers register the scheme) — the tool route (get_agent_pattern) is authoritative.

Pattern JSON structure

Each pattern includes: name, category, topology, context, benefits, tradeoffs, quality_attributes (reliability/cost_efficiency/latency/output_quality/observability/safety/simplicity, numeric scores), suitable_domains, component_types, technology_stack, design_principles, best_practices.

Required fields: name, context, category, topology, suitable_domains, quality_attributes (all 7 keys).

Install Alternatives

Docker (manual)

# Build the image
make docker-build

# Run with your API key
MINIMAXAI_API_KEY=your_key docker compose -f docker/docker-compose.yml up -d

Local Development (uv)

Prerequisites: Python 3.12+, uv

# Install
make install

# Configure
cp config/config.json ~/.config/agent-pattern-mcp/config.json
# Edit ~/.config/agent-pattern-mcp/config.json and set your GENERATOR_API_KEY

# Run the server
uv run python -m src.main --transport stdio              # for Claude Code / Codex
uv run python -m src.main --port 8050                    # for OpenCode (HTTP, default)

Or use the installed console script (after make install):

agent-pattern-mcp --transport stdio

The TEI embedder (Qwen3-Embedding-0.6B) is required for domain-scoped pattern retrieval. Without it, the server falls back to the default pattern. Docker compose starts it automatically; local users must run it separately on port 8080.

The retrieval legs are built at server startup: BM25 always, the FAISS dense leg from the embedding-index cache when a valid snapshot exists (otherwise embedded from scratch). Startup stays fail-fast — every start makes one probe embedding call, so a misconfigured or unreachable TEI sidecar aborts warmup rather than breaking the user's first design request. Docker compose's service_healthy dependency ordering guarantees TEI is ready before the app starts.

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 (FROM ghcr.io/huggingface/text-embeddings-inference:cpu-1.9, ORT backend — batch cap 8 for this model) and the Stage-0 router is built CPU-only (--features ort,http). This repo ships no GPU build path — running on CUDA would require changing the runtime base image to :cuda-1.9 and rebuilding the router with the CUDA feature set, which is not a supported recipe here (only design-pattern-mcp-local ships one: make docker-build-tei-embed-gpu). A stock upstream TEI image without PR #884 silently ignores WARMUP_TOKENS.

Already-running embedder/reranker: when embedding and reranking endpoints already run on other servers, point the MCP server at them and skip the sidecars (docker/docker-compose.hub.yml starts the MCP server only and wires exactly this). The remote embedder must be TEI serving the same model — keep EMBEDDER_PROVIDER=tei and set EMBEDDER_BASE_URL to its OpenAI-compatible route (http://<host>:8080/v1, the config.json default). This server's embedder config has no model field (src/patterns/embedder.py::build_embedder sends an empty model name for the non-tei providers), so openai / ollama / vllm / hosted_vllm cannot address an arbitrary remote model without a code change. The reranker is not a LiteLLM client — it POSTs {RERANKER_BASE_URL}/rerank directly (default http://pattern-tei-rerank:8080, no /v1); provider/model syntax in the LiteLLM embedding docs applies to the embedder only. EMBEDDER_API_KEY is forwarded as the LiteLLM api_key (any non-empty string satisfies a no-auth TEI).

Configuration

config.json

The server reads ~/.config/agent-pattern-mcp/config.json (override with --config-path):

{
  "generator": {
    "provider": "openai",
    "config": {
      "model": "gpt-4o-mini",
      "base_url": "https://api.openai.com/v1",
      "api_key": "{env:GENERATOR_API_KEY}",
      "temperature": 0.1,
      "top_p": 1.0,
      "top_k": 20
    }
  },
  "embedder": {
    "provider": "tei",
    "config": {
      "base_url": "http://pattern-tei-embed:8080/v1"
    }
  },
  "retrieval": {
    "bm25_top_k": 0,
    "dense_top_k": 0,
    "top_k_patterns": 5,
    "min_quality_score": 50.0
  },
  "pattern_directory": "~/.config/agent-pattern-mcp/pattern",
  "transport": "streamable-http",
  "host": "0.0.0.0",
  "port": 8050,
  "logging_level": "INFO",
  "logging_format": "json"
}

{env:VAR:-default} syntax expands environment variables at load time.

Generator LLM (LlamaIndex LiteLLM)

The generator LLM is accessed through the LlamaIndex LiteLLM integration (llama-index-llms-litellm). All provider settings therefore follow LiteLLM's model syntax: <provider>/<model> (e.g. openai/gpt-4o-mini, anthropic/claude-sonnet-4-5, openrouter/minimax/minimax-m2).

The server composes the LiteLLM model string from your configuration as generator.provider + generator.config.model:

If the configured model already contains a provider prefix (e.g. openai/gpt-4o-mini), that prefix is stripped and replaced by the configured provider.

• Provider list, model names, and the exact <provider>/<model> syntax: LiteLLM Providers documentation

• Custom/OpenAI-compatible endpoints (proxies, vLLM, Ollama, …): set GENERATOR_BASE_URL (generator.config.base_url) — it is passed as the LiteLLM api_base

• GENERATOR_API_KEY is passed as the LiteLLM api_key; temperature, top_p, top_k, and stream map to the corresponding LiteLLM parameters

Key environment variables

Note: the dev and systemd compose files set RETRIEVAL_BM25_TOP_K=20 / RETRIEVAL_DENSE_TOP_K=20 (per-leg stage-1 caps) and RETRIEVAL_MIN_FUSION_SCORE=0.015, overriding the config defaults above. The deployed MiniMax generator block (GENERATOR_PROVIDER=minimax, GENERATOR_MODEL=minimax/MiniMax-M2.7, GENERATOR_BASE_URL=https://api.minimax.io/v1, RETRIEVAL_USE_LEAN_WIRE_SCHEMA=true) also differs from the OpenAI config defaults.

Embedding-index cache (dense retrieval snapshot)

The dense retrieval leg is one FAISS index over every catalogue domain slug (36 on the shipped 68-pattern catalogue). Its embeddings are snapshotted to disk after a cold build and reloaded on the next start, so a warm start costs one probe embedding instead of a full corpus pass (measured on a dev TEI sidecar container, 36 slugs: 3.3 s → 0.28 s). BM25 is cheap and rebuilt every start.

• Path: EMBEDDING_CACHE. The image bakes /var/cache/agent-pattern-mcp/embedding-index; host runs (uv) use ~/.config/agent-pattern-mcp/embedding-index.

• Where the files live: the logged path is the in-container view. Docker stores the named volume at /var/lib/docker/volumes/<volume-name>/_data (root-owned), so /var/cache on the host stays empty by design. Inspect without sudo: docker exec <container> ls /var/cache/agent-pattern-mcp/embedding-index, or docker volume inspect -f '{{.Mountpoint}}' <volume-name> for the host side.

• Containers persist it in a named volume (agent-pattern-mcp-dev-embedding-index / agent-pattern-mcp-systemd-embedding-index), so the snapshot survives image rebuilds, container recreation and docker compose down. Reset it with docker compose down -v or docker volume rm <name>; a bare docker run needs -v agent-pattern-mcp-embedding-index:/var/cache/agent-pattern-mcp/embedding-index.

• Rebuilt automatically when the embedding function changes (provider, base_url, resolved model name, query/text instruction prefixes), when the slug corpus changes, or when a probe vector shows a different model behind an unchanged config (e.g. a redeployed TEI sidecar). Log lines: Embedding index cache hit: N slugs, 0 corpus embed calls (snapshot <cache-dir>) / Embedding index cache miss (<reason>); embedding corpus / Embedding index snapshot written: N slugs (path <cache-dir>) — emitted immediately after the embedding pass, before any other startup step — and, with the cache switched off, Embedding index cache disabled; embedding corpus (never reported as a miss).

• Single writer: no locking — run one server process per cache directory. A failed snapshot write only logs a warning; the server runs cacheless and never fails the start.

• Operations notes (volumes, permissions, disable switch): INSTALL.md.

CLI flags

Structured Reasoning (shannonthinking / code-reasoning)

Before each LLM phase call (ANALYZE / GENERATE / EVALUATE / RETRY), the server optionally runs a bounded ThoughtGenerator loop: it authors each reasoning step with the generator's own LLM (LlamaIndex LiteLLM; one completion per step) and submits it 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).

Key properties:

• Embedded in Docker — the build-mcps stage bakes both npm packages (server-shannon-thinking@0.1.1, @mettamatt/code-reasoning@0.8.1) into the image at /usr/local/lib/node_modules/...; the runtime invokes them directly via node (no network, no npx).

• Auto-fallback to npx outside Docker — when the embedded entry points are missing, the client falls back to npx -y <pkg> (first call downloads).

• Process-per-call isolation — each tool call runs in a fresh subprocess (keep_alive=False); nothing persists between calls.

• Silent per-call degradation — any spawn/timeout/tool failure logs a WARNING and the phase proceeds with a degraded in-prompt thinking scaffold (decompose → classify → calibrate → resolve → verify); it never raises.

• Loud startup — the lifespan health-check probes both tools and logs an ERROR (with resolution hints) if one is unreachable; set REASONING_FAIL_FAST=true to make startup fail instead.

• Trace caching — ANALYZE and GENERATE traces are computed once per design request and reused across design-loop attempts.

Opting in / tuning

Reasoning is enabled by default in this repo's deployed stacks (both compose files set REASONING_ENABLED=true):

export REASONING_ENABLED=true           # enable the reasoning MCP integration
export REASONING_FAIL_FAST=true         # refuse to start with broken MCPs

Per-phase tool selection (defaults in src/reasoning/config.py::_default_per_phase): analyze ["code", "shannon"] × 4 thoughts, generate ["code"] × 3, evaluate ["shannon"] × 3, refine ["code", "shannon"] × 2. A full design run issues up to 24 reasoning tool calls as serial subprocesses — minutes, not seconds.

Local (non-Docker) development needs Node.js; either install the packages globally (npm install -g server-shannon-thinking @mettamatt/code-reasoning) or let the npx fallback download them on first use.

Set LOGGING_LEVEL=DEBUG to capture the authored thought and tool response for every per-step reasoning call. Docker/systemd stacks default to INFO; export LOGGING_LEVEL=DEBUG before make docker-up.

Extending with Custom Patterns

Pattern files are loaded from ~/.config/agent-pattern-mcp/pattern/ (configurable via PATTERN_DIRECTORY). Drop a JSON file alongside the 68 built-in patterns.

Minimal pattern structure:

{
  "category": "tool_use",
  "name": "my-custom-pattern",
  "topology": "single-agent-loop",
  "context": "Describe when this pattern applies.",
  "benefits": ["Benefit 1", "Benefit 2"],
  "tradeoffs": ["Tradeoff 1"],
  "quality_attributes": {
    "reliability": 7,
    "cost_efficiency": 6,
    "latency": 7,
    "output_quality": 7,
    "observability": 6,
    "safety": 7,
    "simplicity": 5
  },
  "suitable_domains": ["tool-use-tasks"]
}

Required fields: name, context, category, topology, suitable_domains, quality_attributes (all 7 keys).

Valid category values: reasoning, tool_use, planning, reflection, research_synthesis, multi_agent, memory, retrieval, safety_control, observability.

Full JSON Schema with all enums: docs/pattern-schema.json

Long-running tools & timeouts

design_agent_system runs a multi-stage LLM pipeline that can take 5–10 minutes per call. The single-phase tools are much cheaper: analyze_agent_system is one analysis LLM call (23.3 s measured on this host) that returns topology and scored patterns without generating a design, while generate_agent_system and evaluate_agent_system are one large completion each. The long design call is inherent to the workload, not a bug: the generator LLM must process a large input payload — the selected pattern definitions from the 68-pattern catalog, your requirements, and the full output of every previous stage — and produce a large, strictly structured JSON document (agents, relationships, tool contracts, state models, message contracts, quality scores) one token at a time. The design_agent_system pipeline repeats generate → evaluate up to three times, so a single call can comprise 9+ LLM round trips.

The timeout problem

MCP clients (AI coding agents, MCP SDKs) sit between the server and the LLM. Many of them implement a client-side idle timeout: if no data is received on the HTTP connection for some period (typically 30–120 seconds), the client aborts the request. The server is still working — the LLM is still generating — but the client closes the connection and reports a timeout error to the agent.

This is a client-side behaviour, not a server-side one. The server processes the full request correctly; the client simply gives up before the response arrives.

Affected clients (hardcoded short timeouts):

These clients cannot be reconfigured to accept longer timeouts — the timeout is baked into the SDK.

Clients covered by the heartbeat defence:

Works for these because their idle timers are reset by any incoming data — the heartbeat progress notifications sent from a parallel async task on the server are received by the client, resetting its clock.

The heartbeat defence (applied by default)

Every long-running tool emits progress notifications from a parallel coroutine every 30 seconds (configurable via TASKS_HEARTBEAT_INTERVAL_SECONDS). As long as the client resets its idle timer on any received data, the request stays alive for the full duration of the pipeline.

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

The async job trio (for timeout-constrained clients)

For full control and compatibility with timeout-limited clients, three tools provide a durable job handle:

submit_agent_design_job(requirements, domain, override_topology)  → job_id
get_agent_design_status(job_id)                                     → {status, result, error}
cancel_agent_design(job_id)                                         → {cancelled, status}

submit_agent_design_job returns a job_id in milliseconds. The pipeline runs in a background task. Poll get_agent_design_status(job_id) every 10–30 seconds. When status is completed, the full design is in the result field. Cancellation is best-effort — the job exits at the next pipeline stage boundary.

This is the only fix that works for TS-SDK clients (Claude Desktop, Cursor).

The job store is SQLite at ~/.config/agent-pattern-mcp/jobs.db (configurable via AGENT_PATTERN_JOBS_DB).

Bypassing client timeouts with a direct HTTP client

The example client in examples/agent_client.py is a direct Python HTTP client — it is not an MCP agent. It calls the server over HTTP without an MCP SDK, and therefore has no client-side idle timeout: it makes a single blocking request and waits for the full response.

# Start the server (from project root)
docker compose -f docker/docker-compose.yml up --build

# In another terminal: fast analyze demo / full design demo (minutes)
make client-analyze        # analyze_agent_system only
make client-design         # design_agent_system, 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. For production use with MCP agents, the heartbeat defence covers the majority of clients; the async job trio is the universal fallback.

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: compose logs should show MCPAgentPatternServer initialized

3. Confirm the TEI embedder is healthy: docker exec agent-pattern-mcp python -c "import urllib.request; print(urllib.request.urlopen('http://pattern-tei-embed:8080/health').status)"

"Connection refused" or timeout errors

The server waits for the TEI embedder to become healthy:

docker compose -f docker/docker-compose.yml logs agent-pattern-mcp

LLM provider errors (502 / 401)

• Confirm GENERATOR_API_KEY is set and not expired

• Verify GENERATOR_BASE_URL matches your provider's endpoint

• If using a proxy, check reachability from inside the container

Pattern JSON files not loading

• Files must have .json extension and match *-pattern.json

• Required fields: name, context, category, topology, suitable_domains, quality_attributes (all 7 keys)

• Check the startup log for Pattern validation failed warnings

Building & Development

Common make targets (full reference: docs/make_rules.md):

Development workflow:

make install                      # First-time setup
uv run pre-commit install         # First-time setup: commit hook
make check-all                    # Before pushing (lint + types + dead code + deps)
make docker-build-all             # Build both images (first time and after code changes)
make docker-up                    # Start services
make docker-logs-follow           # Watch logs
make docker-down                  # Stop

Publishing

All three images are published to two registries simultaneously:

All three images share the same $(DOCKER_TAG) (the version from pyproject.toml), so tei:1.0.3 always ships with mcp:1.0.3. Blob deduplication keeps re-tagging unchanged TEI images cheap.

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.

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, individual images can be pushed with make docker-publish-tei or make docker-publish-tei-rerank.

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.

File layout

The systemd/ directory contains three files:

The production compose file is a deployment variant of docker/docker-compose.yml: it has no build: sections (images must be pre-built), uses absolute paths, and lives under /etc/agent-pattern-mcp/ on the host. The systemd-managed project uses the distinct name agpmcp-systemd — distinct from both the dev compose and the sibling architecture-pattern-mcp systemd stack (apmcp-systemd), so neither stack's up -d --remove-orphans treats the other's container as an orphan.

TEI sidecars are NOT defined in this stack — the pattern-tei-embed embedder and pattern-tei-rerank reranker containers live in the shared pattern-tei-infra stack. This stack owns the pattern-tei-shared Docker network and exposes the sidecars at http://pattern-tei-embed:8080/v1 (embedder) and http://pattern-tei-rerank:8080 (reranker). The systemd MCP stack joins that network and reaches them by those DNS names.

Prerequisite — one-time TEI infra setup:

# Clone the infra stack (if not already on the host)
git clone https://github.com/olk/pattern-tei-infra.git ~/pattern-tei-infra

# Install and enable the pattern-tei-infra systemd unit
sudo install -m 644 ~/pattern-tei-infra/pattern-tei-infra.service \
                /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now pattern-tei-infra.service
# Wait ~2 min for the TEI sidecars to become healthy

Start agent-pattern-mcp.service only AFTER pattern-tei-infra.service is active (running). See pattern-tei-infra/README.md for full details.

Prerequisites

• systemd-based Linux host with Docker (docker compose version).

• <user> is in the docker group.

• Both images pre-built locally (make docker-build-all from the repo).

• Shared TEI infra stack installed and enabled (see tei-infra README).

Install

# 0. Install + enable shared TEI infra (once)
sudo install -m 644 {HOME}/pattern-tei-infra/pattern-tei-infra.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now pattern-tei-infra.service

# 1. Build images (once)
make docker-build-all

# 2. Deploy /etc/agent-pattern-mcp/
sudo install -d /etc/agent-pattern-mcp/config
sudo install -m 644 systemd/docker-compose.yml /etc/agent-pattern-mcp/
sudo install -m 644 ~/.config/agent-pattern-mcp/config.json /etc/agent-pattern-mcp/config/

# 3. Create the .env file (root:docker 640) and edit it.
#     640 root:docker — not 600 root:root — so the systemd service
#     running as User=graemer (a member of the `docker` group) can read this
#     file when docker compose auto-loads it.  The `docker` group is
#     effectively privileged; this is the standard trade-off for non-root
#     systemd services that manage Docker containers.
sudo install -o root -g docker -m 640 /dev/null /etc/agent-pattern-mcp/.env
sudo $EDITOR /etc/agent-pattern-mcp/.env
# Contents:
#   MINIMAXAI_API_KEY=sk-...
#   COMPOSE_PROJECT_NAME=agpmcp-systemd

# 4. Install and enable the service.
sudo install -m 644 systemd/agent-pattern-mcp.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now agent-pattern-mcp.service

Prebuilt-image shortcut: for the no-build install from Docker Hub (pull + retag, JSON-RPC probe, day-2 operations), see INSTALL.md Path B instead.

Verify

systemctl status shows active (exited) within seconds, but the containers take up to ~40 s to become healthy (MCP start_period: 40s; TEI readiness is owned by pattern-tei-infra with start_period: 120s). The unit does not wait for healthchecks.

systemctl status agent-pattern-mcp
journalctl -u agent-pattern-mcp -n 50
docker compose -p agpmcp-systemd -f /etc/agent-pattern-mcp/docker-compose.yml ps
docker inspect -f '{{.State.Health.Status}}' agent-pattern-mcp  # "healthy"
# Probe the MCP endpoint — must print 200 (GET /health is 404 by design).
curl -s -o /dev/null -w '%{http_code}\n' -X POST "http://localhost:8811/mcp" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"probe","version":"0.0.0"}},"id":1}'

Day-to-day

sudo systemctl start|stop|restart|reload agent-pattern-mcp
journalctl -u agent-pattern-mcp -n 200 -f
docker compose -p agpmcp-systemd -f /etc/agent-pattern-mcp/docker-compose.yml logs -f

Updating the stack

make docker-build-all                     # rebuild both images
sudo systemctl reload agent-pattern-mcp   # recreate containers

Uninstall

sudo systemctl disable --now agent-pattern-mcp.service
sudo rm /etc/systemd/system/agent-pattern-mcp.service
sudo systemctl daemon-reload
sudo rm -rf /etc/agent-pattern-mcp

For full troubleshooting, networking details, and the coexistence guide, see systemd/README.md.

Verification Program

The repo carries a layered verification program (see docs/verification.md and docs/testing-strategies.md):

Fast gates: make check-all (lint + types + dead code + deps) and make test-all (unit + oracles). The nightly canary lives in .github/workflows/verification.yml.

License

MIT License. See LICENSE.