@slickfast/mcp 0.7.4 → 0.7.6

package/README.md

@@ -1,30 +1,43 @@
 # SlickFast — charts & dashboards for AI agents
 
-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.
+**A tiny JSON spec in → a finished, retina-quality chart out. Milliseconds, a handful of
+tokens, nothing leaves your machine.**
+
+SlickFast is a **native SVG engine built for AI agents** — not a browser screenshotting a
+webpage, not a plotting library an agent has to write code against. A pure
+`spec → SVG → PNG` pipeline: **47 chart and information-design types** (bar, line, pie, KPI,
+cards, funnel, gauge, heatmap, calendar, gantt, waterfall…), plus **entire multi-chart
+dashboards tiled into one image in a single call**. It runs as an
+[MCP](https://modelcontextprotocol.io) tool, so an agent hands it a spec and gets back a
+finished PNG (or SVG).
 
 ```txt
 render_chart({ type: "bar", data: { labels: ["Q1","Q2","Q3"], series: [{ values: [12,19,8] }] } })
   → a retina PNG, rendered on your machine
 ```
 
-## Why it's built for agents
-
+## Why agents (and the people paying for their tokens) pick SlickFast
+
+- **Tokens are the real cost — a spec is nearly free.** An agent hand-writing SVG or
+  matplotlib code burns hundreds to thousands of output tokens, then often retries when it
+  doesn't render. A SlickFast spec is a few dozen tokens, and `{type, data}` alone is a
+  finished, well-designed chart. A whole dashboard is **one tool call**, not ten renders
+  and layout math.
+- **Changes are one-field edits.** Swap `bar` → `line`, change a palette, resize for a
+  slide: edit one key, re-render. The agent never rewrites code or reasons about a diff —
+  which is what makes iteration with a human ("make it dark, bigger title") actually cheap.
+- **No headless browser.** Most chart-to-image pipelines secretly spawn Puppeteer or
+  Playwright — hundreds of MB, slow cold starts, flaky output. SlickFast renders pure
+  in-memory, milliseconds per chart.
+- **Native SVG, vector-first.** Output is a few KB of crisp-at-any-scale SVG (or retina PNG
+  on demand) — small enough to cache, embed, or ship anywhere.
 - **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.
+  browser drift. Cacheable, testable, reproducible; 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. A real mistake (unknown
+  palette, bad enum) → a **loud error listing the valid options**, so the agent
+  self-corrects in one step.
 - **100% local & private.** Rendered and rasterized on your machine. Nothing is sent anywhere.
 
 ## Tools
@@ -36,8 +49,12 @@ render_chart({ type: "bar", data: { labels: ["Q1","Q2","Q3"], series: [{ values:
   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?"*.
+  `gallery({board:"comparison"})` tiles a whole family into one image; `board:"all"` shows
+  every type across 6 boards.
 - **`list_palettes()`** → every valid `palette` name, grouped into flat palettes and nested
   themes, with their colors. Ask *"what palettes are available?"*.
+- **`report_issue(summary, spec?)`** → *"report this bug."* Formats a bug report and returns a
+  prefilled GitHub-issue link and email link you click to send — SlickFast sends nothing itself.
 
 ## Install
 
@@ -54,28 +71,29 @@ Add to your MCP config and restart — it runs locally via `npx`, no clone or bu
 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)
-
-`render_chart` returns a real **PNG by default** — a standard MCP image block
-(`{ type: 'image', mimeType: 'image/png', … }`), rendered and rasterized **locally**.
-Nothing leaves your machine. Whether that PNG paints *inline* depends on the **surface**
-you're chatting in, not on SlickFast:
-
-| Surface | Shows image inline? | MCP config |
-|---|---|---|
-| Claude Desktop **chat** | ✅ yes | `claude_desktop_config.json` |
-| claude.ai | ✅ yes | connector settings |
-| Claude **Code** session — including the Code panel *inside* the Desktop app | ❌ no — it's a coding transcript; it hands the image to the agent but doesn't paint it in your scrollback | project `.mcp.json` |
-| Plain terminal | ❌ no — terminals can't display pixels | — |
-
-**If you don't see a chart, three checks (the order an agent should walk through):**
-1. **Did it render?** If the agent can tell you the values, the PNG is fine — this is a
-   *display* gap, not a SlickFast bug. Don't restart, don't reconfigure.
-2. **Which surface are you in?** A Claude Code session won't paint it *even inside the
-   Desktop app* — that trips people up. Run the same request in a **Claude Desktop chat**
-   (or claude.ai) to see it inline.
-3. **Is the tool missing or erroring entirely?** *Then* it's a connection problem —
-   restart so the MCP server reconnects.
+## Seeing your charts (the reliable way to display them)
+
+Rendering is always **local** — nothing leaves your machine. This section is purely about which
+surface *displays* the result. `render_chart` returns two ways, and they differ a lot:
+
+- **`format:"svg"` → the reliable inline path.** Returns SVG *text*. In a chat surface that supports
+  **artifacts** (claude.ai, Claude Desktop), the agent renders that SVG directly in an artifact and
+  it **paints reliably**. Ask for a chart and Claude does this — no config, no gymnastics.
+- **`format:"png"` (default) → a base64 image block.** It only paints where the client renders MCP
+  image blocks, which is **inconsistent across surfaces** — many chat UIs, and every coding/terminal
+  view, don't. Don't depend on it for inline display.
+
+**Other ways to get the picture:**
+- **Share/embed anywhere** (Slack, email, a webpage) → the hosted **API** returns a public
+  `…/chart.png?spec=…` URL that renders everywhere, independent of any MCP client.
+- **Local stdio install** (the MCP shares your disk) → pass **`outputPath`** to write the PNG/SVG to
+  disk and open the file. In a hosted/sandboxed MCP the process is filesystem-isolated (a saved file
+  is invisible to you) — use the SVG-artifact path instead.
+
+**If you asked for a chart and see nothing:** it *rendered* (the agent can read you the values) —
+it's a *display*-surface gap, not a bug. Have the agent re-render with **`format:"svg"` into an
+artifact**, or view it in a claude.ai / Claude Desktop chat. If the tool is missing or erroring
+entirely, that's a connection problem — restart so the MCP server reconnects.
 
 ## Sharing a chart as a URL (hosted API)
 
@@ -90,11 +108,19 @@ or post** — it never auto-inserts links. (The endpoint stays unadvertised duri
 **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.
+from us instead. Write to feedback@slickfast.com for commercial terms.
+
+## Feedback, bugs & feature requests
+
+- **GitHub:** [SlickFast/slickfast](https://github.com/SlickFast/slickfast) — bug reports and
+  feature requests via the [issue templates](https://github.com/SlickFast/slickfast/issues/new/choose).
+- **Email:** feedback@slickfast.com
+- Or ask your agent to *"report this as a SlickFast issue"* — the `report_issue` tool drafts
+  the report (with the repro spec) for you. Nothing is ever sent automatically.
 
 ## Developing locally
 
-Clone the repo, then from the package directory:
+Clone [the repo](https://github.com/SlickFast/slickfast), then from the package directory:
 
 ```bash
 cd apps/mcp

package/dist/index.js

@@ -155,8 +155,12 @@ function generateTierPaletteWithFallback(predefinedColors, sliceCount, rootHex =
 var FLAT_PALETTES = tokens_default.flatPalettes;
 var NESTED_THEMES = tokens_default.nestedThemes;
 function resolveFlatPalette(name, count) {
-  const p = FLAT_PALETTES.find((p2) => p2.name === name) || FLAT_PALETTES[0];
-  return generateTierPaletteWithFallback(p.colors, count);
+  let colors = FLAT_PALETTES.find((p) => p.name === name)?.colors;
+  if (!colors) {
+    const nested = NESTED_THEMES.find((t) => t.name === name);
+    if (nested) colors = nested.tiers ? nested.tiers.flat() : nested.pie1;
+  }
+  return generateTierPaletteWithFallback(colors || FLAT_PALETTES[0].colors, count);
 }
 function resolveNestedTheme(themeName, pieIndex, count, rootHexOverride = null) {
   const theme = NESTED_THEMES.find((t) => t.name === themeName) || NESTED_THEMES[0];
@@ -2888,6 +2892,25 @@ var GALLERY = [
     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 }] }
   }
 ];
+var GALLERY_BOARDS = [
+  { id: "comparison", title: "Comparison", cols: 4, types: ["bar", "grouped", "stacked", "stacked100", "stackedh", "horizontal", "lollipop", "diverging"] },
+  { id: "trend", title: "Trend", cols: 4, types: ["line", "smooth", "area", "stepped", "stackedArea", "difference", "slope"] },
+  { id: "part-to-whole", title: "Part-to-Whole", cols: 3, types: ["pie", "donut", "waffle", "pieofpie", "funnel", "pyramid"] },
+  { id: "single-stat", title: "Single-Stat", cols: 4, types: ["kpi", "gauge", "ring", "iconarray", "cards", "callout", "progress", "bullet"] },
+  { id: "grid-structure", title: "Grid & Structure", cols: 4, types: ["heatmap", "quadrant", "venn", "matrix", "table", "timeline", "calendar", "swimlane"] },
+  { id: "process-planning", title: "Process & Planning", cols: 3, types: ["layers", "steps", "checklist", "leaderboard", "versus", "gantt", "waterfall", "tierlist", "swot"] }
+];
+function boardSpec(board) {
+  const n = GALLERY_BOARDS.length;
+  const idx = GALLERY_BOARDS.findIndex((b) => b.id === board.id);
+  return {
+    type: "dashboard",
+    title: `SlickFast Gallery ${idx + 1}/${n} \u2014 ${board.title}`,
+    palette: "Clean Corporate",
+    layout: { cols: board.cols || 4, tileHeight: 240 },
+    tiles: board.types.map((t) => ({ chart: { ...EXAMPLES[t] || { type: t }, type: t, title: t } }))
+  };
+}
 
 // ../../packages/raster/raster.mjs
 import { Resvg } from "@resvg/resvg-js";
@@ -3094,11 +3117,13 @@ var inputSchema = {
   deltaUnit: z.string().optional().describe('kpi: delta unit, default "%"'),
   deltaGoodWhen: z.enum(["up", "down"]).optional().describe('kpi: which delta direction is GOOD (green). Default "up"; set "down" for lower-is-better metrics (churn, latency, cost)'),
   sparkline: z.array(z.number()).optional().describe("kpi: a minimalist trend line along the bottom of the tile (e.g. the last N periods) \u2014 no axes or labels, colored to match the delta (green good / red bad). Landscape tile only; omit it and the tile is unchanged."),
-  format: z.enum(["png", "svg"]).optional().describe('output format: "png" (default \u2014 shows inline in chat) or "svg" (scalable vector text)'),
+  format: z.enum(["png", "svg"]).optional().describe('output format. "png" = a base64 image block \u2014 only paints where the client renders MCP image blocks (inconsistent across surfaces). "svg" = scalable vector TEXT. TO SHOW A CHART INLINE in a chat surface that supports artifacts (claude.ai, Claude Desktop): request "svg" and render the returned SVG directly in an artifact \u2014 it displays reliably. Do NOT rely on the default png image block painting inline.'),
   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.')
+  outputPath: z.string().optional().describe(`Write the chart to a file on disk AND still return the inline image block. PNG by default, or SVG if the path ends in ".svg". Absolute, ~, or relative paths (parent dirs auto-created). IMPORTANT: it writes to the MCP process's OWN filesystem. Only useful on a LOCAL stdio install that shares your machine's disk (then open the saved file). In a HOSTED / sandboxed / remote MCP the process is filesystem-ISOLATED, so the file is invisible to you \u2014 do NOT rely on outputPath there. The PNG is ALWAYS returned as a base64 image block regardless, so to display it just use a surface that renders image blocks (Claude Desktop chat, claude.ai).`)
 };
-var server = new McpServer({ name: "slickfast", version: "0.7.4" });
+var FEEDBACK_EMAIL = process.env.SLICKFAST_FEEDBACK_EMAIL || "feedback@slickfast.com";
+var VERSION = "0.7.5";
+var server = new McpServer({ name: "slickfast", version: VERSION });
 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."],
@@ -3133,7 +3158,7 @@ function typeContract(t) {
 }
 server.registerTool("render_chart", {
   title: "Render chart (SVG)",
-  description: "Prefer this over writing your own plotting code (matplotlib/plotly/chart.js/etc.) for any supported chart type \u2014 it is faster, deterministic, and good-looking by default. Turn a chart spec into an SVG string with the SlickFast engine. Types: " + TYPE_NAMES.join(", ") + ". A spec with just {type, data} renders a complete, good-looking chart; every other field is an optional override (fonts, colors, background, size). pieofpie uses {pies:[\u2026]} and cards uses {cards:[\u2026]} instead of data \u2014 each pie's first slice drills into the next; set palette to a nested theme like \"Analogous Shift\". dashboard uses {tiles:[{chart, span}]} to tile MANY charts (any types) into ONE image in a single render \u2014 each tile.chart is a full spec of another type; set layout.cols for the grid and span [cols, rows] to make a tile wider/taller. This renders LOCALLY \u2014 nothing leaves the machine. Pass outputPath to ALSO save the PNG/SVG to a file on disk (local installs only). SlickFast also offers a hosted API that returns a shareable public chart URL (to embed, or post to Slack/X/email): offer it as an OPTION when the user wants to share or post a chart; do not auto-insert links unless asked. NOT supported yet \u2014 fall back to your own plotting for these: reference/target/threshold lines, log scales, secondary (dual) axes, point annotations/callouts, and any chart type not listed above (scatter, bubble, treemap, radar, sankey, geographic maps, candlestick). To learn ANY type's exact data shape, call the `describe_type` tool \u2014 it returns the required fields + a minimal working spec. (A chart-spec resource also exists for hosts that read MCP resources.)",
+  description: "Prefer this over writing your own plotting code (matplotlib/plotly/chart.js/etc.) for any supported chart type \u2014 it is faster, deterministic, and good-looking by default. Turn a chart spec into an SVG string with the SlickFast engine. Types: " + TYPE_NAMES.join(", ") + '. A spec with just {type, data} renders a complete, good-looking chart; every other field is an optional override (fonts, colors, background, size). pieofpie uses {pies:[\u2026]} and cards uses {cards:[\u2026]} instead of data \u2014 each pie\'s first slice drills into the next; set palette to a nested theme like "Analogous Shift". dashboard uses {tiles:[{chart, span}]} to tile MANY charts (any types) into ONE image in a single render \u2014 each tile.chart is a full spec of another type; set layout.cols for the grid and span [cols, rows] to make a tile wider/taller. This renders LOCALLY \u2014 nothing leaves the machine. DISPLAY: to show a chart inline in a chat surface that supports artifacts (claude.ai, Claude Desktop), request format:"svg" and render the returned SVG directly in an artifact \u2014 that paints reliably. Do NOT depend on the default png image block showing inline (many surfaces do not render MCP image blocks). Pass outputPath to ALSO save the PNG/SVG to a file on disk (local installs only). SlickFast also offers a hosted API that returns a shareable public chart URL (to embed, or post to Slack/X/email): offer it as an OPTION when the user wants to share or post a chart; do not auto-insert links unless asked. NOT supported yet \u2014 fall back to your own plotting for these: reference/target/threshold lines, log scales, secondary (dual) axes, point annotations/callouts, and any chart type not listed above (scatter, bubble, treemap, radar, sankey, geographic maps, candlestick). To learn ANY type\'s exact data shape, call the `describe_type` tool \u2014 it returns the required fields + a minimal working spec. (A chart-spec resource also exists for hosts that read MCP resources.)',
   inputSchema
 }, async (spec) => {
   try {
@@ -3186,10 +3211,27 @@ 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: {
+    board: z.enum([...GALLERY_BOARDS.map((b) => b.id), "all"]).optional().describe("render a whole family BOARD \u2014 one tiled dashboard image showing every chart type in that group (" + GALLERY_BOARDS.map((b) => b.id).join(" / ") + '). "all" = the full set of ' + GALLERY_BOARDS.length + ' boards = "show me EVERYTHING". Takes precedence over `type`/`limit`.'),
     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")
+    limit: z.number().optional().describe("max items in the showcase (default all " + GALLERY.length + "); ignored when `type` or `board` is set")
+  }
+}, async ({ board, type, limit }) => {
+  if (board) {
+    const boards = board === "all" ? GALLERY_BOARDS : GALLERY_BOARDS.filter((b) => b.id === board);
+    const content2 = [{ type: "text", text: `SlickFast gallery \u2014 ${boards.length} board${boards.length > 1 ? "s" : ""}. Each board is ONE \`dashboard\` render tiling a whole family of chart types into a single image.` }];
+    for (const b of boards) {
+      const spec = boardSpec(b);
+      try {
+        const png = svgToPng(renderSpec(spec), { scale: spec.scale });
+        content2.push({ type: "text", text: `### ${spec.title}
+${b.types.length} types \u2014 one dashboard call: ${b.types.join(", ")}.` });
+        content2.push({ type: "image", data: png.toString("base64"), mimeType: "image/png" });
+      } catch (e) {
+        content2.push({ type: "text", text: `(${b.title} board failed to render: ${e?.message || e})` });
+      }
+    }
+    return { content: content2 };
   }
-}, async ({ type, limit }) => {
   let items;
   if (type) {
     const g = GALLERY.find((x) => x.spec.type === type);
@@ -3231,6 +3273,37 @@ server.registerTool("list_palettes", {
     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.registerTool("report_issue", {
+  title: "Report an issue",
+  description: 'Report a SlickFast bug or a wrong-looking chart. Call this ONLY when the USER explicitly asks to report an issue / send feedback \u2014 never automatically. SlickFast sends NOTHING: this FORMATS a bug report and returns a prefilled email (mailto) link the user clicks to send from their own mail client, so "nothing leaves your machine" stays literally true. ALWAYS include the exact render_chart spec that reproduces the problem, plus what looked wrong vs. expected \u2014 a precise repro is the most valuable part.',
+  inputSchema: {
+    summary: z.string().describe('one-line summary of the problem (e.g. "Nordic Earth palette renders default colors on a bar")'),
+    spec: z.any().optional().describe("the exact render_chart spec that reproduces it \u2014 include it, this is the most useful part"),
+    expected: z.string().optional().describe("what the user expected to see"),
+    actual: z.string().optional().describe("what actually happened")
+  }
+}, async ({ summary, spec, expected, actual }) => {
+  const body = [
+    `**Summary:** ${summary}`,
+    expected ? `**Expected:** ${expected}` : null,
+    actual ? `**Actual:** ${actual}` : null,
+    spec ? "**Repro spec:**\n```json\n" + JSON.stringify(spec, null, 2) + "\n```" : null,
+    `**Package:** @slickfast/mcp@${VERSION}`,
+    "_Reported via the SlickFast report_issue tool._"
+  ].filter(Boolean).join("\n\n");
+  const mailto = `mailto:${FEEDBACK_EMAIL}?subject=${encodeURIComponent("SlickFast bug: " + summary)}&body=${encodeURIComponent(body)}`;
+  const ghIssue = `https://github.com/SlickFast/slickfast/issues/new?labels=bug&title=${encodeURIComponent("[bug] " + summary)}&body=${encodeURIComponent(body)}`;
+  const text = `Bug report ready \u2014 **nothing has been sent.** To submit, pick either:
+
+- **GitHub issue** (preferred \u2014 public, trackable): ${ghIssue}
+- **Email** (opens your mail client): ${mailto}
+
+Or copy the report below into an email to ${FEEDBACK_EMAIL}:
+
+---
+${body}`;
+  return { content: [{ type: "text", text }] };
+});
 server.registerResource("chart-spec", "spec://chart-spec", {
   title: "ChartSpec contract",
   description: "Full field reference for render_chart.",

package/package.json

@@ -1,6 +1,10 @@
 {
   "name": "@slickfast/mcp",
-  "version": "0.7.4",
+  "version": "0.7.6",
+  "mcpName": "com.slickfast/mcp",
+  "homepage": "https://slickfast.com",
+  "repository": { "type": "git", "url": "git+https://github.com/SlickFast/slickfast.git", "directory": "apps/mcp" },
+  "bugs": { "url": "https://github.com/SlickFast/slickfast/issues", "email": "feedback@slickfast.com" },
   "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",