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

export GENERATOR_API_KEY=your_key_here

# 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

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]"

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

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

# 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

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")

[
  { "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..." }
]

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

# 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"}}'

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.

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

{
  "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
  }
}

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

{
  "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": [
    {
      "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"]
    }
  ]
}

{
  "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)"
    ]
  }
}

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

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

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

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

# 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

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

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

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

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

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

# 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

{
  "$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"]
}

{
  "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"
}

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

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