olkowa/agent-pattern-mcp repository overview

⁠Agent-Pattern MCP server

An MCP server that provides AI agent pattern expertise to AI coding agents. Analyses requirements, selects from a curated catalog of 61 agent patterns (ReAct, supervisor-worker, reflexion, self-RAG, LLMCompiler, …), generates concrete agent system designs with agents, relationships, and tool contracts, and evaluates them against quality attributes.

⁠What is this?

This Docker image contains a complete MCP (Model Context Protocol) server that brings agent design expertise to your AI coding agents. Given a requirements string and a domain, it:

• Analyzes the problem and selects matching agent patterns (hybrid BM25 + dense retrieval, TEI cross-encoder reranked)
• Generates concrete agent system designs with agents, relationships, tool contracts, and data models
• Evaluates designs against quality attributes (reliability, cost efficiency, latency, output quality, observability, safety, simplicity)
• Drives structured reasoning inside the analyze / generate / evaluate / refine phases with two embedded reasoning-MCP scratchpads (shannonthinking, code-reasoning)

⁠Key Features

• 61 Built-in Patterns across 10 categories (reasoning, tool_use, planning, reflection, research_synthesis, multi_agent, memory, retrieval, safety_control, observability) and 8 topologies (single-agent-loop, hierarchical, pipeline, plan-execute, parallel-fan-out, evaluator-loop, graph-orchestrated, swarm)
• Full Design Pipeline: Analyze → Generate → Evaluate → Refine (up to 3 automatic refinement attempts)
• Quality Attribute Scoring: final_quality_score (0–100) plus per-attribute scores (1–10)
• Hybrid Retrieval + Reranking: BM25 + dense (FAISS) fusion, then a TEI cross-encoder rerank
• Embedded Structured Reasoning: two Node-based reasoning MCPs are baked into the image — no runtime npx fetch; the deployed stacks set REASONING_FAIL_FAST=true so the server refuses to start when they are unreachable
• Dual Transport Support: Stdio for local agents, StreamableHTTP for remote deployments
• Extensible: add custom patterns via JSON files — no rebuild required

┌───────────────────────────────────────────────────────────────────┐
│  OpenCode / Claude Code / VS Code / any MCP client                │
│        ────────── HTTP ──────────► :8061/mcp (Path A, compose)    │
│                                 or :8051/mcp (Path B, systemd)    │
│                                                                   │
│        ┌──────────────────────────────┐                           │
│        │      agent-pattern-mcp       │                           │
│        │      container port 8051     │                           │
│        └───────────────┬──────────────┘                           │
│                        │                                          │
│    ┌───────────────────┼────────────────────┐                     │
│    │ pattern-tei-embed │ pattern-tei-rerank │ ← own copies (A) /  │
│    │    :8080 (TEI)    │   :8080 (TEI)      │   pattern-tei-infra │
│    └───────────────────┴────────────────────┘   shared stack (B)  │
└───────────────────────────────────────────────────────────────────┘

This image is the MCP server only. The TEI embedder and TEI reranker are separate infrastructure (published from the pattern-tei-infra project⁠) as olkowa/pattern-tei-embed⁠ and olkowa/pattern-tei-rerank⁠.

They connect via Docker DNS using the hostnames pattern-tei-embed and pattern-tei-rerank on a shared Docker network — those are the defaults baked into this image (EMBEDDER_BASE_URL=http://pattern-tei-embed:8080/v1, RERANKER_BASE_URL=http://pattern-tei-rerank:8080), so no URL overrides are required.

Two deployment paths (see INSTALL.md⁠):

The MCP server itself runs as a non-root user and serves StreamableHTTP on container port 8051 (path /mcp). Startup takes up to ~40 s: retrieval indexes (FAISS + BM25) are built at startup, and the server refuses to start when the TEI sidecars are unreachable or the embedded reasoning MCPs cannot be spawned (REASONING_FAIL_FAST=true in both deployed stacks).

⁠Tools at a Glance

Example call:

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

Patterns are also exposed as MCP resources: pattern:// (catalog list), pattern://{name} (full pattern JSON), template://{name} (curated design templates: react, supervisor-worker, multi-agent-debate, agentic-rag) and component://{type} (component blueprints).

⁠Prompts (Slash Commands)

* = required

In tool-only clients the prompts are also callable as tools via FastMCP's PromptsAsTools transform — the server then exposes list_prompts and get_prompt alongside the nine domain tools above.

⁠Prerequisites

• Repo clone — install runs from a clone (test -f docker/docker-compose.yml); config template is config/config.json
• Docker ≥ v2.20 with compose plugin (docker compose version) + membership in the docker group
• A generator API key — deployed stacks default to MiniMax (MINIMAXAI_API_KEY); any LiteLLM-compatible provider works (OpenAI, Anthropic, DeepSeek, Ollama, vLLM, OpenRouter, … — see Switching the generator LLM⁠)
• Disk: ≥ 5 GB free (MCP ≈ 0.3 GB, TEI ≈ 2–4 GB)
• CPU only — no GPU required (shipped TEI sidecars are CPU/ORT images)
• linux/amd64 — images are amd64-only; on arm64 build locally via make docker-build-all

⁠Long-running Tools & Timeouts

design_agent_system runs multi-stage LLM pipelines that can take 5–10 minutes — the generator LLM processes the selected pattern definitions, your requirements, and the full output of every previous stage across 9+ round trips.

⁠The Timeout Problem

MCP clients implement client-side idle timeouts (typically 30–120 s). If no data is received, the client aborts — even though the server is still working correctly.

⁠Solutions

1. Heartbeat defence (default) — The server emits progress notifications every 30 s (TASKS_HEARTBEAT_INTERVAL_SECONDS), resetting idle timers for most HTTP clients. TS-SDK clients (Claude Desktop, Cursor) do not reset on progress.

2. Async job trio — For timeout-constrained clients (Claude Desktop, Cursor), use submit_agent_design_job + get_agent_design_status + cancel_agent_design. Returns a job_id immediately; poll every 10–30 s.

3. Direct HTTP client — The repo's example client (examples/agent_client.py, make client) bypasses the MCP SDK entirely with no idle timeout.

⁠Quick start

Prebuilt images from Docker Hub — but install runs from a repo clone (compose files and config template live there). Pick one path; both can run concurrently (distinct container names and ports).

Path A — Compose stack (:8061, no sudo, own TEI copies):

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

# TEI images release rarely, currently 1.9.4)
VERSION=$(grep -m 1 '^version' pyproject.toml | sed -E 's/.*"([^"]+)".*/\1/')
TEI_VERSION=1.9.4
docker pull "olkowa/agent-pattern-mcp:${VERSION}"
docker pull "olkowa/pattern-tei-embed:${TEI_VERSION}"
docker pull "olkowa/pattern-tei-rerank:${TEI_VERSION}"

# Env file for compose interpolation
cat > docker/.env <<EOF
MCP_IMAGE=olkowa/agent-pattern-mcp:${VERSION}
TEI_IMAGE=olkowa/pattern-tei-embed:${TEI_VERSION}
TEI_RERANK_IMAGE=olkowa/pattern-tei-rerank:${TEI_VERSION}
MINIMAXAI_API_KEY=sk-REPLACE-ME
MCP_HOST_PORT=8061
EOF

docker compose --env-file docker/.env -f docker/docker-compose.yml up -d

# Wait until all three report "healthy" (TEI cold start ~2 min, MCP ≤ ~40 s after)
docker inspect -f '{{.Name}} {{.State.Health.Status}}' \
  agent-pattern-tei-dev agent-pattern-tei-rerank-dev agent-pattern-mcp-dev

# Probe — must print 200 (GET /health is 404 by design; the POST is the probe)
curl -s -o /dev/null -w '%{http_code}\n' -X POST "http://localhost:8061/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}'

Installed endpoint: http://localhost:8061/mcp (streamable-http).

Path B — systemd stack (:8051, persistent, needs sudo): shared pattern-tei-infra TEI stack plus a systemd unit (agpmcp-systemd, config at /etc/agent-pattern-mcp/). Full runbook with verification probes: INSTALL.md Path B⁠.

⁠Bringing your own LLM

Both compose files hardcode the MiniMax generator block (deployed default). To use another LiteLLM provider, edit the four GENERATOR_* lines in the installed compose file and put the key in the env file, then restart:

⁠Generator LLM (LlamaIndex LiteLLM)

The generator LLM is accessed through the LlamaIndex LiteLLM integration (llama-index-llms-litellm⁠). All provider settings 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 (a contained provider prefix is stripped and replaced):

• Provider list, model names, and the exact <provider>/<model> syntax: LiteLLM Providers documentation⁠
• Custom/OpenAI-compatible endpoints (proxies, vLLM, Ollama, …): set GENERATOR_BASE_URL — it is passed as the LiteLLM api_base
• GENERATOR_API_KEY is passed as the LiteLLM api_key; GENERATOR_TEMPERATURE, GENERATOR_TOP_P, GENERATOR_TOP_K, and GENERATOR_STREAM map to the corresponding LiteLLM parameters

⁠TEI sidecar configuration

The MCP server connects to the TEI embedder at http://pattern-tei-embed:8080/v1 and the TEI reranker at http://pattern-tei-rerank:8080 by default (Docker DNS names). Override if your setup differs:

The embedder (olkowa/pattern-tei-embed) carries Qwen3-Embedding-0.6B (ONNX fp32) and the reranker (olkowa/pattern-tei-rerank) carries gte-reranker-modernbert-base — both baked into their images, fully offline (HF_HUB_OFFLINE=1, no downloads, no API keys at runtime).

Deployed-stack overrides (differ from config.json defaults): per-leg stage-1 caps RETRIEVAL_BM25_TOP_K=20 / RETRIEVAL_DENSE_TOP_K=20 (0 = full corpus in config), RETRIEVAL_MIN_FUSION_SCORE=0.015, and RETRIEVAL_USE_LEAN_WIRE_SCHEMA=true (omits free-form contract lists — the deployed MiniMax model emits unquoted JS-style keys otherwise).

Full env var reference: GitHub README → Configuration⁠

⁠Embedded reasoning MCPs

The image bakes two Node-based reasoning MCP servers — shannonthinking ([email protected]) and code-reasoning (@mettamatt/[email protected]) — into /usr/local/lib/node_modules. The pipeline invokes them directly via node (no runtime npx fetch outside Docker it falls back to npx -y); they act as structured scratchpads that validate and number the thoughts the pipeline's own LLM authors.

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

Set REASONING_ENABLED=false to opt out (loses the structured-reasoning cross-validation; pipeline output stays valid).

⁠Connect your agent

⁠OpenCode

Add to ~/.config/opencode/opencode.json:

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

(Use port 8051 for the systemd stack.)

⁠VS Code (MCP extension)

Add to .vscode/mcp.json:

{
  "servers": {
    "agent-pattern-mcp": {
      "url": "http://localhost:8061/mcp",
      "type": "http"
    }
  }
}

⁠Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.agent-pattern-mcp]
url = "http://localhost:8061/mcp"

⁠Claude Code (stdio transport)

# Install (one-time)
git clone https://github.com/olk/agent-pattern-mcp.git && cd agent-pattern-mcp
uv pip install -e .

# Add to your agent
claude mcp add agent-pattern \
  -e GENERATOR_API_KEY=your_key \
  -e GENERATOR_PROVIDER=openai \
  -- agent-pattern-mcp --transport stdio

The repo also ships an OMP skill (skills/agent-pattern-mcp/) teaching deadline-aware entry-point selection (async job trio by default under OMP's 30 s MCP deadline).

⁠Try it

Ask your agent:

This should call design_agent_system with:

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

The tool runs the full pipeline — analyze (pattern retrieval + requirements-weighted scoring) → generate (LLM structured output) → evaluate (metric scoring) → refine (bounded retry loop) — and returns a complete design with agents, relationships, tool contracts, and quality scores.

⁠Operations

# Path A: upgrade (re-pull pins, restart)
VERSION=$(grep -m 1 '^version' pyproject.toml | sed -E 's/.*"([^"]+)".*/\1/')
docker pull "olkowa/agent-pattern-mcp:${VERSION}"
docker compose --env-file docker/.env -f docker/docker-compose.yml up -d

# View logs
docker compose --env-file docker/.env -f docker/docker-compose.yml logs -f agent-pattern-mcp

# Stop / remove
docker compose --env-file docker/.env -f docker/docker-compose.yml down
# rm docker/.env   # contains the API key — remove or keep as you prefer

# Path B: day-2 (systemd)
sudo systemctl stop|start agent-pattern-mcp     # compose down / up -d
sudo systemctl reload agent-pattern-mcp         # recreate after editing compose/.env
journalctl -u agent-pattern-mcp -n 50

On Linux with a shared host, restrict your env file (chmod 600 docker/.env; Path B uses root:docker 640 at /etc/agent-pattern-mcp/.env).

⁠Troubleshooting

⁠Links

• GitHub (source, docs, issue tracker): olk/agent-pattern-mcp⁠
• Install runbook (agent-executed, Path A/B with probes): INSTALL.md⁠
• GHCR mirror: ghcr.io/olk/agent-pattern-mcp⁠ (not anonymously pullable — use Docker Hub)
• TEI infrastructure (embedder + reranker): olk/pattern-tei-infra⁠ · olkowa/pattern-tei-embed⁠ · olkowa/pattern-tei-rerank⁠
• Sister project (architecture design rather than agent design): olk/architecture-pattern-mcp⁠
• License: MIT⁠