API Reference

The package root exports two registration entry points plus the authoring, widget-hosting, embed, and adapter helpers:

addCharts(server, options)

Registers the visualize tool and the ui://bonnard/chart widget resource on an existing MCP server.

import { addCharts } from "@bonnard/mcp-charts";

addCharts(server, options);

AddChartsOptions

ChartData

interface ChartData {
  rows: Record<string, unknown>[];
  fields?: FieldMeta[]; // optional typed columns; inferred from the rows when omitted
}

When fields are omitted, column roles (dimension, measure, time) and formats are inferred from the data and column names.

The visualize tool

Once registered, the agent calls visualize with:

• sql: the query to run (required)
• chartType: one of the supported chart types (optional; auto-detected when omitted)
• title: a chart title (optional)
• stacking: "stacked", "grouped", or "stacked100" (optional). Bar and area only. stacked100 normalises each x position to 100%.
• horizontal: boolean (optional). Bar only. Runs bars horizontally with categories on the y-axis. Bars are vertical unless you set this, except that the widget auto-flips when a category label runs past 12 characters.
• reference: { target?: number, average?: boolean } (optional). Draws horizontal lines on the value axis: target at a fixed value, average at the mean of the primary series.
• encode: explicit column mapping (optional). Accepts x, y, series, y2 (measures on a secondary right axis, drawn as a line), line (measures drawn as a line on the same axis), and size (scatter only, a third numeric column mapped to point size).

The result returns a ChartSpec in structuredContent for the widget, plus a text fallback for non-widget clients.

addViews(server, options)

Registers two tools over a registry of named views: explore_views (list) and render_view (render one by view_id). Each view returns a ChartSpec or a DashboardSpec. This is the one authored entrypoint for both single charts and dashboards.

import { addViews, chart } from "@bonnard/mcp-charts";

addViews(server, {
  views: [
    {
      id: "revenue_trend",
      title: "Revenue trend",
      description: "Monthly revenue",
      render: () => chart(rows, { chartType: "line" }),
    },
  ],
});

render_view inputs

render_view takes:

• view_id (required): the view to render, an enum of the registered ids.
• params (optional): the chosen view's declared params, validated per view (strict).
• item_id (optional): for a dashboard-kind view, the id of one chart cell to render alone. params apply to the whole view first, then the named cell is projected out and returned as a ChartSpec. A ChartCell gets its id from chartCell(rows, { id }). See Rendering one cell.

See Named views for the ViewDef shape and per-view params.

Authoring helpers

Build specs and cells directly, or diagnose an encoding:

opts on chart / chartCell / explain is ResolveOptions (chartType, title, stacking, horizontal, reference, strict) plus the fields and encode escape hatches. See Connecting a Database for typed fields and strict.

Widget hosting

addCharts and addViews register the widget for you. These exports let you serve the same renderer yourself, or register the resource without a tool.

Embed mode

Render one chart, KPI, or table with no chrome of its own inside a layout you own, driven over postMessage. Serve WIDGET_HTML from your own route with a #embed fragment, then send it a render message. The package root exports the wire contract:

See Embed mode for the fragment flags, the message sequence, sizing, theme precedence, and the security model.

Building blocks for custom adapters

If you are writing your own adapter, these are exported from the package root:

Supporting types: SourceColumn, KindMapper, CellNormalizer, BuildChartDataOptions.