agent-pattern-mcp

# agent-pattern-mcp

[![CI](https://img.shields.io/github/actions/workflow/status/olk/architecture-pattern-mcp/ci.yml?branch=main)](https://github.com/olk/architecture-pattern-mcp/actions)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

MCP server that provides AI agent pattern expertise: generate, analyze, and evaluate agent system designs against a curated catalog of 61 agent patterns (ReAct, supervisor-worker, reflexion, self-RAG, LLMCompiler, and more).

## Table of Contents

- [Quickstart](#-quickstart)
- [Connect Your Agent](#-connect-your-agent)
- [Use the Tools](#use-the-tools)
- [Tools at a Glance](#️-tools-at-a-glance)
- [Prompts](#-prompts)
- [Pattern Catalog](#-pattern-catalog)
- [SKILL for AI Agents](#-skill-for-ai-agents)
- [Install Alternatives](#install-alternatives)
- [Configuration](#configuration)
- [Extending with Custom Patterns](#extending-with-custom-patterns)
- [Troubleshooting](#troubleshooting)
- [Building & Development](#building--development)
- [Publishing](#publishing)
- [systemd Service (Linux)](#systemd-service-linux)
- [License](#license)

## ⚡ Quickstart

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

# 2. Add your API key
echo 'GENERATOR_API_KEY=sk-...' >> .env

# 3. Start (Docker builds + starts everything)
make docker-up

# 4. Demo
make client
```

## 🔌 Connect Your Agent

### Claude Code

```bash
# Install (one-time)
npm install -g @anthropic-ai/claude-code

# Run as stdio subprocess — pass API key via env
GENERATOR_API_KEY=sk-... claude mcp add agent-pattern-mcp -- python -m src.main --transport stdio
```

### OpenCode

```bash
# Terminal 1: start the server
make docker-up
# or locally:
uv run python -m src.main

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

```jsonc
{
  "mcp": {
    "agent-pattern-mcp": {
      "type": "remote",
      "url": "http://localhost:8061/mcp",
      "enabled": true
    }
  }
}
```

### Codex CLI

```bash
# Install (one-time)
brew install codex

# Add to ~/.codex/config.toml
```

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

## Use the Tools

### Design your first agent system

Ask your agent (or call the tool directly):

> Use design_agent_system to design a research assistant that combines 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 `AgentSystemDesign` with agents, relationships, tool contracts, and quality scores.

### Explore the pattern catalog

> List all agent patterns in the tool_use category.

> Get the full JSON of the react pattern.

### 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 is `design_agent_system` with heartbeat defence. `submit_agent_design_job` returns a `job_id` immediately; poll `get_agent_design_status` until done:

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

## 🛠️ Tools at a Glance

| Tool | Description |
|---|---|
| `design_agent_system` | Full pipeline: analyze → generate → evaluate → refine. Returns complete design + evaluation + quality metrics. *Long-running (5–10 min); use this unless your client has a short request timeout.* |
| `analyze_agent_system` | Analyse requirements and derive agent pattern recommendations using pattern matching and domain similarity. *Long-running (LLM call). Not idempotent.* |
| `generate_agent_system` | Generate an agent system design from requirements, topology, domain, and selected patterns. *Long-running (LLM call). Not idempotent.* |
| `evaluate_agent_system` | Evaluate an agent system design against specified criteria and domain using pattern benchmarking. *Long-running (LLM call). Not idempotent.* |
| `list_agent_patterns` | List all 61 patterns; filter by `category` and/or `domain` |
| `get_agent_pattern` | Get full JSON for a specific pattern by name |
| `submit_agent_design_job` | Start a background design job and return a `job_id` immediately. **ONLY for clients with short request timeouts** (Cursor, Claude Desktop, TS-SDK). For other clients use `design_agent_system`. Poll `get_agent_design_status` every 10–30 s. |
| `get_agent_design_status` | Poll job status. Returns the current status, progress message, and the full design output when `completed`. |
| `cancel_agent_design` | Cancel a running job (best-effort; takes effect at the next pipeline stage boundary; may take up to one LLM call). |

## 💬 Prompts

The server also exposes four user-invoked workflow prompts (slash commands in clients that support them):

| Prompt | Args | What it does |
|---|---|---|
| `design_agent_system_workflow` | `requirements*` | Full analyze → generate → evaluate pipeline |
| `explore_pattern_catalog` | `domain`, `category` | Live catalog discovery with embedded pattern names |
| `evaluate_my_agent_system` | `focus` | Guide evaluation criteria + finding prioritisation |
| `compare_agent_topologies` | `topology_a*`, `topology_b*`, `requirements*` | Two designs side-by-side; ~2× token cost |

\* = required argument

### Tool-only clients

In tool-only clients, the prompts are also exposed as tools via FastMCP's `PromptsAsTools` transform — you can call them like any other tool.

## 🧑‍🏫 SKILL for AI Agents

AI coding agents (Claude Code, OpenCode, Codex CLI) can load a SKILL that teaches them how and when to use this server's tools — including timeout-aware entry-point selection, output interpretation, and the full workflow recipe.

The SKILL lives in `skills/agent-pattern-mcp/`:

```
skills/agent-pattern-mcp/
├── SKILL.md                 # Discovery, critical rules, decision guide
└── references/
    ├── tools.md             # All 9 tool signatures and output schemas
    └── workflows.md         # 4 worked examples, 4 prompts, best practices
```

**For agents that support file-based skills** (OpenCode, Claude Code): point the agent's skill loader at `skills/agent-pattern-mcp/SKILL.md`. The skill tells the agent:

- Which tool to use based on client type and timeout budget
- How to phrase `requirements`, `domain`, and `topology` as separate structured arguments
- How to interpret `final_quality_score`, `attempts > 1`, and `evaluation.recommendations`
- When to use the async job trio vs `design_agent_system` directly

---

## 📖 Pattern Catalog

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

### Via MCP tools (recommended — works in all clients)

```
list_agent_patterns(category="multi_agent")
get_agent_pattern(name="supervisor-worker")
```

### 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
```

### Pattern JSON structure

Each `pattern/*-pattern.json` file contains: `name`, `category`, `topology`, `context`, `benefits`, `tradeoffs`, `quality_attributes` (7 dims, 1-10), `suitable_domains`, `unsuitable_domains`, `use_cases`, `avoid_when`, `component_types`, `technology_stack`, `anti_patterns`, `migration_from`, `migration_to`, `design_principles`, `best_practices`, `references`.

## Install Alternatives

### Docker (manual)

```bash
# Build the image
docker build --target production -f docker/Dockerfile -t agent-pattern-mcp:latest .

# Run with your API key
docker run -p 8061:8051 --env-file .env agent-pattern-mcp:latest
```

### Docker Hub image (compose)

Pull `olkowa/agent-pattern-mcp` without building. The hub compose starts the
MCP server only; start the TEI sidecars (`olkowa/pattern-tei-embed`,
`olkowa/pattern-tei-rerank`) separately and wire them via `EMBEDDER_BASE_URL`
/ `RERANKER_BASE_URL`:

```bash
TAG=latest docker compose -f docker/docker-compose.hub.yml up -d
```

### Local Development (uv)

```bash
# Install
uv sync

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

# Run the server
uv run python -m src.main
```

## Configuration

### config.json

See `config/config.json` for the full annotated example. Key sections:

- **generator** — single LLM configuration: provider, model, temperature. Serves all pipeline phases (planning, generation, reflection).
- **embedder** — TEI (default), OpenAI, or Ollama embeddings for dense retrieval.
- **retrieval** — hybrid BM25 + dense fusion tuning: top-k caps, fusion mode (`simple` / `reciprocal_rerank`), reranker settings, quality thresholds, blend weights, topology score threshold.