# Blueprint

An MCP server for generating and visualizing [C4 software architecture diagrams](https://c4model.com).

## What is Blueprint?

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

| Tool | Purpose |
|------|---------|
| `create_c4_diagram` | Build C4 diagrams from structured element/relationship data |
| `scan_codebase` | Get a structural overview of a project (language, deps, entry points) |
| `get_c4_reference` | C4 model documentation (element types, diagram types, relationships) |

## What are C4 Diagrams?

The [C4 model](https://c4model.com) 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:

```json
{
  "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`:

```json
{
  "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](https://kroki.io) — 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](https://docs.astral.sh/uv/) for zero-config setup — no manual virtual environment needed.

```bash
# 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:

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

## Usage

### Scan a Codebase

Use `scan_codebase` to get a quick structural overview before diagramming:

```json
{
  "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:

```json
{
  "topic": "all"
}
```

Valid topics: `elements`, `diagrams`, `relationships`, `all`.

## Output Formats

| Format | Source code | Rendered SVG |
|--------|------------|--------------|
| **Mermaid** (default) | ✅ Inline in VS Code, GitHub, markdown editors | ✅ Via Kroki |
| **PlantUML** | ✅ Full C4-PlantUML macro support | ✅ Via Kroki |

## Development

```bash
# Run tests
uv run --extra dev pytest

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

## License

MIT