@bonnard/mcp-charts 0.1.3 → 0.2.0

package/dist/fixtures.js

@@ -0,0 +1,156 @@
+import {
+  resolve
+} from "./chunk-EZYN3JQ4.js";
+import {
+  buildChartData
+} from "./chunk-IXRGLZX2.js";
+
+// src/fixtures/dashboards.ts
+var KIND_BY_TOKEN = {
+  string: "string",
+  number: "number",
+  time: "time",
+  boolean: "boolean"
+};
+var mapKind = (type) => KIND_BY_TOKEN[String(type)] ?? "string";
+function buildCellSpec(input) {
+  const data = buildChartData({ rows: input.rows, columns: input.columns, mapKind });
+  return resolve(data, input.opts);
+}
+function isChartInput(input) {
+  return input.kind === "chart";
+}
+function toItem(input) {
+  if (isChartInput(input)) {
+    return input.span != null ? { spec: buildCellSpec(input), span: input.span } : { spec: buildCellSpec(input) };
+  }
+  return input;
+}
+function toSpec(inputs) {
+  const spec = { items: inputs.items.map(toItem) };
+  if (inputs.title != null) spec.title = inputs.title;
+  if (inputs.columns != null) spec.columns = inputs.columns;
+  if (inputs.notes != null) spec.notes = inputs.notes;
+  return spec;
+}
+var col = (name, type) => ({ name, type });
+var chart = (rows, columns, opts, span) => ({ kind: "chart", rows, columns, opts, ...span != null && { span } });
+var barRevenueByStatus = chart(
+  [
+    { status: "shipped", revenue: 43700 },
+    { status: "open", revenue: 8400 },
+    { status: "cancelled", revenue: 1450 }
+  ],
+  [col("status", "string"), col("revenue", "number")],
+  { chartType: "bar", title: "Revenue by Status" }
+);
+var lineMonthly = chart(
+  [
+    { month: "2026-04-01", revenue: 18e3 },
+    { month: "2026-05-01", revenue: 15500 },
+    { month: "2026-06-01", revenue: 20300 }
+  ],
+  [col("month", "time"), col("revenue", "number")],
+  { chartType: "line", title: "Monthly Revenue" }
+);
+var pieRegion = chart(
+  [
+    { region: "EU", revenue: 29300 },
+    { region: "US", revenue: 23e3 },
+    { region: "APAC", revenue: 850 }
+  ],
+  [col("region", "string"), col("revenue", "number")],
+  { chartType: "pie", title: "Revenue by Region" }
+);
+var tableOrders = chart(
+  [
+    { id: "o_1001", amount: 4200, status: "shipped" },
+    { id: "o_1003", amount: 900, status: "open" }
+  ],
+  [col("id", "string"), col("amount", "number"), col("status", "string")],
+  { chartType: "table", title: "Orders Sample" }
+);
+var barRegion = chart(
+  [
+    { region: "EU", revenue: 29300 },
+    { region: "US", revenue: 23e3 }
+  ],
+  [col("region", "string"), col("revenue", "number")],
+  { chartType: "bar", title: "Revenue by Region" }
+);
+var emptyTable = chart([], [col("label", "string"), col("value", "number")], { chartType: "table" });
+var kpiCurrency = {
+  type: "kpi",
+  label: "Revenue",
+  value: 128400,
+  format: "currency",
+  currency: "USD",
+  delta: 12400,
+  caption: "vs last month"
+};
+var kpiPercent = {
+  type: "kpi",
+  label: "Conversion",
+  value: 0.184,
+  format: "percent",
+  fraction: true,
+  delta: -0.021,
+  deltaFraction: true
+};
+var kpiPlain = {
+  type: "kpi",
+  label: "Orders",
+  value: 1042,
+  caption: "this month"
+};
+var kpiNull = {
+  type: "kpi",
+  label: "Refunds",
+  value: null
+};
+var textIntro = {
+  type: "text",
+  heading: "Q2 Overview",
+  text: "Revenue is up quarter over quarter, led by the EU region.",
+  span: 2
+};
+var dashboardFixtures = [
+  {
+    name: "single-chart",
+    ...pack({ columns: 1, items: [barRevenueByStatus] })
+  },
+  {
+    name: "grid-2x2",
+    ...pack({ columns: 2, items: [barRegion, lineMonthly, pieRegion, tableOrders] })
+  },
+  {
+    name: "kpi-row",
+    ...pack({ columns: 3, items: [kpiCurrency, kpiPercent, kpiPlain] })
+  },
+  {
+    name: "mixed",
+    ...pack({
+      title: "Sales Dashboard",
+      columns: 2,
+      items: [textIntro, kpiCurrency, kpiPercent, { ...lineMonthly, span: 2 }]
+    })
+  },
+  {
+    name: "narrow-stacked",
+    ...pack({ columns: 1, items: [kpiPlain, barRevenueByStatus, lineMonthly] })
+  },
+  {
+    // Edge cases in one grid: an empty-result chart cell (renders `.empty`) + a null-value KPI
+    // (renders a placeholder, not "null").
+    name: "degenerate",
+    ...pack({ columns: 2, items: [emptyTable, kpiNull] })
+  }
+];
+function pack(inputs) {
+  return { inputs, spec: toSpec(inputs) };
+}
+export {
+  buildCellSpec,
+  dashboardFixtures
+};
+//# sourceMappingURL=fixtures.js.map

package/dist/fixtures.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/fixtures/dashboards.ts"],"sourcesContent":["// Shared dashboard fixtures. Each carries both INPUTS and the expected OUTPUT `spec`: the widget\n// consumes `spec`; a platform that composes dashboards from SQL reproduces `spec` from `inputs`.\n//\n// Chart-cell specs are computed at module load through the library's own path (buildChartData +\n// resolve), so a fixture is definitionally what core produces and cannot rot against resolve().\n// Fixture names are load-bearing: both repos' tests iterate them by name.\nimport { buildChartData } from \"../adapters/sql.js\";\nimport type { SourceColumn } from \"../adapters/sql.js\";\nimport { resolve } from \"../resolve/resolve.js\";\nimport type {\n  ChartSpec,\n  DashboardItem,\n  DashboardSpec,\n  FieldKind,\n  KpiTile,\n  ResolveOptions,\n  TextBlock,\n} from \"../types.js\";\n\n/** Raw inputs for a chart cell: a SQL-shaped result (rows + typed columns) + resolve options. */\nexport interface ChartCellInput {\n  kind: \"chart\";\n  rows: Record<string, unknown>[];\n  columns: SourceColumn[];\n  opts: ResolveOptions;\n  span?: number;\n}\n\n/** A dashboard-item input: either a chart to be built, or a final KPI/text item. */\nexport type DashboardItemInput = ChartCellInput | KpiTile | TextBlock;\n\n/** Inputs from which a DashboardSpec is (re)producible without hand-authoring chart specs. */\nexport interface DashboardFixtureInputs {\n  title?: string;\n  columns?: number;\n  items: DashboardItemInput[];\n  notes?: string[];\n}\n\nexport interface DashboardFixture {\n  name: string;\n  inputs: DashboardFixtureInputs;\n  spec: DashboardSpec;\n}\n\n// Column-type tokens the test mapKind understands. Chart-cell inputs declare these so the fixture\n// spec is built the same way an adapter would build it (typed columns -> buildChartData).\nconst KIND_BY_TOKEN: Record<string, FieldKind> = {\n  string: \"string\",\n  number: \"number\",\n  time: \"time\",\n  boolean: \"boolean\",\n};\n\nconst mapKind = (type: unknown): FieldKind => KIND_BY_TOKEN[String(type)] ?? \"string\";\n\n/** Build a ChartCell's ChartSpec through the library path: buildChartData -> resolve. */\nexport function buildCellSpec(input: ChartCellInput): ChartSpec {\n  const data = buildChartData({ rows: input.rows, columns: input.columns, mapKind });\n  return resolve(data, input.opts);\n}\n\nfunction isChartInput(input: DashboardItemInput): input is ChartCellInput {\n  return (input as ChartCellInput).kind === \"chart\";\n}\n\nfunction toItem(input: DashboardItemInput): DashboardItem {\n  if (isChartInput(input)) {\n    return input.span != null ? { spec: buildCellSpec(input), span: input.span } : { spec: buildCellSpec(input) };\n  }\n  return input;\n}\n\nfunction toSpec(inputs: DashboardFixtureInputs): DashboardSpec {\n  const spec: DashboardSpec = { items: inputs.items.map(toItem) };\n  if (inputs.title != null) spec.title = inputs.title;\n  if (inputs.columns != null) spec.columns = inputs.columns;\n  if (inputs.notes != null) spec.notes = inputs.notes;\n  return spec;\n}\n\nconst col = (name: string, type: string): SourceColumn => ({ name, type });\n\nconst chart = (\n  rows: Record<string, unknown>[],\n  columns: SourceColumn[],\n  opts: ResolveOptions,\n  span?: number,\n): ChartCellInput => ({ kind: \"chart\", rows, columns, opts, ...(span != null && { span }) });\n\n// --- Reusable chart-cell inputs ---\n\nconst barRevenueByStatus = chart(\n  [\n    { status: \"shipped\", revenue: 43700 },\n    { status: \"open\", revenue: 8400 },\n    { status: \"cancelled\", revenue: 1450 },\n  ],\n  [col(\"status\", \"string\"), col(\"revenue\", \"number\")],\n  { chartType: \"bar\", title: \"Revenue by Status\" },\n);\n\nconst lineMonthly = chart(\n  [\n    { month: \"2026-04-01\", revenue: 18000 },\n    { month: \"2026-05-01\", revenue: 15500 },\n    { month: \"2026-06-01\", revenue: 20300 },\n  ],\n  [col(\"month\", \"time\"), col(\"revenue\", \"number\")],\n  { chartType: \"line\", title: \"Monthly Revenue\" },\n);\n\nconst pieRegion = chart(\n  [\n    { region: \"EU\", revenue: 29300 },\n    { region: \"US\", revenue: 23000 },\n    { region: \"APAC\", revenue: 850 },\n  ],\n  [col(\"region\", \"string\"), col(\"revenue\", \"number\")],\n  { chartType: \"pie\", title: \"Revenue by Region\" },\n);\n\nconst tableOrders = chart(\n  [\n    { id: \"o_1001\", amount: 4200, status: \"shipped\" },\n    { id: \"o_1003\", amount: 900, status: \"open\" },\n  ],\n  [col(\"id\", \"string\"), col(\"amount\", \"number\"), col(\"status\", \"string\")],\n  { chartType: \"table\", title: \"Orders Sample\" },\n);\n\nconst barRegion = chart(\n  [\n    { region: \"EU\", revenue: 29300 },\n    { region: \"US\", revenue: 23000 },\n  ],\n  [col(\"region\", \"string\"), col(\"revenue\", \"number\")],\n  { chartType: \"bar\", title: \"Revenue by Region\" },\n);\n\n// An empty result: buildChartData over zero rows, then resolve as a table (matches the platform's\n// emptyResult table shape for a cell that returned no rows).\nconst emptyTable = chart([], [col(\"label\", \"string\"), col(\"value\", \"number\")], { chartType: \"table\" });\n\n// --- KPI + text item inputs ---\n\nconst kpiCurrency: KpiTile = {\n  type: \"kpi\",\n  label: \"Revenue\",\n  value: 128400,\n  format: \"currency\",\n  currency: \"USD\",\n  delta: 12400,\n  caption: \"vs last month\",\n};\n\nconst kpiPercent: KpiTile = {\n  type: \"kpi\",\n  label: \"Conversion\",\n  value: 0.184,\n  format: \"percent\",\n  fraction: true,\n  delta: -0.021,\n  deltaFraction: true,\n};\n\nconst kpiPlain: KpiTile = {\n  type: \"kpi\",\n  label: \"Orders\",\n  value: 1042,\n  caption: \"this month\",\n};\n\nconst kpiNull: KpiTile = {\n  type: \"kpi\",\n  label: \"Refunds\",\n  value: null,\n};\n\nconst textIntro: TextBlock = {\n  type: \"text\",\n  heading: \"Q2 Overview\",\n  text: \"Revenue is up quarter over quarter, led by the EU region.\",\n  span: 2,\n};\n\n// --- The six fixtures ---\n\nexport const dashboardFixtures: DashboardFixture[] = [\n  {\n    name: \"single-chart\",\n    ...pack({ columns: 1, items: [barRevenueByStatus] }),\n  },\n  {\n    name: \"grid-2x2\",\n    ...pack({ columns: 2, items: [barRegion, lineMonthly, pieRegion, tableOrders] }),\n  },\n  {\n    name: \"kpi-row\",\n    ...pack({ columns: 3, items: [kpiCurrency, kpiPercent, kpiPlain] }),\n  },\n  {\n    name: \"mixed\",\n    ...pack({\n      title: \"Sales Dashboard\",\n      columns: 2,\n      items: [textIntro, kpiCurrency, kpiPercent, { ...lineMonthly, span: 2 }],\n    }),\n  },\n  {\n    name: \"narrow-stacked\",\n    ...pack({ columns: 1, items: [kpiPlain, barRevenueByStatus, lineMonthly] }),\n  },\n  {\n    // Edge cases in one grid: an empty-result chart cell (renders `.empty`) + a null-value KPI\n    // (renders a placeholder, not \"null\").\n    name: \"degenerate\",\n    ...pack({ columns: 2, items: [emptyTable, kpiNull] }),\n  },\n];\n\nfunction pack(inputs: DashboardFixtureInputs): { inputs: DashboardFixtureInputs; spec: DashboardSpec } {\n  return { inputs, spec: toSpec(inputs) };\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.ts

@@ -1,12 +1,124 @@
-import { C as ChartData, R as ResolveOptions, a as ChartSpec, F as FieldMeta, b as ChartContext, c as ChartType, d as FieldKind } from './types-6ALzXWjE.js';
-export { A as AxisSpec, e as ColumnSpec, E as Encode, f as FieldFormat, g as FieldRole, h as ReferenceLine, S as SeriesSpec, i as Stacking, T as TimeGranularity } from './types-6ALzXWjE.js';
+import { a as ChartSpec, D as DashboardSpec, R as ResolveOptions, F as FieldMeta, E as Encode, C as ChartData, b as ChartCell, c as ChartExplanation, d as ChartContext, e as ChartType } from './types-DUKpye7m.js';
+export { A as AxisSpec, f as ColumnSpec, g as DashboardItem, h as FieldFormat, i as FieldKind, j as FieldRole, K as KpiTile, k as ReferenceLine, S as SeriesSpec, l as Stacking, T as TextBlock, m as TimeGranularity } from './types-DUKpye7m.js';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+export { B as BuildChartDataOptions, C as CellNormalizer, K as KindMapper, S as SourceColumn, a as assertReadOnlySql, b as buildChartData, d as defaultNormalizeCell } from './sql-BYkJnQOP.js';
+
+declare function isDashboardSpec(x: unknown): x is DashboardSpec;
+declare function isChartSpec(x: unknown): x is ChartSpec;
+
+/** Extra per-cell options layered on top of resolve()'s options. */
+interface ChartCellOptions extends ResolveOptions {
+    /** Stable id for addressing this cell via render_view's item_id (re-render one chart alone). */
+    id?: string;
+    /** Grid columns this cell spans (renderer clamps to the dashboard's column count). */
+    span?: number;
+    /** Declare field typing when inference can't nail it (currency, numeric-string dimensions). */
+    fields?: FieldMeta[];
+    /** Map columns to x / y / series when the names aren't obvious. */
+    encode?: Encode;
+}
+/** Options for a standalone chart: resolve()'s options plus the field-typing / encoding escape hatches. */
+type ChartOptions = ResolveOptions & {
+    fields?: FieldMeta[];
+    encode?: Encode;
+};
+/**
+ * Build a standalone ChartSpec, inferring the encoding via resolve(). The first arg is EITHER raw
+ * rows (`Record<string, unknown>[]` — inference sniffs types) OR a typed `ChartData` (`{ rows,
+ * fields?, encode?, notes? }` from an adapter — driver types are trusted, no sniff). For a
+ * DB-connected view, `chart(await runSql("select ..."), { chartType: "line" })` is the same one
+ * line but rides declared types. `fields`/`encode` are escape hatches for the raw path. The sibling
+ * of chartCell, which wraps this spec in a dashboard cell.
+ */
+declare function chart(source: Record<string, unknown>[] | ChartData, opts?: ChartOptions): ChartSpec;
+/**
+ * Build a dashboard chart cell, inferring the encoding via resolve(). Like chart(), the first arg is
+ * either raw rows or a typed `ChartData`. `fields`/`encode` are escape hatches; `span` sets the grid
+ * width.
+ */
+declare function chartCell(source: Record<string, unknown>[] | ChartData, opts: ChartCellOptions): ChartCell;
+/**
+ * Diagnose how rows (or a typed ChartData) would be charted, WITHOUT building the render payload:
+ * the inferred field typing, the resolved chartType / x / series, and any notes. For asserting the
+ * encoding in a unit test or CI before a host ever renders it, e.g.
+ * `expect(explain(sampleRows, { chartType: "bar" }).series.length).toBeGreaterThan(0)`. Pair with
+ * `strict: true` to throw on a bad encoding (zero series, ignored encode column) instead of noting.
+ */
+declare function explain(source: Record<string, unknown>[] | ChartData, opts?: ChartOptions): ChartExplanation;
+/** A compact, bounded text summary of a dashboard for the model + a non-widget fallback. One line
+ *  per item (KPI value/delta, chart title/type/row-count, text heading) — never echoes chart rows. */
+declare function summarizeDashboard(spec: DashboardSpec): string;
+/** The DashboardSpec envelope: structuredContent for the widget + a text fallback + the widget link.
+ *  Absorbs the structuredContent cast so callers never write it. */
+declare function dashboardResult(spec: DashboardSpec, opts?: {
+    summary?: string | ((s: DashboardSpec) => string);
+}): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: Record<string, unknown>;
+    _meta: {
+        readonly ui: {
+            readonly resourceUri: "ui://bonnard/chart";
+        };
+        readonly "openai/outputTemplate": "ui://bonnard/chart";
+    };
+};
+declare const DASHBOARD_OUTPUT_SCHEMA: {
+    title: z.ZodOptional<z.ZodString>;
+    columns: z.ZodOptional<z.ZodNumber>;
+    items: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    notes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+};
+/** What a view's render returns: a bare spec or one paired with a summary. */
+type ViewResult = ChartSpec | DashboardSpec | {
+    spec: ChartSpec | DashboardSpec;
+    summary?: string;
+};
+/** One named, renderable view in a views registry. */
+interface ViewDef {
+    /** The render_view view_id enum value (snake/kebab, stable). */
+    id: string;
+    title: string;
+    /** One line; shown in explore_views and the render_view catalog. */
+    description: string;
+    /** Optional author hint for the catalog. */
+    kind?: "chart" | "dashboard";
+    /** Per-view input params as a zod raw shape. */
+    params?: Record<string, z.ZodTypeAny>;
+    /**
+     * Produce the view's spec(s). For a DB-connected view, return a typed `ChartData` so the encoding
+     * rides driver types instead of a value sniff, e.g. `chart(await runSql("select ..."), { chartType:
+     * "line" })` — `chart`/`chartCell` accept a `ChartData` anywhere they accept raw rows.
+     */
+    render: (args: Record<string, unknown>) => ViewResult | Promise<ViewResult>;
+}
+/** Options for addViews. */
+interface AddViewsOptions {
+    views: ViewDef[];
+    /** Override the discovery tool name (default: "explore_views"). */
+    exploreToolName?: string;
+    /** Override the execute tool name (default: "render_view"). */
+    renderToolName?: string;
+    /** Extra text appended to render_view's description. */
+    renderDescription?: string;
+}
+/**
+ * Register a two-tool named-views surface: `explore_views` (list the available views) and
+ * `render_view` (render one, bound to the chart widget). Each view returns a ChartSpec or a
+ * DashboardSpec. Owns the widget resource, the outputSchema, the _meta link, param validation, the
+ * result envelope, and error handling.
+ */
+declare function addViews(server: McpServer, opts: AddViewsOptions): void;
 
 declare function resolve(data: ChartData, opts?: ResolveOptions): ChartSpec;
 
 /** Complete field metadata for every column, declared values taking precedence. */
 declare function inferFields(data: ChartData): FieldMeta[];
 
+declare const CHART_RESOURCE_URI = "ui://bonnard/chart";
 /** Options for addCharts. */
 interface AddChartsOptions {
     /** SQL mode: the agent writes SQL; you execute it read-only and return rows. */
@@ -20,39 +132,11 @@ interface AddChartsOptions {
     /** Override the tool name (default: "visualize"). */
     toolName?: string;
 }
+/** Register the chart/dashboard widget ui:// resource. Idempotent per server. A consumer that
+ *  returns a ChartSpec/DashboardSpec from its own tool (instead of `visualize`) calls this so the
+ *  host has the widget to render into. */
+declare function registerChartWidget(server: McpServer): void;
 /** Register the generic `visualize` tool on an MCP server. */
 declare function addCharts(server: McpServer, options: AddChartsOptions): void;
 
-/** A source column: its name + the engine's declared type, in whatever shape the driver reports. */
-interface SourceColumn {
-    name: string;
-    /** Engine type, passed verbatim to mapKind (e.g. "INT64", a Postgres OID, "VARCHAR", a field object). */
-    type: unknown;
-}
-/** Map an engine's column type to our FieldKind. The one piece of real per-engine work. */
-type KindMapper = (type: unknown, column: SourceColumn) => FieldKind;
-/** Coerce one cell value to a flat scalar, guided by the resolved kind. */
-type CellNormalizer = (value: unknown, kind: FieldKind, column: SourceColumn) => unknown;
-interface BuildChartDataOptions {
-    rows: Record<string, unknown>[];
-    columns: SourceColumn[];
-    mapKind: KindMapper;
-    /** Optional; defaults to {@link defaultNormalizeCell}, which suits drivers that return JS-native values. */
-    normalizeCell?: CellNormalizer;
-}
-/** Default cell normalizer: pass scalars through, coerce numbers/booleans, stringify non-scalars.
- *  Handles `{ value }` wrapper objects (some drivers wrap typed values). Adapters whose driver
- *  needs special handling (e.g. BigQuery's typed-string + wrapper mix) supply their own. */
-declare function defaultNormalizeCell(value: unknown, kind: FieldKind): unknown;
-/**
- * Turn a SQL result (rows + column types) into typed ChartData. Builds a complete FieldMeta per
- * column from the engine kind + name-based format/granularity hints, then normalizes every cell.
- */
-declare function buildChartData({ rows, columns, mapKind, normalizeCell, }: BuildChartDataOptions): ChartData;
-/**
- * Reject anything that isn't a single SELECT/WITH statement. A cheap check on LLM-authored SQL;
- * enforce real read-only access with a database role.
- */
-declare function assertReadOnlySql(sql: string): void;
-
-export { type AddChartsOptions, type BuildChartDataOptions, type CellNormalizer, ChartContext, ChartData, ChartSpec, ChartType, FieldKind, FieldMeta, type KindMapper, ResolveOptions, type SourceColumn, addCharts, assertReadOnlySql, buildChartData, defaultNormalizeCell, inferFields, resolve };
+export { type AddChartsOptions, type AddViewsOptions, CHART_RESOURCE_URI, ChartCell, type ChartCellOptions, ChartContext, ChartData, ChartExplanation, type ChartOptions, ChartSpec, ChartType, DASHBOARD_OUTPUT_SCHEMA, DashboardSpec, Encode, FieldMeta, ResolveOptions, type ViewDef, type ViewResult, addCharts, addViews, chart, chartCell, dashboardResult, explain, inferFields, isChartSpec, isDashboardSpec, registerChartWidget, resolve, summarizeDashboard };