@adobe/design-data-agent-mcp 1.11.0 → 1.13.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`, `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).
+MCP server and Claude Code skill for the [Spectrum Design Data](../../packages/design-data/) agent surface. Read tools (`primer`, `resolve_token`, `query_tokens`, `suggest_token`, `describe_component`, `describe_guideline`, `list_guidelines`) run fully in-process via `@adobe/design-data-wasm` — no CLI binary required for those. `suggest_token` uses the wasm `suggest` API directly; `authoring_session_step_intent` still invokes the native binary for session-state-aware ranking within an authoring flow.
 
 ## Install
 
@@ -152,6 +152,7 @@ node tools/design-data-agent-mcp/src/index.js
 | `primer`             | Load full token taxonomy, component list, and field definitions |
 | `resolve_token`      | Resolve a token property to its literal value                   |
 | `query_tokens`       | Filter tokens by expression                                     |
+| `suggest_token`      | Suggest tokens matching a natural-language intent               |
 | `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       |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/design-data-agent-mcp",
-  "version": "1.11.0",
+  "version": "1.13.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,8 +30,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
-    "@adobe/design-data": "3.2.0",
-    "@adobe/design-data-wasm": "0.9.0",
+    "@adobe/design-data": "3.2.1",
+    "@adobe/design-data-wasm": "0.10.0",
     "@adobe/spectrum-design-data": "3.2.5"
   },
   "devDependencies": {

package/skills/design-data/SKILL.md

@@ -6,12 +6,12 @@ description: >
   system, token lookup, spec-conformance, drift detection, or token authoring on custom data.
 metadata:
   author: adobe
-  version: "1.11.0"
+  version: "1.13.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,
   design-data write, product-context.json.
-allowed-tools: mcp__design-data-agent__primer, mcp__design-data-agent__query_tokens, mcp__design-data-agent__resolve_token, mcp__design-data-agent__describe_component, mcp__design-data-agent__validate_usage, mcp__design-data-agent__diff_datasets, mcp__design-data-agent__write, mcp__design-data-agent__start_authoring_session, mcp__design-data-agent__authoring_session_step_intent, mcp__design-data-agent__authoring_session_step_classification, mcp__design-data-agent__authoring_session_step_values, mcp__design-data-agent__authoring_session_commit, mcp__design-data-agent__authoring_session_cancel, mcp__design-data-agent__authoring_session_get, mcp__design-data-agent__authoring_session_list
+allowed-tools: mcp__design-data-agent__primer, mcp__design-data-agent__query_tokens, mcp__design-data-agent__suggest_token, mcp__design-data-agent__resolve_token, mcp__design-data-agent__describe_component, mcp__design-data-agent__validate_usage, mcp__design-data-agent__diff_datasets, mcp__design-data-agent__write, mcp__design-data-agent__start_authoring_session, mcp__design-data-agent__authoring_session_step_intent, mcp__design-data-agent__authoring_session_step_classification, mcp__design-data-agent__authoring_session_step_values, mcp__design-data-agent__authoring_session_commit, mcp__design-data-agent__authoring_session_cancel, mcp__design-data-agent__authoring_session_get, mcp__design-data-agent__authoring_session_list
 ---
 
 # design-data agent skill
@@ -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,14 +92,25 @@ 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).
 
+### Suggest a token from a description — `suggest_token`
+
+Required: `intent` (string) — a natural-language description of the design need,
+such as `"primary CTA button background color"`.
+
+Optional: `limit` (number, default `5`) — the maximum number of suggestions to return.
+Results are ranked by confidence using token names, name-object fields, and description
+text. Use this when the user describes what they need rather than knowing a token name.
+
 ***
 
 ## Component info — `describe_component`
@@ -152,8 +172,9 @@ Helper tools: `authoring_session_get` (inspect state), `authoring_session_list`
 `authoring_session_commit` accepts an optional `schema_path` to override the schemas directory
 for Layer-1 JSON-Schema validation before writing.
 
-> **Note:** `authoring_session_step_intent` (NLP suggestion ranking) still delegates to the
-> `design-data` CLI because the NLP `suggest` API is not yet on the wasm surface.
+> **Note:** The standalone `suggest_token` tool calls the wasm `suggest` API directly.
+> `authoring_session_step_intent` still delegates to the `design-data` CLI for
+> session-state-aware ranking within an authoring flow.
 
 ***
 

package/src/tools/read.js

@@ -20,8 +20,9 @@
  * @adobe/design-data-mcp package's `design-data-guideline` tool via the
  * `@adobe/design-data/guideline` module, rather than duplicated here.
  *
- * Note: authoring_session_step_intent in authoring.js still uses the CLI because
- * the NLP suggest ranking is not yet on the wasm surface.
+ * suggest_token uses the wasm suggest surface directly. The separate
+ * authoring_session_step_intent flow still uses the CLI for session-state-aware
+ * ranking within an authoring session.
  *
  * Cascade scope (see cascade-bootstrap.js / spectrum-design-data-h890.14): once a
  * `.design-data.toml` cascade is resolved, primer/resolve_token/query_tokens/
@@ -121,16 +122,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(
@@ -142,11 +143,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() ?? [],
@@ -163,7 +166,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"],
@@ -171,7 +176,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",
@@ -187,10 +194,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,
         );
@@ -198,10 +241,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;
@@ -218,7 +270,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,
@@ -231,6 +287,36 @@ export function createReadTools() {
       },
     },
 
+    {
+      name: "suggest_token",
+      description:
+        "Suggest Spectrum tokens matching a natural-language intent using Jaccard similarity " +
+        "scoring over token name segments, name-object fields, and description text. " +
+        "Returns matches ranked by confidence with token name, layer, value, and name object. " +
+        "Use when the user describes what they need rather than knowing the token name.",
+      inputSchema: {
+        type: "object",
+        required: ["intent"],
+        properties: {
+          intent: {
+            type: "string",
+            description:
+              'Natural-language description of the design need, e.g. "primary CTA button background color"',
+          },
+          limit: {
+            type: "number",
+            description: "Maximum number of suggestions to return (default: 5)",
+            default: 5,
+          },
+        },
+        additionalProperties: false,
+      },
+      async handler({ intent, limit = 5 }) {
+        const ds = await getDataset();
+        return ds.suggest(intent, undefined, limit);
+      },
+    },
+
     {
       name: "describe_component",
       description: