@adobe/design-data-agent-mcp 1.10.1 → 1.12.0

package/README.md

@@ -1,6 +1,6 @@
 # `@adobe/design-data-agent-mcp`
 
-MCP server and Claude Code skill for the [Spectrum Design Data](../../packages/design-data/) agent surface. Read tools (`primer`, `resolve_token`, `query_tokens`, `describe_component`, `describe_guideline`) run fully in-process via `@adobe/design-data-wasm` — no CLI binary required for those. Only `authoring_session_step_intent` still invokes the native binary (for NLP suggest ranking, not yet on the wasm surface).
+MCP server and Claude Code skill for the [Spectrum Design Data](../../packages/design-data/) agent surface. Read tools (`primer`, `resolve_token`, `query_tokens`, `describe_component`, `describe_guideline`, `list_guidelines`) run fully in-process via `@adobe/design-data-wasm` — no CLI binary required for those. Only `authoring_session_step_intent` still invokes the native binary (for NLP suggest ranking, not yet on the wasm surface).
 
 ## Install
 
@@ -77,10 +77,11 @@ node tools/design-data-agent-mcp/src/index.js
 > json`, run from the config's directory) to resolve its `.design-data.toml`
 > source (path/npm/github/git) and any top-level `manifest` cascade, then
 > materializes the result to a temp dir and points `primer` / `resolve_token` /
-> `query_tokens` / `validate_usage` at it instead of the embedded Spectrum
-> snapshot. `describe_component` / `describe_guideline` are unaffected — they always
-> read components/guidelines from `@adobe/spectrum-design-data` regardless of
-> cascade state. If resolution fails
+> `query_tokens` / `validate_usage` / `describe_component` /
+> `describe_guideline` / `list_guidelines` at it instead of the embedded
+> Spectrum snapshot. Component, relationship, and guideline catalogs are copied
+> from the fallback dataset and overlaid with platform manifest extensions. If
+> resolution fails
 > (e.g. no network for a github source), the server logs a warning and falls
 > back to the embedded/local dataset rather than crashing.
 
@@ -153,6 +154,7 @@ node tools/design-data-agent-mcp/src/index.js
 | `query_tokens`       | Filter tokens by expression                                     |
 | `describe_component` | Fetch component schema and token bindings                       |
 | `describe_guideline` | Fetch guideline documentBlocks content and metadata             |
+| `list_guidelines`    | List guideline slugs and metadata, optionally by category       |
 | `validate_usage`     | Validate token usage and return a diagnostic report             |
 | `diff_datasets`      | Compare two datasets and return a semantic diff                 |
 | `write`              | Write agent-generated product context to the dataset            |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/design-data-agent-mcp",
-  "version": "1.10.1",
+  "version": "1.12.0",
   "description": "MCP server and Claude Code skill for the design-data agent surface — read tools run in-process via wasm",
   "type": "module",
   "main": "./src/index.js",
@@ -30,9 +30,9 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
-    "@adobe/design-data": "3.1.0",
-    "@adobe/design-data-wasm": "0.9.0",
-    "@adobe/spectrum-design-data": "3.2.4"
+    "@adobe/design-data": "3.2.1",
+    "@adobe/design-data-wasm": "0.10.0",
+    "@adobe/spectrum-design-data": "3.2.5"
   },
   "devDependencies": {
     "ava": "^6.0.1"

package/skills/design-data/SKILL.md

@@ -6,7 +6,7 @@ description: >
   system, token lookup, spec-conformance, drift detection, or token authoring on custom data.
 metadata:
   author: adobe
-  version: "1.10.1"
+  version: "1.12.0"
 when_to_use: >
   Trigger on: design system, design tokens, spec-conformant, drift, validate tokens, token
   authoring, custom dataset, DESIGN_DATA_PATH, design-data validate, design-data diff,
@@ -67,9 +67,18 @@ all subsequent lookups. No inputs required.
 
 ### Resolve a token to its literal value — `resolve_token`
 
-Required: `property` (string) — e.g. `"accent-background-color-default"`
-Optional: `colorScheme` (`"light"` or `"dark"`), `scale` (`"desktop"` or `"mobile"`),
-`contrast` (`"regular"` or `"high"`)
+Required: `property` (string) — the bare `name.property` segment, e.g. `"background-color"`
+or `"corner-radius"` (see `primer().properties` for the full list). **Not** a flattened
+legacyKey like `"accent-background-color-default"` — that form never resolves.
+Optional context: `colorScheme` (`"light"` or `"dark"`), `scale` (`"desktop"` or `"mobile"`),
+`contrast` (`"regular"` or `"high"`). Optional narrowing: `component`, `variant`, `state`, and
+`colorRole`. Set `excludeDeprecated` to omit tokens with `lifecycle.deprecatedIn`.
+
+> **Gotcha:** when several tokens share a property, use `variant`, `state`, or `colorRole` to
+> narrow the match, then check `ambiguous` and `deprecated` on the result. `component` is
+> sparsely populated in the current dataset, so prefer the other fields when available.
+> `resolve_token` still uses cascade ranking when multiple candidates remain; use `query_tokens`
+> to inspect the full candidate set.
 
 ### Query tokens by filter expression — `query_tokens`
 
@@ -83,12 +92,14 @@ Filter syntax examples:
 ```
 property=background-color
 property=*background*
-component=button
-component=button,state=hover
 property=background-color|property=border-color
 $schema=https://spectrum.adobe.com/page/design-token/
 ```
 
+> **Gotcha:** `component=<id>` currently always returns `[]` — tokens aren't
+> component-indexed in this dataset. Use `describe_component` to see a component's known
+> token bindings instead.
+
 > **Exit codes:** `0` = matches found; empty array = no matches (not an error).
 
 ***

package/src/cascade-bootstrap.js

@@ -17,11 +17,22 @@
  * The CLI already does config discovery, github fetch/cache, and manifest-cascade
  * application on every data-touching subcommand — this just shells out to it once
  * (`design-data query --filter "" --format json`, cwd = the config's directory)
- * and materializes the result as a single `*.tokens.json` cascade-array file in a
- * temp dir, which loadDataset()/validateDataset() already know how to read.
+ * and materializes the result as a cascade dataset in a temp dir, which
+ * loadDataset()/validateDataset() already know how to read. Catalog directories
+ * are copied from the configured fallback dataset and then overlaid with any
+ * manifest extensions so component/guideline reads see the same cascade.
  */
 
-import { existsSync, mkdtempSync, statSync, writeFileSync } from "node:fs";
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { runCli } from "./cli.js";
@@ -32,6 +43,80 @@ function resolveConfigDir(configPath) {
   return statSync(configPath).isDirectory() ? configPath : dirname(configPath);
 }
 
+function resolveManifestPath(configDir) {
+  const configPath = join(configDir, ".design-data.toml");
+  if (!existsSync(configPath)) return null;
+
+  const configText = readFileSync(configPath, "utf-8");
+  const match = configText.match(/^\s*manifest\s*=\s*["']([^"']+)["']\s*$/m);
+  const manifestPath = join(configDir, match?.[1] ?? "manifest.json");
+  return existsSync(manifestPath) ? manifestPath : null;
+}
+
+function materializeCatalogs(config, cascadeDir, configDir) {
+  const manifestPath = resolveManifestPath(configDir);
+  let extensionsDir = null;
+  if (manifestPath) {
+    const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+    extensionsDir = join(
+      dirname(manifestPath),
+      manifest.extensionsDir ?? "extensions",
+    );
+  }
+
+  for (const [key, subdir] of [
+    ["componentsDir", "components"],
+    ["relationshipsDir", "relationships"],
+    ["guidelinesDir", "guidelines"],
+  ]) {
+    const targetDir = join(cascadeDir, subdir);
+    mkdirSync(targetDir, { recursive: true });
+    const fallbackDir = config[key];
+    if (fallbackDir && existsSync(fallbackDir)) {
+      cpSync(fallbackDir, targetDir, { recursive: true, force: true });
+    }
+    const extensionDir = extensionsDir && join(extensionsDir, subdir);
+    if (extensionDir && existsSync(extensionDir)) {
+      cpSync(extensionDir, targetDir, { recursive: true, force: true });
+      if (subdir === "guidelines") {
+        mergeGuidelineManifest(targetDir, extensionDir);
+      }
+    }
+  }
+}
+
+function mergeGuidelineManifest(targetDir, extensionDir) {
+  const manifestPath = join(targetDir, "manifest.json");
+  const manifest = existsSync(manifestPath)
+    ? JSON.parse(readFileSync(manifestPath, "utf-8"))
+    : { guidelines: [] };
+  const entries = new Map(
+    (manifest.guidelines ?? []).map((entry) => [entry.slug, entry]),
+  );
+
+  for (const file of readdirSync(extensionDir)) {
+    if (!file.endsWith(".json") || file === "manifest.json") continue;
+    const document = JSON.parse(
+      readFileSync(join(extensionDir, file), "utf-8"),
+    );
+    const slug = document.name ?? file.replace(/\.json$/, "");
+    entries.set(slug, {
+      slug,
+      ...(document.title && { title: document.title }),
+      ...(document.category && { category: document.category }),
+      ...(document.status && { status: document.status }),
+      ...(document.sourceUrl && { sourceUrl: document.sourceUrl }),
+      file: `guidelines/${file}`,
+    });
+  }
+
+  writeFileSync(
+    manifestPath,
+    JSON.stringify({ ...manifest, guidelines: [...entries.values()] }),
+    "utf-8",
+  );
+}
+
 /**
  * Resolve `config.designDataConfig`'s cascade and populate
  * `config.cascadeDataPath` / `config.cascadeActive` with the result.
@@ -74,6 +159,7 @@ export async function bootstrapCascade(config, { run = runCli } = {}) {
       JSON.stringify(tokens),
       "utf-8",
     );
+    materializeCatalogs(config, dir, configDir);
 
     config.cascadeDataPath = dir;
     config.cascadeActive = true;

package/src/tools/read.js

@@ -15,8 +15,8 @@
  * required. primer and describe_component were migrated in issue m1r.
  * describe_guideline (spectrum-design-data-9fe.7) is the read-back counterpart to
  * data_create/data_edit's "guidelines" category, closing the same read/write
- * asymmetry describe_component already closes for components. Its guideline-loading
- * logic (including the path-traversal guard) is shared with the sibling
+ * asymmetry describe_component already closes for components. Its guideline
+ * loading and listing logic is shared with the sibling
  * @adobe/design-data-mcp package's `design-data-guideline` tool via the
  * `@adobe/design-data/guideline` module, rather than duplicated here.
  *
@@ -26,19 +26,17 @@
  * Cascade scope (see cascade-bootstrap.js / spectrum-design-data-h890.14): once a
  * `.design-data.toml` cascade is resolved, primer/resolve_token/query_tokens/
  * validate_usage all reflect it (they read config.cascadeDataPath instead of
- * config.dataPath when config.cascadeActive). describe_component/describe_guideline
- * do not — components/relationships/guidelines still come from config.componentsDir /
- * config.relationshipsDir / config.guidelinesDir, which resolve from the embedded
- * @adobe/spectrum-design-data package regardless of cascade state. A platform source
- * repo generally carries a token cascade only, not its own component/guideline
- * schemas, so this is left out of scope rather than guessed at; revisit if a platform
- * manifest starts declaring components or guidelines.
+ * config.dataPath when config.cascadeActive). Cascade bootstrap copies the
+ * fallback component/relationship/guideline catalogs into that snapshot and
+ * overlays manifest extensions, so describe_component/describe_guideline/list_guidelines
+ * read the same active cascade while preserving the embedded fallback for inactive
+ * cascades.
  */
 
 import { readFileSync, existsSync, readdirSync } from "fs";
 import { join } from "path";
 import { loadDataset } from "@adobe/design-data/load";
-import { loadGuideline } from "@adobe/design-data/guideline";
+import { listGuidelines, loadGuideline } from "@adobe/design-data/guideline";
 import { config } from "../config.js";
 import { checkDatasetFreshness } from "../dataset-freshness.js";
 
@@ -100,6 +98,15 @@ function validateGuidelineId(id) {
   validateKebabId(id, "guideline");
 }
 
+function getCascadeAwareDir(baseDir, subdir) {
+  if (!baseDir || !config.cascadeActive || !config.cascadeDataPath) {
+    return baseDir;
+  }
+
+  const cascadeDir = join(config.cascadeDataPath, subdir);
+  return existsSync(cascadeDir) ? cascadeDir : baseDir;
+}
+
 export function createReadTools() {
   return [
     {
@@ -114,16 +121,16 @@ export function createReadTools() {
       async handler() {
         // Shape note: this response intentionally diverges from the CLI PrimerData
         // struct (sdk/core/src/primer.rs). The CLI emits modeSets as an array of
-        // {name, values} objects and taxonomyFields as a flat array. This in-process
-        // shape uses keyed objects (matching the sibling design-data-mcp), which agents
-        // and the SKILL.md skill prompt consume by key name. Skill contract:
-        // tokenCount, modeSets.{colorScheme,scale,contrast}, components[],
+        // {name, modes, defaultMode} objects and taxonomyFields as a flat array. This
+        // in-process shape uses keyed objects (matching the sibling design-data-mcp),
+        // which agents and the SKILL.md skill prompt consume by key name. Skill
+        // contract: tokenCount, modeSets.{colorScheme,scale,contrast}, components[],
         // taxonomyFields.{indexed,advisory}. provenance is included for metrics:
         // for the embedded dataset it carries designDataVersion (@adobe/spectrum-design-data
         // version baked in at wasm build time); for custom datasets the source differs.
         const wasm = await getWasm();
         const ds = await getDataset();
-        const { provenance } = ds.primer();
+        const { provenance, modeSets: rawModeSets } = ds.primer();
         // Best-effort staleness check (spectrum-design-data-9fe.5) — silent on
         // failure, never blocks the primer response.
         const datasetStatus = await checkDatasetFreshness(
@@ -135,11 +142,13 @@ export function createReadTools() {
           // and consumers should prefer it going forward.
           source: config.cascadeActive ? "cascade" : "embedded",
           tokenCount: ds.tokenCount(),
-          modeSets: {
-            colorScheme: wasm.getFieldValues("colorScheme") ?? [],
-            scale: wasm.getFieldValues("scale") ?? [],
-            contrast: wasm.getFieldValues("contrast") ?? [],
-          },
+          // Mode-set dimensions (colorScheme, scale, contrast) live in
+          // graph.mode_sets, not the field-catalog registry, so they're read from
+          // ds.primer()'s modeSets array rather than wasm.getFieldValues()
+          // (spectrum-design-data-v9bb).
+          modeSets: Object.fromEntries(
+            rawModeSets.map((ms) => [ms.name, ms.modes]),
+          ),
           taxonomyFields: {
             indexed: wasm.getIndexedFields(),
             advisory: wasm.getAdvisoryFields() ?? [],
@@ -156,7 +165,9 @@ export function createReadTools() {
     {
       name: "resolve_token",
       description:
-        "Resolve a design token property to its final value for a given color scheme, scale, and contrast level.",
+        "Resolve a design token property to its final value for a given context. " +
+        "Use component, variant, state, or colorRole to disambiguate shared properties; " +
+        "inspect ambiguous and deprecated in the result.",
       inputSchema: {
         type: "object",
         required: ["property"],
@@ -164,7 +175,9 @@ export function createReadTools() {
           property: {
             type: "string",
             description:
-              "Token property name, e.g. accent-background-color-default",
+              "Bare token property name (the name.property segment, e.g. " +
+              '"background-color", "corner-radius" — see primer().properties for ' +
+              "the full list). Not a flattened legacyKey.",
           },
           colorScheme: {
             type: "string",
@@ -180,10 +193,46 @@ export function createReadTools() {
             enum: ["regular", "high"],
             description: "Contrast: regular or high",
           },
+          component: {
+            type: "string",
+            description:
+              "Optional component name-object field. It is sparsely populated; " +
+              "prefer variant, state, or colorRole when available.",
+          },
+          variant: {
+            type: "string",
+            description:
+              "Optional token variant used to narrow shared properties.",
+          },
+          state: {
+            type: "string",
+            description:
+              "Optional token state used to narrow shared properties (including array-valued state).",
+          },
+          colorRole: {
+            type: "string",
+            description:
+              "Optional color role such as accent, negative, or positive.",
+          },
+          excludeDeprecated: {
+            type: "boolean",
+            description:
+              "Exclude tokens with lifecycle.deprecatedIn from candidate resolution.",
+          },
         },
         additionalProperties: false,
       },
-      async handler({ property, colorScheme, scale, contrast }) {
+      async handler({
+        property,
+        colorScheme,
+        scale,
+        contrast,
+        component,
+        variant,
+        state,
+        colorRole,
+        excludeDeprecated,
+      }) {
         const ds = await loadDataset(
           config.cascadeActive ? config.cascadeDataPath : config.dataPath,
         );
@@ -191,10 +240,19 @@ export function createReadTools() {
         if (colorScheme) context.colorScheme = colorScheme;
         if (scale) context.scale = scale;
         if (contrast) context.contrast = contrast;
-        const result = ds.resolve(property, context);
+        const result = ds.resolve(property, context, {
+          component,
+          variant,
+          state,
+          colorRole,
+          excludeDeprecated: excludeDeprecated ?? false,
+        });
         if (!result) {
+          const deprecatedHint = excludeDeprecated
+            ? " Only deprecated matches may exist; retry without excludeDeprecated to inspect them."
+            : "";
           throw new Error(
-            `No token found for property "${property}" in context ${JSON.stringify(context)}`,
+            `No token found for property "${property}" in context ${JSON.stringify(context)}.${deprecatedHint}`,
           );
         }
         return result;
@@ -211,7 +269,11 @@ export function createReadTools() {
         properties: {
           filter: {
             type: "string",
-            description: 'Filter expression, e.g. "category=color"',
+            description:
+              'Filter expression, e.g. "property=background-color". Valid keys: ' +
+              "property, component, variant, state, colorScheme, scale, contrast, " +
+              'uuid, $schema. Note: "component" is not currently populated on ' +
+              "tokens — component=<id> always returns []; use describe_component instead.",
           },
         },
         additionalProperties: false,
@@ -238,7 +300,10 @@ export function createReadTools() {
       },
       async handler({ id }) {
         validateComponentId(id);
-        const componentsDir = config.componentsDir;
+        const componentsDir = getCascadeAwareDir(
+          config.componentsDir,
+          "components",
+        );
         if (!componentsDir) {
           throw new Error(
             `@adobe/spectrum-design-data is not installed — cannot load component "${id}". ` +
@@ -268,7 +333,10 @@ export function createReadTools() {
         // of the component file into relationships/<id>.json — merge them back
         // in so callers relying on this tool for a component's token bindings
         // still see them (see spectrum-design-data-x29.4).
-        const relationshipsDir = config.relationshipsDir;
+        const relationshipsDir = getCascadeAwareDir(
+          config.relationshipsDir,
+          "relationships",
+        );
         const relationshipFile = relationshipsDir
           ? join(relationshipsDir, `${id}.json`)
           : null;
@@ -302,7 +370,10 @@ export function createReadTools() {
       },
       async handler({ id }) {
         validateGuidelineId(id);
-        const guidelinesDir = config.guidelinesDir;
+        const guidelinesDir = getCascadeAwareDir(
+          config.guidelinesDir,
+          "guidelines",
+        );
         if (!guidelinesDir) {
           throw new Error(
             `@adobe/spectrum-design-data is not installed — cannot load guideline "${id}". ` +
@@ -315,9 +386,8 @@ export function createReadTools() {
           if (err.message.startsWith("Not found:")) {
             let available;
             try {
-              available = readdirSync(guidelinesDir)
-                .filter((f) => f.endsWith(".json") && f !== "manifest.json")
-                .map((f) => f.replace(/\.json$/, ""))
+              available = listGuidelines(guidelinesDir)
+                .map((guideline) => guideline.slug)
                 .sort()
                 .join(", ");
             } catch {
@@ -332,5 +402,39 @@ export function createReadTools() {
         }
       },
     },
+
+    {
+      name: "list_guidelines",
+      description:
+        "List available Spectrum design guidelines and their metadata. Optionally " +
+        "filter the catalog by category before calling describe_guideline.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          category: {
+            type: "string",
+            description:
+              "Optional guideline category, e.g. designing or implementing",
+          },
+        },
+        additionalProperties: false,
+      },
+      async handler({ category } = {}) {
+        const guidelinesDir = getCascadeAwareDir(
+          config.guidelinesDir,
+          "guidelines",
+        );
+        if (!guidelinesDir) {
+          throw new Error(
+            `@adobe/spectrum-design-data is not installed — cannot list guidelines. ` +
+              `Install it with: pnpm add @adobe/spectrum-design-data`,
+          );
+        }
+        const guidelines = listGuidelines(guidelinesDir);
+        return category
+          ? guidelines.filter((guideline) => guideline.category === category)
+          : guidelines;
+      },
+    },
   ];
 }