@blueprint-chart/docs 0.1.20 → 0.1.22

package/dist/manifest.json

@@ -109,9 +109,16 @@
       "slug": "getting-started",
       "group": "guide",
       "title": "getting started",
-      "blurb": "Blueprint Chart is published as four packages on NPM. Pick the one that matches what you're building.",
+      "blurb": "Blueprint Chart is published as four packages on NPM, plus a separate `@blueprint-chart/mcp` server for authoring charts with AI. Pick the one that matches what you're building.",
       "mdPath": "guide/getting-started.md"
     },
+    {
+      "slug": "mcp",
+      "group": "guide",
+      "title": "mcp",
+      "blurb": "Describe the chart you want; let your AI assistant build it. The",
+      "mdPath": "guide/mcp.md"
+    },
     {
       "slug": "palettes",
       "group": "guide",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blueprint-chart/docs",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "description": "Public documentation for Blueprint Chart — handbook, guide, BPC DSL spec, and lib API reference.",
   "type": "module",
   "license": "MIT",
@@ -48,8 +48,8 @@
     "vitepress": "^1.5.0",
     "vitest": "^3.2.4",
     "vue": "^3.5",
-    "@blueprint-chart/lib": "0.1.20",
-    "@blueprint-chart/ui": "0.1.20"
+    "@blueprint-chart/lib": "0.1.22",
+    "@blueprint-chart/ui": "0.1.22"
   },
   "scripts": {
     "dev": "vitepress dev src --host 0.0.0.0 --port 4445",

package/src/guide/getting-started.md

@@ -1,6 +1,6 @@
 # Getting Started
 
-Blueprint Chart is published as four packages on NPM. Pick the one that matches what you're building.
+Blueprint Chart is published as four packages on NPM, plus a separate `@blueprint-chart/mcp` server for authoring charts with AI. Pick the one that matches what you're building.
 
 <table>
 <thead><tr><th>Package</th><th>When to use it</th></tr></thead>
@@ -9,6 +9,7 @@ Blueprint Chart is published as four packages on NPM. Pick the one that matches
 <tr><td nowrap><a href="https://www.npmjs.com/package/@blueprint-chart/ui"><code>@blueprint-chart/ui</code></a></td><td>Vue 3 component library — forms, panels, navigation, scene timeline, layout primitives.</td></tr>
 <tr><td nowrap><a href="https://www.npmjs.com/package/@blueprint-chart/editor"><code>@blueprint-chart/editor</code></a></td><td>The full SPA — runs on top of <code>lib</code> + <code>ui</code>. Deployed at <a href="https://blueprintchart.com">blueprintchart.com</a>.</td></tr>
 <tr><td nowrap><a href="https://www.npmjs.com/package/@blueprint-chart/docs"><code>@blueprint-chart/docs</code></a></td><td>The markdown source of this site — handbook, guide, BPC DSL spec, and lib API reference. Exposes <code>listDocs</code> / <code>getDoc</code> + <code>manifest.json</code> for tooling such as <code>@blueprint-chart/mcp</code>.</td></tr>
+<tr><td nowrap><a href="https://www.npmjs.com/package/@blueprint-chart/mcp"><code>@blueprint-chart/mcp</code></a></td><td>MCP server (separate repo) — lets Claude, Claude Code, Cursor, or any MCP client author <code>.bpc</code> files, grounded in the handbook with a parse + render feedback loop. See <a href="/guide/mcp">Authoring with AI</a>.</td></tr>
 </tbody>
 </table>
 

package/src/guide/mcp.md

@@ -0,0 +1,139 @@
+# Authoring with AI
+
+Describe the chart you want; let your AI assistant build it. The
+[`@blueprint-chart/mcp`](https://github.com/blueprint-chart/mcp) server connects Blueprint
+Chart to any [Model Context Protocol](https://modelcontextprotocol.io) client — Claude (web,
+desktop, and Code), ChatGPT, Cursor, VS Code, and more. The model reads the dataviz handbook,
+writes the `.bpc`, validates it, and renders it — so you get a real, accessible chart from a
+sentence instead of guesswork.
+
+## How it works
+
+The MCP gives your assistant a tight, grounded loop:
+
+**read the handbook → write `.bpc` → `validate_dsl` → `render` → iterate**
+
+It is primed on Blueprint Chart's dataviz pedagogy *before* it writes a line of DSL, then
+closes the loop with deterministic parse + render feedback instead of hallucinating syntax.
+
+## Connect your client
+
+There are two ways to connect: use the **hosted** endpoint (nothing to install) or **run the
+server locally** with `npx`.
+
+### Hosted — `mcp.blueprintchart.com`
+
+Point any remote-capable client at the public endpoint. There's nothing to install and no token
+to configure — it's open.
+
+**Endpoint:** `https://mcp.blueprintchart.com`
+
+- **Claude.ai (web)** — requires a Claude Pro, Team, or Enterprise plan:
+  1. Open **Settings → Connectors**.
+  2. Click **Add custom integration**.
+  3. Paste `https://mcp.blueprintchart.com` and save. There's no auth header to enter.
+- **ChatGPT** — add `https://mcp.blueprintchart.com` as a custom connector (no authentication).
+- **Cursor** — **Settings → MCP → Add server**, then enter the URL.
+- **Claude Code** — add it over HTTP:
+
+  ```bash
+  claude mcp add blueprint-chart --transport http https://mcp.blueprintchart.com
+  ```
+
+### Local — run it with `npx`
+
+Prefer to run the server on your own machine (for desktop apps, offline use, or full control)?
+`npx` fetches it on demand — nothing is installed globally.
+
+::: code-group
+
+```bash [Claude Code]
+claude mcp add blueprint-chart -- npx -y @blueprint-chart/mcp
+```
+
+```json [Claude Desktop]
+{
+  "mcpServers": {
+    "blueprint-chart": {
+      "command": "npx",
+      "args": ["-y", "@blueprint-chart/mcp"]
+    }
+  }
+}
+```
+
+```json [Cursor]
+{
+  "mcpServers": {
+    "blueprint-chart": {
+      "command": "npx",
+      "args": ["-y", "@blueprint-chart/mcp"]
+    }
+  }
+}
+```
+
+```json [VS Code]
+{
+  "servers": {
+    "blueprint-chart": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@blueprint-chart/mcp"]
+    }
+  }
+}
+```
+
+:::
+
+Any other MCP client works too — run `npx -y @blueprint-chart/mcp` over stdio and drop it into
+that client's server config.
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `validate_dsl` | Parse `.bpc`; returns `{ valid, errors[], warnings[] }` — each error carries a `code`, `message`, and actionable `suggestion` |
+| `inspect_dsl` | Summarize a `.bpc`: chart type, scenes, series/row counts, feature flags |
+| `recommend_chart_type` | Rank chart types for a given column shape and row count |
+| `render` | Render to SVG (default) or PNG, with structured errors on failure |
+| `list_chart_types` | List all renderable chart types |
+| `describe_chart_type` | Properties, when-to-use, and data shape for one chart type |
+| `get_example` | Fetch a canonical `.bpc` sample by chart type or name |
+| `get_grammar` | Full DSL syntax reference |
+
+## Resources
+
+The handbook, DSL grammar, guides, chart-type docs, and canonical samples are all exposed as
+`bpc://` resources — the same content you're reading on this site:
+
+- `bpc://grammar` — the full DSL syntax reference
+- `bpc://handbook/<slug>` — dataviz pedagogy (choosing, color, typography, 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>` and `bpc://reference/api/<slug>` — the full reference
+
+## Example
+
+> **You:** Make a horizontal bar chart of English letter frequencies — top 10, highlight E.
+>
+> **Your assistant:** *(calls `list_chart_types` and `get_example`, writes the `.bpc`, calls
+> `validate_dsl` to confirm it parses, then `render` and shows you the image and the source)*
+
+```bpc
+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; ... }
+}
+```
+
+## Learn more
+
+Full setup, the complete tool/resource reference, and release notes live in the
+[MCP repository](https://github.com/blueprint-chart/mcp) and on
+[npm](https://www.npmjs.com/package/@blueprint-chart/mcp).