@adobe/design-data-agent-mcp 1.12.0 → 1.14.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
 
@@ -71,11 +71,14 @@ node tools/design-data-agent-mcp/src/index.js
 | `DESIGN_DATA_SCHEMAS`    | —             | Override schema path (for `validate`)                                          |
 | `DESIGN_DATA_EXCEPTIONS` | —             | Override exceptions path (for `validate`)                                      |
 | `DESIGN_DATA_CONFIG`     | —             | Path to a `.design-data.toml` (or its directory) to resolve a platform cascade |
+| `DESIGN_DATA_PLATFORM`   | —             | Select a named `[platforms.<id>]` entry (needs `DESIGN_DATA_CONFIG`)           |
 
 > **Platform cascade.** If `DESIGN_DATA_CONFIG` is set, the server shells out to
 > the `design-data` CLI once at startup (`design-data query --filter "" --format
 > 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
+> source (path/npm/github/git) and either its top-level `manifest` cascade or,
+> if `DESIGN_DATA_PLATFORM` is also set, that named `[platforms.<id>]` entry's
+> manifest — mirroring the CLI's own `--platform`/`DESIGN_DATA_PLATFORM`, then
 > materializes the result to a temp dir and points `primer` / `resolve_token` /
 > `query_tokens` / `validate_usage` / `describe_component` /
 > `describe_guideline` / `list_guidelines` at it instead of the embedded
@@ -152,6 +155,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.12.0",
+  "version": "1.14.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.2.1",
-    "@adobe/design-data-wasm": "0.10.0",
-    "@adobe/spectrum-design-data": "3.2.5"
+    "@adobe/design-data": "3.2.2",
+    "@adobe/design-data-wasm": "0.10.1",
+    "@adobe/spectrum-design-data": "3.3.0"
   },
   "devDependencies": {
     "ava": "^6.0.1"

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.12.0"
+  version: "1.14.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
@@ -102,6 +102,15 @@ $schema=https://spectrum.adobe.com/page/design-token/
 
 > **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`
@@ -163,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/cascade-bootstrap.js

@@ -43,18 +43,64 @@ function resolveConfigDir(configPath) {
   return statSync(configPath).isDirectory() ? configPath : dirname(configPath);
 }
 
-function resolveManifestPath(configDir) {
+function resolveManifestPath(configDir, platformId) {
   const configPath = join(configDir, ".design-data.toml");
   if (!existsSync(configPath)) return null;
 
   const configText = readFileSync(configPath, "utf-8");
+
+  if (platformId) {
+    // Named `[platforms.<id>]` entries (spectrum-design-data-h890.27.3) are
+    // either a bare local path (`id = "platforms/id/manifest.json"`, matched
+    // here) or a remote `github`-sourced table. This regex only resolves the
+    // local-path shape — a remote platform entry's extensions/ catalogs still
+    // need fetching, which the CLI's `query` shell-out below does not surface
+    // to this file; local-path is the shape every platform incubating in this
+    // monorepo uses today (see platforms/README.md).
+    const idPattern = platformId.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const match = configText.match(
+      new RegExp(`^\\s*${idPattern}\\s*=\\s*["']([^"']+)["']\\s*$`, "m"),
+    );
+    if (!match) return null;
+    const manifestPath = join(configDir, match[1]);
+    return existsSync(manifestPath) ? manifestPath : null;
+  }
+
   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);
+/**
+ * Determine which named `[platforms.<id>]` entry, if any, the CLI would pick
+ * for the *tokens* cascade so catalog materialization can match it exactly.
+ * `config.platformId` (from `DESIGN_DATA_PLATFORM`) always wins; otherwise
+ * this asks the CLI which id `default_platform` resolves to, via
+ * `platform list --format json`, rather than re-implementing the CLI's own
+ * precedence rules (`--manifest` > `--platform` > `DESIGN_DATA_PLATFORM` >
+ * `default_platform` > legacy `manifest` key) in a second, drifting regex.
+ * Returns `null` on any failure (no platforms configured, CLI error,
+ * unparsable output) so callers fall back to the legacy `manifest` key.
+ */
+async function resolveActivePlatformId(configDir, config, run) {
+  if (config.platformId) return config.platformId;
+  try {
+    const { exitCode, stdout } = await run(
+      ["platform", "list", "--format", "json"],
+      { timeout: 10_000, cwd: configDir },
+    );
+    if (exitCode !== 0) return null;
+    const rows = JSON.parse(stdout);
+    const defaultRow = rows.find((row) => row.default);
+    if (!defaultRow || defaultRow.id === "(default)") return null;
+    return defaultRow.id;
+  } catch {
+    return null;
+  }
+}
+
+function materializeCatalogs(config, cascadeDir, configDir, activePlatformId) {
+  const manifestPath = resolveManifestPath(configDir, activePlatformId);
   let extensionsDir = null;
   if (manifestPath) {
     const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
@@ -119,7 +165,13 @@ function mergeGuidelineManifest(targetDir, extensionDir) {
 
 /**
  * Resolve `config.designDataConfig`'s cascade and populate
- * `config.cascadeDataPath` / `config.cascadeActive` with the result.
+ * `config.cascadeDataPath` / `config.cascadeActive` with the result. If
+ * `config.platformId` is set, selects that named `[platforms.<id>]` entry
+ * (spectrum-design-data-h890.27.14) — both for the CLI query shell-out and
+ * for materializing that platform's `extensions/` catalogs, instead of the
+ * legacy top-level `manifest` key. If `platformId` is unset but the config
+ * has a `default_platform`, `resolveActivePlatformId` discovers that id from
+ * the CLI itself so both halves still agree on the same platform.
  * Deliberately does not touch `config.dataPath`/`config.dataRoot` — those
  * remain the fallback anchors for unrelated write/authoring/data tools,
  * which must keep targeting the real dataset root, not the cascade's
@@ -144,10 +196,25 @@ export async function bootstrapCascade(config, { run = runCli } = {}) {
   }
 
   try {
-    const { exitCode, stdout, stderr } = await run(
-      ["query", "--filter", "", "--format", "json"],
-      { timeout: 60_000, cwd: configDir },
+    const activePlatformId = await resolveActivePlatformId(
+      configDir,
+      config,
+      run,
     );
+    const queryArgs = ["query", "--filter", "", "--format", "json"];
+    if (activePlatformId) {
+      // Must follow the subcommand — see the CLI's own --platform help text
+      // on this ordering limitation. Passing this explicitly (even when it
+      // only came from `default_platform`, not an explicit selection) keeps
+      // the token query and the catalog materialization below looking at
+      // the exact same platform, instead of letting the CLI's own default
+      // resolution and this file's manifest-path regex potentially disagree.
+      queryArgs.push("--platform", activePlatformId);
+    }
+    const { exitCode, stdout, stderr } = await run(queryArgs, {
+      timeout: 60_000,
+      cwd: configDir,
+    });
     if (exitCode !== 0) {
       throw new Error(stderr || `design-data exited with code ${exitCode}`);
     }
@@ -159,7 +226,7 @@ export async function bootstrapCascade(config, { run = runCli } = {}) {
       JSON.stringify(tokens),
       "utf-8",
     );
-    materializeCatalogs(config, dir, configDir);
+    materializeCatalogs(config, dir, configDir, activePlatformId);
 
     config.cascadeDataPath = dir;
     config.cascadeActive = true;

package/src/config.js

@@ -89,6 +89,12 @@ export const config = {
   // cascadeDataPath/cascadeActive below. Unset by default so an in-repo run's
   // ambient .design-data.toml (if any) doesn't surprise it.
   designDataConfig: anchorPath(process.env.DESIGN_DATA_CONFIG ?? null),
+  // Selects a named `[platforms.<id>]` entry from designDataConfig's
+  // `.design-data.toml` (spectrum-design-data-h890.27.14), mirroring the CLI's
+  // own `--platform`/`DESIGN_DATA_PLATFORM`. Has no effect unless
+  // designDataConfig is also set. Unset by default: falls back to the config's
+  // legacy top-level `manifest` key or `default_platform`, same as the CLI.
+  platformId: process.env.DESIGN_DATA_PLATFORM ?? null,
   // Set by cascade-bootstrap.js on a successful resolve: the temp dir holding
   // the materialized cascade dataset. Deliberately separate from dataPath —
   // dataPath/dataRoot are also the fallback anchors for unrelated

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/
@@ -286,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: