Blueprint Chart

用于借助大模型编写 Blueprint Chart .bpc 文件的模型上下文协议服务，基于真实的数据可视化教学方法，并提供紧密的解析与渲染反馈循环。这是一种开放的纯文本图表格式，AI 可以编写，任何浏览器都能渲染。独立运行，无需后端，也无需账号。

该 MCP 服务将 Blueprint Chart 的数据可视化手册、DSL 语法参考、图表类型文档和权威示例作为 MCP 资源公开，并提供 11 个确定性工具：validate_dsl、inspect_dsl、recommend_chart_type、render、list_chart_types、describe_chart_type、get_example、get_grammar、export_chart、search_examples 和 list_palettes。你的大模型负责编写 .bpc 文件；MCP 服务以真实的数据可视化教学方法为依据，并提供紧密的反馈循环。

安装

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

与 Claude Desktop 配合使用

添加到 claude_desktop_config.json：

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

与 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

工具

工具	用途
validate_dsl	解析 .bpc；返回 { valid, errors[], warnings[] } — 每个错误都包含 code、message、suggestion
inspect_dsl	解析并汇总：chartType、scenes、seriesCount、rowCount、hasHighlights、hasColorizes 等
recommend_chart_type	根据给定的列结构和行数对图表类型进行排序
render	渲染为 SVG（默认）、PNG 或 HTML；使用 format:"png" 时会返回内嵌图片，你和用户都可以看到。始终返回结构化的框架元数据。设置 MCP_PUBLIC_URL 后，会包含 urls（{png,svg,bpc}）——无状态链接，图表数据包含在 URL 中。设置 modelVisible:false 可从响应中完全移除内嵌图片，不消耗图片令牌。传入 save:<path> 可将输出写入磁盘（需要 MCP_FS_WRITE_DIR；写入范围限定在该目录中）。宽度和高度上限为 1600；PNG 为 2× 视网膜分辨率。
list_chart_types	列出所有可渲染的图表类型（相当于 bpc://handbook/choosing 的工具）
describe_chart_type	说明一种图表类型的属性、适用场景、不适用场景和数据结构（相当于 bpc://chart-types/{slug} 的工具）
get_example	按图表类型或示例名称获取规范的 .bpc 示例（相当于 bpc://samples/{id} 的工具）
search_examples	按主题关键词和／或图表类型查找规范示例（返回指向示例的链接；使用 get_example 获取完整 DSL）
get_grammar	完整的 DSL 语法参考（相当于 bpc://grammar 的工具）
list_palettes	列出 colorPalette 可用的具名颜色调色板及其十六进制颜色值
export_chart	验证 .bpc 并返回可分享的 URL 及内嵌预览。返回 { copyUrl, embedUrl, urls?, frame } — copyUrl 可在编辑器中编辑，embedUrl 是只读 iframe 目标，urls.{png,svg,bpc} 是无状态的渲染结果／源文件链接（设置 MCP_PUBLIC_URL 后提供）。设置 modelVisible:false 可从响应中完全移除内嵌预览，不消耗图片令牌。需要 BLUEPRINT_CHART_EDITOR_URL；预览失败不会阻止导出。

发现工具（list_chart_types、describe_chart_type、get_example、search_examples、get_grammar、list_palettes）让不支持 MCP 资源的客户端也能访问 bpc:// URI 所提供的相同参考资料。

保存渲染结果

render 工具可通过 save: <path> 将输出写入磁盘。默认禁用此功能。设置 MCP_FS_WRITE_DIR 为某个目录即可启用——最好使用绝对路径；相对路径会在服务启动时按服务的工作目录解析。所有写入都发生在该目录内（沙盒），因此无需担心客户端将文件放在何处：相对 save 路径会与该目录拼接；位于该目录内的绝对路径会按原样使用；其他绝对路径则会重新锚定到该目录下（去掉开头的斜杠，再拼接剩余部分，因此 save: "/tmp/foo.png" 会变成 <dir>/tmp/foo.png）。只有通过 ../ 路径遍历仍能逃出目录的路径才会被拒绝。缺失的子目录会自动创建。路径包含性检查采用词法方式（不使用 realpath），因此词法路径位于沙盒内的符号链接仍会通过检查，并在写入时由操作系统解析——如果其目标位于沙盒之外，写入就会到达该目标。如果需要隔离，请避免在沙盒中放置符号链接。

将 -e 标志添加到 claude mcp add 命令中：

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

资源

• bpc://grammar — 完整的 DSL 语法参考
• bpc://handbook/<slug> — 数据可视化教学内容（选择、设计原则、颜色、字体、注释、无障碍等）
• bpc://guide/<slug> — 使用指南（场景、调色板、数据转换等）
• bpc://chart-types/<slug> — 各图表类型的文档
• bpc://samples/<id> — 规范的 .bpc 示例
• bpc://reference/dsl/<slug>、bpc://reference/api/<slug> — 完整参考资料

提示词

• author_chart — 引导大模型完成端到端流程（读取 → 编写 → 验证 → 渲染 → 迭代）

示例

使用 Claude 快速入门

连接 MCP 后，请 Claude 制作图表：

你： 制作一张英语字母频率的水平条形图——显示前 10 个字母，并突出显示 E。

Claude： （调用 list_chart_types、get_example({ chartType: "bar-horizontal" })，编写 .bpc，调用 validate_dsl 确认解析通过，调用 render 并设置 format: 'png'，然后向你展示图像和源代码）

图表如下：

![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; ... }
}

MCP 会先让 Claude 以真实的数据可视化教学内容（手册）为依据，再让它编写第一行 DSL，随后通过确定性的解析和渲染反馈完成闭环。

.bpc 的样子

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
    ...
  }
}

完整语法见 bpc://grammar；17 个规范示例见 bpc://samples/<id>（letter-frequency、co2-emissions、quarterly-revenue、browser-market、temperature-anomaly、population-stacked-bar 等）。

validate_dsl — 使用结构化诊断进行解析

请求：

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

响应——valid 为 false；errors[] 中的每个条目都包含 code、易于理解的 message 和可执行的 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 — 结构化摘要

请求：

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

响应：

{
  "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 — 排序后的建议

请求：

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

响应：

{
  "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（默认）、PNG 或 HTML

请求：

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

响应：

{
  "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=…"
    }
  }
}

只有配置了 MCP_PUBLIC_URL 时才会提供 urls 字段；此时，每个 render 和 export_chart 响应都会包含这些无状态链接，图表数据则包含在 URL 中（以 bpc64 的形式，即对 .bpc 源码进行 URL 安全的 base64 编码）——无需会话，也无需服务器状态。在请求中设置 modelVisible:false，即可完全移除响应中的内嵌图像，不消耗图像令牌。

如果栅格化失败（极少发生），errors[] 将不为空——每个条目都包含 code（"E_RENDER"）和 suggestion；并且响应仍会包含已成功生成的 SVG，从而保留部分成功结果。

托管渲染 URL

将图表直接嵌入页面：

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

/render.bpc 会提供原始 .bpc 源码——相当于任何图表 URL 的“查看源代码”，便于分享或仅凭链接复现图表。

编码后超过 8 KB 的源文件会导致端点返回 413（工具会省略 urls，改为返回 urlsOmitted: "source-too-large"）——对于超大型图表，请使用内嵌 PNG。

读取资源

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

返回“选择合适的图表”手册页面的完整 Markdown（内容与 docs.blueprintchart.com 相同）。

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

以 text/plain 的形式返回字母频率示例的原始 .bpc 源码——正是大模型应当模仿的内容。

许可证

MIT