Clarity-beta

Clarity-beta is an MCP server that converts Markdown files into beautiful diagrams — flowcharts, mind maps, architecture diagrams, ER diagrams, Gantt charts, sequence diagrams, and more. Built with Apple HIG design language.

Installation

git clone https://github.com/rutika196/clarity-beta.git
cd clarity-beta
python3 -m venv .venv
source .venv/bin/activate        # macOS / Linux
# .venv\Scripts\activate         # Windows
pip install -e .
playwright install chromium

IDE Setup

Cursor

Create or edit .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "clarity-beta": {
      "command": "/absolute/path/to/clarity-beta/.venv/bin/python",
      "args": ["-m", "src.server"],
      "cwd": "/absolute/path/to/clarity-beta"
    }
  }
}

Replace /absolute/path/to/clarity-beta with your actual project path.

VS Code

Create .vscode/mcp.json in your project root:

{
  "servers": {
    "clarity-beta": {
      "command": "/absolute/path/to/clarity-beta/.venv/bin/python",
      "args": ["-m", "src.server"],
      "cwd": "/absolute/path/to/clarity-beta"
    }
  }
}

VS Code reads MCP config from .vscode/mcp.json — no need to touch settings.json.

IntelliJ IDEA / WebStorm / PyCharm (JetBrains)

JetBrains IDEs (2025.1+) support MCP via the AI Assistant plugin.

1. Go to Settings → Tools → AI Assistant → MCP Servers.

2. Click + Add and fill in:

Or edit the MCP config file directly at ~/.config/jetbrains/mcp.json:

{
  "mcpServers": {
    "clarity-beta": {
      "command": "/absolute/path/to/clarity-beta/.venv/bin/python",
      "args": ["-m", "src.server"],
      "cwd": "/absolute/path/to/clarity-beta"
    }
  }
}

Windows users: replace .venv/bin/python with .venv\\Scripts\\python.exe and use \\ in paths.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "clarity-beta": {
      "command": "/absolute/path/to/clarity-beta/.venv/bin/python",
      "args": ["-m", "src.server"],
      "cwd": "/absolute/path/to/clarity-beta"
    }
  }
}

Usage

As a standalone server (stdio transport)

source .venv/bin/activate
clarity-beta
# or
python -m src.server

MCP Tools

render_diagram

Render the first diagram found in a Markdown file or raw text.

render_all_diagrams

Render every diagram block in a file. Same parameters plus output_dir to save files.

list_diagrams

List detected diagram blocks with types and line numbers, without rendering.

Supported Diagram Types

Via Mermaid.js (Playwright)

flowchart, sequence, class, ER, state, gantt, gitGraph, pie, timeline, quadrant, sankey, xychart, block-beta, architecture-beta, kanban, journey, C4

Custom SVG Renderers

• Mind maps — balanced horizontal tree with organic Bézier connectors

• Architecture / service diagrams — Miro-style auto-layout with icons, step badges, groups

Examples

See the examples/ folder — 13 ready-to-render Markdown files:

Running Tests

python tests/test_all.py

Dependencies

• mcp[cli] — MCP Python SDK

• playwright — Headless Chromium for Mermaid rendering and PNG/JPEG export

• cairosvg — SVG to PDF conversion

• Pillow — Image processing (optional, for JPEG)