olkowa/architecture-pattern-mcp repository overview

⁠Architecture-Pattern MCP server

An MCP server that provides architecture design expertise to AI coding agents. Analyzes requirements, selects from 40 built-in patterns, generates concrete architecture designs with components/API contracts, and evaluates against quality attributes.

⁠What is this?

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

• Analyzes the problem and selects matching architecture patterns
• Generates concrete architecture designs with components, relationships, API contracts, data models, and event contracts
• Evaluates designs against quality attributes (scalability, maintainability, reliability, security, performance)

⁠Key Features

• 40 Built-in Patterns: Microservices, event-driven, hexagonal, layered monolith, CQRS, saga, pipe-and-filter, and more
• Full Design Pipeline: Analyze → Generate → Evaluate → Refine (up to 3 automatic refinement attempts)
• Quality Attribute Scoring: Rate designs on scalability, maintainability, reliability, security, performance, and simplicity (1-10 scale)
• Dual Transport Support: Stdio for local agents, StreamableHTTP for remote deployments
• Extensible: Add custom patterns via JSON files

┌───────────────────────────────────────────────────────────────────┐
│  OpenCode / Claude Code / VS Code / any MCP client                │
│        ────────── HTTP ──────────► :8060/mcp (Path A)             │
│                                 or :8050/mcp (Path B)             │
│                                                                   │
│        ┌──────────────────────────────┐                           │
│        │   architecture-pattern-mcp   │                           │
│        └───────────────┬──────────────┘                           │
│                        │                                          │
│    ┌───────────────────┼────────────────────┐                     │
│    │ pattern-tei-embed │ pattern-tei-rerank │ ← pattern-tei-infra │
│    │    :8080 (TEI)    │   :8080 (TEI)      │   (Path B shares it)│
│    └───────────────────┴────────────────────┘                     │
└───────────────────────────────────────────────────────────────────┘

⁠Architecture

This image is the MCP server only. The TEI embedder (Qwen3-Embedding-0.6B) and TEI reranker are separate infrastructure (see pattern-tei-infra project⁠) published 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.

⁠Tools at a Glance

Example call:

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

⁠Prompts (Slash Commands)

* = required

⁠Prerequisites

• A clone of the repo — compose files and config template ship with it (test -f docker/docker-compose.yml)
• Docker with compose plugin ≥ v2.20 (docker compose version), Docker group membership, ~5 GB free (MCP ≈ 0.3 GB, TEI ≈ 2–4 GB)
• A generator LLM API key — defaults to MiniMax (MINIMAXAI_API_KEY); any LiteLLM-compatible provider works (OpenAI, Anthropic, DeepSeek, Ollama, vLLM, OpenRouter, …)
• Images are linux/amd64 only; on arm64 build locally with make docker-build-all
• GHCR mirrors exist but are not anonymously pullable — use Docker Hub

⁠Long-running Tools & Timeouts

design_architecture runs multi-stage LLM pipelines that can take 5–10 minutes — the generator LLM processes large input payloads 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 do not reset on progress — use the job trio.

2. Async job trio — For timeout-constrained clients (Claude Desktop, Cursor), use submit_architecture_design_job + get_architecture_design_status + cancel_architecture_design. Returns a job_id immediately; poll every 10–30 s. Jobs persist in SQLite (ARCHITECTURE_PATTERN_JOBS_DB).

3. Direct HTTP client — make client bypasses MCP SDK entirely with no idle timeout.

⁠Quick start

Two paths (full runbook: INSTALL.md⁠). Pick exactly one — both can run concurrently (distinct container names and ports).

# 0. Clone (compose files + config template ship with the repo)
git clone https://github.com/olk/architecture-pattern-mcp.git && cd architecture-pattern-mcp

# A1. Resolve versions and pull. TEI pins differ from the MCP version
#     (TEI images release rarely); TEI is currently 1.9.4
VERSION=$(grep -m 1 '^version' pyproject.toml | sed -E 's/.*"([^"]+)".*/\1/')
TEI_VERSION=1.9.4
docker pull "olkowa/architecture-pattern-mcp:${VERSION}"
docker pull "olkowa/pattern-tei-embed:${TEI_VERSION}"
docker pull "olkowa/pattern-tei-rerank:${TEI_VERSION}"

# A2. Write the env file next to the compose file
cat > docker/.env <<EOF
MCP_IMAGE=olkowa/architecture-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=8060
EOF

# A3. Start. TEI sidecars cold-start model weights; first start takes ~2 min.
docker compose --env-file docker/.env -f docker/docker-compose.yml up -d

# A4. Wait until all three report "healthy" (poll if still "starting").
docker inspect -f '{{.Name}} {{.State.Health.Status}}' \
  pattern-tei-embed-dev pattern-tei-rerank-dev architecture-pattern-mcp-dev

# A5. Probe the MCP endpoint — must print 200.
#     (GET /health is 404 by design; the JSON-RPC initialize POST is the probe.
#      The MCP image has no curl binary; probe from the host.)
curl -s -o /dev/null -w '%{http_code}\n' -X POST "http://localhost:8060/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}'

The server starts on streamable-http at http://localhost:8060/mcp. Config is the repo file config/config.json (mounted at /app/config); restart the server container after editing.

⁠Bringing your own LLM

The default stack uses MiniMax (GENERATOR_PROVIDER=minimax, GENERATOR_MODEL=minimax/MiniMax-M2.7, key from MINIMAXAI_API_KEY). To use another LiteLLM provider, edit the four GENERATOR_* lines in the compose file and put your key in the env file, then restart:

      - GENERATOR_PROVIDER=openai
      - GENERATOR_MODEL=openai/gpt-4o-mini      # LiteLLM syntax: provider/model
      - GENERATOR_BASE_URL=https://api.openai.com/v1
      - GENERATOR_API_KEY=${OPENAI_API_KEY}

⁠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

⁠TEI sidecar configuration

The MCP server reaches the sidecars by Docker DNS (pattern-tei-embed, pattern-tei-rerank) — these match the defaults, so no URL overrides are required in the standard stacks:

The embedder must be TEI serving the same model — the embedder config has no model field, so openai / ollama / vllm providers cannot address an arbitrary remote model without a code change. The reranker is not a LiteLLM client.

Full env var reference: GitHub README → Configuration⁠

⁠Connect your agent

Point at Path A (:8060) or Path B (:8050) depending on which stack you installed.

⁠OpenCode

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

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

⁠VS Code (MCP extension)

Add to .vscode/mcp.json:

{
  "servers": {
    "architecture-pattern": {
      "url": "http://localhost:8060/mcp",
      "type": "http"
    }
  }
}

⁠Claude Code / Codex CLI

# Install (one-time)
git clone https://github.com/olk/architecture-pattern-mcp.git && cd architecture-pattern-mcp
make install

# Add to your agent
claude mcp add architecture-pattern \
  -e GENERATOR_API_KEY=sk-... \
  -- architecture-pattern-mcp --transport stdio

Full client docs: GitHub README → Connect Your Agent⁠

⁠Try it

Ask your agent (or use the Inspector):

This should call design_architecture with:

• requirements: "ETL pipeline for IoT sensor data: ingest 10k events/sec from Kafka, parse JSON, enrich with geolocation from Redis, write to InfluxDB and S3"
• domain: "data-processing"
• style: "pipe-and-filter"

⁠Operations

# Update images (re-resolve VERSION first, then pull + restart)
docker compose --env-file docker/.env -f docker/docker-compose.yml pull
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 architecture-pattern-mcp

# Stop (keep the env file — it holds the API key)
docker compose --env-file docker/.env -f docker/docker-compose.yml down

# Change host port (then update your client URL)
MCP_HOST_PORT=8061 docker compose --env-file docker/.env -f docker/docker-compose.yml up -d

On Linux with a shared host, restrict your env file:

chmod 600 docker/.env

⁠Troubleshooting

⁠Links

• GitHub (source, docs, issue tracker): olk/architecture-pattern-mcp⁠
• Install runbook (agent step-by-step, both paths): INSTALL.md⁠
• TEI infrastructure (embedder + reranker): olk/pattern-tei-infra⁠ · olkowa/pattern-tei-embed⁠ · olkowa/pattern-tei-rerank⁠
• License: MIT⁠