@carto/meridian-ds 3.0.2-alpha.e34a00a.237 → 3.0.2-alpha.f30ac88.245

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

@@ -13,16 +13,11 @@ function resolveBundlePath() {
   } catch {
     let dir = __dirname;
     for (let i = 0; i < 6; i++) {
-      const candidate = path.join(
-        dir,
-        "ai-metadata",
-        "generated",
-        "metadata.json"
-      );
+      const candidate = path.join(dir, "dist", "metadata.json");
       if (fs.existsSync(candidate)) return candidate;
       dir = path.dirname(dir);
     }
-    return path.resolve(__dirname, "..", "generated", "metadata.json");
+    return path.resolve(__dirname, "..", "..", "dist", "metadata.json");
   }
 }
 var DOCS = [];
@@ -31,7 +26,7 @@ var VERSION = "0.0.0";
 var TOOLS = [
   {
     name: "meridian_list_components",
-    description: "List all Meridian components with their description, search keywords, and example count. Start here: the catalog is small, so read it and pick the component whose description/keywords match your need.",
+    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: {},
@@ -40,7 +35,7 @@ var TOOLS = [
   },
   {
     name: "meridian_get_component",
-    description: "Curation for one component \u2014 when to use it, alternatives, gotchas, the high-value inherited MUI props worth knowing (curation.mui), and its example story ids. Props & exact types come from the package .d.ts (import the component; your IDE/tsc has them). Call meridian_get_examples for example code.",
+    description: "Curation for one component: when to use it, its decisionTree (when to reach for a different component), and the high-value inherited MUI props (curation.mui, some with an aiHint). Props, types, and JSDoc are NOT here \u2014 import the component and let your IDE/tsc show them.",
     inputSchema: {
       type: "object",
       properties: {
@@ -52,11 +47,15 @@ var TOOLS = [
   },
   {
     name: "meridian_get_examples",
-    description: "Real, copy-able example code for a component (one entry per Storybook story: name, id, source), shipped in the package.",
+    description: "Real, copy-able example code for a component (one entry per Storybook story: name, id, source), shipped in the package. With no storyId, returns every story's code \u2014 or, when that would be too large for one response, an index of {name, id} to fetch individually. Pass a storyId (from the index or meridian_get_component) to get a single story's full code.",
     inputSchema: {
       type: "object",
       properties: {
-        name: { type: "string", description: 'Component name, e.g. "Button"' }
+        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
@@ -64,7 +63,7 @@ var TOOLS = [
   },
   {
     name: "meridian_get_conventions",
-    description: "System-wide Meridian usage conventions an agent should apply when generating code (selection, a11y, props, examples).",
+    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: {},
@@ -90,21 +89,43 @@ function getComponent(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,
     props: {
       note: "Own props + exact types/JSDoc come from the package's type declarations \u2014 `import { " + doc.name + " } from '@carto/meridian-ds/components'` and your IDE/tsc shows the full signature. High-value inherited MUI props are in `curation.mui` (e.g. color, variant, size).",
       promotedMuiProps: doc.curation.mui ?? []
     },
     examples: {
-      note: "Call meridian_get_examples for the source code of these stories.",
+      note: "Call meridian_get_examples for the source of these stories (pass a storyId for one at a time if the full set is large).",
       storyIds: doc.examples.map((e) => e.id)
     }
   };
 }
-function getComponentExamples(name) {
+var EXAMPLES_INLINE_LIMIT = 3e4;
+function getComponentExamples(name, storyId) {
   const doc = find(name);
   if (!doc) return notFound(name);
-  return { component: doc.name, examples: doc.examples };
+  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 { component: doc.name, example: ex };
+  }
+  const total = doc.examples.reduce((n, e) => n + e.code.length, 0);
+  if (total <= EXAMPLES_INLINE_LIMIT) {
+    return { component: doc.name, examples: doc.examples };
+  }
+  return {
+    component: doc.name,
+    note: `${doc.examples.length} examples (~${Math.round(total / 1024)} KB) \u2014 too large to return at once. Call meridian_get_examples again with a storyId from the list below for one story's full code.`,
+    examples: doc.examples.map((e) => ({
+      name: e.name,
+      id: e.id,
+      bytes: e.code.length
+    }))
+  };
 }
 function callTool(name, args) {
   switch (name) {
@@ -113,13 +134,27 @@ function callTool(name, args) {
     case "meridian_get_component":
       return getComponent(String(args.name ?? ""));
     case "meridian_get_examples":
-      return getComponentExamples(String(args.name ?? ""));
+      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. For large sets it returns an index of story ids instead of all code; pass a storyId to fetch one story.
+
+Exact props, types, and JSDoc are NOT served here: import the component from '@carto/meridian-ds/components' and let your IDE/tsc show the full, version-correct signature. Prefer a Meridian component over a bare MUI one whenever one exists.`;
 function send(msg) {
   process.stdout.write(JSON.stringify(msg) + "\n");
 }
@@ -131,7 +166,8 @@ function handle(req) {
       return reply({
         protocolVersion: "2024-11-05",
         capabilities: { tools: {} },
-        serverInfo: { name: "meridian-design-system", version: VERSION }
+        serverInfo: { name: "meridian-design-system", version: VERSION },
+        instructions: SERVER_INSTRUCTIONS
       });
     case "notifications/initialized":
       return;