@unovis/mcp 1.7.0-mcp.0

package/docs/chart-spec.md

@@ -0,0 +1,148 @@
+# Chart spec
+
+Every chart in this package is described by one JSON object — the `ChartSpec`.
+Tools build it from their simplified inputs; the headless renderer, the browser
+widget and the code generator all consume it.
+
+```
+tool input ──(recipe)──► ChartSpec ──┬──► headless renderer ──► SVG / PNG
+                                     ├──► browser widget    ──► HTML / inline widget
+                                     └──► code generator    ──► framework source
+```
+
+Because the spec is plain JSON, you can obtain one with
+`outputType: "config"`, edit it, and render it directly — which is how you
+reach Unovis options the tool schemas deliberately don't expose.
+
+## Shape
+
+```ts
+interface ChartSpec {
+  container: 'xy' | 'single'
+  width: number
+  height: number
+  theme: 'light' | 'dark'
+  title?: string
+  containerConfig?: Record<string, unknown>   // extra container options
+  components: { type: string; config: Record<string, unknown> }[]
+  xAxis?: Record<string, unknown>              // XY containers only
+  yAxis?: Record<string, unknown>
+  colors?: string[]
+  legend?: { name: string; color?: string; paletteIndex?: number }[]
+  data: unknown
+}
+```
+
+- **`container: 'xy'`** holds any number of XY components (line, area, bars,
+  scatter, timeline, boxplot, plus `Plotband`/`Plotline` decorations) on shared,
+  domain-synchronized scales, plus optional axes.
+- **`container: 'single'`** holds exactly one component (donut, sankey, heatmap,
+  treemap, chord, graph, map, …).
+- `components` renders in array order, so later entries draw on top.
+
+## A complete example
+
+```json
+{
+  "container": "xy",
+  "width": 800,
+  "height": 480,
+  "theme": "light",
+  "title": "Revenue vs Target",
+  "components": [
+    {
+      "type": "GroupedBar",
+      "config": {
+        "x": { "$index": true },
+        "y": { "$field": "revenue", "as": "number" },
+        "roundedCorners": 3
+      }
+    },
+    {
+      "type": "Line",
+      "config": {
+        "x": { "$index": true },
+        "y": { "$field": "target", "as": "number" },
+        "lineWidth": 3,
+        "color": "var(--vis-color1)"
+      }
+    }
+  ],
+  "xAxis": { "tickFormat": { "$lookup": ["Jan", "Feb", "Mar"] }, "tickValues": [0, 1, 2] },
+  "yAxis": { "gridLine": true, "tickFormat": { "$numTickFormat": true } },
+  "legend": [
+    { "name": "Revenue", "paletteIndex": 0 },
+    { "name": "Target", "paletteIndex": 1 }
+  ],
+  "data": [
+    { "revenue": 420, "target": 430 },
+    { "revenue": 510, "target": 460 },
+    { "revenue": 470, "target": 490 }
+  ]
+}
+```
+
+That spec is a bar + line combo chart — something no single tool emits today,
+but which the spec layer has always supported.
+
+## Accessor references
+
+Unovis accessors are functions, which JSON can't hold, so the spec uses
+descriptors that the renderer converts into real functions. **Nothing in a spec
+is ever evaluated as code** — field names are looked up as properties, and
+that's the whole mechanism.
+
+| Descriptor | Becomes | Use |
+|---|---|---|
+| `{ "$field": "sales" }` | `d => d.sales` | Read a field |
+| `{ "$field": "sales", "as": "number" }` | numeric coercion | Numeric fields arriving as strings |
+| `{ "$field": "date", "as": "date" }` | epoch milliseconds | Time axes |
+| `{ "$index": true }` | `(d, i) => i` | Categorical x positions |
+| `{ "$const": 5 }` | `() => 5` | Constant value |
+| `{ "$lookup": ["Jan", "Feb"] }` | index → label | Category tick labels |
+| `{ "$numTickFormat": true }` | thousands separators | Numeric axis labels |
+| `{ "$dateTickFormat": true }` | short date labels | Time axis labels |
+| `{ "$format": { "field": "value", "prefix": "$", "suffix": " USD" } }` | formatted string | Sankey sub-labels, etc. |
+| `{ "$mapField": { "field": "group", "mapping": { "a": "#4D8CFD" }, "fallback": "#ccc" } }` | category → value | Color by category |
+| `{ "$unovisMap": "WorldMapTopoJSON" }` | the topojson payload | Map charts |
+| `{ "$mapProjection": "AlbersUsa" }` | `MapProjection.AlbersUsa()` | Map projections |
+
+Descriptors can appear anywhere in a component config, including nested inside
+objects and arrays. `y: [{ "$field": "a" }, { "$field": "b" }]` is a two-series
+chart.
+
+## Component types
+
+XY components (`container: "xy"`): `Line`, `Area`, `GroupedBar`, `StackedBar`,
+`Scatter`, `Timeline`, `Boxplot`, `XYLabels`, `Plotband`, `Plotline`.
+
+Single components (`container: "single"`): `Donut`, `NestedDonut`, `RadialBar`,
+`Sankey`, `Heatmap`, `Treemap`, `ChordDiagram`, `Graph`, `TopoJSONMap`.
+
+Any option from the corresponding Unovis config passes straight through, as
+long as it's JSON-serializable or expressible as a descriptor. Interaction
+options (events, tooltips, brushes) are meaningless for static output and are
+ignored; the interactive widget adds its own.
+
+## Rendering a spec yourself
+
+```ts
+import { renderChart } from '@unovis/mcp'
+
+const { svg, width, height, warnings } = await renderChart(spec)
+```
+
+Charts always render with `duration: 0` so output is deterministic, and the
+renderer waits for the container's `onRenderComplete` — plus the component's own
+completion signal for asynchronous layouts like force-directed graphs.
+
+## Deliberate limits
+
+- **Functions can't be smuggled in.** If you need a bespoke callback, use the
+  library directly with [`renderToSvg`](./programmatic.md#rendertosvg).
+- **One coordinate system per chart.** Components in an XY container share
+  synchronized domains, so mixing wildly different units (revenue and
+  percentages) will flatten one of them. True dual axes aren't supported yet.
+- **`Graph` layouts** are limited to `force`, `circular` and `concentric` in the
+  tools; `dagre` and `elk` work through a hand-written spec in Node but not in
+  the browser widget (see [Troubleshooting](./troubleshooting.md)).

package/docs/getting-started.md

@@ -0,0 +1,175 @@
+# Getting started
+
+## Requirements
+
+- **Node.js 20 or newer.** Native dependencies ship as prebuilt binaries
+  (`@napi-rs/canvas`, `@resvg/resvg-js`), so there is no compile step and no
+  `node-gyp`.
+- Nothing else. No browser download, no database, no API keys.
+
+## Connect a client
+
+The server speaks stdio by default, which is what every MCP client uses for
+local servers. You register it once; the client starts and stops it for you.
+
+### Claude Code
+
+```bash
+claude mcp add unovis -- npx -y @unovis/mcp
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "unovis": {
+      "command": "npx",
+      "args": ["-y", "@unovis/mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json` in your project (or the global equivalent):
+
+```json
+{
+  "mcpServers": {
+    "unovis": {
+      "command": "npx",
+      "args": ["-y", "@unovis/mcp"]
+    }
+  }
+}
+```
+
+### Codex CLI
+
+Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.unovis]
+command = "npx"
+args = ["-y", "@unovis/mcp"]
+```
+
+Codex runs in a terminal and cannot display inline images, so prefer
+`outputType: "svg"` (plain text) or `outputPath` (writes a file, returns the
+path). See [Output types](./output-types.md).
+
+### VS Code
+
+```json
+{
+  "servers": {
+    "unovis": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@unovis/mcp"]
+    }
+  }
+}
+```
+
+### Any other MCP client
+
+There is nothing client-specific in the server: standard stdio JSON-RPC,
+`tools/list` + `tools/call`, plus one optional UI resource. If your client
+speaks MCP, point it at `npx -y @unovis/mcp`.
+
+## Verify the installation
+
+```bash
+npx @unovis/mcp --version
+npx @modelcontextprotocol/inspector npx -y @unovis/mcp
+```
+
+The Inspector lists every tool with its schema and lets you call one
+interactively — the fastest way to confirm the server works before wiring it
+into an agent.
+
+## Remote / shared deployments
+
+For a team server, use the streamable HTTP transport:
+
+```bash
+npx @unovis/mcp --transport http --host 0.0.0.0 --port 3737 --endpoint /mcp
+```
+
+```bash
+claude mcp add --transport http unovis https://charts.example.com/mcp
+```
+
+Two things to know before exposing it:
+
+- **There is no built-in authentication.** Keep it on a private network or put
+  a reverse proxy with a bearer-token check in front.
+- **Renders are serialized per process** (one shared jsdom document). The
+  server is stateless, so scale by running several replicas behind a load
+  balancer rather than expecting concurrency from one instance.
+
+A container image needs nothing unusual:
+
+```dockerfile
+FROM node:24-slim
+RUN npm install -g @unovis/mcp
+# Pre-provision fonts so containers don't download them on first render
+ENV UNOVIS_MCP_FONTS_DIR=/fonts
+COPY fonts/ /fonts/
+EXPOSE 3737
+CMD ["unovis-mcp", "--transport", "http", "--host", "0.0.0.0"]
+```
+
+## CLI options
+
+```
+--transport <stdio|http>   Transport (default: stdio)
+--host <host>              HTTP bind address (default: 127.0.0.1)
+--port <port>              HTTP port (default: 3737)
+--endpoint <path>          HTTP endpoint path (default: /mcp)
+--tools <a,b,...>          Expose only these tools
+--version                  Print the version
+--help                     Show usage
+```
+
+Diagnostics go to stderr; stdout carries only protocol traffic.
+
+## Environment variables
+
+| Variable | Purpose |
+|---|---|
+| `DISABLED_TOOLS` | Comma-separated tool names to hide |
+| `UNOVIS_MCP_FONTS_DIR` | Directory of font files to use for text measurement |
+| `UNOVIS_MCP_NO_DOWNLOAD` | Set to `1` to skip the one-time Inter download and use system fonts |
+
+## Limiting the tool surface
+
+Some clients degrade with large tool counts, and you may simply not want maps
+or graphs. Both directions are supported:
+
+```bash
+# Allowlist
+unovis-mcp --tools generate_line_chart,generate_bar_chart,generate_donut_chart
+
+# Denylist
+DISABLED_TOOLS=generate_choropleth_map,generate_network_graph unovis-mcp
+```
+
+`get_unovis_info` always reports the tools that are actually active, so an
+agent can discover the trimmed surface at runtime.
+
+## First render
+
+Ask your agent something like:
+
+> Chart the deploy counts in `deploys.csv` by week as a bar chart, and save it
+> to `docs/deploys.svg`
+
+A well-behaved agent reads the file, calls `generate_bar_chart` with the parsed
+rows and `outputPath: "/abs/path/docs/deploys.svg"`, and tells you where the
+file landed.

package/docs/interactive.md

@@ -0,0 +1,125 @@
+# Interactive charts
+
+Static SVG and PNG are the universal baseline. When you want hover, tooltips and
+zoom, the same chart spec can be delivered as a live chart instead — driven by a
+browser bundle that shares the spec layer with the headless renderer.
+
+```
+ChartSpec ──┬──► headless renderer  ──► SVG / PNG   (works everywhere)
+            ├──► widget bundle      ──► .html file   (any browser)
+            └──► widget bundle      ──► ui:// resource (MCP UI clients)
+```
+
+## What you get
+
+- **Hover tooltips** tailored per chart type — bars and points show their
+  record, sankey nodes show totals, map areas show their value, graph links show
+  their endpoints.
+- **A crosshair** on line and area charts, with a shared readout of every series
+  at the hovered x position.
+- **Unovis's real HTML legend** (`BulletLegend`) — impossible in standalone SVG,
+  because it isn't SVG.
+- **Component interactions** that come free with a live chart: graph drag and
+  zoom, map panning (when enabled), label collision handling.
+- **Responsive layout**: the chart fills its container and re-renders on resize.
+
+## Self-contained HTML
+
+```json
+{ "outputType": "html", "outputPath": "/abs/path/revenue.html" }
+```
+
+or programmatically:
+
+```ts
+import { buildChartDocument } from '@unovis/mcp'
+
+const html = buildChartDocument(spec, {
+  duration: 400,          // animation ms; 0 renders immediately
+  documentTitle: 'Q3 revenue',
+})
+```
+
+One file, nothing external: the widget bundle (~665kB), the spec, and the styles
+are all inlined. It opens offline, survives being emailed, and can be committed
+to a repo.
+
+## Inline in the conversation
+
+```json
+{ "outputType": "interactive" }
+```
+
+The tool returns the spec as structured content plus a reference to the
+`ui://unovis/chart` resource, which is the widget in embed mode. Clients that
+implement MCP UI resources render it inline; the others fall back to the text
+summary.
+
+This is **experimental** — the conventions are still moving, so don't build a
+product on it yet. `html` is the dependable path.
+
+## Embedding the widget in your own page
+
+The widget doubles as a plain iframe component, so any web app can render Unovis
+specs without bundling Unovis. Serve the embed document (it's what the `ui://`
+resource returns, and `buildEmbedDocument()` produces it), point an iframe at it
+with the `#embed` hash, and post it a spec:
+
+```html
+<iframe id="chart" src="/unovis-widget.html#embed" style="width:100%;border:0"></iframe>
+
+<script>
+  const frame = document.getElementById('chart')
+
+  window.addEventListener('message', (event) => {
+    if (event.data?.type === 'unovis:ready') {
+      // The widget is loaded and waiting for a spec
+      frame.contentWindow.postMessage({ type: 'unovis:render', spec, options: { duration: 400 } }, '*')
+    }
+    if (event.data?.type === 'unovis:size') {
+      // Grow the iframe to fit its content
+      frame.style.height = `${event.data.height}px`
+    }
+  })
+</script>
+```
+
+### Protocol
+
+| Direction | Message | Meaning |
+|---|---|---|
+| widget → host | `{ type: 'unovis:ready' }` | Loaded, waiting for a spec |
+| host → widget | `{ type: 'unovis:render', spec, options }` | Render this spec (replaces any previous chart) |
+| widget → host | `{ type: 'unovis:size', width, height }` | Content size after a render |
+
+Send `unovis:render` as often as you like — each one tears down the previous
+chart. `options` accepts `duration` and `showTitle`.
+
+## Using the widget API directly
+
+If you'd rather not use an iframe, the bundle exposes a global:
+
+```js
+const handle = window.UnovisChart.render(spec, document.getElementById('chart'), { duration: 400 })
+// …later
+handle.destroy()
+```
+
+`window.UnovisChart.unovis` is the full Unovis namespace from the bundle, if you
+want to build charts by hand in the same page.
+
+## Limits
+
+- **Graph layouts**: `force`, `circular`, `concentric` and `dagre` all work. Only
+  `elk` is excluded — at 1.4MB its engine would have to be inlined into every
+  generated file.
+- **A background tab renders nothing until you look at it.** Browsers pause
+  `requestAnimationFrame` for hidden pages, and Unovis schedules its rendering
+  through it. The chart appears as soon as the tab becomes visible. This is
+  ordinary browser behavior, but it surprises people (and it will make an
+  automated screenshot of a hidden page come out blank).
+- **Fonts** come from the viewer's machine. The document asks for the Inter
+  stack and falls back to system UI fonts, so text can be a few pixels wider or
+  narrower than in the SVG output, which measures with bundled Inter.
+- **Map charts** embed their topojson in the file, which makes world maps
+  noticeably larger than other charts.

package/docs/output-types.md

@@ -0,0 +1,170 @@
+# Output types
+
+Every chart tool accepts the same `outputType`, so you pick a chart once and
+decide separately how you want it delivered.
+
+| `outputType` | Returns | Best for |
+|---|---|---|
+| `svg` (default) | Standalone SVG markup as text | Embedding in docs, READMEs, anything; works in every client |
+| `png` | A rendered PNG image (base64) | Chat clients that display images; slides; anywhere SVG isn't accepted |
+| `html` | Path to a self-contained interactive file | Exploration: tooltips, crosshair, hover |
+| `interactive` | The chart spec + a widget reference | Clients that render MCP UI resources inline |
+| `config` | The resolved chart spec as JSON | Iterating on a chart before rendering; feeding another tool |
+| `code` | Ready-to-paste Unovis source | Putting the chart into your own app |
+
+## Shared options
+
+These exist on every chart tool:
+
+| Option | Type | Default | Notes |
+|---|---|---|---|
+| `width` | number | `800` | Final image width in pixels |
+| `height` | number | `480` | Final image height, before the title/legend header is added |
+| `theme` | `light` \| `dark` | `light` | Dark theme bakes Unovis's dark palette and a dark background |
+| `title` | string | — | Rendered as a heading above the chart |
+| `colors` | string[] | — | Hex palette replacing the default one, in order |
+| `outputType` | see above | `svg` | |
+| `outputPath` | string | — | Absolute path with an extension matching `outputType` (`.svg`, `.png`, `.html`) |
+| `scale` | 1–4 | `2` | PNG pixel density only |
+| `framework` | `ts` \| `react` \| `svelte` \| `vue` \| `angular` \| `solid` | `ts` | `code` output only |
+
+`width` and `height` describe the **image**, not the plot area. The chart is
+drawn inside a 16px frame (12px at the top) so nothing touches the edges, and
+the title/legend header adds height on top.
+
+## `svg`
+
+The default, and the most portable. The returned markup is genuinely
+standalone:
+
+- stylesheet rules are inlined as presentation attributes, and the emotion
+  classes are stripped
+- `var(--vis-*)` theme references are baked to literal colors for the requested
+  theme
+- element ids are rewritten with a per-render prefix, so several charts can
+  coexist in one document without clashing
+- no external references at all — no fonts, stylesheets, or images to fetch
+
+That means it renders correctly inside `<img>`, in GitHub markdown, in Figma,
+and in rasterizers that don't implement CSS custom properties.
+
+```json
+{ "outputType": "svg" }
+```
+
+With `outputPath`, the file gets an XML declaration and the tool returns the
+path instead of the markup — useful for large charts you don't want in the
+conversation.
+
+## `png`
+
+Rasterized locally with [resvg](https://github.com/thx/resvg-js) from the very
+same SVG, using the same fonts that were used to measure the text. `scale`
+multiplies the pixel dimensions (`2` gives a retina-quality image).
+
+```json
+{ "outputType": "png", "scale": 2, "width": 800, "height": 480 }
+```
+
+Returned as base64 image content, which most graphical clients render inline.
+Terminal clients generally can't — use `outputPath` there.
+
+## `html`
+
+Writes a **self-contained interactive** document and returns its path. Opening
+it gives you the real chart: hover tooltips, a crosshair readout on line and
+area charts, hover highlighting, drag/zoom on graphs, and Unovis's real HTML
+legend. Everything (the widget bundle, the spec, the styles) is inlined, so it
+works offline and can be emailed or committed.
+
+```json
+{ "outputType": "html", "outputPath": "/abs/path/revenue.html" }
+```
+
+Without `outputPath` the file goes to a temp directory. It is always written to
+disk rather than returned inline — the document is ~600kB.
+
+See [Interactive charts](./interactive.md) for what's supported and how the
+widget works.
+
+## `interactive`
+
+Returns the chart spec as structured content plus a reference to the
+`ui://unovis/chart` widget resource, letting clients that support MCP UI
+resources render the chart **inside the conversation**. The text content is a
+short summary, which is what clients without widget support will show.
+
+```json
+{ "outputType": "interactive" }
+```
+
+This is experimental: the conventions for embedded UI in MCP are still
+settling, so treat client support as best-effort and prefer `html` when you
+need a guaranteed result.
+
+## `config`
+
+Returns the resolved chart spec as JSON without rendering anything. Two good
+uses: letting an agent inspect and adjust a chart before spending time on
+pixels, and hand-editing a spec to reach options the tool schemas don't expose.
+
+```json
+{ "outputType": "config" }
+```
+
+The result can be fed straight to `renderChart()` — see
+[Chart spec](./chart-spec.md) and [Programmatic use](./programmatic.md).
+
+## `code`
+
+Emits ready-to-paste Unovis source for your framework, with the data included
+so it runs as-is.
+
+```json
+{ "outputType": "code", "framework": "react" }
+```
+
+```tsx
+import React from 'react'
+import { VisAxis, VisGroupedBar, VisXYContainer } from '@unovis/react'
+
+const data = [
+  { q: 'Q1', rev: 42 },
+  { q: 'Q2', rev: 51 },
+]
+
+const categories = [
+  'Q1',
+  'Q2'
+]
+
+const formatNumber = (value: number | Date): string =>
+  Number(value).toLocaleString('en-US', { maximumFractionDigits: 6 })
+
+export default function Chart (): JSX.Element {
+  return (
+    <>
+      <VisXYContainer height={480}>
+        <VisGroupedBar data={data} x={(d, i) => i} y={[d => d.rev]} orientation="vertical" roundedCorners={true} />
+        <VisAxis type="x" gridLine={false} tickFormat={(index: number | Date) => categories[Math.round(Number(index))]} tickValues={[0, 1]} />
+        <VisAxis type="y" gridLine={true} tickFormat={formatNumber} />
+      </VisXYContainer>
+    </>
+  )
+}
+```
+
+Notes on the generated code:
+
+- Each framework gets its real syntax: `Vis*` components for React, Solid,
+  Svelte and Vue; `<vis-*>` elements for Angular. Angular returns **two files**
+  (template plus component class), because Angular templates can't contain
+  arrow functions — accessors become typed class fields.
+- Enum-typed props emit the enum member and its import (for example
+  `curveType={CurveType.MonotoneX}` from `@unovis/ts`) rather than a bare
+  string, which wouldn't type-check.
+- Map charts import their topojson (`import { WorldMapTopoJSON } from
+  '@unovis/ts/maps'`) instead of inlining megabytes of geometry.
+- The vanilla-TypeScript target is type-checked against `@unovis/ts` in this
+  package's test suite, so the emitted imports, generics and prop names are
+  known to be real.