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 36+ 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).

Prerequisites

• Python 3.12+
• uv (fast Python package manager)
• Docker & Docker Compose (for containerized deployment)
• API key for an LLM provider (OpenAI, MiniMax, Anthropic, etc.)

Quick Start — Docker

1. Clone and configure

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

cp config/config.json ~/.config/architecture-pattern-mcp/config.json

Add your API keys to ~/.config/architecture-pattern-mcp/config.json or export them as environment variables (see Environment Variables):

export GENERATOR_API_KEY=your_key_here

Note for Docker users: The docker compose file ships MINIMAXAI_API_KEY as the outer env var and maps it to GENERATOR_API_KEY inside the container. If you set GENERATOR_API_KEY directly (as shown above), it takes precedence and works for both local and Docker runs.

2. Build and start

# Option A: via docker compose (builds + starts)
docker compose -f docker/docker-compose.yml up --build

# Option B: via make (builds the image, then starts services)
make docker-build
make docker-up

The MCP server starts on streamable-http transport on port 8050. The TEI embedder container (Qwen3-Embedding-0.6B) must be healthy before the server accepts requests — the depends_on + healthcheck in the compose file handles this.

3. Connect an AI agent

See AI Agent Configuration for your specific agent.

Quick Start — Local Development

1. Clone and install

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

# Install with all development dependencies
make install

# Or manually:
uv pip install -e ".[dev]"

2. Configure

cp config/config.json ~/.config/architecture-pattern-mcp/config.json

Edit ~/.config/architecture-pattern-mcp/config.json or set environment variables:

export GENERATOR_API_KEY=your_key_here
export GENERATOR_PROVIDER=openai   # or minimax, anthropic, etc.
export GENERATOR_BASE_URL=https://api.openai.com/v1

3. Start the server

# Direct Python (requires TEI embedder running separately on port 8080)
uv run python -m src.main

# Or use the installed console script
architecture-pattern-mcp

The MCP server listens on streamable-http transport at http://localhost:8050/mcp.

TEI embedder: The local install does not start the TEI embedder automatically. The server will start but pattern retrieval by domain will fall back to the default pattern until the embedder is available at http://127.0.0.1:8080/v1.

4. Connect an AI agent

See AI Agent Configuration for your specific agent.

Tools

The server exposes six MCP tools:

Tool	Description
analyze_architecture	Analyse requirements and domain; returns strengths, weaknesses, recommended style, selected patterns, and quality metrics
generate_architecture	Generate an architecture design from requirements, domain, and selected patterns
evaluate_architecture	Evaluate an existing design against criteria; returns per-metric scores, findings, and recommendations
design_architecture	Full pipeline: analyse → generate → evaluate → refine (up to 3 attempts); returns the best design and its evaluation
list_architecture_patterns	List all known patterns (name + description); optional category and domain filters
get_architecture_pattern	Get the full JSON of a specific pattern by name (e.g. microservices)

Pattern Catalog Access

Two ways to browse the architecture pattern catalog:

Option A — MCP tools (recommended, works in every client)

The list_architecture_patterns and get_architecture_pattern tools return plain JSON text and work in all MCP clients including Claude Code, OpenCode, and Codex.

list_architecture_patterns()                                  # all 36+ patterns
list_architecture_patterns(category="structural")            # filter by category
list_architecture_patterns(domain="microservices")         # filter by domain
list_architecture_patterns(category="dataflow", domain="etl") # combined filters
get_architecture_pattern(name="microservices")               # full pattern JSON
get_architecture_pattern(name="pipe-and-filter")

Output of list_architecture_patterns():

[
  { "name": "microservices", "description": "Large-scale distributed systems requiring independent deployability..." },
  { "name": "pipe-and-filter", "description": "Data transformation pipelines composed of independent filters..." },
  { "name": "event-driven", "description": "Loosely coupled components communicating asynchronously via events..." }
]

Valid category values: messaging, structural, cloud, data, ai_cognitive, specialized, api_gateway, coordination, dataflow, presentation.

Option B — MCP resources (pattern://)

The server also exposes patterns as MCP resources. In OpenCode use the model-invoked resource tools:

mcp_list_resources(server="architecture-pattern")                                  # list all
mcp_read_resource(server="architecture-pattern", uri="pattern://microservices")   # by name

Available resource URIs:

URI	Description
pattern://	List all patterns (returns JSON array with uri, name, description)
pattern://{name}	Get a specific pattern by name (e.g. pattern://microservices)
template://{name}	Get an architecture template by name
component://{type}	Get a component blueprint by type (e.g. component://data-source)

OpenCode @-mention limitation: @-mentioning a resource with a custom URI scheme (like pattern://) may fail because OpenCode attempts to HTTP-dereference the URI as a URL — see opencode#30928. Prefer Option A (the tools) for reliable access in OpenCode.

Raw curl (advanced)

If you need to test resources directly via HTTP, the MCP Streamable HTTP transport requires a session ID:

# 1. Initialize and capture the Mcp-Session-Id header
SESSION=$(curl -sS -i -X POST http://localhost:8050/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{"resources":{}},"clientInfo":{"name":"test","version":"1.0"}}}' \
  | grep -i 'mcp-session-id' | awk '{print $2}' | tr -d '\r\n')

# 2. Use the session for subsequent requests
curl -sS -X POST http://localhost:8050/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: $SESSION" \
  -d '{"jsonrpc":"2.0","id":2,"method":"resources/list","params":{}}'

curl -sS -X POST http://localhost:8050/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: $SESSION" \
  -d '{"jsonrpc":"2.0","id":3,"method":"resources/read","params":{"uri":"pattern://microservices"}}'

Example prompts

Note: Domain and Style are structured tool parameters — the MCP server does not parse them from the requirements text. An AI agent must extract them and pass them as separate tool arguments.

Build a scalable distributed system for processing IoT sensor data with
100k events per second throughput, written in Python, deployed on Kubernetes.

Analyse the requirements for an e-commerce platform handling flash-sales events.
Domain: e-commerce.

Design an architecture for an e-commerce platform handling flash-sales events.
Use microservices style.
Domain: e-commerce.  Style: microservices.

Evaluate this architecture for a banking application that requires strong
consistency and low latency.

Getting pattern details

Ask about any specific pattern to see its full description, components, tradeoffs, and best practices:

Show me details about the blackboard pattern.
What are the components of the event-driven architecture pattern?
Explain the microservices pattern in detail.

This calls get_architecture_pattern(name="blackboard") (or whichever pattern name is mentioned) and returns the full JSON including:

Field	Description
name	Pattern name
category	Pattern category (e.g. ai_cognitive, structural)
context	When this pattern applies
benefits	Key advantages
tradeoffs	Disadvantages and costs
quality_attributes	Scores (1–10) for scalability, maintainability, reliability, security, performance, simplicity
suitable_domains	Where this pattern works well
unsuitable_domains	Where to avoid this pattern
use_cases	Concrete examples
component_types	Key components and their roles
technology_stack	Common technology choices
design_principles	Core principles to follow
best_practices	Recommended practices

Example output for get_architecture_pattern(name="blackboard"):

{
  "name": "blackboard",
  "category": "ai_cognitive",
  "context": "Complex problems requiring multiple specialized knowledge sources where no deterministic solution strategy exists...",
  "benefits": [
    "Reusable knowledge sources: each KS can be reused across different problem domains",
    "Fault tolerance and robustness: wrong hypotheses are filtered out...",
    "Support for changeability and maintainability: KSs, control algorithm, and central data structure are strictly separated"
  ],
  "quality_attributes": {
    "scalability": 7,
    "maintainability": 6,
    "reliability": 6,
    "security": 3,
    "performance": 4,
    "simplicity": 4
  }
}

Example Output

Request to design_architecture for an IoT data-processing pipeline:

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

The server returns a PipelineResult containing:

Architecture overview

{
  "overview": {
    "style": "pipe-and-filter",
    "category": "dataflow",
    "principles": [
      "Single Responsibility: Each filter performs one distinct transformation",
      "Independent Scalability: Each filter scales horizontally based on workload",
      "Fault Isolation: Failures in one filter don't cascade to others"
    ]
  }
}

Components (7 filters + source + sink)

{
  "components": [
    {
      "id": "kafka-source",
      "name": "Kafka Source Connector",
      "type": "data-source",
      "description": "Ingests raw IoT sensor data from Kafka topic with consumer group management",
      "technology_stack": ["Apache Kafka", "Confluent Schema Registry"],
      "config_requirements": ["KAFKA_BOOTSTRAP_SERVERS", "KAFKA_TOPIC", "KAFKA_CONSUMER_GROUP"]
    },
    {
      "id": "json-parser-filter",
      "name": "JSON Parser Filter",
      "type": "filter",
      "description": "Parses JSON-encoded sensor payloads into structured objects",
      "technology_stack": ["Python", "orjson", "pydantic"]
    }
  ]
}

Evaluation

{
  "summary": {
    "overall_score": 78.0,
    "strengths": ["Scalable parallel processing", "Fault isolation per stage"],
    "weaknesses": ["Operational complexity of Kafka"]
  },
  "metrics": {
    "maintainability": 8.2,
    "scalability": 9.1,
    "reliability": 7.8,
    "security": 6.5,
    "performance": 8.0
  },
  "recommendations": {
    "maintainability": [
      "Split transformer-filter into unit-converter-filter, timestamp-normalizer-filter, and outlier-detector-filter"
    ],
    "scalability": [
      "Ensure Kafka partition count exceeds maximum parallelism (recommend 2x current max of 20)"
    ]
  }
}

AI Agent Configuration

All three major AI coding agents use MCP. The server runs as a local stdio subprocess.

Claude Code

First install the package, then add it as an MCP server:

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

# Add as MCP server
claude mcp add architecture-pattern -- architecture-pattern-mcp

Or with environment variables:

claude mcp add architecture-pattern \
  -e GENERATOR_API_KEY=your_key \
  -e GENERATOR_PROVIDER=openai \
  -- architecture-pattern-mcp

Project-scoped (shared with team via .mcp.json):

claude mcp add --scope project architecture-pattern -- architecture-pattern-mcp

OpenCode

The architecture-pattern-mcp server uses HTTP transport (streamable-http on port 8050 by default). Start the server first, then configure opencode as a remote MCP server.

1. Install and start the server:

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

# Option A: Direct Python (from project directory)
uv run python -m src.main

# Option B: Via Docker
make docker-up

2. Add to opencode.json (project root or ~/.config/opencode/opencode.json):

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

Note: The server must be running before opencode connects. Environment variables like GENERATOR_API_KEY are read from the server's config file (~/.config/architecture-pattern-mcp/config.json), not from opencode's config.

Codex CLI

First install the package, then add it as an MCP server:

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

Add to ~/.codex/config.toml:

[mcp_servers.architecture-pattern]
command = "architecture-pattern-mcp"

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

Or via CLI:

codex mcp add architecture-pattern \
  --env GENERATOR_API_KEY=your_key \
  -- architecture-pattern-mcp

Building & Development

The project uses Make as its primary build automation tool. Run make help to see all available targets.

Common targets

Target	Description
make install	Install package in editable mode with all dev dependencies
make lint	Run ruff linting checks
make lint-fix	Auto-fix linting issues and format code
make typecheck	Run pyright type checking
make integration-tests	Run integration tests (tests/integration/)
make client	Run the example MCP client demo (requires server running)
make docker-build	Build the production Docker image
make docker-up	Build and start all services via docker compose
make docker-down	Stop all docker compose services
make docker-logs	Show docker compose logs
make docker-logs-follow	Follow docker compose logs
make docker-verify	Smoke-test the running MCP server (POST initialize, SSE stream, HTTP 406 rejection)
make unit-test	Run unit tests inside a Docker container
make docker-rm	Remove the Docker image

Development workflow

# First-time setup
make install

# Before pushing
make lint typecheck integration-tests

# Docker workflow
make docker-up              # Start services
make docker-verify          # Smoke-test MCP handshake
make docker-logs-follow     # Watch logs in real time
make docker-down            # Stop services

Extending with New Patterns

Architecture patterns are loaded from ~/.config/architecture-pattern-mcp/pattern/ (configurable via PATTERN_DIRECTORY). The server ships with 36+ patterns in pattern/. To add a custom pattern, place a JSON file there.

Minimal pattern structure

{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "category": "structural",
  "name": "my-custom-pattern",
  "context": "Describe when this pattern applies. Be specific about the problem it solves.",
  "benefits": [
    "Benefit 1",
    "Benefit 2"
  ],
  "tradeoffs": [
    "Tradeoff 1",
    "Tradeoff 2"
  ],
  "quality_attributes": {
    "scalability": 7,
    "maintainability": 8,
    "reliability": 7,
    "security": 6,
    "performance": 7,
    "simplicity": 5
  },
  "suitable_domains": ["microservices", "cloud-native"],
  "unsuitable_domains": ["simple-crud-applications", "small-teams"]
}

Required fields

Field	Type	Description
category	string (enum)	messaging, structural, cloud, data, ai_cognitive, specialized, api_gateway, coordination, dataflow, presentation
name	string	Unique kebab-case name
context	string	Problem description
benefits	array of strings	What the pattern provides
tradeoffs	array of strings	Disadvantages
quality_attributes	object	Scores 1–10 for scalability, maintainability, reliability, security, performance, simplicity

Optional fields

Field	Type	Description
suitable_domains	array of strings	Domain names where this pattern works well
unsuitable_domains	array of strings	Domain names where to avoid
use_cases	array of strings	Concrete use case examples
avoid_when	array of strings	When NOT to use this pattern
component_types	array of strings	Key component roles in the pattern
technology_stack	array of strings	Common technology choices
anti_patterns	array of strings	Common mistakes with this pattern
migration_from	array of strings	Patterns commonly migrated from
migration_to	array of strings	Patterns commonly migrated to
design_principles	array of strings	Core design principles
best_practices	array of strings	Recommended practices

The full JSON Schema (with all domain enums) is at docs/pattern-schema.json.

Configuration Reference

The server reads config/config.json (or the path in 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.7,
      "top_p": 1.0,
      "top_k": 20
    }
  },
  "embedder": {
    "provider": "tei",
    "config": {
      "model": "data/qwen3-embedding-0.6b",
      "base_url": "http://127.0.0.1:8080/v1",
      "embedding_dim": 1024
    }
  },
  "retrieval": {
    "bm25_top_k": 0,
    "dense_top_k": 0,
    "top_k_patterns": 5,
    "mode": "reciprocal_rerank",
    "min_quality_score": 50.0,
    "pattern_context_limits": {
      "benefits": 3,
      "tradeoffs": 3,
      "best_practices": 3,
      "component_types": 5,
      "technology_stack": 5,
      "anti_patterns": 3,
      "suitable_domains": 5
    }
  },
  "pattern_directory": "~/.config/architecture-pattern-mcp/pattern"
}

Note: bm25_top_k: 0 / dense_top_k: 0 means "full corpus" — no limit is applied to stage-1 recall. The retriever uses the full pattern set before fusion and re-ranking.

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

Environment Variables

Variable	Default	Description
CONFIG_PATH	~/.config/architecture-pattern-mcp/config.json	Path to config file
GENERATOR_PROVIDER	openai	LLM provider (openai, minimax, anthropic, etc.)
GENERATOR_MODEL	gpt-4o-mini	Model name
GENERATOR_BASE_URL	https://api.openai.com/v1	API base URL
GENERATOR_API_KEY	(required)	API key for the LLM provider
GENERATOR_TEMPERATURE	0.7	LLM sampling temperature
EMBEDDER_PROVIDER	tei	Embedder provider (tei or openai)
EMBEDDER_MODEL	data/qwen3-embedding-0.6b	TEI model name or path
EMBEDDER_BASE_URL	http://127.0.0.1:8080/v1	TEI server URL
EMBEDDER_API_KEY	not-needed	TEI API key (not needed for local TEI)
PATTERN_DIRECTORY	~/.config/architecture-pattern-mcp/pattern	Directory for pattern JSON files
RETRIEVAL_BM25_TOP_K	0	BM25 retrieval count (0 = full corpus, no limit)
RETRIEVAL_DENSE_TOP_K	0	Dense vector retrieval count (0 = full corpus, no limit)
RETRIEVAL_TOP_K_PATTERNS	5	Number of top patterns to retrieve
RETRIEVAL_MODE	reciprocal_rerank	Retrieval fusion mode
RETRIEVAL_MIN_QUALITY_SCORE	50.0	Early-stop quality threshold

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: the compose logs should show MCPArchitectServer initialized.
3. Confirm the TEI embedder is healthy: curl http://127.0.0.1:8080/health inside the container.

"Connection refused" or timeout errors

The server waits for the TEI embedder to become healthy. Check:

docker compose -f docker/docker-compose.yml logs tei

If TEI fails to start, verify the model path data/qwen3-embedding-0.6b is accessible inside the container (it's baked in at build time via docker/Dockerfile.tei).

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 GENERATOR_BASE_URL is reachable from inside the container.

No patterns found for domain

The embedder is required for domain-scoped pattern retrieval. Without it, the server falls back to the DEFAULT_FALLBACK_PATTERN_NAME pattern. Ensure:

curl http://127.0.0.1:8080/v1/embeddings \
  -X POST \
  -d '{"inputs":"cloud-native microservices"}' \
  -H 'Content-Type: application/json'

returns a vector.

Pattern JSON files not loading

• Files must have .json extension.
• Required fields: category, name, context, benefits, tradeoffs, quality_attributes.
• Validate against docs/pattern-schema.json with a JSON schema validator.
• Check for trailing commas or missing quotes — the server uses Pydantic validation and will emit a clear error.