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:

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)

Quick Start

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows

# Install
pip install -e ".[dev]"

# Run tests
pytest

# Start the MCP server
python -m blueprint.server

MCP Client Configuration

Add to your MCP client settings:

{
  "mcpServers": {
    "blueprint": {
      "command": "python",
      "args": ["-m", "blueprint.server"],
      "cwd": "/path/to/blueprint"
    }
  }
}

Usage

Create a C4 Context Diagram

The LLM discusses architecture with the user, then calls create_c4_diagram:

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

Scan a Codebase

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

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

Output Formats

• Mermaid (default) — Renders inline in VS Code, GitHub, and many markdown editors
• PlantUML — Full C4-PlantUML macro support, requires external renderer

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with verbose output
pytest -v

License

MIT