Blueprint Chart

[blueprint-chart]

Model Context Protocol server for authoring Blueprint Chart .bpc files with LLMs, grounded in real dataviz pedagogy with a tight parse + render feedback loop. An open, plain-text chart format an AI can write and any browser can render. Self-contained, no backend, no account required.

The MCP exposes Blueprint Chart's dataviz handbook, DSL grammar reference, chart-type docs, and canonical samples as MCP resources, plus eleven deterministic tools: validate_dsl, inspect_dsl, recommend_chart_type, render, list_chart_types, describe_chart_type, get_example, get_grammar, export_chart, search_examples, and list_palettes. Your LLM writes the .bpc; the MCP grounds it in real dataviz pedagogy and gives it a tight feedback loop.

Install

npx @blueprint-chart/mcp           # stdio (for Claude Desktop, Claude Code, Cursor)npx @blueprint-chart/mcp --http    # HTTP/SSE on 127.0.0.1:4321

Use with Claude Desktop

Add to claude_desktop_config.json:

{  "mcpServers": {    "blueprint-chart": {      "command": "npx",      "args": ["-y", "@blueprint-chart/mcp"]    }  }}

Use with Claude Code

claude mcp add blueprint-chart \  -e BLUEPRINT_CHART_EDITOR_URL=https://blueprintchart.com \  -e BLUEPRINT_CHART_DOCS_URL=https://docs.blueprintchart.com \  -- npx -y @blueprint-chart/mcp

Tools

The discovery tools (list_chart_types, describe_chart_type, get_example, search_examples, get_grammar, list_palettes) let clients without MCP resource support access the same reference material that the bpc:// URIs expose.

Saving rendered output

The render tool can write its output to disk via save: <path>. This is disabled by default. Set MCP_FS_WRITE_DIR to a directory to enable it — ideally an absolute path; a relative value is resolved from the server's working directory at startup. Every write lands inside that directory (a sandbox), so you never have to worry about where a client puts files: relative save paths are joined to it, an absolute path already inside it is used as-is, and any other absolute path is re-anchored under it (the leading slash is stripped and the rest joined on, so save: "/tmp/foo.png" becomes <dir>/tmp/foo.png). Only paths that still escape via ../ traversal are rejected. Missing subdirectories are created automatically. Containment is checked lexically (no realpath), so a symlink whose lexical path is inside the sandbox still passes the check and is then resolved by the OS at write time — if its target is outside the sandbox, the write reaches it. Avoid placing symlinks in the sandbox if isolation matters to you.

Add the -e flag to your claude mcp add command:

claude mcp add blueprint-chart \  -e MCP_FS_WRITE_DIR=/path/to/output \  -- npx -y @blueprint-chart/mcp

Resources

• bpc://grammar — full DSL syntax reference
• bpc://handbook/<slug> — dataviz pedagogy (choosing, design-principles, color, typography, annotations, accessibility, ...)
• bpc://guide/<slug> — usage guides (scenes, palettes, data-transforms, ...)
• bpc://chart-types/<slug> — per-chart-type docs
• bpc://samples/<id> — canonical .bpc examples
• bpc://reference/dsl/<slug>, bpc://reference/api/<slug> — full reference

Prompts

• author_chart — primes the LLM end-to-end (read → write → validate → render → iterate)

Examples

Quickstart with Claude

Once the MCP is connected, ask Claude to make a chart:

You: Make a horizontal bar chart of English letter frequencies — top 10, highlight E.

Claude: (calls list_chart_types, get_example({ chartType: "bar-horizontal" }), writes the .bpc, calls validate_dsl to confirm it parses, calls render with format: 'png' and shows you the image and the source)

Here's the chart:

![image]

chart bar-horizontal {  title = "E is the most frequent letter in English"  sort = descending  valueLabels = true  highlight "E"  data { "E" = 12.70; "T" = 9.06; "A" = 8.17; ... }}

The MCP grounds Claude in real dataviz pedagogy (the handbook) before it writes a single line of DSL, then closes the loop with deterministic parse + render feedback.

What .bpc looks like

chart bar-vertical {  title = "E is the most frequent letter in English"  description = "How often each letter appears in typical English text"  source = "Lewand, Cryptological Mathematics"  colorPalette = "London"  sort = descending  valueLabels = true  highlight "E"
  data {    "E" = 12.70    "T" = 9.06    "A" = 8.17    "O" = 7.51    ...  }}

Full grammar at bpc://grammar; 17 canonical samples at bpc://samples/<id> (letter-frequency, co2-emissions, quarterly-revenue, browser-market, temperature-anomaly, population-stacked-bar, ...).

validate_dsl — parse with structured diagnostics

Request:

{  "name": "validate_dsl",  "arguments": { "source": "chart bar-vertical {\n  title = \"oops\n}" }}

Response — valid is false; each entry in errors[] carries a code, human-readable message, and an actionable suggestion:

{  "valid": false,  "errors": [    {      "code": "E_PARSE",      "message": "Expected \"\\\"\" but end of input found.",      "suggestion": "Close the string literal on line 2."    }  ],  "warnings": []}

inspect_dsl — structured summary

Request:

{ "name": "inspect_dsl", "arguments": { "source": "<.bpc source>" } }

Response:

{  "ok": true,  "data": {    "chartType": "bar-vertical",    "scenes": [{ "index": 1, "hasTransition": false }],    "hasAnnotations": false,    "hasColorizes": false,    "hasHighlights": true,    "hasAreaFills": false,    "seriesCount": 0,    "rowCount": 26  }}

recommend_chart_type — ranked suggestions

Request:

{  "name": "recommend_chart_type",  "arguments": { "columnTypes": ["date", "number", "number", "number"], "rowCount": 24 }}

Response:

{  "ok": true,  "data": {    "recommendations": [      { "chartType": "line-multi", "label": "Multi-Line Chart", "fitness": "best",        "reason": "1 date + 3 numeric columns — compare trends" },      { "chartType": "bar-multi",  "label": "Grouped Bar Chart", "fitness": "alternative",        "reason": "Can also show as grouped bars" }    ]  }}

render — SVG (default), PNG, or HTML

Request:

{  "name": "render",  "arguments": { "source": "<.bpc source>", "format": "png", "width": 800, "height": 500 }}

Response:

{  "ok": true,  "data": {    "svg": "<svg ...>...</svg>",    "png": "<base64-encoded image>",    "mimeType": "image/png",    "urls": {      "png": "https://mcp.blueprintchart.com/render.png?bpc64=…",      "svg": "https://mcp.blueprintchart.com/render.svg?bpc64=…",      "bpc": "https://mcp.blueprintchart.com/render.bpc?bpc64=…"    }  }}

The urls field is only present when MCP_PUBLIC_URL is configured; every render and export_chart response then includes these stateless links, with the chart data travelling inside the URL (as bpc64, a URL-safe base64 encoding of the .bpc source) — no session, no server state required. Set modelVisible:false in the request to drop the inline image from the response entirely, spending no image tokens.

If rasterization fails (rare), errors[] is non-empty — each entry has a code ("E_RENDER") and a suggestion — and the response still includes the SVG that was successfully produced, so partial success is preserved.

Hosted render URLs

Embed a chart directly in a page:

<img src="https://<your-mcp-host>/render.png?bpc64=<bpc64value>&width=800&height=500" alt="My chart" width="800" height="500">

/render.bpc serves the raw .bpc source — it's "view source" for any chart URL, handy for sharing or reproducing a chart from its link alone.

Sources whose encoding exceeds 8 KB return 413 from the endpoints (and the tool omits urls, returning urlsOmitted: "source-too-large" instead) — use the inline PNG for very large charts.

Reading a resource

{ "uri": "bpc://handbook/choosing" }

Returns the full Markdown of the "Choosing the Right Chart" handbook page (same content as docs.blueprintchart.com).

{ "uri": "bpc://samples/letter-frequency" }

Returns the raw .bpc source for the letter-frequency sample as text/plain — exactly what the LLM should imitate.

License

MIT