Architecture Pattern MCP

architecture-pattern-mcp

An MCP (Model Context Protocol) server that provides architecture design expertise to AI coding agents. Given a requirements string and a domain, it analyses the problem, selects matching architecture patterns (from 128 built-in patterns), generates a concrete architecture design with components, relationships, API contracts, data models, and event contracts, and evaluates it against quality attributes (maintainability, scalability, reliability, security, performance).

---

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 architecture
• Explore the pattern catalog
• 🛠️ Tools at a Glance
• 📖 Pattern Catalog
• Working Together with design-pattern-mcp-local
• 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

---

⚡ Quickstart

# 1. Clone

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

2. Add your API key

export GENERATOR_API_KEY=your_key_here

3. Start (Docker builds + starts everything)

docker compose -f docker/docker-compose.yml up --build

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

make client-analyze

Server starts on streamable-http at http://localhost:8820/mcp (dev compose host port; systemd uses 8810). 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](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 8820).

My generator API key is: sk-...

Pick one path in INSTALL.md:

• Path A — Compose stack (:8820): evaluating / developing, no sudo needed. Own TEI sidecar copies.
• Path B — systemd stack (:8810): 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 architecture-pattern \ -e GENERATOR_API_KEY=your_key \ -e GENERATOR_PROVIDER=openai \ -- architecture-pattern-mcp --transport stdio

Or add to your project for the whole team:

claude mcp add --scope project architecture-pattern \

-e GENERATOR_API_KEY=your_key \ -- architecture-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

or locally:

uv run python -m src.main --port 8050

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

{

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

Note: GENERATOR_API_KEY is read from the server's config file (~/.config/architecture-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.architecture-pattern]

command = "architecture-pattern-mcp" args = ["--transport", "stdio"]

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

Or via CLI:

codex mcp add architecture-pattern \

-e GENERATOR_API_KEY=your_key \ -- architecture-pattern-mcp --transport stdio

---

🧑🏫 SKILL for AI Agents

The SKILL in skills/architecture-pattern-mcp/ is written for Oh My Pi (OMP), where this server's tools are reached as xd://mcp__architecture_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/architecture-pattern-mcp/

├── SKILL.md # OMP constraints, entry-point decision guide, device quick reference └── references/ ├── tools.md # 11 tool signatures, output schemas, error codes, design-dict shape └── workflows.md # 5 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/architecture-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_architecture only after raising the server's timeout (analyze_architecture alone measured 66 s, evaluate_architecture 197 s)
• How to phrase requirements, domain, and style as separate structured arguments
• How to interpret final_quality_score, attempts > 1, and evaluation.recommendations
• That read mcp://pattern://… is ambiguous while the sibling agent-pattern server is connected, so the tool route (get_architecture_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. data-processing, microservices, e-commerce) as arguments. The examples below show the exact tool call shape so you can use them in any MCP client or API consumer.

Try each tool

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

Build a scalable ETL pipeline for IoT sensor data: ingest 10k events/sec

from Kafka, parse JSON, enrich with geolocation from Redis, write to InfluxDB and S3.

Your agent calls design_architecture internally. The server returns a full architecture design: components (Kafka source, JSON parser filter, geolocation enricher, InfluxDB sink, S3 sink), quality attribute scores (scalability: 9.1, maintainability: 8.2, …), 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 code itself and only needs the pattern expertise, call analyze_architecture instead — it returns the recommended style, selected patterns with scores, requirement weights, quality metrics and matched domains without generating a design. Two measured facts from the committed benchmark corpus: generate + evaluate are ~92 % of a design call's wall clock (benchmarks/base-noreasoning/), and the two paths agree on the style in all 31 completed records (15 base + 16 no-reasoning; the one remaining base record is a design call that failed with a malformed-JSON validation error and produced no design) — a design call buys the artifact, not a better pattern choice.

Or call tools directly from your agent:

Call analyze_architecture with:

requirements: "Real-time data processing pipeline for 10k events/sec IoT sensor data" domain: "data-processing"

Call generate_architecture with: requirements: "ETL pipeline: Kafka → JSON parse → Redis geo-enrich → InfluxDB + S3" domain: "data-processing" selected_patterns: ["pipe-and-filter"]

Call evaluate_architecture with: architecture: { ... paste a design dict here ... } criteria: "scalability, reliability"

Call list_architecture_patterns() # all 128 patterns Call list_architecture_patterns(category="messaging") # filter by category Call get_architecture_pattern(name="event-driven") # full pattern JSON

Async job pattern: submit_architecture_design_job + get_architecture_design_status

ONLY for clients with short request timeouts (Cursor, Claude Desktop, TS-SDK). The default is design_architecture with heartbeat defence. submit_architecture_design_job returns a job_id immediately; poll get_architecture_design_status until done:

# Step 1: start the job

Call submit_architecture_design_job with: requirements: "ETL pipeline for IoT: Kafka → JSON → Redis geo-enrich → InfluxDB + S3" domain: "data-processing"

Step 2: poll every 10-30 seconds

Call get_architecture_design_status with: job_id: " "

→ 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/architecture_client_async.py):

import asyncio, aiohttp

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

async def main(): async with aiohttp.ClientSession() as sess:

Start

async with sess.post(SERVER, json={ "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "submit_architecture_design_job", "arguments": { "requirements": "ETL pipeline for IoT: Kafka → JSON → Redis → InfluxDB + S3", "domain": "data-processing", } }, "id": 1 }) as resp: job_id = (await resp.json())"result"0["job_id"]

print(f"Job started: {job_id}")

Poll

while True: await asyncio.sleep(POLL_EVERY) async with sess.post(SERVER, json={ "jsonrpc": "2.0", "method": "tools/call", "params": {"name": "get_architecture_design_status", "arguments": {"job_id": job_id}}, "id": 2 }) as resp: result = (await resp.json())"result"0 print(f" status={result['status']}") if result["status"] in ("completed", "failed", "cancelled"): break

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

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

docker compose -f docker/docker-compose.yml up --build   # Terminal