@carto/meridian-ds 3.0.2 → 3.0.3-alpha.c232590.252

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- feat(ai-metadata): expose component knowledge to AI agents via the new `meridian-ds-mcp` MCP server — a build-time `dist/metadata.json` bundle (curation, conventions, example code) authored per component via `<Name>.metadata.ts` + JSDoc, validated in CI [#443](https://github.com/CartoDB/meridian-ds/pull/443)
+
 ## 3.0
 
 ### 3.0.2

package/README.md

@@ -42,3 +42,37 @@ Meridian ships CARTO's custom icon set as React components under `@carto/meridia
 ## Figma integration
 
 Meridian publishes `Figma Code Connect` templates for all components, so **AI coding agents using the Figma MCP server can read designs and generate Meridian-conformant code**: the right component, the right import path, only real prop values, and the encoded semantics of Meridian primitives. The same templates surface the matching snippet to developers inspecting an instance in Figma's Dev Mode. See setup, MCP install, and template-authoring details in the [Figma Code Connect documentation](https://meridian.carto.com/?path=/docs/figma-code-connect--docs).
+
+## AI readiness
+
+Meridian ships structured metadata so **AI coding agents in apps that depend on it generate correct Meridian code** — the right component, real prop values, and Meridian conventions instead of bare MUI. Knowledge splits two ways: exact props and types come from the package's TypeScript declarations (`.d.ts`, which the consumer's IDE/`tsc` already reads), and everything types can't express — which component to use and when, gotchas, the high-value MUI props, and real examples — comes from a metadata bundle served over MCP.
+
+### Meridian MCP
+
+The package ships an MCP server as the `meridian-ds-mcp` bin. In a repo that has `@carto/meridian-ds` installed, register it with the Claude Code CLI:
+
+```bash
+claude mcp add --scope project meridian-design-system -- npx meridian-ds-mcp
+```
+
+`--scope project` writes `.mcp.json` at the repo root — Claude Code loads it whether the team commits it (to share the server) or gitignores it:
+
+```json
+{
+  "mcpServers": {
+    "meridian-design-system": {
+      "command": "npx",
+      "args": ["meridian-ds-mcp"]
+    }
+  }
+}
+```
+
+It's a stdio server (a local command, not a hosted URL), so it needs no network — the bin reads the metadata bundle that ships inside the installed `@carto/meridian-ds`, so the agent's knowledge always matches the installed version.
+
+It exposes four tools:
+
+- `meridian_list_components` — discover components by description + keywords.
+- `meridian_get_component` — when to use it, alternatives, and the high-value inherited MUI props.
+- `meridian_get_examples` — real, copy-able example code.
+- `meridian_get_conventions` — cross-cutting usage rules.

package/dist/bin/meridian-ds-mcp.js

@@ -0,0 +1,269 @@
+#!/usr/bin/env node
+
+// ai-metadata/mcp/server.ts
+import * as fs from "fs";
+import * as path from "path";
+import { fileURLToPath } from "url";
+import { createRequire } from "module";
+var __dirname = path.dirname(fileURLToPath(import.meta.url));
+function resolveBundlePath() {
+  if (process.env.MERIDIAN_DS_METADATA) return process.env.MERIDIAN_DS_METADATA;
+  try {
+    return createRequire(import.meta.url).resolve("@carto/meridian-ds/metadata");
+  } catch {
+    let dir = __dirname;
+    for (let i = 0; i < 6; i++) {
+      const candidate = path.join(dir, "dist", "metadata.json");
+      if (fs.existsSync(candidate)) return candidate;
+      dir = path.dirname(dir);
+    }
+    return path.resolve(__dirname, "..", "..", "dist", "metadata.json");
+  }
+}
+var DOCS = [];
+var CONVENTIONS = "";
+var VERSION = "0.0.0";
+var TOOLS = [
+  {
+    name: "meridian_list_components",
+    description: "List all Meridian components with their description, keywords, and example count. Start here: the catalog is small, so read it and pick the component whose description/keywords match your need.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false
+    }
+  },
+  {
+    name: "meridian_get_component",
+    description: "Curation for one component: when to use it, its decisionTree (when to reach for a different component), any limitations (capabilities it lacks vs. similar components \u2014 check before downgrading from one), and the high-value inherited MUI props (curation.mui, some with an aiHint). Own props, types, and JSDoc are NOT here \u2014 read the shipped .d.ts (the propTypes field gives the exact command).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: 'Component name, e.g. "Button"' }
+      },
+      required: ["name"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "meridian_get_examples",
+    description: "Real, copy-able example code (per Storybook story, with imports), shipped in the package. With no storyId: the first few stories in full plus an 'Other Stories' list (name + id) of the rest. Pass a storyId (from that list or meridian_get_component) to get just that story's full code.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: 'Component name, e.g. "Button"' },
+        storyId: {
+          type: "string",
+          description: "Optional. A story id (or name) to fetch just that one example \u2014 use for components whose full set is too large to return at once."
+        }
+      },
+      required: ["name"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "meridian_get_conventions",
+    description: "Mandatory system-wide Meridian rules to apply whenever generating or editing UI (component selection, a11y, i18n, styling/theme tokens, props, examples). Call this once per session BEFORE writing code and follow it \u2014 these rules are not repeated in the per-component data.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false
+    }
+  }
+];
+var find = (name) => DOCS.find((d) => d.name.toLowerCase() === String(name).toLowerCase());
+var notFound = (name) => ({
+  error: `Unknown component "${name}". Available: ${DOCS.map((d) => d.name).join(", ")}`
+});
+function listComponents() {
+  return DOCS.map((d) => ({
+    name: d.name,
+    description: d.description,
+    keywords: d.curation.keywords ?? [],
+    examples: d.examples.length
+  }));
+}
+function getComponent(name) {
+  const doc = find(name);
+  if (!doc) return notFound(name);
+  return {
+    name: doc.name,
+    description: doc.description,
+    reminder: "Apply the session conventions when using this \u2014 call meridian_get_conventions first if you have not this session.",
+    curation: doc.curation,
+    // Own props/types/JSDoc aren't in the bundle by design; point a headless
+    // agent at the shipped .d.ts (no IDE/hover assumed). Promoted inherited MUI
+    // props, when curated, are already in `curation.mui` above.
+    propTypes: `Own props, exact types, and JSDoc are not in this payload \u2014 they ship as TypeScript declarations. Read them from the installed package: \`find node_modules/@carto/meridian-ds/dist/types -name '${doc.name}.d.ts'\`. Import the component from '@carto/meridian-ds/components'.`,
+    examples: {
+      note: "Call meridian_get_examples(name) for the first stories in full plus an index of the rest; pass a storyId for any specific one.",
+      storyIds: doc.examples.map((e) => e.id)
+    }
+  };
+}
+var EXAMPLES_FULL = 5;
+function titleize(name) {
+  return name.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2").trim();
+}
+function getComponentExamples(name, storyId) {
+  const doc = find(name);
+  if (!doc) return notFound(name);
+  if (storyId) {
+    const ex = doc.examples.find((e) => e.id === storyId || e.name === storyId);
+    if (!ex)
+      return {
+        error: `Unknown story "${storyId}" for ${doc.name}. Available: ${doc.examples.map((e) => e.id).join(", ")}`
+      };
+    return `# ${doc.name} - ${titleize(ex.name)}
+
+${ex.code}`;
+  }
+  if (!doc.examples.length) return `# ${doc.name}
+
+No examples available.`;
+  const componentId = doc.examples[0].id.split("--")[0];
+  const shown = doc.examples.slice(0, EXAMPLES_FULL);
+  const rest = doc.examples.slice(EXAMPLES_FULL);
+  let md = `# ${doc.name}
+
+ID: ${componentId}
+
+## Stories
+`;
+  for (const e of shown)
+    md += `
+### ${titleize(e.name)}
+
+Story ID: ${e.id}
+
+${e.code}
+`;
+  if (rest.length) {
+    md += `
+### Other Stories
+
+Fetch any with meridian_get_examples(storyId):
+
+`;
+    md += rest.map((e) => `- ${titleize(e.name)} (${e.id})`).join("\n") + "\n";
+  }
+  return md;
+}
+function callTool(name, args) {
+  switch (name) {
+    case "meridian_list_components":
+      return listComponents();
+    case "meridian_get_component":
+      return getComponent(String(args.name ?? ""));
+    case "meridian_get_examples":
+      return getComponentExamples(
+        String(args.name ?? ""),
+        args.storyId ? String(args.storyId) : void 0
+      );
+    case "meridian_get_conventions":
+      return { conventions: CONVENTIONS };
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}
+var SERVER_INSTRUCTIONS = `Meridian Design System knowledge for writing React UI in an app that depends on @carto/meridian-ds.
+
+REQUIRED FIRST STEP: before writing or editing ANY Meridian UI, call meridian_get_conventions once and follow it for the rest of the session. These are mandatory cross-cutting rules (component selection, a11y, i18n, styling/theme tokens, props, examples) that the per-component data does NOT repeat \u2014 skipping them produces off-spec code.
+
+Flow:
+1. meridian_get_conventions \u2014 read first; apply throughout the session.
+2. meridian_list_components \u2014 read the (small) catalog and pick by description + keywords. There is no search tool; match by meaning (the model already knows "picker" \u2248 "dropdown" \u2248 "select").
+3. meridian_get_component(name) \u2014 when to use it, its decisionTree (conditions that point to a different component), and the high-value inherited MUI props worth knowing (curation.mui; some carry an aiHint). It also returns the example story ids.
+4. meridian_get_examples(name[, storyId]) \u2014 real, copy-able example code. With no storyId: the first few stories in full plus a list of the rest; pass a storyId for one story's full code.
+
+Exact own props, types, and JSDoc are NOT served here \u2014 they ship as TypeScript declarations in the installed package. Read them with: find node_modules/@carto/meridian-ds/dist/types -name '<Component>.d.ts'. Import the component from '@carto/meridian-ds/components'. Prefer a Meridian component over a bare MUI one whenever one exists.`;
+function send(msg) {
+  process.stdout.write(JSON.stringify(msg) + "\n");
+}
+function handle(req) {
+  const { id, method, params } = req;
+  const reply = (result) => send({ jsonrpc: "2.0", id, result });
+  switch (method) {
+    case "initialize":
+      return reply({
+        protocolVersion: "2024-11-05",
+        capabilities: { tools: {} },
+        serverInfo: { name: "meridian-design-system", version: VERSION },
+        instructions: SERVER_INSTRUCTIONS
+      });
+    case "notifications/initialized":
+      return;
+    // notification, no response
+    case "ping":
+      return reply({});
+    case "tools/list":
+      return reply({ tools: TOOLS });
+    case "tools/call":
+      try {
+        const result = callTool(params?.name, params?.arguments ?? {});
+        const text = typeof result === "string" ? result : JSON.stringify(result, null, 2);
+        return reply({ content: [{ type: "text", text }] });
+      } catch (err) {
+        return reply({
+          content: [{ type: "text", text: `Error: ${err.message}` }],
+          isError: true
+        });
+      }
+    default:
+      if (id !== void 0) {
+        send({
+          jsonrpc: "2.0",
+          id,
+          error: { code: -32601, message: `Method not found: ${method}` }
+        });
+      }
+  }
+}
+function load() {
+  const bundlePath = resolveBundlePath();
+  if (!fs.existsSync(bundlePath)) {
+    throw new Error(
+      `metadata bundle not found at ${bundlePath}. In the Meridian repo run \`yarn metadata:build\`; in a consumer it ships with @carto/meridian-ds.`
+    );
+  }
+  const bundle = JSON.parse(
+    fs.readFileSync(bundlePath, "utf8")
+  );
+  DOCS = bundle.components;
+  CONVENTIONS = bundle.conventions;
+  VERSION = bundle.version;
+  process.stderr.write(
+    `[meridian-design-system] v${VERSION} ready: ${DOCS.map((d) => d.name).join(", ")}
+`
+  );
+}
+function main() {
+  load();
+  let buf = "";
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("data", (chunk) => {
+    buf += chunk;
+    let nl;
+    while ((nl = buf.indexOf("\n")) >= 0) {
+      const line = buf.slice(0, nl).trim();
+      buf = buf.slice(nl + 1);
+      if (!line) continue;
+      try {
+        handle(JSON.parse(line));
+      } catch (err) {
+        process.stderr.write(
+          `[meridian-design-system] bad message: ${err.message}
+`
+        );
+      }
+    }
+  });
+  process.stdin.on("end", () => process.exit(0));
+}
+try {
+  main();
+} catch (err) {
+  process.stderr.write(`[meridian-design-system] fatal: ${err}
+`);
+  process.exit(1);
+}