@bicharts/chart-mcp 0.6.51 → 0.6.52

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bicharts/chart-mcp",
-  "version": "0.6.51",
+  "version": "0.6.52",
   "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",
@@ -47,8 +47,8 @@
     "zod": "^3.23.0"
   },
   "devDependencies": {
-    "@bicharts/chart-host": "^0.6.51",
-    "@bicharts/shape-core": "^0.6.51",
+    "@bicharts/chart-host": "^0.6.52",
+    "@bicharts/shape-core": "^0.6.52",
     "@types/node": "^20.0.0",
     "@types/papaparse": "^5.3.14",
     "esbuild": "^0.28.1",

package/skills/bic-charts/SKILL.md

@@ -460,6 +460,13 @@ A Fabric App built from Rayfin's `dataapp` template is a React app over a semant
 path above applies unchanged; these are the places a data app differs, each one measured on a real
 build.
 
+**0. Once, right after scaffolding: `setup_fabric_app`.** It installs `@bicharts/chart-host` and `d3`, adds
+`src/lib/bic-chart-options.ts` (`useBicChartOptions()`: the app's Fabric theme - palette, foreground,
+background - as chart options, so charts follow light and dark) and `src/components/bic-chart-panel.tsx`
+(`<BicChartPanel result={useSemanticModelQuery(...)}>`: a box that measures itself and shows the query's
+loading, error and empty states), and ignores `.bic/`. It never overwrites a file, and its reply ends with a
+worked example.
+
 **1. Pull each chart's rows at the chart's GRAIN, with a query written for that chart.** One row per
 country for a country map, one per route for a flow map, one per month for a trend. The template's
 writing-phase command is `npx fabric-app-data query <alias> --query '<DAX>'`. Don't pull a fact
@@ -479,6 +486,15 @@ name. Pass the model's metadata as you rename: `isMeasure`, `format` and `descri
 `INFO.VIEW.MEASURES()` / `INFO.VIEW.COLUMNS()`) go on each column in `data`, which is the context a
 Power BI visual gets for free.
 
+**Steps 1-3 are one call: `query_semantic_model`.** Give it the chart's DAX (`dax`, or a `.dax` file) and a
+`name`; it runs the query through the project's own `fabric-app-data` CLI, renames the headers (dropping the
+table and any symbols: `[Return Rate %]` becomes `ReturnRate`), saves every row to `.bic/data/<name>.csv`,
+reads each column's role, format and description from the model (`INFO.VIEW.MEASURES()` / `INFO.VIEW.COLUMNS()`),
+and profiles the result. Its reply ends with the arguments for the next two calls - `csv_path`, `measures`,
+`dimensions`, `formats`, `descriptions` - so pass them to `list_eligible_charts` and `generate_chart` as they
+are. The CLI returns at most 1,000 rows; the tool says so when it cut a result, and the fix is a query at the
+chart's grain.
+
 **4. Ask before choosing, then choose what answers the question.** `list_eligible_charts` on that
 data. The catalogue goes past the template's own charts, and these are the ones people describe
 without naming:
@@ -495,7 +511,30 @@ when your table is small, and it says when `name_filter` hid description matches
 
 **5. Render live rows through the group, with the binding the generation returned.** The template
 queries at run time (`useSemanticModelQuery`), so the payload is rebuilt from live rows every time -
-never hand-built. `generate_chart` returns `binding` (`geo`, `point`, `destination`); pass all three:
+never hand-built. **With `out_dir`, a D3 chart arrives with `chart.component.tsx` beside `chart.js`: a component that
+already does all of this** - the columns, the binding (`geo`, `point`, `destination`), the geometry kind, the
+d3 plugins the chart calls, and `rowsFromTable`, which maps a DAX result's `Table[Column]` and `[Measure]`
+headers onto the chart's plain names. Use it as it is:
+
+```tsx
+// The component is named after the chart type ("Bivariate World Choropleth" -> BivariateWorldChoroplethChart).
+import { BivariateWorldChoroplethChart, rowsFromTable } from "@/charts/country-map/chart.component";
+
+import { BicChartPanel } from "@/components/bic-chart-panel";
+import { useBicChartOptions } from "@/lib/bic-chart-options";
+
+const result = useSemanticModelQuery({ connection: "<alias>", query: QUERY });  // the DAX it was generated on
+const options = useBicChartOptions();
+<BicChartPanel result={result}>
+  {(table, size) => (                                // table = the live { columns, rows } result
+    <BivariateWorldChoroplethChart table={table} {...size} options={options}
+      onSelectRows={picked => onPick(picked[0]?.CountryCode ?? null)} />
+  )}
+</BicChartPanel>
+```
+
+It is rewritten with the chart on every generation, so keep app logic outside it. What it does, if you
+host by hand instead - `generate_chart` returns `binding`; pass all three:
 
 ```tsx
 import * as d3 from "d3";
@@ -535,6 +574,28 @@ into the model's key (`CountryCode` above), keep it in app state, and filter the
 it. Anything saved against a mark - a note, a flag - is keyed the same way, never by `__rowIdx__`
 (see the row-index hazard above).
 
+**Notes (or flags) shown ON a mark: pass `annotations`, never measure the chart.** The host draws the
+badge on the key's mark after every render and keeps it there through filters, re-queries and zooms;
+it never reads a row position. From a notes table keyed by the model's key:
+
+```tsx
+<BivariateWorldChoroplethChart table={table} {...size} options={options}
+  annotations={notes.map(n => ({ column: "CountryCode", value: n.countryCode,
+                                 label: String(n.count), title: n.latestText }))}
+  onAnnotationClick={a => openNotes(a.value)} />
+```
+
+A route is keyed by BOTH of its ends with `where` - no key column to add, no query to change and no
+chart to regenerate:
+
+```tsx
+annotations={laneNotes.map(n => ({ where: { OriginCountryCode: n.origin, DestinationCountryCode: n.dest },
+                                   label: String(n.count), title: n.latestText }))}
+```
+
+Don't read `data-row-idx` or bounding boxes to place anything: that breaks on the next redraw, and
+this does it for you.
+
 **7. A reader's choice inside a chart is view state.** A what-if chart's rate and horizon are its
 own controls, reported through `viewState` on `<BicChart>` (`uiState` / `setUiState` in the
 integration contract). To save a named scenario, store that - don't rebuild the slider beside it.