API Reference

The addCharts function, its options, and the building blocks for custom adapters.

`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);

Option	Type	Description
`runSql`	`(sql: string) => Promise<ChartData>`	Required. Runs the agent's SQL and returns rows (and optionally typed `fields`).
`discovery`	`{ toolName: string }`	Optional. Names your schema-discovery tool so the `visualize` description can point the agent to it.
`allow`	`ChartType[]`	Optional. Restricts the `chartType` enum exposed to the agent.

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.

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)
encode — explicit axis/series mapping (optional)

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

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

Export	Purpose
`buildChartData`	Turns driver rows + columns into `ChartData` using a kind mapper.
`defaultNormalizeCell`	Default per-cell normalisation (dates, numerics, etc.).
`assertReadOnlySql`	Lightweight SELECT-only guardrail for SQL strings.

Supporting types: SourceColumn, KindMapper, CellNormalizer, BuildChartDataOptions.

The bundled warehouse adapters are built on exactly these primitives — read their source for worked examples.