Blueprint

An MCP server for generating and visualizing C4 software architecture diagrams.

What is Blueprint?

Blueprint is a Model Context Protocol (MCP) server that enables AI assistants to create C4 architecture diagrams. It provides three tools:

Related MCP server: AI Charts

What are C4 Diagrams?

The C4 model is a lean graphical notation technique for modelling software architecture. It uses a hierarchical set of four diagrams at different abstraction levels:

1. Context (Level 1) — The big picture: your system, its users, and the external systems it interacts with. Use this to communicate with non-technical stakeholders.

2. Container (Level 2) — Zooms into a system to show the high-level technical building blocks (web apps, mobile apps, databases, message brokers) and how they interact.

3. Component (Level 3) — Zooms into a container to show its major structural components (services, repositories, controllers, etc.) and their responsibilities.

4. Code (Level 4) — Optional: UML class diagrams for individual components. Blueprint does not generate this level.

Blueprint also supports Deployment diagrams (how containers are deployed to infrastructure) and Dynamic diagrams (runtime interactions and data flow between elements).

How to Create C4 Diagrams

There are two ways to direct Blueprint to generate a diagram:

Option 1: Describe Your Architecture in Conversation

Simply describe your system to the AI assistant in natural language. The LLM will extract the relevant C4 elements and relationships, then call create_c4_diagram on your behalf. For example:

"I need a context diagram for an e-commerce platform. There's a customer who browses products and places orders through a web application. The web app talks to a payment service and an inventory database."

The assistant will translate this into the structured JSON that Blueprint expects and return a diagram.

Option 2: Call the Tool Directly with Structured Data

If you prefer precise control, ask the LLM to call create_c4_diagram with explicit JSON. First, optionally use scan_codebase to get a project overview, or get_c4_reference to look up valid element types. Then create the diagram:

{
  "diagram_type": "context",
  "title": "My System",
  "elements": [
    {"type": "Person", "alias": "user", "label": "User", "description": "A system user"},
    {"type": "System", "alias": "myapp", "label": "My Application", "description": "The main system"}
  ],
  "relationships": [
    {"source": "user", "target": "myapp", "label": "Uses", "technology": "HTTPS"}
  ],
  "output_format": "mermaid"
}

Supported diagram types: context, container, component, deployment, dynamic

Use boundaries (EnterpriseBoundary, SystemBoundary, ContainerBoundary) to visually group related elements.

Rendered SVG Output

To get a rendered SVG image alongside the source code, set render_image to true:

{
  "diagram_type": "context",
  "title": "My System",
  "elements": [
    {"type": "Person", "alias": "user", "label": "User"},
    {"type": "System", "alias": "myapp", "label": "My Application"}
  ],
  "relationships": [
    {"source": "user", "target": "myapp", "label": "Uses"}
  ],
  "output_format": "mermaid",
  "render_image": true
}

When render_image is true, the tool returns both the diagram source code and the rendered SVG. SVG is vector-based — it scales to any size without quality loss and renders inline in VS Code, GitHub, and most markdown editors. Rendering is powered by Kroki — no local dependencies required. If rendering fails, the source code is still returned with an error message.

To use a self-hosted Kroki instance, set the BLUEPRINT_KROKI_URL environment variable (defaults to https://kroki.io).

Quick Start

Blueprint uses uv for zero-config setup — no manual virtual environment needed.

# Install uv (if not already installed)

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Start the MCP server (dependencies are installed automatically)
uv run blueprint

# Run tests (includes dev dependencies)
uv run --extra dev pytest

MCP Client Configuration

Add to your MCP client settings:

{
  "mcpServers": {
    "blueprint": {
      "command": "uv",
      "args": ["run", "blueprint"]
    }
  }
}

Usage

Scan a Codebase

Use scan_codebase to get a quick structural overview before diagramming:

{
  "project_path": "/path/to/project",
  "max_depth": 3
}

Returns project structure, detected language/framework, dependencies, and entry points.

Look Up C4 Reference

Use get_c4_reference to retrieve documentation on valid element types, diagram types, and relationships:

{
  "topic": "all"
}

Valid topics: elements, diagrams, relationships, all.

Output Formats

Development

# Run tests
uv run --extra dev pytest

# Run tests with verbose output
uv run --extra dev pytest -v

License

MIT