@microcharts/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ganapati V S
+
+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,116 @@
+# @microcharts/mcp
+
+An MCP server and Vercel AI-SDK toolset for [microcharts](https://microcharts.dev) — let a model **find** the right
+word-sized chart, **get** exactly how to wire it, and **render** it to a finished SVG with real alt text.
+
+microcharts is built so a model can _write_ charts. This is how a model _calls_ them: not "emit some grammar and hope
+the client renders it," but a tool call that returns the real library's static SVG, honest by construction, with the
+generated `describeSeries` accessible name attached.
+
+- **Runs on your machine.** stdio server, distributed on npm. Nothing is hosted; no account, no key, no data leaves.
+- **Works anywhere.** The render tool returns self-contained SVG, so a chat surface that can't run React can still show
+  a real chart.
+- **Zero setup.** `npx @microcharts/mcp` — the package brings its own copy of `@microcharts/react`.
+
+## Install
+
+Add it to any MCP client. For **Claude Desktop** (`claude_desktop_config.json`) or **Cursor** (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "microcharts": {
+      "command": "npx",
+      "args": ["-y", "@microcharts/mcp"]
+    }
+  }
+}
+```
+
+That's it — the client spawns the server over stdio on demand.
+
+## Tools
+
+### `find_microchart(question, dataShape?)`
+
+Rank the catalog against a plain-language question. Start here when you know the question, not the chart.
+
+```
+find_microchart({ question: "is it trending?" })
+→ [{ slug: "sparkline", name: "Sparkline", why: "inline trend", dataShape: "number[]" }, …]
+```
+
+### `get_microchart(slug)`
+
+Everything needed to wire one chart: import paths, its props plus the shared props, data shape, best/avoid guidance, a
+copy-runnable example, and `sample` — that same example as JSON props, ready to pass straight to `render_microchart`.
+
+```
+get_microchart({ slug: "bullet" })
+→ {
+    staticImport: "@microcharts/react/bullet",
+    props: [...],
+    example: { code: "<Bullet value={72} target={80} bands={[50, 90]} title=\"Quota\" />" },
+    sample: { value: 72, target: 80, bands: [50, 90], title: "Quota" },
+    …
+  }
+```
+
+Every chart takes its own data shape — `number[]` for a sparkline, `{ label, value }[]` for a dot plot,
+`{ open, high, low, close }[]` for OHLC — so `sample` is the shortest path from "which chart" to "a render that works".
+
+### `render_microchart(type, data?, props?, format?)`
+
+Render to a finished, self-contained SVG plus its generated alt text. Pass the series as `data`; put other props
+(`value`, `target`, `curve`, `color`, `width`) in `props`.
+
+```
+render_microchart({ type: "sparkline", data: [132, 148, 141, 165, 159, 182] })
+→ {
+    svg: "<svg …><style>…</style>…</svg>",
+    summary: "Trending up 38%. Range 132 to 182. Last value 182.",
+    mimeType: "image/svg+xml", width: 80, height: 20
+  }
+```
+
+`format` is `"svg"` (default, styles embedded — drops into any surface) or `"bare"` (no CSS, for pages that already load
+`@microcharts/react/styles.css`).
+
+Missing or wrong-shaped data is rejected by name rather than passed through to React, so a caller gets
+`"dot-plot" needs \`data\`. Data shape: { label, value }[]. Call get_microchart("dot-plot") for a ready-to-render
+sample.` instead of a stack trace. Oversized payloads are refused too — a microchart is a word-sized mark.
+
+It also exposes two resources: `microcharts://catalog` (every chart + metadata) and `microcharts://agent-setup` (the
+prompt for wiring microcharts into a codebase).
+
+## Use it from the Vercel AI SDK
+
+The same three capabilities ship as AI-SDK tools (on the `/ai-sdk` subpath, so the core never pulls in `ai`):
+
+```ts
+import { microchartsTools } from "@microcharts/mcp/ai-sdk";
+import { streamText } from "ai";
+
+const result = streamText({
+  model,
+  tools: microchartsTools,
+  prompt: "Summarise this quarter and show the revenue trend as a chart.",
+});
+```
+
+The functions are exported directly too — `findChart`, `getChart`, `renderChart` — if you want them without the tool
+wrapper.
+
+## Versioning
+
+This server bundles the chart catalog and renders with `@microcharts/react` (installed as a normal dependency). Its
+version tracks its own changes; a compatible library is pulled in automatically. The library version a given snapshot
+was cut from is on the `microcharts://catalog` resource.
+
+## Links
+
+- Docs: <https://microcharts.dev/docs/mcp>
+- Library: [`@microcharts/react`](https://www.npmjs.com/package/@microcharts/react)
+- Source: <https://github.com/ganapativs/microcharts/tree/main/packages/mcp>
+
+MIT

package/dist/ai-sdk.d.mts

@@ -0,0 +1,10 @@
+import { ToolSet } from "ai";
+//#region src/ai-sdk.d.ts
+/**
+ * The same three capabilities as the MCP server, packaged as Vercel AI-SDK
+ * tools for apps built with the `ai` package: `import { microchartsTools }` and
+ * spread them into `streamText`/`generateText`. One core, two front doors.
+ */
+declare const microchartsTools: ToolSet;
+//#endregion
+export { microchartsTools };

package/dist/ai-sdk.mjs

@@ -0,0 +1,46 @@
+import { i as findChart, r as getChart, t as renderChart } from "./render-core-CnQfk-v1.mjs";
+import { z } from "zod";
+import { tool } from "ai";
+//#region src/ai-sdk.ts
+/**
+* The same three capabilities as the MCP server, packaged as Vercel AI-SDK
+* tools for apps built with the `ai` package: `import { microchartsTools }` and
+* spread them into `streamText`/`generateText`. One core, two front doors.
+*/
+const microchartsTools = {
+	find_microchart: tool({
+		description: "Find which microcharts chart type best answers a question about data (e.g. \"is it trending?\", \"error budget\", \"part to whole\"). Returns ranked candidates with the reason each matched. Call this first when you know the question but not the chart.",
+		inputSchema: z.object({
+			question: z.string().describe("What the data needs to show, in plain language."),
+			dataShape: z.string().optional().describe("Optional filter, e.g. \"number[]\" or \"{label,value}[]\"."),
+			limit: z.number().int().min(1).max(20).optional().describe("Max results (default 6).")
+		}),
+		execute: async ({ question, dataShape, limit }) => findChart(question, {
+			...dataShape ? { dataShape } : {},
+			...limit ? { limit } : {}
+		})
+	}),
+	get_microchart: tool({
+		description: "Get the full wiring detail for one chart by slug: import paths, its props plus the shared props, the data shape, best/avoid guidance, and a copy-runnable example. Call after find_microchart to scaffold the component.",
+		inputSchema: z.object({ slug: z.string().describe("Chart slug, e.g. \"sparkline\" or \"bullet\".") }),
+		execute: async ({ slug }) => getChart(slug) ?? { error: `Unknown chart "${slug}".` }
+	}),
+	render_microchart: tool({
+		description: "Render a chart to a finished, self-contained SVG string (styles embedded) plus its generated alt text — usable in any surface that can't run React. Pass the series as `data` and any other props (value, target, curve, color, width) in `props`; check get_microchart for the exact shape.",
+		inputSchema: z.object({
+			type: z.string().describe("Chart slug, e.g. \"sparkline\"."),
+			data: z.any().optional().describe("Primary series; omit for scalar charts."),
+			props: z.record(z.string(), z.any()).optional().describe("Other props (value, target, color, …)."),
+			format: z.enum(["svg", "bare"]).optional().describe("`svg` (default, self-contained) or `bare` (no embedded CSS).")
+		}),
+		execute: async (input) => {
+			try {
+				return await renderChart(input);
+			} catch (err) {
+				return { error: err.message };
+			}
+		}
+	})
+};
+//#endregion
+export { microchartsTools };

package/dist/cli.d.mts

@@ -0,0 +1 @@
+export {}

package/dist/cli.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { t as createServer } from "./server-C0ga2mbD.mjs";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+//#region src/cli.ts
+/**
+* The stdio entry point (`npx @microcharts/mcp`). A client (Claude Desktop,
+* Cursor, …) spawns this process and speaks MCP over stdin/stdout. Nothing is
+* hosted; it runs on the user's machine.
+*/
+async function main() {
+	await createServer().connect(new StdioServerTransport());
+}
+main().catch((err) => {
+	process.stderr.write(`microcharts-mcp: ${err.message}\n`);
+	process.exit(1);
+});
+//#endregion
+export {};

package/dist/index.d.mts

@@ -0,0 +1,190 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+//#region src/tools/find.d.ts
+interface FindResult {
+  slug: string;
+  name: string;
+  tagline: string;
+  dataShape: string;
+  /** Why this chart matched — the bestFor phrase or tagline that hit. */
+  why: string;
+}
+interface FindOptions {
+  /** Filter to charts whose dataShape contains this substring (e.g. "number[]"). */
+  dataShape?: string;
+  /** Max results (default 6). */
+  limit?: number;
+}
+/**
+ * Rank the catalog against a natural-language question ("is it trending?",
+ * "error budget", "part to whole"). Pure over the committed snapshot — no
+ * rendering, no library import. Returns only stable charts (the wireable set),
+ * best first; empty when nothing scores.
+ */
+declare function findChart(question: string, opts?: FindOptions): FindResult[];
+//#endregion
+//#region src/types.d.ts
+/**
+ * Local mirror of the catalog shapes the package consumes. Kept self-contained
+ * (not imported from the docs app) so the published package never reaches into
+ * `apps/docs`. The `catalog-sync` test guarantees `catalog.generated.json` still
+ * matches the live registry, so these types can't silently drift.
+ */
+interface ChartProp {
+  name: string;
+  type: string;
+  required: boolean;
+  description: string;
+  /** `true` ⇒ only on the `…/interactive` entry (callbacks, announce config). */
+  interactive?: boolean;
+}
+interface ChartEntry {
+  name: string;
+  slug: string;
+  status: "stable" | "planned";
+  collection: "core" | "decision" | "expressive" | "frontier";
+  variantOf?: string;
+  tagline: string;
+  staticImport: string;
+  interactiveImport?: string;
+  animates?: boolean;
+  picker?: false;
+  dataShape: string;
+  encoding: {
+    channel: string;
+    precision: string;
+  };
+  nodeBudget: string;
+  bestFor: string[];
+  avoidFor: string[];
+  props: ChartProp[];
+  /** Copy-runnable snippet — sample-data definitions already prepended. */
+  example: {
+    title: string;
+    code: string;
+  };
+  /**
+   * A ready-to-render JSON prop bag derived from `example` at generation time —
+   * what `render_microchart` actually takes. Present for every chart whose
+   * example is fully serializable; absent when the example is mostly callbacks.
+   */
+  sample?: Record<string, unknown>;
+}
+/** The committed snapshot: catalog data + the library version it was cut from. */
+interface Catalog {
+  /** `@microcharts/react` version this snapshot was generated from. */
+  library: string;
+  /** Shared grammar/layout/i18n props every chart accepts. */
+  sharedProps: ChartProp[];
+  charts: ChartEntry[];
+}
+//#endregion
+//#region src/tools/get.d.ts
+interface GetResult {
+  slug: string;
+  name: string;
+  tagline: string;
+  status: "stable" | "planned";
+  dataShape: string;
+  encoding: {
+    channel: string;
+    precision: string;
+  };
+  staticImport: string;
+  interactiveImport?: string;
+  bestFor: string[];
+  avoidFor: string[];
+  props: ChartProp[];
+  /** Grammar / layout / i18n props every chart accepts, in addition to `props`. */
+  sharedProps: ChartProp[];
+  /** Copy-runnable example: sample-data defs prepended to the snippet. */
+  example: {
+    title: string;
+    code: string;
+  };
+  /**
+   * The same example as a JSON prop bag — exactly what `render_microchart`
+   * takes. `example.code` is JSX for a human to paste; this is for a model to
+   * adapt. Absent only if the example is not fully serializable.
+   */
+  sample?: Record<string, unknown>;
+}
+/**
+ * Full wiring detail for one chart: import paths, its own props + the shared
+ * props, dataShape, best/avoid, and a copy-runnable example. Pure over the
+ * snapshot. Returns undefined for an unknown slug.
+ */
+declare function getChart(slug: string): GetResult | undefined;
+//#endregion
+//#region src/render-core.d.ts
+/**
+ * Render a static chart to a self-contained SVG string, using the real
+ * `@microcharts/react` static component (imported at runtime from the package's
+ * own dependency — carry model A). The default `svg` format embeds the shipped
+ * stylesheet so the mark renders correctly dropped into any surface with no
+ * external CSS; `bare` omits it for callers that already load `styles.css`.
+ *
+ * The `summary` is the chart's own generated accessible name (read back out of
+ * the rendered markup) — correct for every data shape, no assumption that the
+ * data is a number series.
+ *
+ * React and `react-dom/server` are imported lazily, inside the first render:
+ * a session that only calls `find` / `get` (and every consumer of the AI-SDK
+ * subpath that never renders) then never pays for loading them.
+ */
+type RenderFormat = "svg" | "bare";
+interface RenderResult {
+  /** The rendered mark. SVG for most charts; HTML for the few inline text marks
+   *  (delta, token-confidence) — see `mimeType`. */
+  svg: string;
+  /** `image/svg+xml` for SVG-rooted charts, `text/html` for inline text marks. */
+  mimeType: "image/svg+xml" | "text/html";
+  /** The chart's generated accessible name — its honest alt text. */
+  summary: string;
+  /** Pixel size for SVG-rooted charts; 0 for font-relative inline marks. */
+  width: number;
+  height: number;
+  /** The `@microcharts/react` version that produced this render. */
+  library: string;
+}
+interface RenderInput {
+  /** Chart slug, e.g. "sparkline". */
+  type: string;
+  /** Primary data — mapped to the `data` prop; omit for scalar charts. */
+  data?: unknown;
+  /** Any other props (e.g. `value`, `target`, `curve`, `color`, `width`). */
+  props?: Record<string, unknown> | undefined;
+  /** `svg` (default, self-contained) or `bare` (no embedded CSS). */
+  format?: RenderFormat | undefined;
+}
+declare function renderChart(input: RenderInput): Promise<RenderResult>;
+//#endregion
+//#region src/server.d.ts
+/**
+ * Build the microcharts MCP server: three tools (find / get / render) + two
+ * resources (the catalog, the agent-setup prompt). Transport-agnostic — `cli.ts`
+ * wires it to stdio; a remote host could wire the same server to Streamable HTTP
+ * without changing anything here.
+ */
+declare function createServer(): McpServer;
+//#endregion
+//#region src/catalog.d.ts
+/**
+ * The committed catalog snapshot, loaded once. `catalog.generated.json` is
+ * produced by `scripts/gen.ts` from the docs registry and guard-tested by
+ * `catalog-sync.test.ts`, so this is always in step with the shipped library.
+ */
+declare const catalog: Catalog;
+declare const CHARTS: ChartEntry[];
+/** The `@microcharts/react` version this snapshot was cut from (compat stamp). */
+declare const LIBRARY_VERSION: string;
+declare function getEntry(slug: string): ChartEntry | undefined;
+/** Only stable charts have a shipped subpath — the wireable/renderable set. */
+declare const STABLE_CHARTS: ChartEntry[];
+//#endregion
+//#region src/assets.generated.d.ts
+declare const AGENT_SETUP: string;
+//#endregion
+//#region src/version.d.ts
+declare const MCP_VERSION: string;
+//#endregion
+export { AGENT_SETUP, CHARTS, type Catalog, type ChartEntry, type ChartProp, type FindOptions, type FindResult, type GetResult, LIBRARY_VERSION, MCP_VERSION, type RenderFormat, type RenderInput, type RenderResult, STABLE_CHARTS, catalog, createServer, findChart, getChart, getEntry, renderChart };

package/dist/index.mjs

@@ -0,0 +1,3 @@
+import { a as CHARTS, c as catalog, i as findChart, l as getEntry, n as AGENT_SETUP, o as LIBRARY_VERSION, r as getChart, s as STABLE_CHARTS, t as renderChart } from "./render-core-CnQfk-v1.mjs";
+import { n as MCP_VERSION, t as createServer } from "./server-C0ga2mbD.mjs";
+export { AGENT_SETUP, CHARTS, LIBRARY_VERSION, MCP_VERSION, STABLE_CHARTS, catalog, createServer, findChart, getChart, getEntry, renderChart };