@slickfast/mcp 0.7.2 → 0.7.4

package/README.md

@@ -1,37 +1,58 @@
-# SlickFast MCP server
+# SlickFast — charts & dashboards for AI agents
 
-Exposes the render-core engine as an MCP tool so an AI agent can generate charts.
+SlickFast turns a small JSON spec into a polished, retina-quality chart — **47 chart and
+information-design types** (bar, line, pie, KPI, cards, funnel, gauge, heatmap, calendar,
+gantt, waterfall…), plus **multiple charts tiled into a single dashboard image in one call**.
+It runs as an [MCP](https://modelcontextprotocol.io) tool, so an AI agent hands it a spec and
+gets back a finished PNG (or SVG). Everything renders **locally** — nothing leaves your machine.
 
-- **Tool:** `render_chart(spec)` → returns the chart as an SVG string. Spec contract
-  is in `../../packages/render-core/SPEC.md` (also served as the `chart-spec` resource).
-- **Transport:** stdio (local). Streamable HTTP (remote/hosted, e.g. Railway) comes later.
-
-## Run / test
-```bash
-npm install
-node test-client.mjs   # spawns the server, calls render_chart, checks the SVG
+```txt
+render_chart({ type: "bar", data: { labels: ["Q1","Q2","Q3"], series: [{ values: [12,19,8] }] } })
+  → a retina PNG, rendered on your machine
 ```
 
-## Use it in Claude Desktop
-Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):
-```json
-{
-  "mcpServers": {
-    "slickfast": {
-      "command": "node",
-      "args": ["/Users/alexmacbook/SlickFast/platform/apps/mcp/server.mjs"]
-    }
-  }
-}
-```
-Restart Claude Desktop, then ask it to "render a bar chart of …" — it calls `render_chart`.
+## Why it's built for agents
+
+- **Deterministic — same spec, same bytes, forever.** No randomness, no timestamps, no
+  headless-browser drift. Outputs are **cacheable, testable, and reproducible**, with zero
+  flaky pixel diffs. Almost no charting tool can promise this — and it's exactly what a
+  tool-calling agent needs.
+- **Never throws garbage at the model.** Empty data, a bad tile, a filtered-to-nothing series →
+  a clean, graceful frame, not a crash or a stack trace. Reliability is a feature when the
+  caller is an agent, not a human who can eyeball the error.
+- **Fails loud on real mistakes.** An unknown palette or enum is *rejected* with a clear error
+  listing the valid options — so the agent fixes it immediately instead of silently shipping the
+  wrong-looking chart.
+- **Good-looking by default.** A spec of just `{type, data}` renders a complete, well-designed
+  chart; fonts, colors, palettes, and size are optional overrides.
+- **100% local & private.** Rendered and rasterized on your machine. Nothing is sent anywhere.
+
+## Tools
+
+- **`render_chart(spec)`** → the chart as a PNG image (default) or SVG (`format: "svg"`). For a
+  dashboard, pass `type: "dashboard"` with `tiles: [{ chart, span }]` — each tile is a full spec
+  of any other type, composited into one image in a single render.
+- **`describe_type(type)`** → the exact data shape, a minimal working spec, and per-type
+  gotchas. Call it first when you're unsure how to structure a type.
+- **`gallery()`** → a curated demo gallery of example charts and dashboards — each as a
+  rendered image plus its spec. Just ask *"show me a demo"* or *"what can you make?"*.
+- **`list_palettes()`** → every valid `palette` name, grouped into flat palettes and nested
+  themes, with their colors. Ask *"what palettes are available?"*.
+
+## Install
+
+Add to your MCP config and restart — it runs locally via `npx`, no clone or build needed:
 
-## Use it in Claude Code
-Project-scoped config (`.mcp.json` at the workspace root):
 ```json
-{ "mcpServers": { "slickfast": { "command": "node", "args": ["/Users/alexmacbook/SlickFast/platform/apps/mcp/server.mjs"] } } }
+{ "mcpServers": { "slickfast": { "command": "npx", "args": ["-y", "@slickfast/mcp"] } } }
 ```
-Restart the session; the `render_chart` tool becomes available.
+
+- **Claude Desktop** — `claude_desktop_config.json` (Settings → Developer → Edit Config)
+- **Claude Code** — project `.mcp.json` at the workspace root
+- **claude.ai** — connector settings
+
+Then ask it to *"render a bar chart of last quarter's revenue"* or *"build a dashboard with an
+MRR tile, a signups funnel, and a usage heatmap."*
 
 ## Seeing your charts (why an image might not show inline)
 
@@ -64,14 +85,22 @@ embedding, posting to Slack/X/email, or getting a chart into a surface that can'
 local image (see the table above). The agent should **offer this only when you ask to share
 or post** — it never auto-inserts links. (The endpoint stays unadvertised during soft-launch.)
 
-## Install via npm (published)
-```json
-{ "mcpServers": { "slickfast": { "command": "npx", "args": ["-y", "@slickfast/mcp"] } } }
-```
-Restart Claude; everything runs locally on your machine — nothing leaves.
-
 ## License
+
 **AGPL-3.0-only.** Free to use, self-host, and embed under the AGPL's terms (your friends
 running it locally are completely unaffected). Building it into a **closed-source product
 or a hosted service**? That needs the AGPL'd source opened — or a **commercial license**
 from us instead. Reach out for commercial terms.
+
+## Developing locally
+
+Clone the repo, then from the package directory:
+
+```bash
+cd apps/mcp
+npm install
+node test-client.mjs   # spawns the server, calls render_chart, checks the output
+```
+
+To point an MCP client at a local checkout instead of the published package, use
+`"command": "node", "args": ["<path-to-clone>/apps/mcp/server.mjs"]`.

package/dist/index.js

@@ -786,7 +786,7 @@ function renderKpi(spec) {
   const fs = spec.fontSize ? Number(spec.fontSize) : Math.max(13, Math.round(13 * Math.sqrt(W * H) / 600));
   const font = resolveFont(spec);
   const watermark = spec.watermark !== false;
-  const accent = resolveFlatPalette(spec.palette || "Clean Corporate", 1)[0];
+  const accent = spec.color || resolveFlatPalette(spec.palette || "Clean Corporate", 1)[0];
   const labelCol = txt(spec, isDark ? "#94a3b8" : "#64748b");
   const valueCol = txt(spec, isDark ? "#f1f5f9" : "#0f172a");
   const faint = isDark ? "#475569" : "#94a3b8";
@@ -2002,7 +2002,9 @@ function renderTable(spec) {
       const v = cells[ci];
       if (v === void 0 || v === null || v === "") continue;
       const num = ci > 0 && isNum(v);
-      const out = num ? fmt(Number(v)) : String(v);
+      const nv = Number(v);
+      const yearLike = num && Number.isInteger(nv) && nv >= 1900 && nv <= 2100;
+      const out = num ? yearLike ? String(nv) : fmt(nv) : String(v);
       p.push(`<text x="${r(cellX(ci, num))}" y="${r(y + ROWH / 2 + 4)}" ${num ? 'text-anchor="end" ' : ""}font-size="${fs}"${wOpt(spec)} fill="${cellCol}">${esc(out)}</text>`);
     }
   });
@@ -2845,6 +2847,47 @@ var EXAMPLES = {
   swot: { type: "swot", cells: [{ title: "Strengths", items: ["Fast", "Cheap"] }, { title: "Weaknesses", items: ["New brand"] }, { title: "Opportunities", items: ["AI demand"] }, { title: "Threats", items: ["Incumbents"] }] },
   dashboard: { type: "dashboard", title: "Overview", layout: { cols: 2 }, tiles: [{ chart: { type: "kpi", label: "Revenue", value: 128400, valuePrefix: "$", delta: 12.4 } }, { chart: { type: "kpi", label: "Users", value: 8640, delta: 8.1 } }, { span: [2, 1], chart: { type: "bar", data: { labels: ["A", "B", "C"], series: [{ name: "Sales", values: [8, 5, 3] }] } } }] }
 };
+var GALLERY = [
+  {
+    name: "Dashboard \u2014 SaaS business review",
+    blurb: "Nine charts tiled into one image in a single render.",
+    spec: { type: "dashboard", title: "Acme \u2014 Monthly Business Review", palette: "Clean Corporate", layout: { cols: 3, tileHeight: 250 }, tiles: [
+      { chart: { type: "kpi", label: "Monthly Recurring Revenue", value: 128400, valuePrefix: "$", delta: 12.4 } },
+      { chart: { type: "kpi", label: "Active Users", value: 8640, delta: 8.1 } },
+      { chart: { type: "kpi", label: "Churn", value: 2.3, valueUnit: "%", delta: -0.4, deltaUnit: "pt", deltaGoodWhen: "down" } },
+      { span: [2, 1], chart: { type: "line", title: "Monthly active users", data: { labels: ["Jan", "Feb", "Mar", "Apr", "May", "Jun"], series: [{ name: "Product A", values: [120, 190, 170, 250, 230, 310] }, { name: "Product B", values: [80, 110, 160, 140, 210, 260] }] } } },
+      { chart: { type: "gauge", title: "Net revenue retention", value: 112, min: 0, max: 150, valueUnit: "%" } },
+      { chart: { type: "funnel", title: "Signup funnel", stages: [{ label: "Visitors", value: 12e3 }, { label: "Signups", value: 4200 }, { label: "Trials", value: 1800 }, { label: "Paid", value: 640 }] } },
+      { chart: { type: "waffle", title: "Revenue by segment", parts: [{ label: "Enterprise", value: 45 }, { label: "SMB", value: 30 }, { label: "Other", value: 15 }] } },
+      { chart: { type: "bar", title: "Deals by stage", data: { labels: ["Lead", "Demo", "Won"], series: [{ name: "Deals", values: [42, 24, 11] }] } } }
+    ] }
+  },
+  {
+    name: "Line \u2014 trend over time",
+    blurb: "Multi-series line with legend.",
+    spec: { type: "line", title: "Monthly active users", data: { labels: ["Jan", "Feb", "Mar", "Apr", "May", "Jun"], series: [{ name: "Product A", values: [120, 190, 170, 250, 230, 310] }, { name: "Product B", values: [80, 110, 160, 140, 210, 260] }] } }
+  },
+  {
+    name: "Donut \u2014 part of whole",
+    blurb: "Composition with a center total.",
+    spec: { type: "donut", title: "Market share", data: { labels: ["Us", "Rival A", "Rival B", "Other"], series: [{ values: [38, 27, 20, 15] }] } }
+  },
+  {
+    name: "Funnel \u2014 conversion",
+    blurb: "Stages narrowing top \u2192 bottom with %.",
+    spec: { type: "funnel", title: "Signup funnel", stages: [{ label: "Visitors", value: 12e3 }, { label: "Signups", value: 4200 }, { label: "Trials", value: 1800 }, { label: "Paid", value: 640 }] }
+  },
+  {
+    name: "Heatmap \u2014 a grid of values",
+    blurb: "Value \u2192 color intensity.",
+    spec: { type: "heatmap", title: "Active users by day & time", rows: ["Mon", "Tue", "Wed", "Thu", "Fri"], columns: ["9a", "12p", "3p", "6p", "9p"], values: [[2, 5, 8, 3, 1], [1, 4, 9, 6, 2], [0, 3, 7, 8, 4], [2, 6, 9, 7, 3], [3, 7, 6, 4, 5]] }
+  },
+  {
+    name: "Waterfall \u2014 running total",
+    blurb: "Signed steps to a final total.",
+    spec: { type: "waterfall", title: "Cash flow", start: 120, steps: [{ label: "Sales", value: 80 }, { label: "Refunds", value: -18 }, { label: "Costs", value: -42 }, { label: "Other", value: 12 }] }
+  }
+];
 
 // ../../packages/raster/raster.mjs
 import { Resvg } from "@resvg/resvg-js";
@@ -3055,7 +3098,23 @@ var inputSchema = {
   scale: z.number().optional().describe("png pixel-density multiplier (default 2 = retina)"),
   outputPath: z.string().optional().describe('LOCAL save: write the rendered chart to this file on disk AND still return the inline image. PNG by default, or SVG if the path ends in ".svg". Accepts absolute, ~, or relative paths (parent dirs auto-created). Works on a local stdio install only \u2014 a hosted/remote server has no access to your disk.')
 };
-var server = new McpServer({ name: "slickfast", version: "0.7.2" });
+var server = new McpServer({ name: "slickfast", version: "0.7.4" });
+var GOTCHAS = {
+  gantt: ["start/end are timeline positions; the axis spans min(start)\u2026max(end), so a non-zero-based timeline (years, offset quarters) fills the plot correctly."],
+  diverging: ["needs 2 series \u2014 series A is forced positive (up), series B negative (down), regardless of stored sign."],
+  difference: ["needs 2 series; the gap between them is shaded."],
+  kpi: ["sparkline is landscape-only (omit it in portrait).", "the accent bar follows the palette \u2014 pass `color` to fix it."],
+  waffle: ["values are cell counts out of a 10\xD710 grid (100 total); a single part renders as one % gauge."],
+  heatmap: ["`values` is a 2D matrix values[row][col]; `rows` and `columns` are the axis labels."],
+  stacked: ["each ROW is a stack segment shared across every bar; segment color comes from the row, not the series."],
+  stacked100: ["each bar sums to 100%; each row is a shared segment."],
+  pieofpie: ['uses `pies:[\u2026]`, not `data`; each pie\u2019s first slice ("bridge") drills into the next.'],
+  gauge: ["`value` is clamped to [min,max]; set min/max to your scale (default 0\u2013100)."],
+  bullet: ["`bands` are qualitative thresholds on the measure scale; `target` draws the comparison marker."],
+  calendar: ['`days` maps "YYYY-MM-DD" \u2192 value; weekday is computed deterministically (no clock/Date).'],
+  dashboard: ["each tile.chart is a full spec of any other type; tiles keep their OWN scale \u2014 for a shared-scale comparison use one grouped/multi-series chart, not side-by-side tiles."],
+  table: ["year-like integers (1900\u20132100) are shown without thousands separators; other numbers get them."]
+};
 function typeContract(t) {
   const meta = TYPES.find((x) => x.type === t);
   if (!meta) return null;
@@ -3067,6 +3126,8 @@ function typeContract(t) {
     needsData: meta.needsData,
     honorsToggles: TYPE_TOGGLES[t] || [],
     // which of showValues/showTotal/showPoints this type uses (others are ignored)
+    gotchas: GOTCHAS[t] || [],
+    // non-obvious per-type rules (else discovered by rendering twice)
     example: EXAMPLES[t] || null
   };
 }
@@ -3121,6 +3182,55 @@ server.registerTool("describe_type", {
   const all = TYPES.map((t) => ({ type: t.type, family: t.family, summary: t.summary }));
   return { content: [{ type: "text", text: JSON.stringify({ count: all.length, types: all, hint: "call describe_type with a `type` for its fields + a minimal spec" }, null, 2) }] };
 });
+server.registerTool("gallery", {
+  title: "Gallery / demo",
+  description: 'Render a curated DEMO GALLERY of example charts and dashboards. Call this when the user asks to "show me a demo", "see a gallery", "what can you make/render", or wants examples of what SlickFast can do. Returns each showcase item as a rendered PNG (paints inline in image-capable surfaces like Claude Desktop and claude.ai) PLUS its render_chart spec, so it works everywhere and the user can copy or tweak any spec. Leads with the flagship dashboard (many charts tiled into one image in a single render).',
+  inputSchema: {
+    type: z.enum(TYPE_NAMES).optional().describe('render just this ONE type (its showcase spec, or its minimal example) \u2014 for "show me a <type>"; omit for the curated multi-type showcase'),
+    limit: z.number().optional().describe("max items in the showcase (default all " + GALLERY.length + "); ignored when `type` is set")
+  }
+}, async ({ type, limit }) => {
+  let items;
+  if (type) {
+    const g = GALLERY.find((x) => x.spec.type === type);
+    items = [{ name: type, blurb: g ? g.blurb : `Example ${type} chart.`, spec: g ? g.spec : EXAMPLES[type] }];
+  } else {
+    items = GALLERY.slice(0, limit && limit > 0 ? limit : GALLERY.length);
+  }
+  const content = [{ type: "text", text: `SlickFast gallery \u2014 ${items.length} example${items.length > 1 ? "s" : ""}. Each is one render_chart call; the spec is shown under it.` }];
+  for (const it of items) {
+    try {
+      const png = svgToPng(renderSpec(it.spec), { scale: 2 });
+      content.push({ type: "text", text: `### ${it.name}
+${it.blurb}
+\`\`\`json
+${JSON.stringify(it.spec)}
+\`\`\`` });
+      content.push({ type: "image", data: png.toString("base64"), mimeType: "image/png" });
+    } catch (e) {
+      content.push({ type: "text", text: `(${it.name} failed to render: ${e?.message || e})` });
+    }
+  }
+  return { content };
+});
+server.registerTool("list_palettes", {
+  title: "List palettes",
+  description: 'List every valid `palette` name, grouped into FLAT palettes (great for any chart) and NESTED themes (designed for pieofpie drill-downs, but accepted on any chart), each with its representative colors. Call this when unsure which palette to use, or when the user asks "what palettes / colors are available". Any name returned here is a valid `palette` value \u2014 anything else is rejected.',
+  inputSchema: {}
+}, async () => {
+  const flat = FLAT_PALETTES.map((p) => ({ name: p.name, colors: p.colors }));
+  const nested = NESTED_THEMES.map((t) => ({
+    name: t.name,
+    anchor: t.tiers && t.tiers[0] && t.tiers[0][0] || t.pie1 && t.pie1[0] || null,
+    colors: (t.tiers ? t.tiers.flat() : t.pie1) || [],
+    dark: !!t.dark
+  }));
+  return { content: [{ type: "text", text: JSON.stringify({
+    flat,
+    nested,
+    hint: 'pass any name as `palette`. Flat is the default for most charts; nested themes shine on pieofpie. "dark: true" themes assume a dark background.'
+  }, null, 2) }] };
+});
 server.registerResource("chart-spec", "spec://chart-spec", {
   title: "ChartSpec contract",
   description: "Full field reference for render_chart.",

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@slickfast/mcp",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "description": "SlickFast — render 47 chart & info-design types (bar, line, pie, KPI, cards, funnel, matrix, gauge, calendar…) plus multi-chart dashboards tiled into one image, as SVG/PNG via MCP. Local and deterministic; nothing leaves your machine.",
+  "keywords": ["mcp", "model-context-protocol", "chart", "charts", "dashboard", "data-visualization", "svg", "png", "ai", "agent", "claude", "llm", "deterministic"],
   "license": "AGPL-3.0-only",
   "type": "module",
   "bin": { "slickfast-mcp": "dist/index.js" },