@bicharts/chart-mcp 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bicharts/chart-mcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "MCP (Model Context Protocol) stdio server for BIC AI charts: profile a dataset locally, then generate chart code that has passed the BIC backend's render gates. Works with any MCP-capable client (Claude Code, Claude Desktop, Cursor, Copilot Studio). Requires a BIC trial or paid account.",
   "keywords": [
     "mcp",
@@ -25,6 +25,7 @@
   "// files": "dist ONLY — this package ships the built server, not its source. LICENSE.txt and README.md are included automatically by npm, but listed so an audit does not have to know that.",
   "files": [
     "dist",
+    "skills",
     "LICENSE.txt",
     "README.md"
   ],
@@ -44,8 +45,8 @@
     "zod": "^3.23.0"
   },
   "devDependencies": {
-    "@bicharts/chart-host": "^0.3.0",
-    "@bicharts/shape-core": "^0.3.0",
+    "@bicharts/chart-host": "^0.4.0",
+    "@bicharts/shape-core": "^0.4.0",
     "@types/node": "^20.0.0",
     "@types/papaparse": "^5.3.14",
     "esbuild": "^0.28.1",

package/skills/bic-charts/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: bic-charts
+description: Build a web app or dashboard containing BIC-generated charts — a bubble map, a table with in-cell bars, linked cross-filtering. Use whenever the bic-chart MCP tools are available and the task is "put a chart / dashboard in this app".
+---
+
+# Building an app with BIC charts
+
+The golden path, end to end. Following it costs a handful of tool calls; deriving it from
+first principles costs about thirty, and the places people lose time are all called out
+below because they were all measured.
+
+**The mental model.** A BIC chart is *generated source you own* — a plain
+`render(container, data, options)` function you commit to your repo. There is no API key at
+run time, no per-render cost, and no network call. `@bicharts/chart-host` runs it; the MCP
+generates it. Generation happens **once, at build time, by you** — never in your users'
+browsers.
+
+## 1. Scaffold (one command block)
+
+```bash
+npm create vite@latest my-app -- --template react-ts
+cd my-app
+npm install d3@7 @bicharts/chart-host
+npm install -D @types/d3
+```
+
+`d3` is a peer requirement of the **chart**, not of chart-host. `@types/d3` only for
+TypeScript. chart-host has no runtime dependencies.
+
+## 2. Generate — say what the output must BE, not just what it should look like
+
+Call `generate_chart` once per chart, with `out_dir` so the artifacts land on disk.
+
+The single most important habit: **`prompt` is a suggestion lane.** It steers style and
+emphasis, and it competes with the chart lane's own guidance about summarizing. When your
+app *depends* on the shape of the output, use the contract parameters instead — they are
+authoritative, and `required_columns` is verified in the generated code with an automatic
+correction:
+
+| Parameter | Use it when |
+| --- | --- |
+| `rows_policy: "all"` | every source row must appear — a row-per-entity table, a point per location. Without it the engine may legitimately show a Top-N with an "Other" rollup. |
+| `required_columns: [...]` | a field must be visible because your app's interactions depend on it (e.g. the column you colour or filter by). |
+| `forbid_derived_columns: true` | your app owns the analytics; the chart is only the display. Stops per-capita / share-of-total / rank columns being added. |
+
+Asking for these in `prompt` prose instead is the most expensive mistake available here: it
+routinely costs two or three extra generations, and each one is minutes of wall-clock.
+
+Other parameters worth knowing: `chart_type` (a preference, honored unless the data shape
+disqualifies it), `renderer: "D3"` for a web app, `width`/`height`, and
+`reasoning_mode: "1P"` when you want the cheapest, fastest pass.
+
+**Generation takes minutes.** Fire the calls for independent charts **in parallel** rather
+than in sequence — it is the difference between ~4 minutes and ~12.
+
+## 3. Wire it up
+
+Import the generated code as raw text and the sample payload as JSON:
+
+```tsx
+import * as d3 from "d3";
+import { BicChart, BicChartGroup } from "@bicharts/chart-host/react";
+import mapCode from "./charts/map/chart.js?raw";
+import tableCode from "./charts/table/chart.js?raw";
+import payload from "./charts/map/data.sample.json";
+
+// data.sample.json rows are POSITIONAL arrays; the group wants row OBJECTS.
+const columns = payload.columns;
+const rows = payload.rows.map(r =>
+  Object.fromEntries(columns.map((c, i) => [c.name, r[i]])));
+```
+
+### The coordinated dashboard — the recipe, memorized
+
+```tsx
+<BicChartGroup columns={columns} rows={rows} point={{ city: "City", state: "StateOrProvince" }}>
+  <BicChart id="map"   code={mapCode}   d3={d3} geoKind="na" respondsWith="highlight" />
+  <BicChart id="table" code={tableCode} d3={d3} />
+</BicChartGroup>
+```
+
+That is all of it. The map **highlights** (keeps every bubble, dims the rest) and the table
+**filters**. Cross-filtering is mutual by default, a chart never filters itself, and
+`group.clear()` clears.
+
+Do **not** hand-roll dimming out of the `lch-*` CSS classes. They are an implementation
+detail, they are re-applied on every render (so a `classList` poke is lost at the next data
+change), and translating row indices across a filtered payload is the hazard below.
+
+> **The row-index hazard.** `__rowIdx__` is a position *within the payload a chart
+> received*, not an id in your table. Re-render a chart with filtered rows and its payload
+> renumbers from zero, so the same integer denotes a different record. `BicChartGroup` owns
+> that mapping. Comparing indices across two charts by hand does not throw — it quietly
+> filters to the wrong thing.
+
+### Sizing
+
+Sizing is yours. Give each `<BicChart>` a sized container and pass `width`/`height` in
+`options` — a chart handed `undefined` dimensions draws nothing visible.
+
+## 4. Things that will otherwise cost you time
+
+- **Place names, not coordinates.** If your data has city/state/ZIP but no lat/lon, pass a
+  `point` binding and the host resolves coordinates. Never hardcode a city→coordinate table
+  from memory: it breaks silently off famous cities and reports nothing. The host reports
+  what it achieved in `options.geoPoint` — `precisionCounts` (rows per tier) and
+  `unplaced` — so a chart can annotate honestly instead of implying exact positions.
+- **Both code forms work.** `wrap: "esm"` appends `export { render };` so the file can be
+  imported; chart-host strips the clause before compiling. Either form runs anywhere.
+- **D3 plugins.** Some charts call `d3.sankey`, `d3.hexbin` etc., which live in separate
+  packages. `requiredD3Plugins(code)` tells you which to install **before** rendering;
+  `structuredContent.plugins` on the MCP result says the same thing.
+- **Read `integration_contract`** in the MCP result if you need anything beyond this file —
+  it describes the exact payload and option shape for the chart you just generated.
+
+## 5. Check it
+
+Verify in a real browser, not jsdom — a chart can pass a DOM-shape assertion and paint
+nothing. Assert marks carry `data-row-idx`, that clicking one changes the other chart, and
+that `Clear` restores both. If a check fails, suspect the probe before the product: query
+`fillOpacity` as well as `opacity` when testing dimming, and match buttons by role rather
+than by text that also appears in hint copy.