@grampro/kit 2.4.3 → 2.4.4

package/README.md

@@ -90,6 +90,18 @@ In this repository:
 | [`docs/grid-agent-evaluation.md`](docs/grid-agent-evaluation.md) | the 230-case corpus and how a model gets measured against it |
 | [`docs/agent-native-architecture.md`](docs/agent-native-architecture.md) | where this is going, and which parts are still proposal |
 
+## MCP server (beta)
+
+For agents that speak MCP, the catalogue is also served on demand:
+
+```bash
+claude mcp add grampro -- npx -y @grampro/kit mcp
+```
+
+It reads a Figma design, installs what it needs, answers what exists, each component's full contract, working examples, and
+whether the JSX an agent just wrote actually matches the component it used.
+No dependencies, no configuration. See `tools/mcp/README.md`.
+
 ## Agent skill
 
 Install the skill once per project so a coding agent uses these components

package/index.cjs

@@ -1171,7 +1171,7 @@ const validateComponents = (components, beta = false) => {
  * projects a week install this; breaking their scripts to tidy an argument
  * parser is not a trade worth making.
  */
-const COMMANDS = new Set(["add", "list", "skill", "passport"]);
+const COMMANDS = new Set(["add", "list", "skill", "passport", "mcp"]);
 
 /**
  * Flags that take a separate value, so the token after one is that value and
@@ -1274,6 +1274,7 @@ const main = async () => {
     .example("$0 passport --check", "Fail if a passport is stale (CI)")
     .example("$0 add Select --legacy", "Install from the 1.x set")
     .example("$0 add Button --dest app/ui", "Choose where they go")
+    .example("$0 mcp", "Serve the catalogue to a coding agent over MCP")
     .example("$0 -i", "Interactive selection")
     .help().argv;
 
@@ -1291,6 +1292,12 @@ const main = async () => {
     );
   }
 
+  if (parsed && parsed.command === "mcp") {
+    // Speaks JSON-RPC on stdout; nothing else may write there.
+    require("./tools/mcp/server.cjs").main();
+    return;
+  }
+
   if (parsed) {
     if (parsed.command === "list") argv.list = true;
     if (parsed.command === "skill") argv.skill = true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grampro/kit",
-  "version": "2.4.3",
+  "version": "2.4.4",
   "description": "GramproKit \u2014 an agent-native UI runtime for React. Copy-in components you own, each publishing a contract that software can read.",
   "type": "module",
   "files": [

package/source/components/accordion/passport.json

@@ -10,7 +10,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.3",
+    "libraryVersion": "2.4.4",
     "files": [
       "core/index.ts",
       "core/open.ts",

package/source/components/alert/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.3",
+    "libraryVersion": "2.4.4",
     "files": [
       "core/index.ts",
       "core/live.ts",

package/source/components/avatar/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.3",
+    "libraryVersion": "2.4.4",
     "files": [
       "core/identity.ts",
       "core/index.ts",

package/source/components/badge/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.3",
+    "libraryVersion": "2.4.4",
     "files": [
       "core/count.ts",
       "core/index.ts",

package/source/components/breadcrumb/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.3",
+    "libraryVersion": "2.4.4",
     "files": [
       "core/index.ts",
       "core/trail.ts",

package/source/components/button/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.3",
+    "libraryVersion": "2.4.4",
     "files": [
       "core/index.ts",
       "core/state.ts",

package/source/components/card/passport.json

@@ -12,7 +12,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.3",
+    "libraryVersion": "2.4.4",
     "files": [
       "core/index.ts",
       "core/trend.ts",

package/source/components/checkbox/passport.json

@@ -10,7 +10,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.3",
+    "libraryVersion": "2.4.4",
     "files": [
       "core/group.ts",
       "core/index.ts",

package/source/components/combobox/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.3",
+    "libraryVersion": "2.4.4",
     "files": [
       "core/filter.ts",
       "core/index.ts",

package/source/components/data-grid/passport.json

@@ -14,7 +14,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.3",
+    "libraryVersion": "2.4.4",
     "files": [
       "agent/coerce.ts",
       "agent/contract.ts",

package/source/components/date-picker/passport.json

@@ -10,7 +10,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.3",
+    "libraryVersion": "2.4.4",
     "files": [
       "core/calendar.ts",
       "core/format.ts",

package/source/components/dialog/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.3",
+    "libraryVersion": "2.4.4",
     "files": [
       "core/api.ts",
       "core/dialog.ts",

package/source/components/file-uploader/passport.json

@@ -13,7 +13,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.3",
+    "libraryVersion": "2.4.4",
     "files": [
       "core/format.ts",
       "core/index.ts",

package/source/components/input/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.3",
+    "libraryVersion": "2.4.4",
     "files": [
       "core/count.ts",
       "core/index.ts",

package/source/components/menu/passport.json

@@ -16,7 +16,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.3",
+    "libraryVersion": "2.4.4",
     "files": [
       "core/index.ts",
       "core/navigation.ts",

package/source/components/modal/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.3",
+    "libraryVersion": "2.4.4",
     "files": [
       "core/dismiss.ts",
       "core/index.ts",

package/source/components/number-input/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.3",
+    "libraryVersion": "2.4.4",
     "files": [
       "core/format.ts",
       "core/index.ts",

package/source/components/popover/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.3",
+    "libraryVersion": "2.4.4",
     "files": [
       "core/index.ts",
       "core/types.ts",

package/source/components/progress/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.3",
+    "libraryVersion": "2.4.4",
     "files": [
       "core/index.ts",
       "core/progress.ts",

package/source/components/radio-group/passport.json

@@ -10,7 +10,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.3",
+    "libraryVersion": "2.4.4",
     "files": [
       "core/group.ts",
       "core/index.ts",

package/source/components/skeleton/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.3",
+    "libraryVersion": "2.4.4",
     "files": [
       "core/index.ts",
       "core/lines.ts",

package/source/components/spinner/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.3",
+    "libraryVersion": "2.4.4",
     "files": [
       "core/index.ts",
       "core/types.ts",

package/source/components/switch/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.3",
+    "libraryVersion": "2.4.4",
     "files": [
       "core/index.ts",
       "core/toggle.ts",

package/source/components/tabs/passport.json

@@ -12,7 +12,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.3",
+    "libraryVersion": "2.4.4",
     "files": [
       "core/index.ts",
       "core/navigation.ts",

package/source/components/textarea/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.3",
+    "libraryVersion": "2.4.4",
     "files": [
       "core/count.ts",
       "core/index.ts",

package/source/components/toaster/passport.json

@@ -11,7 +11,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.3",
+    "libraryVersion": "2.4.4",
     "files": [
       "core/api.ts",
       "core/index.ts",

package/source/components/tooltip/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.4.3",
+    "libraryVersion": "2.4.4",
     "files": [
       "core/index.ts",
       "core/types.ts",

package/tools/mcp/README.md

@@ -0,0 +1,132 @@
+# GramproKit MCP server — beta
+
+Serves the component catalogue to a coding agent, so it writes against the
+real contract instead of recalling one.
+
+> **Beta.** The tools work and are tested, but their names and shapes may
+> change before this settles. The Figma token handling in particular is not
+> where it should be — see *Credentials* below.
+
+```bash
+claude mcp add grampro -- npx -y @grampro/kit mcp
+```
+
+Codex, Cursor and anything else that speaks MCP take the same command; it is
+a stdio server with no configuration. Without the CLI, write `.mcp.json` in
+your project:
+
+```json
+{
+  "mcpServers": {
+    "grampro": {
+      "command": "node",
+      "args": ["node_modules/@grampro/kit/index.cjs", "mcp"]
+    }
+  }
+}
+```
+
+MCP servers are not invoked by name. There is no `/grampro`; the model calls
+the tools itself when they are relevant. Use `/mcp` to check the server is
+connected.
+
+## Why
+
+An agent asked to build a page has two ways to learn a component's API: read
+the source, which costs a great deal of context and still invites invention,
+or be told. This tells it — one component at a time, from the passport that
+was generated from the source and so cannot drift from it.
+
+The catalogue is 280 KB of passports. A page needs two or three components,
+which is a few KB. That difference is the whole argument for a server over a
+document pasted into the prompt.
+
+## Tools
+
+| tool | what it answers |
+| --- | --- |
+| `list_components` | What exists, and what each one is for |
+| `get_component` | Props with types and allowed values, which are required, handler signatures, slots, states, composition rules |
+| `get_example` | Working usage from the component's README |
+| `get_guidance` | Authored notes on forms, overlays, the grid, pickers, styling, accessibility |
+| `figma_frame` | A design's structure, text, repeated regions and theme variables |
+| `install_component` | Copies components into the project being worked in |
+| `validate_usage` | Whether the JSX an agent wrote matches the passports |
+
+`validate_usage` is the one that earns its place. In the experiment that
+justified building this, a page written from passports alone compiled on the
+first attempt apart from a single prop the model had remembered from
+elsewhere rather than read here. Every type, union value and handler
+signature the passport carried came out right. So the remaining failure is
+invention, and this catches it:
+
+```
+<Alert variant="info" title="Hi" dismissible onDismiss={…} />
+
+  dismissible — not a prop of this component. Did you mean: onDismiss
+```
+
+## From a Figma design
+
+Two routes, and the second needs no credentials.
+
+**By URL.** Pass a `figma.com/design/...` link. Called with just the URL it
+lists the frames in the file; called again with `frame` it returns that
+screen. Needs a token.
+
+**By plugin export.** In Figma, run **Grampro Kit → Export selection for an
+agent**, then pass the JSON as `design`. The plugin reads the scene graph
+directly, so this works on any file you can open and asks for no token at
+all.
+
+Either way the answer is the same shape: the structure, the text, the
+regions whose names repeat — eight `Status cell` nodes are a column — and
+the `--gbs-*` variables the design's own colours and radii map onto.
+
+It does not decide which component each region is. A design drawn without
+the component library has no component instances to look up, so that call is
+inference, and an agent holding the catalogue and the designer's own names
+infers better than string matching in a tool. What is not a kit component is
+reported as such rather than approximated.
+
+Colours are given roles rather than ranked. The most-used colour in a design
+is the body text, and a near-black navy scores high on saturation, so both
+"most common" and "most saturated" pick the wrong thing. Lightness and
+saturation together find the accent.
+
+## Credentials
+
+**This is the weakest part of the current design, and it is temporary.**
+
+The URL route reads `FIGMA_TOKEN` from the environment, or from a `.env`
+file beside the project. That means a long-lived credential sitting in a
+file, which is not where it belongs.
+
+A future release will keep it in the editor's own secret storage — VS Code's
+`SecretStorage` for the extension, and the equivalent elsewhere — so the
+token is held by the host rather than the repository. Until then:
+
+- prefer the plugin export route, which needs no token at all;
+- if you do use a token, give it only `File content: read`;
+- keep `.env` out of version control.
+
+## Suggested use
+
+Tell the agent to call `get_component` before writing JSX for a component,
+and `validate_usage` on what it wrote before reporting back. Both are cheap,
+and together they close the gap between code that looks right and code that
+compiles.
+
+## Notes
+
+No dependencies. MCP is newline-delimited JSON-RPC over stdio, which is a
+few hundred lines, and a server shipped inside a library that every consumer
+installs should not drag an SDK along with it.
+
+The catalogue it serves is the one in this package, not the components
+copied into your project — so an agent can see a component before you
+install it, and `install_component` puts it in place.
+
+A Figma file is fetched once and held for five minutes. The natural flow is
+two calls, list then read, and refetching a large file in between is what
+earns a rate limit.

package/tools/mcp/figma.cjs

@@ -0,0 +1,388 @@
+/*
+ * Read a Figma design through the REST API and condense it to what a coding
+ * agent can act on.
+ *
+ * Written against a real response rather than the documentation: the field
+ * names here were confirmed by fetching a live file, and they match the
+ * plugin API's scene graph exactly — `layoutMode`, `itemSpacing`, `padding*`,
+ * `cornerRadius`, `fills`, `characters`, `primaryAxisAlignItems`.
+ *
+ * What it deliberately does not do is decide which component each region is.
+ * A design drawn without the component library has no `componentId` to look
+ * up, so that call is inference — and the agent, holding the catalogue and
+ * the designer's own names for things, infers better than string matching in
+ * a tool. This supplies structure, names, text and tokens; the agent decides.
+ */
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+/** Figma's own limit is generous; a frame beyond this is unreadable anyway. */
+const MAX_DEPTH = 10;
+
+// ------------------------------------------------------------------ token
+
+/**
+ * The token, from the environment or a .env beside the project.
+ *
+ * MCP clients pass environment through unevenly, so a .env is the fallback
+ * that works everywhere. It is read, never logged.
+ */
+function figmaToken() {
+  if (process.env.FIGMA_TOKEN) return process.env.FIGMA_TOKEN.trim();
+  for (const dir of [process.cwd(), path.join(__dirname, "..", "..")]) {
+    const file = path.join(dir, ".env");
+    if (!fs.existsSync(file)) continue;
+    const match = fs.readFileSync(file, "utf8").match(/^\s*FIGMA_TOKEN\s*=\s*(.+)$/m);
+    if (match) return match[1].trim().replace(/^["']|["']$/g, "");
+  }
+  return null;
+}
+
+/** figma.com/design/<key>/<name>?node-id=1-23 → { fileKey, nodeId } */
+function parseFigmaUrl(url) {
+  const key = String(url).match(/figma\.com\/(?:file|design|proto)\/([A-Za-z0-9]+)/);
+  if (!key) return { error: "That does not look like a Figma file URL." };
+  const node = String(url).match(/[?&]node-id=([0-9]+[-:][0-9]+)/);
+  return { fileKey: key[1], nodeId: node ? node[1].replace("-", ":") : null };
+}
+
+/*
+ * A file is fetched once and held briefly.
+ *
+ * The natural flow is two calls — list the frames, then read one — and a
+ * file of any size is hundreds of KB. Fetching it twice in a row is what
+ * earns a 429, which is how this cache came to exist.
+ */
+const CACHE_MS = 5 * 60 * 1000;
+const cache = new Map();
+
+async function figmaGet(pathname, token) {
+  const hit = cache.get(pathname);
+  if (hit && Date.now() - hit.at < CACHE_MS) return hit.body;
+
+  const res = await fetch(`https://api.figma.com/v1${pathname}`, {
+    headers: { "X-Figma-Token": token },
+  });
+  if (!res.ok) {
+    const body = await res.text();
+    if (res.status === 403) {
+      throw new Error(
+        "Figma refused the token. Check FIGMA_TOKEN has 'File content: read' scope and can see this file.",
+      );
+    }
+    if (res.status === 429) {
+      throw new Error(
+        "Figma is rate limiting this token. Wait a minute and try again; the file is cached for five minutes once it arrives.",
+      );
+    }
+    throw new Error(`Figma returned ${res.status}: ${body.slice(0, 160)}`);
+  }
+
+  const body = await res.json();
+  cache.set(pathname, { at: Date.now(), body });
+  return body;
+}
+
+// ------------------------------------------------------------- condensing
+
+const hex = (c) => Math.round(c * 255).toString(16).padStart(2, "0");
+
+function solidFill(node) {
+  const fill = (node.fills || []).find((f) => f.type === "SOLID" && f.visible !== false);
+  return fill ? `#${hex(fill.color.r)}${hex(fill.color.g)}${hex(fill.color.b)}` : undefined;
+}
+
+function layoutOf(node) {
+  if (!node.layoutMode || node.layoutMode === "NONE") return undefined;
+  const pad = [node.paddingTop, node.paddingRight, node.paddingBottom, node.paddingLeft];
+  return {
+    direction: node.layoutMode === "HORIZONTAL" ? "row" : "column",
+    gap: node.itemSpacing || undefined,
+    padding: pad.some((v) => v) ? pad.map((v) => v || 0) : undefined,
+    align: node.counterAxisAlignItems,
+    justify: node.primaryAxisAlignItems,
+  };
+}
+
+/*
+ * Text is lifted to the parent when a node's only content is one label.
+ * Figma wraps nearly every string in its own frame, and passing that
+ * structure through verbatim buries the design in scaffolding.
+ */
+function condense(node, depth) {
+  const out = { name: node.name, type: node.type };
+
+  const layout = layoutOf(node);
+  if (layout) out.layout = layout;
+
+  if (node.type === "TEXT" && node.characters && node.characters.trim()) {
+    out.text = node.characters.trim();
+    if (node.style) {
+      out.font = { size: node.style.fontSize, weight: node.style.fontWeight };
+    }
+  }
+
+  // An instance is a lookup, when the design was built from a library.
+  if (node.type === "INSTANCE" && node.componentId) out.instanceOf = node.componentId;
+
+  const style = {};
+  const fill = solidFill(node);
+  if (fill && node.type !== "TEXT") style.fill = fill;
+  if (typeof node.cornerRadius === "number" && node.cornerRadius) style.radius = node.cornerRadius;
+  if (Object.keys(style).length) out.style = style;
+
+  if (node.absoluteBoundingBox) {
+    out.size = [Math.round(node.absoluteBoundingBox.width), Math.round(node.absoluteBoundingBox.height)];
+  }
+
+  const kids = (node.children || []).filter((c) => c.visible !== false);
+  if (kids.length && depth < MAX_DEPTH) {
+    const children = kids.map((c) => condense(c, depth + 1));
+    // A frame that exists only to hold one text node is noise.
+    if (children.length === 1 && children[0].text && !children[0].children && !out.text) {
+      out.text = children[0].text;
+      out.font = children[0].font;
+    } else {
+      out.children = children;
+    }
+  }
+
+  return out;
+}
+
+// ---------------------------------------------------------------- tokens
+
+const luminance = (h) => {
+  const [r, g, b] = [1, 3, 5].map((i) => parseInt(h.slice(i, i + 2), 16) / 255);
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+};
+
+const saturation = (h) => {
+  const [r, g, b] = [1, 3, 5].map((i) => parseInt(h.slice(i, i + 2), 16) / 255);
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  return max === 0 ? 0 : (max - min) / max;
+};
+
+/*
+ * Colours get roles, not ranks.
+ *
+ * The most-used colour in a design is almost always the body text, and the
+ * accent is used a handful of times on the one button that matters. Sorting
+ * by frequency alone would theme the whole library the colour of its
+ * paragraphs.
+ */
+function themeFrom(colours, radii, fontSizes) {
+  const used = [...colours.entries()].sort((a, b) => b[1] - a[1]);
+  const theme = [];
+  const take = (variable, entry, note) => {
+    if (entry) theme.push({ variable, value: entry[0], seenOn: entry[1], why: note });
+  };
+
+  /*
+   * A near-black navy reads as highly saturated by the HSV measure — #192435
+   * scores 0.53 — so saturation alone picks the body text as the brand
+   * colour. Requiring real lightness as well is what separates an accent
+   * from a dark neutral.
+   */
+  const saturated = used.filter(
+    ([h]) => saturation(h) > 0.45 && luminance(h) > 0.2 && luminance(h) < 0.8,
+  );
+  const darkest = used.filter(([h]) => luminance(h) < 0.25).sort((a, b) => luminance(a[0]) - luminance(b[0]));
+  const lightest = used.filter(([h]) => luminance(h) > 0.9).sort((a, b) => b[1] - a[1]);
+  const mid = used.filter(([h]) => luminance(h) >= 0.25 && luminance(h) <= 0.9 && saturation(h) <= 0.35);
+
+  take("--gbs-accent", saturated[0], "the most-used saturated colour");
+  take("--gbs-fg", darkest[0], "the darkest colour, used for text");
+  take("--gbs-bg", lightest[0], "the lightest colour, used for surfaces");
+  take("--gbs-muted", mid[0], "a desaturated mid tone");
+
+  const radius = [...radii.entries()].sort((a, b) => b[1] - a[1])[0];
+  if (radius) theme.push({ variable: "--gbs-radius", value: `${radius[0]}px`, seenOn: radius[1] });
+
+  // The body size is the most-used that a person could actually read.
+  const body = [...fontSizes.entries()]
+    .filter(([size]) => size >= 12)
+    .sort((a, b) => b[1] - a[1])[0];
+  if (body) theme.push({ variable: "--gbs-font-size", value: `${body[0]}px`, seenOn: body[1] });
+
+  return theme;
+}
+
+function collectTokens(node, colours, radii, fontSizes) {
+  const fill = solidFill(node);
+  if (fill) colours.set(fill, (colours.get(fill) || 0) + 1);
+  if (typeof node.cornerRadius === "number" && node.cornerRadius) {
+    radii.set(node.cornerRadius, (radii.get(node.cornerRadius) || 0) + 1);
+  }
+  if (node.style && node.style.fontSize) {
+    fontSizes.set(node.style.fontSize, (fontSizes.get(node.style.fontSize) || 0) + 1);
+  }
+  for (const child of node.children || []) collectTokens(child, colours, radii, fontSizes);
+}
+
+/** Names the designer repeated are the ones that mean something. */
+function repeatedNames(node, counts) {
+  counts.set(node.name, (counts.get(node.name) || 0) + 1);
+  for (const child of node.children || []) repeatedNames(child, counts);
+}
+
+// ------------------------------------------------------------------- tool
+
+/*
+ * A selection exported by the plugin, which has already done the condensing
+ * inside Figma. The work left is the part that needs no file access: giving
+ * the colours roles and counting the names that repeat.
+ *
+ * This is the path for anyone who would rather not hold an API token, and
+ * for files the token cannot reach.
+ */
+function fromPluginExport(design) {
+  let parsed;
+  try {
+    parsed = typeof design === "string" ? JSON.parse(design) : design;
+  } catch (error) {
+    return { error: `That is not JSON: ${error.message}` };
+  }
+  if (!parsed || !Array.isArray(parsed.nodes)) {
+    return {
+      error:
+        "Expected the output of the Figma plugin's 'Export selection for an agent' command.",
+    };
+  }
+
+  const colours = new Map();
+  const radii = new Map();
+  const fontSizes = new Map();
+  const names = new Map();
+  const visit = (node) => {
+    names.set(node.name, (names.get(node.name) || 0) + 1);
+    if (node.style) {
+      if (node.style.fill) colours.set(node.style.fill, (colours.get(node.style.fill) || 0) + 1);
+      if (node.style.radius) radii.set(node.style.radius, (radii.get(node.style.radius) || 0) + 1);
+      if (node.style.fontSize) {
+        fontSizes.set(node.style.fontSize, (fontSizes.get(node.style.fontSize) || 0) + 1);
+      }
+    }
+    for (const child of node.children || []) visit(child);
+  };
+  for (const node of parsed.nodes) visit(node);
+
+  const instances = [];
+  const findInstances = (n) => {
+    if (n.component) instances.push(n.component);
+    for (const c of n.children || []) findInstances(c);
+  };
+  for (const node of parsed.nodes) findInstances(node);
+
+  return {
+    source: "figma plugin export",
+    frame: parsed.frame,
+    theme: themeFrom(colours, radii, fontSizes),
+    repeatedRegions: [...names.entries()]
+      .filter(([, n]) => n > 2)
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 20)
+      .map(([name, n]) => ({ name, times: n })),
+    builtFromLibrary: instances.length > 0,
+    componentsNamed: [...new Set(instances)],
+    tree: parsed.nodes,
+  };
+}
+
+async function figmaFrame({ url, design, frame, depth }) {
+  // The export needs no token, so it is offered before one is demanded.
+  if (design) return fromPluginExport(design);
+
+  const token = figmaToken();
+  if (!token) {
+    return {
+      error:
+        "No FIGMA_TOKEN. Either run the kit's Figma plugin → 'Export selection for an agent' and pass the result as `design`, or create a token at Figma → Settings → Security → Personal access tokens (scope: File content, read) and set FIGMA_TOKEN.",
+    };
+  }
+
+  const { fileKey, nodeId, error } = parseFigmaUrl(url);
+  if (error) return { error };
+
+  let file;
+  try {
+    file = nodeId
+      ? await figmaGet(`/files/${fileKey}/nodes?ids=${encodeURIComponent(nodeId)}`, token)
+      : await figmaGet(`/files/${fileKey}`, token);
+  } catch (e) {
+    return { error: e.message };
+  }
+
+  const roots = nodeId
+    ? Object.values(file.nodes || {}).filter(Boolean).map((n) => n.document)
+    : (file.document.children || []).flatMap((page) => page.children || []);
+
+  if (roots.length === 0) return { error: "Nothing to read at that URL." };
+
+  /*
+   * Without a frame named, the whole file would arrive at once — hundreds of
+   * KB that buries the screen the agent was asked about. So the first call
+   * lists what is there and the second asks for one.
+   */
+  const wanted = frame
+    ? roots.filter((r) => r.name.toLowerCase() === String(frame).toLowerCase())
+    : roots;
+
+  if (!frame && roots.length > 1) {
+    return {
+      file: file.name,
+      frames: roots.map((r) => ({
+        name: r.name,
+        size: r.absoluteBoundingBox
+          ? [Math.round(r.absoluteBoundingBox.width), Math.round(r.absoluteBoundingBox.height)]
+          : undefined,
+      })),
+      next: "Call again with `frame` set to the one you want to build.",
+    };
+  }
+
+  if (wanted.length === 0) {
+    return { error: `No frame called "${frame}".`, frames: roots.map((r) => r.name) };
+  }
+
+  const target = wanted[0];
+  const colours = new Map();
+  const radii = new Map();
+  const fontSizes = new Map();
+  const names = new Map();
+  collectTokens(target, colours, radii, fontSizes);
+  repeatedNames(target, names);
+
+  const limit = Math.min(Number(depth) || MAX_DEPTH, MAX_DEPTH);
+  const tree = condense(target, MAX_DEPTH - limit);
+
+  const instances = [];
+  const findInstances = (n) => {
+    if (n.instanceOf) instances.push(n.name);
+    for (const c of n.children || []) findInstances(c);
+  };
+  findInstances(tree);
+
+  return {
+    file: file.name,
+    frame: target.name,
+    size: tree.size,
+    theme: themeFrom(colours, radii, fontSizes),
+    /* Repetition is the signal: eight "Status cell" nodes are a column. */
+    repeatedRegions: [...names.entries()]
+      .filter(([, n]) => n > 2)
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 20)
+      .map(([name, n]) => ({ name, times: n })),
+    builtFromLibrary: instances.length > 0,
+    tree,
+    howToUse: instances.length
+      ? "This design uses component instances; `instanceOf` names the master for each."
+      : "This design was drawn without the component library, so nothing names a component directly. Use the region names and structure to decide which catalogue component each part is, then call get_component before writing it.",
+  };
+}
+
+module.exports = { figmaFrame, parseFigmaUrl, themeFrom };

package/tools/mcp/server.cjs

@@ -0,0 +1,458 @@
+#!/usr/bin/env node
+/*
+ * An MCP server over the component catalogue.
+ *
+ * A coding agent asked to build a page has two ways to learn an API: read the
+ * source, which costs a lot of context and invites invention, or be told. This
+ * tells it — one component at a time, from the passport that was generated
+ * from the source and cannot drift from it.
+ *
+ * It also marks its own homework. `validate_usage` checks written JSX against
+ * the passports, which catches the failure that matters: a prop the model
+ * remembered from somewhere rather than read here. That was the only mistake
+ * in the experiment that justified building this — every type, union value and
+ * handler signature the passport carried came out right, and the one error was
+ * an invented prop.
+ *
+ * No dependencies on purpose. MCP is newline-delimited JSON-RPC over stdio,
+ * which is a few hundred lines, and a server that ships inside a library every
+ * consumer installs should not drag an SDK along for the ride.
+ */
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { execFileSync } = require("child_process");
+const { figmaFrame } = require("./figma.cjs");
+
+const CATALOGUE = path.join(__dirname, "..", "..", "source", "components");
+const REFERENCES = path.join(__dirname, "..", "..", ".gbs", "skills", "gbs-components", "references");
+
+/** The newest protocol revision this server knows. Older clients get theirs back. */
+const PROTOCOL_VERSION = "2025-06-18";
+const SUPPORTED_PROTOCOLS = new Set(["2024-11-05", "2025-03-26", "2025-06-18", "2025-11-25"]);
+
+// --------------------------------------------------------------- catalogue
+
+const readJson = (file) => JSON.parse(fs.readFileSync(file, "utf8"));
+
+const componentFolders = () =>
+  fs
+    .readdirSync(CATALOGUE, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && fs.existsSync(path.join(CATALOGUE, e.name, "passport.json")))
+    .map((e) => e.name)
+    .sort();
+
+/** Resolve a name the way an agent would write it: "DataGrid", "data-grid", "datagrid". */
+function findFolder(name) {
+  const wanted = String(name || "").toLowerCase().replace(/[^a-z0-9]/g, "");
+  for (const folder of componentFolders()) {
+    if (folder.replace(/[^a-z0-9]/g, "") === wanted) return folder;
+    const passport = readJson(path.join(CATALOGUE, folder, "passport.json"));
+    const names = [passport.identity.component, ...(passport.identity.exports || [])];
+    if (names.some((n) => String(n).toLowerCase() === wanted)) return folder;
+  }
+  return null;
+}
+
+/*
+ * Most passports carry no `purpose`, so the README's opening line stands in.
+ * It is the sentence a human wrote about what the component is for, which is
+ * exactly what an agent needs to pick one.
+ */
+function purposeOf(folder, passport) {
+  if (passport.purpose && passport.purpose.trim()) return passport.purpose.trim();
+  const readme = path.join(CATALOGUE, folder, "README.md");
+  if (!fs.existsSync(readme)) return "";
+  const line = fs
+    .readFileSync(readme, "utf8")
+    .split("\n")
+    .map((l) => l.trim())
+    .find((l) => l && !l.startsWith("#") && !l.startsWith("<!--"));
+  return line ? line.replace(/\s+/g, " ") : "";
+}
+
+// -------------------------------------------------------------------- tools
+
+function listComponents() {
+  return componentFolders().map((folder) => {
+    const passport = readJson(path.join(CATALOGUE, folder, "passport.json"));
+    return {
+      component: passport.identity.component,
+      folder,
+      exports: passport.identity.exports || [],
+      purpose: purposeOf(folder, passport),
+    };
+  });
+}
+
+/**
+ * The passport, trimmed to what writing code needs.
+ *
+ * The whole file averages 8.6 KB and runs to 26 KB; most of that is provenance
+ * an agent cannot act on. What it can act on is the shape: names, types, the
+ * union values for enum props, which are required, and the handler signatures.
+ */
+function getComponent(name) {
+  const folder = findFolder(name);
+  if (!folder) {
+    return { error: `No component named "${name}". Call list_components for the catalogue.` };
+  }
+  const p = readJson(path.join(CATALOGUE, folder, "passport.json"));
+  return {
+    component: p.identity.component,
+    folder,
+    exports: p.identity.exports || [],
+    importFrom: `@/component-lib/${folder}`,
+    purpose: purposeOf(folder, p),
+    props: (p.props || []).map((prop) => ({
+      name: prop.name,
+      type: prop.typeText || prop.type,
+      values: prop.values,
+      required: prop.required || undefined,
+      default: prop.default,
+      description: prop.description,
+    })),
+    events: (p.events || []).map((e) => ({
+      name: e.name,
+      signature: e.signature,
+      description: e.description,
+    })),
+    slots: p.slots || [],
+    states: p.states || [],
+    composition: p.composition || {},
+    accessibility: p.accessibility || {},
+  };
+}
+
+/** The README's code fences: how the component is meant to be used. */
+function getExample(name) {
+  const folder = findFolder(name);
+  if (!folder) return { error: `No component named "${name}".` };
+  const readme = path.join(CATALOGUE, folder, "README.md");
+  if (!fs.existsSync(readme)) return { error: `No README for ${folder}.` };
+
+  const blocks = [];
+  const text = fs.readFileSync(readme, "utf8");
+  const fence = /```(\w*)\n([\s\S]*?)```/g;
+  let match;
+  while ((match = fence.exec(text))) blocks.push({ language: match[1] || "txt", code: match[2].trim() });
+  return { component: folder, examples: blocks };
+}
+
+/** The authored guidance that ships with the agent skill. */
+function getGuidance(topic) {
+  const available = fs.existsSync(REFERENCES)
+    ? fs.readdirSync(REFERENCES).filter((f) => f.endsWith(".md")).map((f) => f.replace(/\.md$/, ""))
+    : [];
+  if (!topic) return { topics: available };
+  const file = path.join(REFERENCES, `${topic}.md`);
+  if (!fs.existsSync(file)) return { error: `No guidance for "${topic}".`, topics: available };
+  return { topic, text: fs.readFileSync(file, "utf8") };
+}
+
+/*
+ * Check written JSX against the passports.
+ *
+ * Deliberately tolerant parsing rather than a real one: the agent hands over a
+ * fragment, not a file, and the failure worth catching is a prop that does not
+ * exist. Spread props and expressions are skipped rather than guessed at — a
+ * validator that invents errors is worse than none.
+ */
+function validateUsage(code) {
+  const source = String(code || "");
+  const known = new Map();
+  for (const folder of componentFolders()) {
+    const p = readJson(path.join(CATALOGUE, folder, "passport.json"));
+    const props = new Set((p.props || []).map((x) => x.name));
+    for (const e of p.events || []) props.add(e.name);
+    const required = (p.props || []).filter((x) => x.required).map((x) => x.name);
+    for (const exported of [p.identity.component, ...(p.identity.exports || [])]) {
+      known.set(exported, { folder, props, required, values: p.props || [] });
+    }
+  }
+
+  const issues = [];
+  const used = [];
+  const opening = /<([A-Z][A-Za-z0-9]*)(?=[\s/>])/g;
+  let match;
+
+  while ((match = opening.exec(source))) {
+    const [, name] = match;
+    const entry = known.get(name);
+    if (!entry) continue; // Not ours; the agent may compose with its own components.
+
+    /*
+     * Scan to the tag's own `>` rather than matching one. An attribute can
+     * hold an arrow function — `onDismiss={() => {}}` — so the first `>` is
+     * usually inside a brace, and a regex that stops there finds nothing.
+     */
+    let depth = 0;
+    let quote = null;
+    let end = -1;
+    for (let i = match.index + match[0].length; i < source.length; i += 1) {
+      const ch = source[i];
+      if (quote) {
+        if (ch === quote) quote = null;
+      } else if (ch === '"' || ch === "'" || ch === "`") {
+        quote = ch;
+      } else if (ch === "{") {
+        depth += 1;
+      } else if (ch === "}") {
+        depth -= 1;
+      } else if (ch === ">" && depth === 0) {
+        end = i;
+        break;
+      }
+    }
+    if (end === -1) continue; // Unterminated fragment; nothing reliable to say.
+
+    const rawAttrs = source.slice(match.index + match[0].length, end);
+    const attrs = [...rawAttrs.matchAll(/(?:^|\s)([a-zA-Z][a-zA-Z0-9:_-]*)(?=\s*=|\s|$)/g)].map(
+      (m) => m[1],
+    );
+    used.push({ component: name, props: attrs });
+
+    for (const attr of attrs) {
+      if (entry.props.has(attr)) continue;
+      if (attr.startsWith("data-") || attr.startsWith("aria-") || attr === "key") continue;
+      /*
+       * A wrong prop is usually a near miss for a real one — `dismissible`
+       * for `onDismiss`, `onChange` for `onValueChange`. Matching on a shared
+       * stem in either direction finds those; matching on a prefix does not,
+       * because the handler's name starts with `on`.
+       */
+      const low = attr.toLowerCase();
+      const stem = low.slice(0, Math.max(4, Math.round(low.length * 0.6)));
+      const near = [...entry.props].filter((p) => {
+        const other = p.toLowerCase();
+        return other.includes(stem) || low.includes(other.replace(/^on/, "").slice(0, 5));
+      });
+      issues.push({
+        component: name,
+        prop: attr,
+        problem: "not a prop of this component",
+        didYouMean: near.slice(0, 4),
+      });
+    }
+
+    for (const req of entry.required) {
+      if (!attrs.includes(req) && !/\{\s*\.\.\./.test(rawAttrs)) {
+        issues.push({ component: name, prop: req, problem: "required prop is missing" });
+      }
+    }
+  }
+
+  return {
+    checked: used,
+    issues,
+    ok: issues.length === 0,
+    summary: issues.length
+      ? `${issues.length} problem(s) across ${used.length} element(s).`
+      : `${used.length} element(s) check out against their passports.`,
+  };
+}
+
+/*
+ * Put components into the project the agent is working in.
+ *
+ * The CLI already knows where they belong — it finds an existing install or
+ * follows the project's own layout — so this runs it rather than
+ * reimplementing that judgement.
+ */
+function installComponents(names) {
+  const list = Array.isArray(names) ? names : String(names || "").split(/[\s,]+/);
+  const wanted = list.map((n) => String(n).trim()).filter(Boolean);
+  if (wanted.length === 0) return { error: "Name at least one component." };
+
+  const unknown = wanted.filter((n) => !findFolder(n));
+  if (unknown.length) {
+    return {
+      error: `Not in the catalogue: ${unknown.join(", ")}. Call list_components.`,
+    };
+  }
+
+  const cli = path.join(__dirname, "..", "..", "index.cjs");
+  try {
+    const output = execFileSync(process.execPath, [cli, "add", ...wanted], {
+      cwd: process.cwd(),
+      encoding: "utf8",
+      timeout: 120000,
+    });
+    // The installer prints the one manual step; the agent needs to see it.
+    const importLine = (output.match(/^\s*@import .+$/gm) || []).map((l) => l.trim());
+    return { installed: wanted, stylesheet: importLine, output: output.trim().slice(-1200) };
+  } catch (error) {
+    return { error: `Install failed: ${(error.stdout || error.message || "").toString().slice(-600)}` };
+  }
+}
+
+const TOOLS = [
+  {
+    name: "list_components",
+    description:
+      "Every component in the catalogue with its exports and what it is for. Call this first when deciding which component a design calls for.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    run: () => listComponents(),
+  },
+  {
+    name: "get_component",
+    description:
+      "A component's full contract: props with types and allowed values, which are required, event handler signatures, slots, states and composition rules. Read this before writing any JSX that uses it, rather than recalling the API.",
+    inputSchema: {
+      type: "object",
+      properties: { name: { type: "string", description: 'Component or folder name, e.g. "DataGrid".' } },
+      required: ["name"],
+      additionalProperties: false,
+    },
+    run: (args) => getComponent(args.name),
+  },
+  {
+    name: "get_example",
+    description: "Working usage taken from the component's own README.",
+    inputSchema: {
+      type: "object",
+      properties: { name: { type: "string" } },
+      required: ["name"],
+      additionalProperties: false,
+    },
+    run: (args) => getExample(args.name),
+  },
+  {
+    name: "get_guidance",
+    description:
+      "Authored guidance on a topic: forms, overlays, data-grid, pickers, styling, accessibility, data-display, toaster, install. Omit the topic to list them.",
+    inputSchema: {
+      type: "object",
+      properties: { topic: { type: "string" } },
+      additionalProperties: false,
+    },
+    run: (args) => getGuidance(args.topic),
+  },
+  {
+    name: "figma_frame",
+    description:
+      "BETA. Read a Figma design, from a URL (needs FIGMA_TOKEN) or from the plugin export (no token). Called with just a URL it lists the frames in the file; called with `frame` it returns that screen's structure, text, the repeated regions that indicate lists and tables, and the theme variables its colours and radii map onto. Needs FIGMA_TOKEN.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        url: { type: "string", description: "A figma.com/design/... URL. Needs FIGMA_TOKEN." },
+        design: {
+          type: "string",
+          description:
+            "Alternative to url, needing no token: JSON from the kit's Figma plugin, 'Export selection for an agent'.",
+        },
+        frame: { type: "string", description: "Which frame to read, from the listing." },
+        depth: { type: "number", description: "How deep to descend. Lower it if the payload is large." },
+      },
+      required: [],
+      additionalProperties: false,
+    },
+    run: (args) => figmaFrame(args),
+  },
+  {
+    name: "install_component",
+    description:
+      "Copy components into the project being worked in, with their shared folder and stylesheet. Run this before importing them.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        names: {
+          type: "array",
+          items: { type: "string" },
+          description: 'Component names, e.g. ["DataGrid", "Button"].',
+        },
+      },
+      required: ["names"],
+      additionalProperties: false,
+    },
+    run: (args) => installComponents(args.names),
+  },
+  {
+    name: "validate_usage",
+    description:
+      "Check JSX against the passports and report props that do not exist or required props left out. Run this on code you have written before telling the user it is done.",
+    inputSchema: {
+      type: "object",
+      properties: { code: { type: "string", description: "JSX source to check." } },
+      required: ["code"],
+      additionalProperties: false,
+    },
+    run: (args) => validateUsage(args.code),
+  },
+];
+
+// ------------------------------------------------------------- the protocol
+
+const send = (message) => process.stdout.write(JSON.stringify(message) + "\n");
+const reply = (id, result) => send({ jsonrpc: "2.0", id, result });
+const fail = (id, code, message) => send({ jsonrpc: "2.0", id, error: { code, message } });
+
+function handle(request) {
+  const { id, method, params } = request;
+
+  if (method === "initialize") {
+    const asked = params && params.protocolVersion;
+    return reply(id, {
+      protocolVersion: SUPPORTED_PROTOCOLS.has(asked) ? asked : PROTOCOL_VERSION,
+      capabilities: { tools: {} },
+      serverInfo: { name: "grampro-kit", version: require("../../package.json").version },
+    });
+  }
+
+  if (method === "notifications/initialized") return; // A notification; no reply.
+  if (method === "ping") return reply(id, {});
+
+  if (method === "tools/list") {
+    return reply(id, {
+      tools: TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })),
+    });
+  }
+
+  if (method === "tools/call") {
+    const tool = TOOLS.find((t) => t.name === (params && params.name));
+    if (!tool) return fail(id, -32602, `Unknown tool: ${params && params.name}`);
+    try {
+      // Some tools reach the network, so a result may be a promise.
+      const result = tool.run((params && params.arguments) || {});
+      return Promise.resolve(result).then(
+        (value) => reply(id, { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] }),
+        (error) =>
+          reply(id, { content: [{ type: "text", text: `Tool failed: ${error.message}` }], isError: true }),
+      );
+    } catch (error) {
+      // Reported as a result, not a protocol error: the model should see it and retry.
+      return reply(id, {
+        content: [{ type: "text", text: `Tool failed: ${error.message}` }],
+        isError: true,
+      });
+    }
+  }
+
+  if (id !== undefined) fail(id, -32601, `Method not found: ${method}`);
+}
+
+function main() {
+  let buffer = "";
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("data", (chunk) => {
+    buffer += chunk;
+    // Newline-delimited JSON: a message may arrive split across chunks.
+    let newline;
+    while ((newline = buffer.indexOf("\n")) !== -1) {
+      const line = buffer.slice(0, newline).trim();
+      buffer = buffer.slice(newline + 1);
+      if (!line) continue;
+      try {
+        handle(JSON.parse(line));
+      } catch {
+        fail(null, -32700, "Parse error");
+      }
+    }
+  });
+  process.stdin.on("end", () => process.exit(0));
+}
+
+if (require.main === module) main();
+
+module.exports = { main, listComponents, getComponent, getExample, getGuidance, validateUsage, installComponents, TOOLS };