@bonnard/mcp-charts 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present Bonnard (bonnard-data)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,39 @@
+# @bonnard/mcp-charts
+
+Add agent-ready, interactive charts to your MCP server in a few lines. `addCharts` registers a
+`visualize` tool plus an embedded chart widget; your agent writes SQL, you run it, and the result
+renders as an interactive chart inside the MCP host (Claude, ChatGPT, and other MCP Apps clients).
+
+```bash
+npm install @bonnard/mcp-charts
+```
+
+```ts
+import { addCharts } from "@bonnard/mcp-charts";
+
+addCharts(server, {
+  // your read-only query callback — return { rows } (and optionally typed `fields`)
+  runSql: async (sql) => ({ rows: await db.query(sql) }),
+  discovery: { toolName: "explore_schema" }, // your schema-discovery tool
+});
+```
+
+You own the database connection; the SDK only turns the rows into a chart. Bring your own SQL, or
+use a bundled warehouse adapter (BigQuery, Postgres, DuckDB, Snowflake, Databricks):
+
+```ts
+import { postgresRunSql } from "@bonnard/mcp-charts/postgres";
+addCharts(server, { runSql: postgresRunSql(pool) });
+```
+
+## Read-only access
+
+The agent writes the SQL, so run it through a **read-only database role** — that is the security
+boundary. The bundled adapters also apply a lightweight SELECT-only check (`assertReadOnlySql`), but
+treat that as a guardrail, not a substitute for least-privilege credentials.
+
+Full docs and examples: https://github.com/bonnard-data/mcp-charts
+
+## License
+
+MIT

package/dist/bigquery.d.ts

@@ -0,0 +1,37 @@
+import { TableField, BigQuery } from '@google-cloud/bigquery';
+import { C as ChartData } from './types-CHiUU9mj.js';
+
+/** A BigQuery schema field. Anchored to the client's own `TableField` type so it tracks the driver:
+ *  if @google-cloud/bigquery changes the schema shape, this and its consumers fail to compile.
+ *  Relevant fields: `type` (INT64/FLOAT64/NUMERIC/BOOL/STRING/DATE/DATETIME/TIMESTAMP/TIME/RECORD/…),
+ *  `mode` (NULLABLE | REQUIRED | REPEATED, where REPEATED is a non-scalar ARRAY). */
+type BigQueryField = TableField;
+/**
+ * Convert a BigQuery query result into ChartData.
+ * @param rows   Result rows (record objects), as returned by `@google-cloud/bigquery` or the REST API.
+ * @param schema The result's `schema.fields` (BigQuery's standard TableFieldSchema list).
+ */
+declare function bigQueryToChartData(rows: Record<string, unknown>[], schema: BigQueryField[]): ChartData;
+
+interface BigQueryRunSqlOptions {
+    /** BigQuery processing location (must match the dataset region), e.g. "europe-west2". */
+    location?: string;
+    /** Cost guard: max bytes a single query may bill (BigQuery's string API shape). */
+    maximumBytesBilled?: string;
+    /** Per-query timeout in milliseconds. */
+    jobTimeoutMs?: number;
+    /** Default dataset so the agent can write unqualified table names (e.g. `weekly_sales`). */
+    defaultDataset?: string | {
+        datasetId: string;
+        projectId?: string;
+    };
+    /** Reject non-SELECT (DML/DDL) statements. Default: true. A read-only IAM role is the real boundary. */
+    readOnly?: boolean;
+}
+/**
+ * Build the `runSql` callback for `addCharts` from a BigQuery client.
+ * Runs the query with the configured guards and returns schema-typed ChartData.
+ */
+declare function bigQueryRunSql(bq: BigQuery, opts?: BigQueryRunSqlOptions): (sql: string) => Promise<ChartData>;
+
+export { type BigQueryField, type BigQueryRunSqlOptions, bigQueryRunSql, bigQueryToChartData };

package/dist/bigquery.js

@@ -0,0 +1,74 @@
+import {
+  assertReadOnlySql,
+  buildChartData
+} from "./chunk-NGXV4I2L.js";
+
+// src/adapters/bigquery.ts
+var NUMERIC = /* @__PURE__ */ new Set(["INT64", "INTEGER", "FLOAT64", "FLOAT", "NUMERIC", "BIGNUMERIC"]);
+var TEMPORAL = /* @__PURE__ */ new Set(["DATE", "DATETIME", "TIMESTAMP"]);
+var BOOLEAN = /* @__PURE__ */ new Set(["BOOL", "BOOLEAN"]);
+function bqKind(field) {
+  if (field.mode === "REPEATED") return "string";
+  const t = (field.type || "").toUpperCase();
+  if (t === "RECORD" || t === "STRUCT") return "string";
+  if (NUMERIC.has(t)) return "number";
+  if (TEMPORAL.has(t)) return "time";
+  if (BOOLEAN.has(t)) return "boolean";
+  return "string";
+}
+function bqNormalize(value, kind) {
+  if (value == null) return null;
+  const obj = typeof value === "object" ? value : null;
+  if (kind === "number") {
+    const raw = obj ? "value" in obj ? obj.value : value.toString() : value;
+    const n = Number(raw);
+    return Number.isFinite(n) ? n : null;
+  }
+  if (kind === "time") {
+    if (obj && "value" in obj) return obj.value;
+    return typeof value === "string" ? value : String(value);
+  }
+  if (kind === "boolean") {
+    if (typeof value === "boolean") return value;
+    const s = String(value).toLowerCase();
+    return s === "true" || s === "1" ? true : s === "false" || s === "0" ? false : null;
+  }
+  if (obj) {
+    if (Array.isArray(value)) return JSON.stringify(value);
+    if ("value" in obj) return String(obj.value);
+    return JSON.stringify(value);
+  }
+  return String(value);
+}
+function bigQueryToChartData(rows, schema) {
+  const columns = schema.map((f) => ({ name: f.name ?? "", type: f }));
+  return buildChartData({
+    rows,
+    columns,
+    mapKind: (type) => bqKind(type),
+    normalizeCell: bqNormalize
+  });
+}
+
+// src/bigquery.ts
+function bigQueryRunSql(bq, opts = {}) {
+  const defaultDataset = typeof opts.defaultDataset === "string" ? { datasetId: opts.defaultDataset } : opts.defaultDataset;
+  return async (sql) => {
+    if (opts.readOnly !== false) assertReadOnlySql(sql);
+    const [job] = await bq.createQueryJob({
+      query: sql,
+      ...opts.location && { location: opts.location },
+      ...opts.maximumBytesBilled && { maximumBytesBilled: opts.maximumBytesBilled },
+      ...opts.jobTimeoutMs && { jobTimeoutMs: opts.jobTimeoutMs },
+      ...defaultDataset && { defaultDataset }
+    });
+    const [rows, , apiResponse] = await job.getQueryResults();
+    const schema = apiResponse?.schema?.fields ?? [];
+    return bigQueryToChartData(rows, schema);
+  };
+}
+export {
+  bigQueryRunSql,
+  bigQueryToChartData
+};
+//# sourceMappingURL=bigquery.js.map

package/dist/bigquery.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/adapters/bigquery.ts","../src/bigquery.ts"],"sourcesContent":["// BigQuery -> ChartData adapter. The ONLY engine-specific pieces are here: the type map and the\n// cell normalizer (BigQuery returns typed strings — \"7.19E-4\", \"1389\" — or, via the Node client,\n// wrapper objects like BigQueryDate/Int + Big). The FieldMeta assembly, name hints, ChartData\n// shape and read-only backstop come from ./sql (shared by every adapter).\n//\n// Usage (the dev owns the client + safety):\n//   const [job] = await bq.createQueryJob({ query, location, maximumBytesBilled, jobTimeoutMs });\n//   const [rows, , apiResponse] = await job.getQueryResults();\n//   const data = bigQueryToChartData(rows, apiResponse.schema.fields);  // -> ChartData\nimport type { TableField } from \"@google-cloud/bigquery\";\nimport type { ChartData, FieldKind } from \"../types.js\";\nimport { buildChartData, type SourceColumn } from \"./sql.js\";\n\n/** A BigQuery schema field. Anchored to the client's own `TableField` type so it tracks the driver:\n *  if @google-cloud/bigquery changes the schema shape, this and its consumers fail to compile.\n *  Relevant fields: `type` (INT64/FLOAT64/NUMERIC/BOOL/STRING/DATE/DATETIME/TIMESTAMP/TIME/RECORD/…),\n *  `mode` (NULLABLE | REQUIRED | REPEATED, where REPEATED is a non-scalar ARRAY). */\nexport type BigQueryField = TableField;\n\n// BigQuery reports both GoogleSQL and legacy names depending on the API surface — handle both.\nconst NUMERIC = new Set([\"INT64\", \"INTEGER\", \"FLOAT64\", \"FLOAT\", \"NUMERIC\", \"BIGNUMERIC\"]);\nconst TEMPORAL = new Set([\"DATE\", \"DATETIME\", \"TIMESTAMP\"]);\nconst BOOLEAN = new Set([\"BOOL\", \"BOOLEAN\"]);\n\nfunction bqKind(field: BigQueryField): FieldKind {\n  if (field.mode === \"REPEATED\") return \"string\"; // ARRAY -> not scalar-plottable, stringify\n  const t = (field.type || \"\").toUpperCase();\n  if (t === \"RECORD\" || t === \"STRUCT\") return \"string\"; // nested -> stringify\n  if (NUMERIC.has(t)) return \"number\";\n  if (TEMPORAL.has(t)) return \"time\";\n  if (BOOLEAN.has(t)) return \"boolean\";\n  return \"string\"; // STRING, TIME, BYTES, GEOGRAPHY, JSON, ...\n}\n\n// Coerce one BigQuery cell to a flat scalar, handling raw-string (REST) and wrapper-object (Node\n// client) representations, guided by the column's declared kind.\nfunction bqNormalize(value: unknown, kind: FieldKind): unknown {\n  if (value == null) return null;\n  const obj = typeof value === \"object\" ? (value as Record<string, unknown>) : null;\n  if (kind === \"number\") {\n    const raw = obj ? (\"value\" in obj ? obj.value : (value as { toString(): string }).toString()) : value;\n    const n = Number(raw);\n    return Number.isFinite(n) ? n : null;\n  }\n  if (kind === \"time\") {\n    // BigQueryDate/Datetime/Timestamp -> { value } (ISO string); raw -> ISO string already.\n    if (obj && \"value\" in obj) return obj.value;\n    return typeof value === \"string\" ? value : String(value);\n  }\n  if (kind === \"boolean\") {\n    if (typeof value === \"boolean\") return value;\n    const s = String(value).toLowerCase();\n    return s === \"true\" || s === \"1\" ? true : s === \"false\" || s === \"0\" ? false : null;\n  }\n  // string-ish: stringify arrays/structs so the scalar guard passes; unwrap { value }; else String.\n  if (obj) {\n    if (Array.isArray(value)) return JSON.stringify(value);\n    if (\"value\" in obj) return String(obj.value);\n    return JSON.stringify(value);\n  }\n  return String(value);\n}\n\n/**\n * Convert a BigQuery query result into ChartData.\n * @param rows   Result rows (record objects), as returned by `@google-cloud/bigquery` or the REST API.\n * @param schema The result's `schema.fields` (BigQuery's standard TableFieldSchema list).\n */\nexport function bigQueryToChartData(rows: Record<string, unknown>[], schema: BigQueryField[]): ChartData {\n  const columns: SourceColumn[] = schema.map((f) => ({ name: f.name ?? \"\", type: f }));\n  return buildChartData({\n    rows,\n    columns,\n    mapKind: (type) => bqKind(type as BigQueryField),\n    normalizeCell: bqNormalize,\n  });\n}\n","// @bonnard/mcp-charts/bigquery — drop-in BigQuery adapter for addCharts.\n//\n// The caller owns the client, auth (ADC / service account) and IAM (read-only); this packages the\n// rest of the dev-side `runSql`: a read-only guard, a cost cap + timeout, an optional default\n// dataset, and the schema-driven result -> ChartData transform.\n//\n//   import { addCharts } from \"@bonnard/mcp-charts\";\n//   import { bigQueryRunSql } from \"@bonnard/mcp-charts/bigquery\";\n//   import { BigQuery } from \"@google-cloud/bigquery\";\n//\n//   const bq = new BigQuery(); // ADC: local = gcloud login; prod = Workload Identity service account\n//   addCharts(server, {\n//     runSql: bigQueryRunSql(bq, {\n//       location: \"europe-west2\",\n//       maximumBytesBilled: \"200000000\",      // cost guard\n//       defaultDataset: \"analytics_internal\", // unqualified table names resolve here\n//     }),\n//     discovery: { toolName: \"explore_schema\" },\n//   });\n//\n// `@google-cloud/bigquery` is an OPTIONAL peer (only needed if you import this subpath). The type\n// import below is erased at build, so this module adds no runtime dependency — it just calls methods\n// on the client you pass in.\nimport type { BigQuery } from \"@google-cloud/bigquery\";\nimport type { ChartData } from \"./types.js\";\nimport { assertReadOnlySql } from \"./adapters/sql.js\";\nimport { bigQueryToChartData, type BigQueryField } from \"./adapters/bigquery.js\";\n\nexport { bigQueryToChartData, type BigQueryField };\n\nexport interface BigQueryRunSqlOptions {\n  /** BigQuery processing location (must match the dataset region), e.g. \"europe-west2\". */\n  location?: string;\n  /** Cost guard: max bytes a single query may bill (BigQuery's string API shape). */\n  maximumBytesBilled?: string;\n  /** Per-query timeout in milliseconds. */\n  jobTimeoutMs?: number;\n  /** Default dataset so the agent can write unqualified table names (e.g. `weekly_sales`). */\n  defaultDataset?: string | { datasetId: string; projectId?: string };\n  /** Reject non-SELECT (DML/DDL) statements. Default: true. A read-only IAM role is the real boundary. */\n  readOnly?: boolean;\n}\n\n/**\n * Build the `runSql` callback for `addCharts` from a BigQuery client.\n * Runs the query with the configured guards and returns schema-typed ChartData.\n */\nexport function bigQueryRunSql(bq: BigQuery, opts: BigQueryRunSqlOptions = {}): (sql: string) => Promise<ChartData> {\n  const defaultDataset =\n    typeof opts.defaultDataset === \"string\" ? { datasetId: opts.defaultDataset } : opts.defaultDataset;\n  return async (sql: string): Promise<ChartData> => {\n    if (opts.readOnly !== false) assertReadOnlySql(sql);\n    const [job] = await bq.createQueryJob({\n      query: sql,\n      ...(opts.location && { location: opts.location }),\n      ...(opts.maximumBytesBilled && { maximumBytesBilled: opts.maximumBytesBilled }),\n      ...(opts.jobTimeoutMs && { jobTimeoutMs: opts.jobTimeoutMs }),\n      ...(defaultDataset && { defaultDataset }),\n    });\n    const [rows, , apiResponse] = await job.getQueryResults();\n    const schema: BigQueryField[] = apiResponse?.schema?.fields ?? [];\n    return bigQueryToChartData(rows as Record<string, unknown>[], schema);\n  };\n}\n"],"mappings":";;;;;;AAoBA,IAAM,UAAU,oBAAI,IAAI,CAAC,SAAS,WAAW,WAAW,SAAS,WAAW,YAAY,CAAC;AACzF,IAAM,WAAW,oBAAI,IAAI,CAAC,QAAQ,YAAY,WAAW,CAAC;AAC1D,IAAM,UAAU,oBAAI,IAAI,CAAC,QAAQ,SAAS,CAAC;AAE3C,SAAS,OAAO,OAAiC;AAC/C,MAAI,MAAM,SAAS,WAAY,QAAO;AACtC,QAAM,KAAK,MAAM,QAAQ,IAAI,YAAY;AACzC,MAAI,MAAM,YAAY,MAAM,SAAU,QAAO;AAC7C,MAAI,QAAQ,IAAI,CAAC,EAAG,QAAO;AAC3B,MAAI,SAAS,IAAI,CAAC,EAAG,QAAO;AAC5B,MAAI,QAAQ,IAAI,CAAC,EAAG,QAAO;AAC3B,SAAO;AACT;AAIA,SAAS,YAAY,OAAgB,MAA0B;AAC7D,MAAI,SAAS,KAAM,QAAO;AAC1B,QAAM,MAAM,OAAO,UAAU,WAAY,QAAoC;AAC7E,MAAI,SAAS,UAAU;AACrB,UAAM,MAAM,MAAO,WAAW,MAAM,IAAI,QAAS,MAAiC,SAAS,IAAK;AAChG,UAAM,IAAI,OAAO,GAAG;AACpB,WAAO,OAAO,SAAS,CAAC,IAAI,IAAI;AAAA,EAClC;AACA,MAAI,SAAS,QAAQ;AAEnB,QAAI,OAAO,WAAW,IAAK,QAAO,IAAI;AACtC,WAAO,OAAO,UAAU,WAAW,QAAQ,OAAO,KAAK;AAAA,EACzD;AACA,MAAI,SAAS,WAAW;AACtB,QAAI,OAAO,UAAU,UAAW,QAAO;AACvC,UAAM,IAAI,OAAO,KAAK,EAAE,YAAY;AACpC,WAAO,MAAM,UAAU,MAAM,MAAM,OAAO,MAAM,WAAW,MAAM,MAAM,QAAQ;AAAA,EACjF;AAEA,MAAI,KAAK;AACP,QAAI,MAAM,QAAQ,KAAK,EAAG,QAAO,KAAK,UAAU,KAAK;AACrD,QAAI,WAAW,IAAK,QAAO,OAAO,IAAI,KAAK;AAC3C,WAAO,KAAK,UAAU,KAAK;AAAA,EAC7B;AACA,SAAO,OAAO,KAAK;AACrB;AAOO,SAAS,oBAAoB,MAAiC,QAAoC;AACvG,QAAM,UAA0B,OAAO,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,IAAI,MAAM,EAAE,EAAE;AACnF,SAAO,eAAe;AAAA,IACpB;AAAA,IACA;AAAA,IACA,SAAS,CAAC,SAAS,OAAO,IAAqB;AAAA,IAC/C,eAAe;AAAA,EACjB,CAAC;AACH;;;AC7BO,SAAS,eAAe,IAAc,OAA8B,CAAC,GAAwC;AAClH,QAAM,iBACJ,OAAO,KAAK,mBAAmB,WAAW,EAAE,WAAW,KAAK,eAAe,IAAI,KAAK;AACtF,SAAO,OAAO,QAAoC;AAChD,QAAI,KAAK,aAAa,MAAO,mBAAkB,GAAG;AAClD,UAAM,CAAC,GAAG,IAAI,MAAM,GAAG,eAAe;AAAA,MACpC,OAAO;AAAA,MACP,GAAI,KAAK,YAAY,EAAE,UAAU,KAAK,SAAS;AAAA,MAC/C,GAAI,KAAK,sBAAsB,EAAE,oBAAoB,KAAK,mBAAmB;AAAA,MAC7E,GAAI,KAAK,gBAAgB,EAAE,cAAc,KAAK,aAAa;AAAA,MAC3D,GAAI,kBAAkB,EAAE,eAAe;AAAA,IACzC,CAAC;AACD,UAAM,CAAC,MAAM,EAAE,WAAW,IAAI,MAAM,IAAI,gBAAgB;AACxD,UAAM,SAA0B,aAAa,QAAQ,UAAU,CAAC;AAChE,WAAO,oBAAoB,MAAmC,MAAM;AAAA,EACtE;AACF;","names":[]}

package/dist/chunk-NGXV4I2L.js

@@ -0,0 +1,136 @@
+// src/resolve/infer.ts
+function sniffTimeGranularity(value) {
+  if (typeof value !== "string") return null;
+  if (/^\d{4}-\d{2}-\d{2}([T ]|$)/.test(value)) return "day";
+  if (/^\d{4}-\d{2}$/.test(value)) return "month";
+  if (/^\d{4}-?Q[1-4]$/i.test(value)) return "quarter";
+  if (/^\d{4}-W\d{2}$/i.test(value)) return "week";
+  if (/^\d{4}$/.test(value)) {
+    const y = Number(value);
+    if (y >= 1900 && y <= 2100) return "year";
+  }
+  return null;
+}
+function sniffKind(rows, name) {
+  const sample = rows.find((r) => r[name] != null)?.[name];
+  if (sample == null) return "string";
+  if (typeof sample === "number" || typeof sample === "bigint") return "number";
+  if (typeof sample === "boolean") return "boolean";
+  if (typeof sample === "string" && sniffTimeGranularity(sample) !== null) return "time";
+  return "string";
+}
+function roleFromKind(kind) {
+  if (kind === "time") return "time";
+  if (kind === "number") return "measure";
+  return "dimension";
+}
+function titleCase(s) {
+  return s.replace(/_/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+function formatHint(name) {
+  const n = name.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase();
+  if (/(^|_)(rate|pct|percent|percentage|ratio)(_|$)/.test(n)) return "percent";
+  return void 0;
+}
+function granularityHint(name) {
+  const n = name.toLowerCase();
+  if (n.includes("year")) return "year";
+  if (n.includes("quarter")) return "quarter";
+  if (n.includes("month")) return "month";
+  if (n.includes("week")) return "week";
+  return "day";
+}
+function inferFields(data) {
+  const { rows, fields } = data;
+  const declared = new Map((fields ?? []).map((f) => [f.name, f]));
+  const rowKeys = rows[0] ? Object.keys(rows[0]) : [];
+  const names = [...rowKeys, ...[...declared.keys()].filter((n) => !rowKeys.includes(n))];
+  return names.map((name) => {
+    const d = declared.get(name);
+    const kind = d?.kind ?? sniffKind(rows, name);
+    const role = d?.role ?? roleFromKind(kind);
+    const granularity = d?.granularity ?? (kind === "time" ? sniffTimeGranularity(rows.find((r) => r[name] != null)?.[name]) ?? granularityHint(name) : void 0);
+    const format = d?.format ?? (kind === "number" ? formatHint(name) : void 0);
+    return {
+      name,
+      kind,
+      role,
+      label: d?.label ?? titleCase(name),
+      ...format && { format },
+      ...granularity && { granularity },
+      ...d?.additive != null && { additive: d.additive },
+      ...d?.currency && { currency: d.currency }
+    };
+  });
+}
+
+// src/adapters/sql.ts
+function defaultNormalizeCell(value, kind) {
+  if (value == null) return null;
+  const obj = typeof value === "object" ? value : null;
+  if (kind === "number") {
+    const raw = obj ? "value" in obj ? obj.value : value.toString() : value;
+    const n = Number(raw);
+    return Number.isFinite(n) ? n : null;
+  }
+  if (kind === "boolean") {
+    if (typeof value === "boolean") return value;
+    const s = String(obj && "value" in obj ? obj.value : value).toLowerCase();
+    return s === "true" || s === "1" ? true : s === "false" || s === "0" ? false : null;
+  }
+  if (kind === "time") {
+    if (obj && "value" in obj) return String(obj.value);
+    return value instanceof Date ? value.toISOString() : typeof value === "string" ? value : String(value);
+  }
+  if (obj) {
+    if (Array.isArray(value)) return JSON.stringify(value);
+    if ("value" in obj) return String(obj.value);
+    return JSON.stringify(value);
+  }
+  return value;
+}
+function buildChartData({
+  rows,
+  columns,
+  mapKind,
+  normalizeCell = defaultNormalizeCell
+}) {
+  const fields = columns.map((col) => {
+    const kind = mapKind(col.type, col);
+    const format = kind === "number" ? formatHint(col.name) : void 0;
+    const granularity = kind === "time" ? granularityHint(col.name) : void 0;
+    return {
+      name: col.name,
+      kind,
+      role: roleFromKind(kind),
+      label: titleCase(col.name),
+      ...format && { format },
+      ...granularity && { granularity }
+    };
+  });
+  const kindByName = new Map(fields.map((f) => [f.name, f.kind]));
+  const out = rows.map((row) => {
+    const r = {};
+    for (const col of columns) r[col.name] = normalizeCell(row[col.name], kindByName.get(col.name), col);
+    return r;
+  });
+  return { rows: out, fields };
+}
+function assertReadOnlySql(sql) {
+  const t = sql.trim().replace(/;\s*$/, "");
+  if (/;/.test(t)) throw new Error("Only a single statement is allowed.");
+  if (!/^(select|with)\b/i.test(t)) throw new Error("Only read-only SELECT queries are allowed.");
+  if (/\b(insert|update|delete|merge|drop|alter|create|truncate|grant|revoke|call|export|load|copy|execute|attach|vacuum|lock)\b/i.test(
+    t
+  )) {
+    throw new Error("Write/DDL statements are not allowed.");
+  }
+}
+
+export {
+  inferFields,
+  defaultNormalizeCell,
+  buildChartData,
+  assertReadOnlySql
+};
+//# sourceMappingURL=chunk-NGXV4I2L.js.map

package/dist/chunk-NGXV4I2L.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/resolve/infer.ts","../src/adapters/sql.ts"],"sourcesContent":["// Typing inference: turn a ChartData into a complete, role-tagged FieldMeta list.\n// Priority: declared fields win; anything missing is sniffed from the row values.\n// This is what lets resolve() decide x / y / series when the data source did not\n// supply full typing (e.g. raw SQL rows).\nimport type { ChartData, FieldFormat, FieldKind, FieldMeta, FieldRole, TimeGranularity } from \"../types.js\";\n\n// Period-string -> granularity. Lets the raw-SQL path recognize time buckets that aren't full ISO\n// dates (e.g. strftime('%Y-%m') -> \"2025-01\") so time series are typed TEMPORAL — ordered, drawn\n// vertically, nicely labelled — instead of being mistaken for high-cardinality categories. Used\n// when the data source declares no column types, so the kind is inferred from the value shape.\nexport function sniffTimeGranularity(value: unknown): TimeGranularity | null {\n  if (typeof value !== \"string\") return null;\n  if (/^\\d{4}-\\d{2}-\\d{2}([T ]|$)/.test(value)) return \"day\"; // 2025-01-15 or a full datetime\n  if (/^\\d{4}-\\d{2}$/.test(value)) return \"month\"; // 2025-01\n  if (/^\\d{4}-?Q[1-4]$/i.test(value)) return \"quarter\"; // 2025-Q1 / 2025Q1\n  if (/^\\d{4}-W\\d{2}$/i.test(value)) return \"week\"; // 2025-W03 (ISO week)\n  if (/^\\d{4}$/.test(value)) {\n    const y = Number(value); // bare year as a string (\"2025\"); guard the range to avoid 4-digit codes\n    if (y >= 1900 && y <= 2100) return \"year\";\n  }\n  return null;\n}\n\nexport function sniffKind(rows: Record<string, unknown>[], name: string): FieldKind {\n  const sample = rows.find((r) => r[name] != null)?.[name];\n  if (sample == null) return \"string\";\n  if (typeof sample === \"number\" || typeof sample === \"bigint\") return \"number\";\n  if (typeof sample === \"boolean\") return \"boolean\";\n  if (typeof sample === \"string\" && sniffTimeGranularity(sample) !== null) return \"time\";\n  return \"string\";\n}\n\nexport function roleFromKind(kind: FieldKind): FieldRole {\n  if (kind === \"time\") return \"time\";\n  if (kind === \"number\") return \"measure\";\n  return \"dimension\";\n}\n\nexport function titleCase(s: string): string {\n  return s.replace(/_/g, \" \").replace(/\\b\\w/g, (c) => c.toUpperCase());\n}\n\n// Name-based hints — a purely conventional fallback used only when the data source declares no\n// format/granularity. Centralized here so the adapter path (buildChartData) and the raw-rows path\n// (inferFields) apply identical rules.\n\n// A numeric column whose name reads as a rate/ratio renders as a percent. Currency is deliberately\n// NOT guessed from names (the code is unknowable) — declare it. camelCase is normalized to snake.\nexport function formatHint(name: string): FieldFormat | undefined {\n  const n = name.replace(/([a-z0-9])([A-Z])/g, \"$1_$2\").toLowerCase();\n  if (/(^|_)(rate|pct|percent|percentage|ratio)(_|$)/.test(n)) return \"percent\";\n  return undefined;\n}\n\n// Granularity from the column name, for time columns whose values don't reveal it (e.g. a DATE\n// named \"week_start\" holding full dates). Defaults to day.\nexport function granularityHint(name: string): TimeGranularity {\n  const n = name.toLowerCase();\n  if (n.includes(\"year\")) return \"year\";\n  if (n.includes(\"quarter\")) return \"quarter\";\n  if (n.includes(\"month\")) return \"month\";\n  if (n.includes(\"week\")) return \"week\";\n  return \"day\";\n}\n\n/** Complete field metadata for every column, declared values taking precedence. */\nexport function inferFields(data: ChartData): FieldMeta[] {\n  const { rows, fields } = data;\n  const declared = new Map((fields ?? []).map((f) => [f.name, f]));\n  // Union of returned columns + any declared-only names: declaring fields for SOME columns\n  // augments their typing, it does not drop the columns you didn't declare.\n  const rowKeys = rows[0] ? Object.keys(rows[0]) : [];\n  const names = [...rowKeys, ...[...declared.keys()].filter((n) => !rowKeys.includes(n))];\n\n  return names.map((name) => {\n    const d = declared.get(name);\n    const kind: FieldKind = d?.kind ?? sniffKind(rows, name);\n    const role: FieldRole = d?.role ?? roleFromKind(kind);\n    // Time columns with no declared granularity: infer it from the value shape (YYYY-MM -> month).\n    // declared > value-sniff > name-hint\n    const granularity =\n      d?.granularity ??\n      (kind === \"time\"\n        ? (sniffTimeGranularity(rows.find((r) => r[name] != null)?.[name]) ?? granularityHint(name))\n        : undefined);\n    // declared > name-hint (rate -> percent); only for numeric columns\n    const format = d?.format ?? (kind === \"number\" ? formatHint(name) : undefined);\n    return {\n      name,\n      kind,\n      role,\n      label: d?.label ?? titleCase(name),\n      ...(format && { format }),\n      ...(granularity && { granularity }),\n      ...(d?.additive != null && { additive: d.additive }),\n      ...(d?.currency && { currency: d.currency }),\n    };\n  });\n}\n","// Shared adapter core. An adapter's only engine-specific jobs are (a) report each column's engine\n// type, (b) map that type to a FieldKind, and (c) normalize a cell to a flat scalar. The rest —\n// assembling typed FieldMeta (with name-based format/granularity hints), the ChartData shape, and\n// the read-only check — lives here so every adapter shares it.\n//\n// Connection, auth, read-only enforcement, cost caps and timeouts belong to the caller's database\n// role; assertReadOnlySql is a cheap extra check on LLM-authored SQL, not a substitute for one.\nimport type { ChartData, FieldKind, FieldMeta } from \"../types.js\";\nimport { roleFromKind, titleCase, formatHint, granularityHint } from \"../resolve/infer.js\";\n\n/** A source column: its name + the engine's declared type, in whatever shape the driver reports. */\nexport interface SourceColumn {\n  name: string;\n  /** Engine type, passed verbatim to mapKind (e.g. \"INT64\", a Postgres OID, \"VARCHAR\", a field object). */\n  type: unknown;\n}\n\n/** Map an engine's column type to our FieldKind. The one piece of real per-engine work. */\nexport type KindMapper = (type: unknown, column: SourceColumn) => FieldKind;\n\n/** Coerce one cell value to a flat scalar, guided by the resolved kind. */\nexport type CellNormalizer = (value: unknown, kind: FieldKind, column: SourceColumn) => unknown;\n\nexport interface BuildChartDataOptions {\n  rows: Record<string, unknown>[];\n  columns: SourceColumn[];\n  mapKind: KindMapper;\n  /** Optional; defaults to {@link defaultNormalizeCell}, which suits drivers that return JS-native values. */\n  normalizeCell?: CellNormalizer;\n}\n\n/** Default cell normalizer: pass scalars through, coerce numbers/booleans, stringify non-scalars.\n *  Handles `{ value }` wrapper objects (some drivers wrap typed values). Adapters whose driver\n *  needs special handling (e.g. BigQuery's typed-string + wrapper mix) supply their own. */\nexport function defaultNormalizeCell(value: unknown, kind: FieldKind): unknown {\n  if (value == null) return null;\n  const obj = typeof value === \"object\" ? (value as Record<string, unknown>) : null;\n  if (kind === \"number\") {\n    const raw = obj ? (\"value\" in obj ? obj.value : (value as { toString(): string }).toString()) : value;\n    const n = Number(raw);\n    return Number.isFinite(n) ? n : null;\n  }\n  if (kind === \"boolean\") {\n    if (typeof value === \"boolean\") return value;\n    const s = String(obj && \"value\" in obj ? obj.value : value).toLowerCase();\n    return s === \"true\" || s === \"1\" ? true : s === \"false\" || s === \"0\" ? false : null;\n  }\n  if (kind === \"time\") {\n    if (obj && \"value\" in obj) return String(obj.value);\n    return value instanceof Date ? value.toISOString() : typeof value === \"string\" ? value : String(value);\n  }\n  // string-ish: unwrap { value }, stringify arrays/objects so the scalar guard passes, else pass through.\n  if (obj) {\n    if (Array.isArray(value)) return JSON.stringify(value);\n    if (\"value\" in obj) return String(obj.value);\n    return JSON.stringify(value);\n  }\n  return value;\n}\n\n/**\n * Turn a SQL result (rows + column types) into typed ChartData. Builds a complete FieldMeta per\n * column from the engine kind + name-based format/granularity hints, then normalizes every cell.\n */\nexport function buildChartData({\n  rows,\n  columns,\n  mapKind,\n  normalizeCell = defaultNormalizeCell,\n}: BuildChartDataOptions): ChartData {\n  const fields: FieldMeta[] = columns.map((col) => {\n    const kind = mapKind(col.type, col);\n    const format = kind === \"number\" ? formatHint(col.name) : undefined;\n    const granularity = kind === \"time\" ? granularityHint(col.name) : undefined;\n    return {\n      name: col.name,\n      kind,\n      role: roleFromKind(kind),\n      label: titleCase(col.name),\n      ...(format && { format }),\n      ...(granularity && { granularity }),\n    };\n  });\n  const kindByName = new Map(fields.map((f) => [f.name, f.kind!]));\n  const out = rows.map((row) => {\n    const r: Record<string, unknown> = {};\n    for (const col of columns) r[col.name] = normalizeCell(row[col.name], kindByName.get(col.name)!, col);\n    return r;\n  });\n  return { rows: out, fields };\n}\n\n/**\n * Reject anything that isn't a single SELECT/WITH statement. A cheap check on LLM-authored SQL;\n * enforce real read-only access with a database role.\n */\nexport function assertReadOnlySql(sql: string): void {\n  const t = sql.trim().replace(/;\\s*$/, \"\");\n  if (/;/.test(t)) throw new Error(\"Only a single statement is allowed.\");\n  if (!/^(select|with)\\b/i.test(t)) throw new Error(\"Only read-only SELECT queries are allowed.\");\n  if (\n    /\\b(insert|update|delete|merge|drop|alter|create|truncate|grant|revoke|call|export|load|copy|execute|attach|vacuum|lock)\\b/i.test(\n      t,\n    )\n  ) {\n    throw new Error(\"Write/DDL statements are not allowed.\");\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/databricks.d.ts

@@ -0,0 +1,23 @@
+import { DBSQLSession } from '@databricks/sql';
+import { C as ChartData } from './types-CHiUU9mj.js';
+
+/** A Databricks result column: name + the Thrift TTypeId code. */
+interface DatabricksColumn {
+    name: string;
+    typeId: number;
+}
+/**
+ * Convert a Databricks result into ChartData.
+ * @param rows    Row objects from `operation.fetchAll()`.
+ * @param columns Column name + TTypeId, extracted from `operation.getSchema()` (see databricksRunSql).
+ */
+declare function databricksToChartData(rows: Record<string, unknown>[], columns: DatabricksColumn[]): ChartData;
+
+interface DatabricksRunSqlOptions {
+    /** Reject non-SELECT statements. Default: true. A read-only warehouse/grant is the real boundary. */
+    readOnly?: boolean;
+}
+/** Build the `runSql` callback for `addCharts` from an open Databricks SQL session. */
+declare function databricksRunSql(session: DBSQLSession, opts?: DatabricksRunSqlOptions): (sql: string) => Promise<ChartData>;
+
+export { type DatabricksColumn, type DatabricksRunSqlOptions, databricksRunSql, databricksToChartData };

package/dist/databricks.js

@@ -0,0 +1,65 @@
+import {
+  assertReadOnlySql,
+  buildChartData
+} from "./chunk-NGXV4I2L.js";
+
+// src/adapters/databricks.ts
+var TTypeId = {
+  BOOLEAN: 0,
+  TINYINT: 1,
+  SMALLINT: 2,
+  INT: 3,
+  BIGINT: 4,
+  FLOAT: 5,
+  DOUBLE: 6,
+  STRING: 7,
+  TIMESTAMP: 8,
+  DECIMAL: 15,
+  DATE: 17,
+  VARCHAR: 18,
+  CHAR: 19
+};
+var NUMERIC = /* @__PURE__ */ new Set([
+  TTypeId.TINYINT,
+  TTypeId.SMALLINT,
+  TTypeId.INT,
+  TTypeId.BIGINT,
+  TTypeId.FLOAT,
+  TTypeId.DOUBLE,
+  TTypeId.DECIMAL
+]);
+var TEMPORAL = /* @__PURE__ */ new Set([TTypeId.TIMESTAMP, TTypeId.DATE]);
+function databricksKind(typeId) {
+  if (NUMERIC.has(typeId)) return "number";
+  if (TEMPORAL.has(typeId)) return "time";
+  if (typeId === TTypeId.BOOLEAN) return "boolean";
+  return "string";
+}
+function databricksToChartData(rows, columns) {
+  const cols = columns.map((c) => ({ name: c.name, type: c.typeId }));
+  return buildChartData({ rows, columns: cols, mapKind: (typeId) => databricksKind(typeId) });
+}
+
+// src/databricks.ts
+function databricksRunSql(session, opts = {}) {
+  const readOnly = opts.readOnly !== false;
+  return async (sql) => {
+    if (readOnly) assertReadOnlySql(sql);
+    const operation = await session.executeStatement(sql);
+    try {
+      const [rows, schema] = await Promise.all([operation.fetchAll(), operation.getSchema()]);
+      const columns = (schema?.columns ?? []).map((c) => ({
+        name: c.columnName,
+        typeId: c.typeDesc?.types?.[0]?.primitiveEntry?.type ?? -1
+      }));
+      return databricksToChartData(rows, columns);
+    } finally {
+      await operation.close();
+    }
+  };
+}
+export {
+  databricksRunSql,
+  databricksToChartData
+};
+//# sourceMappingURL=databricks.js.map

package/dist/databricks.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/adapters/databricks.ts","../src/databricks.ts"],"sourcesContent":["// Databricks -> ChartData. Engine-specific only: map Thrift TTypeId codes (from the result schema)\n// to FieldKind. FieldMeta assembly + ChartData shape come from ./sql.\nimport type { ChartData, FieldKind } from \"../types.js\";\nimport { buildChartData, type SourceColumn } from \"./sql.js\";\n\n// Thrift TTypeId codes (@databricks/sql TCLIService_types). These are wire-protocol constants.\nconst TTypeId = {\n  BOOLEAN: 0,\n  TINYINT: 1,\n  SMALLINT: 2,\n  INT: 3,\n  BIGINT: 4,\n  FLOAT: 5,\n  DOUBLE: 6,\n  STRING: 7,\n  TIMESTAMP: 8,\n  DECIMAL: 15,\n  DATE: 17,\n  VARCHAR: 18,\n  CHAR: 19,\n} as const;\n\nconst NUMERIC = new Set<number>([\n  TTypeId.TINYINT,\n  TTypeId.SMALLINT,\n  TTypeId.INT,\n  TTypeId.BIGINT,\n  TTypeId.FLOAT,\n  TTypeId.DOUBLE,\n  TTypeId.DECIMAL,\n]);\nconst TEMPORAL = new Set<number>([TTypeId.TIMESTAMP, TTypeId.DATE]);\n\nfunction databricksKind(typeId: number): FieldKind {\n  if (NUMERIC.has(typeId)) return \"number\";\n  if (TEMPORAL.has(typeId)) return \"time\";\n  if (typeId === TTypeId.BOOLEAN) return \"boolean\";\n  return \"string\"; // string/varchar/char/binary/array/map/struct (stringified) ...\n}\n\n/** A Databricks result column: name + the Thrift TTypeId code. */\nexport interface DatabricksColumn {\n  name: string;\n  typeId: number;\n}\n\n/**\n * Convert a Databricks result into ChartData.\n * @param rows    Row objects from `operation.fetchAll()`.\n * @param columns Column name + TTypeId, extracted from `operation.getSchema()` (see databricksRunSql).\n */\nexport function databricksToChartData(rows: Record<string, unknown>[], columns: DatabricksColumn[]): ChartData {\n  const cols: SourceColumn[] = columns.map((c) => ({ name: c.name, type: c.typeId }));\n  return buildChartData({ rows, columns: cols, mapKind: (typeId) => databricksKind(typeId as number) });\n}\n","// @bonnard/mcp-charts/databricks — drop-in Databricks SQL adapter for addCharts.\n//\n// The caller owns the client/session + auth; this packages the dev-side `runSql`: a read-only check\n// plus the result -> ChartData transform. Use a read-only SQL warehouse / Unity Catalog grants as\n// the real boundary.\n//\n//   import { addCharts } from \"@bonnard/mcp-charts\";\n//   import { databricksRunSql } from \"@bonnard/mcp-charts/databricks\";\n//   import { DBSQLClient } from \"@databricks/sql\";\n//\n//   const client = new DBSQLClient();\n//   await client.connect({ host, path, token });\n//   const session = await client.openSession();\n//   addCharts(server, { runSql: databricksRunSql(session), discovery: { toolName: \"explore_schema\" } });\n//\n// `@databricks/sql` is an OPTIONAL peer — only needed if you import this subpath.\nimport type { DBSQLSession } from \"@databricks/sql\";\nimport type { ChartData } from \"./types.js\";\nimport { assertReadOnlySql } from \"./adapters/sql.js\";\nimport { databricksToChartData } from \"./adapters/databricks.js\";\n\nexport { databricksToChartData, type DatabricksColumn } from \"./adapters/databricks.js\";\n\nexport interface DatabricksRunSqlOptions {\n  /** Reject non-SELECT statements. Default: true. A read-only warehouse/grant is the real boundary. */\n  readOnly?: boolean;\n}\n\n/** Build the `runSql` callback for `addCharts` from an open Databricks SQL session. */\nexport function databricksRunSql(\n  session: DBSQLSession,\n  opts: DatabricksRunSqlOptions = {},\n): (sql: string) => Promise<ChartData> {\n  const readOnly = opts.readOnly !== false;\n  return async (sql: string): Promise<ChartData> => {\n    if (readOnly) assertReadOnlySql(sql);\n    const operation = await session.executeStatement(sql);\n    try {\n      const [rows, schema] = await Promise.all([operation.fetchAll(), operation.getSchema()]);\n      const columns = (schema?.columns ?? []).map((c) => ({\n        name: c.columnName,\n        typeId: c.typeDesc?.types?.[0]?.primitiveEntry?.type ?? -1,\n      }));\n      return databricksToChartData(rows as Record<string, unknown>[], columns);\n    } finally {\n      await operation.close();\n    }\n  };\n}\n"],"mappings":";;;;;;AAMA,IAAM,UAAU;AAAA,EACd,SAAS;AAAA,EACT,SAAS;AAAA,EACT,UAAU;AAAA,EACV,KAAK;AAAA,EACL,QAAQ;AAAA,EACR,OAAO;AAAA,EACP,QAAQ;AAAA,EACR,QAAQ;AAAA,EACR,WAAW;AAAA,EACX,SAAS;AAAA,EACT,MAAM;AAAA,EACN,SAAS;AAAA,EACT,MAAM;AACR;AAEA,IAAM,UAAU,oBAAI,IAAY;AAAA,EAC9B,QAAQ;AAAA,EACR,QAAQ;AAAA,EACR,QAAQ;AAAA,EACR,QAAQ;AAAA,EACR,QAAQ;AAAA,EACR,QAAQ;AAAA,EACR,QAAQ;AACV,CAAC;AACD,IAAM,WAAW,oBAAI,IAAY,CAAC,QAAQ,WAAW,QAAQ,IAAI,CAAC;AAElE,SAAS,eAAe,QAA2B;AACjD,MAAI,QAAQ,IAAI,MAAM,EAAG,QAAO;AAChC,MAAI,SAAS,IAAI,MAAM,EAAG,QAAO;AACjC,MAAI,WAAW,QAAQ,QAAS,QAAO;AACvC,SAAO;AACT;AAaO,SAAS,sBAAsB,MAAiC,SAAwC;AAC7G,QAAM,OAAuB,QAAQ,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,MAAM,EAAE,OAAO,EAAE;AAClF,SAAO,eAAe,EAAE,MAAM,SAAS,MAAM,SAAS,CAAC,WAAW,eAAe,MAAgB,EAAE,CAAC;AACtG;;;ACzBO,SAAS,iBACd,SACA,OAAgC,CAAC,GACI;AACrC,QAAM,WAAW,KAAK,aAAa;AACnC,SAAO,OAAO,QAAoC;AAChD,QAAI,SAAU,mBAAkB,GAAG;AACnC,UAAM,YAAY,MAAM,QAAQ,iBAAiB,GAAG;AACpD,QAAI;AACF,YAAM,CAAC,MAAM,MAAM,IAAI,MAAM,QAAQ,IAAI,CAAC,UAAU,SAAS,GAAG,UAAU,UAAU,CAAC,CAAC;AACtF,YAAM,WAAW,QAAQ,WAAW,CAAC,GAAG,IAAI,CAAC,OAAO;AAAA,QAClD,MAAM,EAAE;AAAA,QACR,QAAQ,EAAE,UAAU,QAAQ,CAAC,GAAG,gBAAgB,QAAQ;AAAA,MAC1D,EAAE;AACF,aAAO,sBAAsB,MAAmC,OAAO;AAAA,IACzE,UAAE;AACA,YAAM,UAAU,MAAM;AAAA,IACxB;AAAA,EACF;AACF;","names":[]}

package/dist/duckdb.d.ts

@@ -0,0 +1,23 @@
+import { DuckDBType, DuckDBConnection } from '@duckdb/node-api';
+import { C as ChartData } from './types-CHiUU9mj.js';
+
+/** A DuckDB result column: its name + the DuckDBType (from reader.columnTypes()). */
+interface DuckDbColumn {
+    name: string;
+    type: DuckDBType;
+}
+/**
+ * Convert a DuckDB result into ChartData.
+ * @param rows    Row objects from `reader.getRowObjectsJson()` (JSON-safe scalar values).
+ * @param columns Column name + DuckDBType pairs (from `reader.columnNames()` + `reader.columnTypes()`).
+ */
+declare function duckDbToChartData(rows: Record<string, unknown>[], columns: DuckDbColumn[]): ChartData;
+
+interface DuckDbRunSqlOptions {
+    /** Reject non-SELECT statements. Default: true. A read-only instance is the real boundary. */
+    readOnly?: boolean;
+}
+/** Build the `runSql` callback for `addCharts` from a DuckDB connection. */
+declare function duckDbRunSql(connection: DuckDBConnection, opts?: DuckDbRunSqlOptions): (sql: string) => Promise<ChartData>;
+
+export { type DuckDbColumn, type DuckDbRunSqlOptions, duckDbRunSql, duckDbToChartData };

package/dist/duckdb.js

@@ -0,0 +1,58 @@
+import {
+  assertReadOnlySql,
+  buildChartData
+} from "./chunk-NGXV4I2L.js";
+
+// src/adapters/duckdb.ts
+import { DuckDBTypeId } from "@duckdb/node-api";
+var NUMERIC = /* @__PURE__ */ new Set([
+  DuckDBTypeId.TINYINT,
+  DuckDBTypeId.SMALLINT,
+  DuckDBTypeId.INTEGER,
+  DuckDBTypeId.BIGINT,
+  DuckDBTypeId.HUGEINT,
+  DuckDBTypeId.UTINYINT,
+  DuckDBTypeId.USMALLINT,
+  DuckDBTypeId.UINTEGER,
+  DuckDBTypeId.UBIGINT,
+  DuckDBTypeId.UHUGEINT,
+  DuckDBTypeId.FLOAT,
+  DuckDBTypeId.DOUBLE,
+  DuckDBTypeId.DECIMAL
+]);
+var TEMPORAL = /* @__PURE__ */ new Set([
+  DuckDBTypeId.DATE,
+  DuckDBTypeId.TIMESTAMP,
+  DuckDBTypeId.TIMESTAMP_S,
+  DuckDBTypeId.TIMESTAMP_MS,
+  DuckDBTypeId.TIMESTAMP_NS,
+  DuckDBTypeId.TIMESTAMP_TZ
+]);
+function duckKind(typeId) {
+  if (NUMERIC.has(typeId)) return "number";
+  if (TEMPORAL.has(typeId)) return "time";
+  if (typeId === DuckDBTypeId.BOOLEAN) return "boolean";
+  return "string";
+}
+function duckDbToChartData(rows, columns) {
+  const cols = columns.map((c) => ({ name: c.name, type: c.type.typeId }));
+  return buildChartData({ rows, columns: cols, mapKind: (typeId) => duckKind(typeId) });
+}
+
+// src/duckdb.ts
+function duckDbRunSql(connection, opts = {}) {
+  return async (sql) => {
+    if (opts.readOnly !== false) assertReadOnlySql(sql);
+    const reader = await connection.runAndReadAll(sql);
+    const names = reader.columnNames();
+    const types = reader.columnTypes();
+    const columns = names.map((name, i) => ({ name, type: types[i] }));
+    const rows = reader.getRowObjectsJson();
+    return duckDbToChartData(rows, columns);
+  };
+}
+export {
+  duckDbRunSql,
+  duckDbToChartData
+};
+//# sourceMappingURL=duckdb.js.map

package/dist/duckdb.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/adapters/duckdb.ts","../src/duckdb.ts"],"sourcesContent":["// DuckDB -> ChartData adapter. Engine-specific pieces only: the type map (DuckDBTypeId -> FieldKind)\n// and the column shape. Rows come from reader.getRowObjectsJson() (JSON-safe values), so the shared\n// defaultNormalizeCell handles coercion; the FieldMeta assembly and ChartData shape come from ./sql.\nimport { DuckDBTypeId } from \"@duckdb/node-api\";\nimport type { DuckDBType } from \"@duckdb/node-api\";\nimport type { ChartData, FieldKind } from \"../types.js\";\nimport { buildChartData, type SourceColumn } from \"./sql.js\";\n\nconst NUMERIC = new Set<DuckDBTypeId>([\n  DuckDBTypeId.TINYINT,\n  DuckDBTypeId.SMALLINT,\n  DuckDBTypeId.INTEGER,\n  DuckDBTypeId.BIGINT,\n  DuckDBTypeId.HUGEINT,\n  DuckDBTypeId.UTINYINT,\n  DuckDBTypeId.USMALLINT,\n  DuckDBTypeId.UINTEGER,\n  DuckDBTypeId.UBIGINT,\n  DuckDBTypeId.UHUGEINT,\n  DuckDBTypeId.FLOAT,\n  DuckDBTypeId.DOUBLE,\n  DuckDBTypeId.DECIMAL,\n]);\nconst TEMPORAL = new Set<DuckDBTypeId>([\n  DuckDBTypeId.DATE,\n  DuckDBTypeId.TIMESTAMP,\n  DuckDBTypeId.TIMESTAMP_S,\n  DuckDBTypeId.TIMESTAMP_MS,\n  DuckDBTypeId.TIMESTAMP_NS,\n  DuckDBTypeId.TIMESTAMP_TZ,\n]);\n\nfunction duckKind(typeId: DuckDBTypeId): FieldKind {\n  if (NUMERIC.has(typeId)) return \"number\";\n  if (TEMPORAL.has(typeId)) return \"time\";\n  if (typeId === DuckDBTypeId.BOOLEAN) return \"boolean\";\n  return \"string\"; // VARCHAR, TIME, BLOB, UUID, LIST/STRUCT/MAP (stringified), ...\n}\n\n/** A DuckDB result column: its name + the DuckDBType (from reader.columnTypes()). */\nexport interface DuckDbColumn {\n  name: string;\n  type: DuckDBType;\n}\n\n/**\n * Convert a DuckDB result into ChartData.\n * @param rows    Row objects from `reader.getRowObjectsJson()` (JSON-safe scalar values).\n * @param columns Column name + DuckDBType pairs (from `reader.columnNames()` + `reader.columnTypes()`).\n */\nexport function duckDbToChartData(rows: Record<string, unknown>[], columns: DuckDbColumn[]): ChartData {\n  const cols: SourceColumn[] = columns.map((c) => ({ name: c.name, type: c.type.typeId }));\n  return buildChartData({ rows, columns: cols, mapKind: (typeId) => duckKind(typeId as DuckDBTypeId) });\n}\n","// @bonnard/mcp-charts/duckdb — drop-in DuckDB adapter for addCharts.\n//\n// The caller owns the instance + connection; this packages the dev-side `runSql`: a read-only\n// check plus the result -> ChartData transform. For engine-enforced read-only, open a file-backed\n// instance with `{ access_mode: \"READ_ONLY\" }`.\n//\n//   import { addCharts } from \"@bonnard/mcp-charts\";\n//   import { duckDbRunSql } from \"@bonnard/mcp-charts/duckdb\";\n//   import { DuckDBInstance } from \"@duckdb/node-api\";\n//\n//   const instance = await DuckDBInstance.create(\"analytics.duckdb\", { access_mode: \"READ_ONLY\" });\n//   const connection = await instance.connect();\n//   addCharts(server, { runSql: duckDbRunSql(connection), discovery: { toolName: \"explore_schema\" } });\n//\n// `@duckdb/node-api` is an OPTIONAL peer — only needed if you import this subpath.\nimport type { DuckDBConnection } from \"@duckdb/node-api\";\nimport type { ChartData } from \"./types.js\";\nimport { assertReadOnlySql } from \"./adapters/sql.js\";\nimport { duckDbToChartData } from \"./adapters/duckdb.js\";\n\nexport { duckDbToChartData, type DuckDbColumn } from \"./adapters/duckdb.js\";\n\nexport interface DuckDbRunSqlOptions {\n  /** Reject non-SELECT statements. Default: true. A read-only instance is the real boundary. */\n  readOnly?: boolean;\n}\n\n/** Build the `runSql` callback for `addCharts` from a DuckDB connection. */\nexport function duckDbRunSql(\n  connection: DuckDBConnection,\n  opts: DuckDbRunSqlOptions = {},\n): (sql: string) => Promise<ChartData> {\n  return async (sql: string): Promise<ChartData> => {\n    if (opts.readOnly !== false) assertReadOnlySql(sql);\n    const reader = await connection.runAndReadAll(sql);\n    const names = reader.columnNames();\n    const types = reader.columnTypes();\n    const columns = names.map((name, i) => ({ name, type: types[i]! }));\n    const rows = reader.getRowObjectsJson() as Record<string, unknown>[];\n    return duckDbToChartData(rows, columns);\n  };\n}\n"],"mappings":";;;;;;AAGA,SAAS,oBAAoB;AAK7B,IAAM,UAAU,oBAAI,IAAkB;AAAA,EACpC,aAAa;AAAA,EACb,aAAa;AAAA,EACb,aAAa;AAAA,EACb,aAAa;AAAA,EACb,aAAa;AAAA,EACb,aAAa;AAAA,EACb,aAAa;AAAA,EACb,aAAa;AAAA,EACb,aAAa;AAAA,EACb,aAAa;AAAA,EACb,aAAa;AAAA,EACb,aAAa;AAAA,EACb,aAAa;AACf,CAAC;AACD,IAAM,WAAW,oBAAI,IAAkB;AAAA,EACrC,aAAa;AAAA,EACb,aAAa;AAAA,EACb,aAAa;AAAA,EACb,aAAa;AAAA,EACb,aAAa;AAAA,EACb,aAAa;AACf,CAAC;AAED,SAAS,SAAS,QAAiC;AACjD,MAAI,QAAQ,IAAI,MAAM,EAAG,QAAO;AAChC,MAAI,SAAS,IAAI,MAAM,EAAG,QAAO;AACjC,MAAI,WAAW,aAAa,QAAS,QAAO;AAC5C,SAAO;AACT;AAaO,SAAS,kBAAkB,MAAiC,SAAoC;AACrG,QAAM,OAAuB,QAAQ,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,MAAM,EAAE,KAAK,OAAO,EAAE;AACvF,SAAO,eAAe,EAAE,MAAM,SAAS,MAAM,SAAS,CAAC,WAAW,SAAS,MAAsB,EAAE,CAAC;AACtG;;;ACzBO,SAAS,aACd,YACA,OAA4B,CAAC,GACQ;AACrC,SAAO,OAAO,QAAoC;AAChD,QAAI,KAAK,aAAa,MAAO,mBAAkB,GAAG;AAClD,UAAM,SAAS,MAAM,WAAW,cAAc,GAAG;AACjD,UAAM,QAAQ,OAAO,YAAY;AACjC,UAAM,QAAQ,OAAO,YAAY;AACjC,UAAM,UAAU,MAAM,IAAI,CAAC,MAAM,OAAO,EAAE,MAAM,MAAM,MAAM,CAAC,EAAG,EAAE;AAClE,UAAM,OAAO,OAAO,kBAAkB;AACtC,WAAO,kBAAkB,MAAM,OAAO;AAAA,EACxC;AACF;","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,58 @@
+import { C as ChartData, R as ResolveOptions, a as ChartSpec, F as FieldMeta, b as ChartContext, c as ChartType, d as FieldKind } from './types-CHiUU9mj.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-CHiUU9mj.js';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+declare function resolve(data: ChartData, opts?: ResolveOptions): ChartSpec;
+
+/** Complete field metadata for every column, declared values taking precedence. */
+declare function inferFields(data: ChartData): FieldMeta[];
+
+/** Options for addCharts. */
+interface AddChartsOptions {
+    /** SQL mode: the agent writes SQL; you execute it read-only and return rows. */
+    runSql?: (sql: string, ctx: ChartContext) => Promise<ChartData>;
+    /** Which chart types the agent may use (default: all). */
+    allow?: ChartType[];
+    /** Names the dev's schema-discovery tool so the agent is told to call it first. */
+    discovery?: {
+        toolName: string;
+    };
+    /** Override the tool name (default: "visualize"). */
+    toolName?: string;
+}
+/** 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 };