@slickfast/mcp 0.7.2 → 0.7.3

package/README.md

@@ -1,37 +1,54 @@
-# 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.
+
+## 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 +81,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>`);
     }
   });
@@ -3055,7 +3057,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.3" });
+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 +3085,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
   };
 }

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@slickfast/mcp",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "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" },