@carto/meridian-ds 3.0.2 → 3.0.3-alpha.14acf93.281

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/{ListItem-BOr1gyyO.cjs → ListItem-CLIaUyDV.cjs}

@@ -4,7 +4,7 @@ const React = require("react");
 const material = require("@mui/material");
 const iconsMaterial = require("@mui/icons-material");
 require("cartocolor");
-const paletteUtils = require("./palette-utils-CfP0zi6X.cjs");
+const paletteUtils = require("./palette-utils-Ou97WiuF.cjs");
 const ReactWindow = require("react-window");
 function _interopNamespaceDefault(e) {
   const n = Object.create(null, { [Symbol.toStringTag]: { value: "Module" } });

package/dist/{ListItem-CW7C1948.js → ListItem-CRSS7jTs.js}

@@ -3,7 +3,7 @@ import React, { forwardRef, useState, createContext, useMemo, useContext } from
 import { styled, Link as Link$1, Alert as Alert$1, Fade, AlertTitle, List as List$1, ListItemButton as ListItemButton$1, ListItem as ListItem$1 } from "@mui/material";
 import { OpenInNewOutlined } from "@mui/icons-material";
 import "cartocolor";
-import { c as ICON_SIZE_SMALL, b as ICON_SIZE_MEDIUM, u as useTranslationWithFallback, T as Typography, m as LIST_MAX_SIZE, n as LIST_OVERSCAN_ITEMS_COUNT, h as LIST_ITEM_SIZE_DENSE, i as LIST_ITEM_SIZE_DEFAULT } from "./palette-utils-gZwK5wCD.js";
+import { c as ICON_SIZE_SMALL, b as ICON_SIZE_MEDIUM, u as useTranslationWithFallback, T as Typography, m as LIST_MAX_SIZE, n as LIST_OVERSCAN_ITEMS_COUNT, h as LIST_ITEM_SIZE_DENSE, i as LIST_ITEM_SIZE_DEFAULT } from "./palette-utils-B2CZD7oM.js";
 import * as ReactWindow from "react-window";
 const ScreenReaderOnly = styled("span")(() => ({
   position: "absolute",

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

@@ -0,0 +1,373 @@
+#!/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";
+
+// ai-metadata/types.ts
+function subName(s) {
+  return typeof s === "string" ? s : s.name;
+}
+function relatedName(e) {
+  return typeof e === "string" ? e : e.name;
+}
+
+// ai-metadata/mcp/server.ts
+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 KNOWN = [];
+var CONVENTIONS = "";
+var VERSION = "0.0.0";
+var TOOLS = [
+  {
+    name: "meridian_list_components",
+    description: "List all Meridian components with their description and keywords, plus a family signal where relevant (`subComponents` for a compound component, `variants` for sibling components chosen between \u2014 each with a one-line description). Start here: the catalog is small, so read it and pick the component whose description/keywords match your need. Rows flagged `documented: false` are not yet curated (no when-to-use/decisionTree/prop guidance): most still have example stories via get_examples; a few are known-only \u2014 real, importable components with no stories yet, for which get_component/get_examples just point at the type declarations.",
+    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). For a not-yet-curated component (`documented: false`) it returns a note + .d.ts pointer in place of curation \u2014 plus its example stories when any exist (a known-only component has none, so rely on the .d.ts). Sub-components and variants (`DialogHeader`, `MultipleAutocomplete`, \u2026) have no standalone catalog entry \u2014 `meridian_get_component`/`meridian_get_examples` on them return a pointer to the parent (check its `curation.subComponents`/`curation.variants`).",
+    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 lead usage story and the notable 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. Sub-components and variants (`DialogHeader`, `MultipleAutocomplete`, \u2026) have no standalone catalog entry \u2014 `meridian_get_component`/`meridian_get_examples` on them return a pointer to the parent (check its `curation.subComponents`/`curation.variants`).",
+    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());
+function notFound(name) {
+  const canonical = KNOWN.find((c) => c.toLowerCase() === String(name).toLowerCase());
+  if (canonical)
+    return {
+      note: `"${canonical}" is a Meridian component but isn't individually documented or listed in this catalog. If it's part of the public API, import it from '@carto/meridian-ds/components' and read its props from its type declarations: ${dtsFindRecipe(canonical)}. Prefer a documented component (see meridian_list_components) when one fits.`
+    };
+  return {
+    error: `No Meridian component named "${name}" (check the spelling). See meridian_list_components for the catalog.`
+  };
+}
+function dtsFindRecipe(...names) {
+  const root = "find node_modules/@carto/meridian-ds/dist/types";
+  const clauses = names.map((n) => `-name '${n}.d.ts'`);
+  return names.length > 1 ? `${root} \\( ${clauses.join(" -o ")} \\)` : `${root} ${clauses[0]}`;
+}
+function familyParent(name) {
+  const lc = String(name).toLowerCase();
+  for (const d of DOCS) {
+    const part = d.curation.subComponents?.map(subName).find((s) => s.toLowerCase() === lc);
+    if (part) return { parent: d.name, canonical: part, role: "sub-component" };
+    const variant = d.curation.variants?.map(subName).find((v) => v.toLowerCase() === lc);
+    if (variant) return { parent: d.name, canonical: variant, role: "variant" };
+  }
+  return void 0;
+}
+function familyRedirect(name) {
+  const f = familyParent(name);
+  if (!f) return void 0;
+  const note = f.role === "sub-component" ? `"${f.canonical}" is a sub-component of ${f.parent} (a compound component) \u2014 it has no standalone catalog entry. See meridian_get_examples('${f.parent}') for how it's composed, and read its own props from its type declarations: ${dtsFindRecipe(f.canonical)}.` : `"${f.canonical}" is a variant of ${f.parent} \u2014 a full component in its own right, not yet individually documented in this catalog. For now use meridian_get_component('${f.parent}') / meridian_get_examples('${f.parent}'), and read ${f.canonical}'s own props from its type declarations: ${dtsFindRecipe(f.canonical)}.`;
+  return { note };
+}
+function partitionExamples(examples) {
+  const usage = examples.filter((e) => e.isUsage);
+  const summarized = examples.filter((e) => !e.isUsage && e.summary);
+  const shown = usage.length ? usage : summarized.length ? summarized : examples.slice(0, 1);
+  const inShown = new Set(shown);
+  return { shown, rest: examples.filter((e) => !inShown.has(e)) };
+}
+function exampleStories(examples) {
+  const { shown, rest } = partitionExamples(examples);
+  const leadId = shown[0]?.id;
+  const ordered = [
+    ...shown,
+    ...rest.filter((e) => e.summary),
+    ...rest.filter((e) => !e.summary)
+  ];
+  return ordered.map((e) => ({
+    id: e.id,
+    name: titleize(e.name),
+    ...e.id === leadId ? { lead: true } : {},
+    ...e.summary ? { summary: e.summary } : {}
+  }));
+}
+function listComponents() {
+  return DOCS.map((d) => ({
+    name: d.name,
+    description: d.description,
+    // LISTED-only components (no metadata file): flagged so an agent knows
+    // get_component won't carry when-to-use/decisionTree/mui guidance for them —
+    // examples + the .d.ts are still available. Documented rows omit the flag.
+    ...d.documented ? {} : { documented: false },
+    keywords: d.curation.keywords ?? [],
+    // Family signal: the parts a compound component is composed with, and the
+    // sibling variants chosen between — each as { name, description } (same shape
+    // as get_component) so an agent can pick a family member while scanning.
+    ...d.curation.subComponents?.length ? { subComponents: d.curation.subComponents } : {},
+    ...d.curation.variants?.length ? { variants: d.curation.variants } : {},
+    // The public hooks/utils/constants that ship with this component — name,
+    // kind, and description (same as subComponents/variants, so an agent can pick
+    // one while scanning without a get_component round-trip). get_component adds
+    // `import` (the entry point — constant across the family, so omitted here).
+    ...d.curation.relatedExports?.length ? {
+      relatedExports: d.curation.relatedExports.map((e) => ({
+        name: relatedName(e),
+        ...typeof e === "object" && e.kind ? { kind: e.kind } : {},
+        ...typeof e === "object" && e.description ? { description: e.description } : {}
+      }))
+    } : {}
+  }));
+}
+function getComponent(name) {
+  const doc = find(name);
+  if (!doc) return familyRedirect(name) ?? notFound(name);
+  const parts = (doc.curation.subComponents ?? []).map(subName);
+  const dtsGlob = dtsFindRecipe(doc.name, ...parts);
+  const compound = parts.length > 0 ? `${doc.name} is a compound component \u2014 compose it with its parts: ${parts.join(", ")}. ` : "";
+  const parent = doc.documented ? void 0 : familyParent(doc.name);
+  const sourceHint = doc.examples.length ? "Use the examples below and its type declarations" : "No example stories ship for it either \u2014 rely on its type declarations (the propTypes recipe below)";
+  const note = doc.documented ? void 0 : `${parent ? `${doc.name} is a ${parent.role} of ${parent.parent} \u2014 compose it within ${parent.parent} (see meridian_get_component('${parent.parent}')). ` : ""}Not yet curated: no when-to-use / decisionTree / keywords / promoted-prop guidance for this component. ${sourceHint} \u2014 and still prefer it over a bare MUI equivalent.`;
+  return {
+    name: doc.name,
+    description: doc.description,
+    documented: doc.documented,
+    ...note ? { note } : {},
+    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) — for the root and, for a
+    // compound component, every part. Promoted inherited MUI props, when curated,
+    // are already in `curation.mui` above.
+    propTypes: `${compound}Own props, exact types, and JSDoc are not in this payload \u2014 they ship as TypeScript declarations. Read them from the installed package: \`${dtsGlob}\`. Import from '@carto/meridian-ds/components'.`,
+    examples: doc.examples.length ? {
+      note: "Stories are ordered by copy-value; the flagged lead is the starting point. Call meridian_get_examples(name) for the lead in full plus an index of the rest; pass a storyId for any specific one.",
+      stories: exampleStories(doc.examples)
+    } : {
+      note: "No example stories ship for this component yet \u2014 read its props from the .d.ts (see propTypes above).",
+      stories: []
+    }
+  };
+}
+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 familyRedirect(name) ?? 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(", ")}`
+      };
+    const summary = ex.summary ? `${ex.summary}
+
+` : "";
+    return `# ${doc.name} - ${titleize(ex.name)}
+
+${summary}${ex.code}`;
+  }
+  if (!doc.examples.length)
+    return `# ${doc.name}
+
+No example stories ship for ${doc.name} yet. It's a real Meridian component \u2014 import it from '@carto/meridian-ds/components' and read its props from its type declarations: ${dtsFindRecipe(doc.name)}.`;
+  const componentId = doc.examples[0].id.split("--")[0];
+  const { shown, rest } = partitionExamples(doc.examples);
+  let md = `# ${doc.name}
+
+ID: ${componentId}
+
+## Stories
+`;
+  for (const e of shown) {
+    md += `
+### ${titleize(e.name)}
+
+Story ID: ${e.id}
+
+`;
+    if (e.summary) md += `${e.summary}
+
+`;
+    md += `${e.code}
+`;
+  }
+  if (rest.length) {
+    md += `
+### Other Stories
+
+Fetch any with meridian_get_examples(storyId):
+
+`;
+    md += rest.map(
+      (e) => `- ${titleize(e.name)} (${e.id})${e.summary ? ` \u2014 ${e.summary}` : ""}`
+    ).join("\n");
+    md += "\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;
+    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 lead usage story and the notable stories in full plus a list of the rest; pass a storyId for one story's full code.
+
+Three tiers of components, by how much each carries (all are real and importable \u2014 always prefer one over a bare MUI equivalent): CURATED (most) have full when-to-use / decisionTree / promoted-prop guidance; LISTED (flagged "documented": false, with example stories) carry no curation yet \u2014 lean on get_examples + the .d.ts; KNOWN (flagged "documented": false, no stories) are real components not yet documented \u2014 get_component/get_examples point you at their type declarations (.d.ts).
+
+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;
+  KNOWN = bundle.knownComponents ?? [];
+  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);
+}