@carto/meridian-ds 3.0.3-alpha.cdb2a4e.260 → 3.0.3-alpha.d1bb4a1.264

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

@@ -5,6 +5,13 @@ 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;
+}
+
+// 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;
@@ -26,7 +33,7 @@ var VERSION = "0.0.0";
 var TOOLS = [
   {
     name: "meridian_list_components",
-    description: "List all Meridian components with their description, keywords, and example count, plus a family signal where relevant (`subComponents` for a compound component, `variants` for sibling components chosen between). 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 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.",
     inputSchema: {
       type: "object",
       properties: {},
@@ -35,7 +42,7 @@ var TOOLS = [
   },
   {
     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).",
+    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). 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: {
@@ -47,7 +54,7 @@ var TOOLS = [
   },
   {
     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.",
+    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: {
@@ -75,24 +82,27 @@ var find = (name) => DOCS.find((d) => d.name.toLowerCase() === String(name).toLo
 var notFound = (name) => ({
   error: `Unknown component "${name}". Available: ${DOCS.map((d) => d.name).join(", ")}`
 });
+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 familyRedirect(name) {
   const lc = String(name).toLowerCase();
   for (const d of DOCS) {
-    const isPart = d.curation.subComponents?.some((s) => s.toLowerCase() === lc);
-    const isVariant = d.curation.variants?.some((v) => v.toLowerCase() === lc);
-    if (!isPart && !isVariant) continue;
-    const rel = isPart ? `a sub-component of ${d.name} (a compound component)` : `a variant of ${d.name}`;
-    return {
-      note: `"${name}" is ${rel} and has no standalone catalog entry. See meridian_get_examples('${d.name}') for usage/composition and meridian_get_component('${d.name}') for its curation. Read ${name}'s own props from its type declarations: find node_modules/@carto/meridian-ds/dist/types -name '${name}.d.ts'.`
-    };
+    const part = d.curation.subComponents?.map(subName).find((s) => s.toLowerCase() === lc);
+    const variant = d.curation.variants?.map(subName).find((v) => v.toLowerCase() === lc);
+    const canonical = part ?? variant;
+    if (!canonical) continue;
+    const note = part ? `"${canonical}" is a sub-component of ${d.name} (a compound component) \u2014 it has no standalone catalog entry. See meridian_get_examples('${d.name}') for how it's composed, and read its own props from its type declarations: ${dtsFindRecipe(canonical)}.` : `"${canonical}" is a variant of ${d.name} \u2014 a full component in its own right, not yet individually documented in this catalog. For now use meridian_get_component('${d.name}') / meridian_get_examples('${d.name}'), and read ${canonical}'s own props from its type declarations: ${dtsFindRecipe(canonical)}.`;
+    return { note };
   }
   return void 0;
 }
 function partitionExamples(examples) {
   const usage = examples.filter((e) => e.isUsage);
   const summarized = examples.filter((e) => !e.isUsage && e.summary);
-  let shown = [...usage, ...summarized];
-  if (!shown.length) shown = examples.slice(0, 1);
+  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)) };
 }
@@ -101,9 +111,9 @@ function listComponents() {
     name: d.name,
     description: d.description,
     keywords: d.curation.keywords ?? [],
-    examples: d.examples.length,
     // Family signal: the parts a compound component is composed with, and the
-    // sibling variants chosen between — so relationships are visible while scanning.
+    // 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 } : {}
   }));
@@ -111,13 +121,12 @@ function listComponents() {
 function getComponent(name) {
   const doc = find(name);
   if (!doc) return familyRedirect(name) ?? notFound(name);
-  const parts = doc.curation.subComponents ?? [];
-  const dtsGlob = parts.length > 0 ? `find node_modules/@carto/meridian-ds/dist/types \\( ${[doc.name, ...parts].map((n) => `-name '${n}.d.ts'`).join(" -o ")} \\)` : `find node_modules/@carto/meridian-ds/dist/types -name '${doc.name}.d.ts'`;
+  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(", ")}. ` : "";
   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) — for the root and, for a
@@ -127,9 +136,14 @@ function getComponent(name) {
     examples: (() => {
       const { shown, rest } = partitionExamples(doc.examples);
       const leadId = shown[0]?.id;
+      const ordered = [
+        ...shown,
+        ...rest.filter((e) => e.summary),
+        ...rest.filter((e) => !e.summary)
+      ];
       return {
-        note: "Stories are ordered by copy-value; the flagged lead is the starting point. Call meridian_get_examples(name) for the lead and the summarized stories in full plus an index of the rest; pass a storyId for any specific one.",
-        stories: [...shown, ...rest].map((e) => ({
+        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: ordered.map((e) => ({
           id: e.id,
           name: titleize(e.name),
           ...e.id === leadId ? { lead: true } : {},