@adobe/design-data-agent-mcp 1.8.25 → 1.9.0

package/README.md

@@ -47,15 +47,27 @@ node tools/design-data-agent-mcp/src/index.js
 
 ### Environment variables
 
-| Variable                 | Default       | Description                                       |
-| ------------------------ | ------------- | ------------------------------------------------- |
-| `DESIGN_DATA_BIN`        | `design-data` | Path to the `design-data` binary (authoring only) |
-| `DESIGN_DATA_ROOT`       | —             | Absolute root that relative paths are anchored to |
-| `DESIGN_DATA_PATH`       | `.`           | Dataset root path                                 |
-| `DESIGN_DATA_COMPONENTS` | —             | Override components directory                     |
-| `DESIGN_DATA_FIELDS`     | —             | Override fields directory                         |
-| `DESIGN_DATA_SCHEMAS`    | —             | Override schema path (for `validate`)             |
-| `DESIGN_DATA_EXCEPTIONS` | —             | Override exceptions path (for `validate`)         |
+| Variable                 | Default       | Description                                                                    |
+| ------------------------ | ------------- | ------------------------------------------------------------------------------ |
+| `DESIGN_DATA_BIN`        | `design-data` | Path to the `design-data` binary (authoring only)                              |
+| `DESIGN_DATA_ROOT`       | —             | Absolute root that relative paths are anchored to                              |
+| `DESIGN_DATA_PATH`       | `.`           | Dataset root path                                                              |
+| `DESIGN_DATA_COMPONENTS` | —             | Override components directory                                                  |
+| `DESIGN_DATA_FIELDS`     | —             | Override fields directory                                                      |
+| `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 |
+
+> **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
+> 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` is unaffected — it always reads components from
+> `@adobe/spectrum-design-data` regardless of cascade state. 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.
 
 > **Path resolution.** The MCP client launches this server with the working
 > directory inherited from wherever the editor was opened — which may be a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/design-data-agent-mcp",
-  "version": "1.8.25",
+  "version": "1.9.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.0.5",
-    "@adobe/design-data-wasm": "0.5.0",
-    "@adobe/spectrum-design-data": "2.2.0"
+    "@adobe/design-data": "3.0.7",
+    "@adobe/design-data-wasm": "0.7.0",
+    "@adobe/spectrum-design-data": "2.3.0"
   },
   "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.8.25"
+  version: "1.9.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,

package/src/cascade-bootstrap.js

@@ -0,0 +1,90 @@
+// Copyright 2026 Adobe. All rights reserved.
+// This file is licensed to you under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License. You may obtain a copy
+// of the License at http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software distributed under
+// the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+// OF ANY KIND, either express or implied. See the License for the specific language
+// governing permissions and limitations under the License.
+
+/**
+ * Resolves a `.design-data.toml` platform source + manifest cascade once at
+ * startup, so the MCP's in-process read/validate tools (which only know how
+ * to read a local directory — see config.dataPath) see the platform-resolved
+ * dataset instead of the embedded Spectrum snapshot or a raw local dir.
+ *
+ * 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.
+ */
+
+import { existsSync, mkdtempSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { runCli } from "./cli.js";
+
+/** Directory containing `.design-data.toml`, given either path. */
+function resolveConfigDir(configPath) {
+  if (!existsSync(configPath)) return null;
+  return statSync(configPath).isDirectory() ? configPath : dirname(configPath);
+}
+
+/**
+ * Resolve `config.designDataConfig`'s cascade and populate
+ * `config.cascadeDataPath` / `config.cascadeActive` with the result.
+ * 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
+ * resolved snapshot. No-ops if `designDataConfig` is unset. Never throws —
+ * a failed resolve (e.g. no network for a github source) logs to stderr and
+ * leaves config untouched, so the server still starts against the
+ * embedded/local fallback.
+ *
+ * @param {object} config - The mutable config object from ./config.js.
+ * @param {{ run?: typeof runCli }} [opts] - `run` is injectable for tests.
+ */
+export async function bootstrapCascade(config, { run = runCli } = {}) {
+  if (!config.designDataConfig) return;
+
+  const configDir = resolveConfigDir(config.designDataConfig);
+  if (!configDir) {
+    console.error(
+      `[design-data-mcp] DESIGN_DATA_CONFIG "${config.designDataConfig}" not found; ` +
+        "ignoring, falling back to embedded/local dataset.",
+    );
+    return;
+  }
+
+  try {
+    const { exitCode, stdout, stderr } = await run(
+      ["query", "--filter", "", "--format", "json"],
+      { timeout: 60_000, cwd: configDir },
+    );
+    if (exitCode !== 0) {
+      throw new Error(stderr || `design-data exited with code ${exitCode}`);
+    }
+    const tokens = JSON.parse(stdout);
+
+    const dir = mkdtempSync(join(tmpdir(), "design-data-mcp-cascade-"));
+    writeFileSync(
+      join(dir, "resolved.tokens.json"),
+      JSON.stringify(tokens),
+      "utf-8",
+    );
+
+    config.cascadeDataPath = dir;
+    config.cascadeActive = true;
+    console.error(
+      `[design-data-mcp] cascade resolved from ${configDir} ` +
+        `(${tokens.length} tokens) -> ${dir}`,
+    );
+  } catch (err) {
+    console.error(
+      `[design-data-mcp] cascade bootstrap failed, falling back to embedded/local ` +
+        `dataset: ${err.message}`,
+    );
+  }
+}

package/src/cli.js

@@ -11,13 +11,15 @@
 import { spawn } from "child_process";
 import { config } from "./config.js";
 
-export function runCli(args, { timeout = 10_000, stdin } = {}) {
+export function runCli(args, { timeout = 10_000, stdin, cwd } = {}) {
   return new Promise((resolve, reject) => {
     const proc = spawn(config.bin, args, {
       // Anchor the CLI's working directory to the resolved data root so its own
       // tier/probe logic (data_source::resolve, is_in_repo) resolves correctly
       // even when Claude Code launched the server from a monorepo subdirectory.
-      cwd: config.dataRoot,
+      // `cwd` override lets the cascade bootstrap point the CLI at a
+      // `.design-data.toml` directory that differs from config.dataRoot.
+      cwd: cwd ?? config.dataRoot,
       // isolates CLI stdout from the MCP JSON-RPC stream on the parent's stdout
       stdio: [stdin != null ? "pipe" : "ignore", "pipe", "pipe"],
     });

package/src/config.js

@@ -78,4 +78,22 @@ export const config = {
     anchorPath(process.env.DESIGN_DATA_FIELDS) ??
     resolveDataPackageDir("fields") ??
     null,
+  // Path to a `.design-data.toml` (or its containing directory) declaring a
+  // platform source + manifest cascade. When set, cascade-bootstrap.js
+  // resolves it once at startup (via the CLI, which already knows how to
+  // fetch/cache a github source and apply the manifest) and populates
+  // 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),
+  // 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
+  // write/authoring/data tools (write.js, data.js, authoring.js), which must
+  // keep targeting the real dataset root regardless of cascade state. Only
+  // read.js/validate.js consult cascadeDataPath.
+  cascadeDataPath: null,
+  // Flipped to true by cascade-bootstrap.js on a successful resolve. Tools
+  // that otherwise default to the embedded Spectrum snapshot (primer,
+  // describe_component) check this to switch to cascadeDataPath instead.
+  cascadeActive: false,
 };

package/src/index.js

@@ -24,6 +24,8 @@ import { createReadTools } from "./tools/read.js";
 import { createValidateTools } from "./tools/validate.js";
 import { createDiffTools } from "./tools/diff.js";
 import { createWriteTools } from "./tools/write.js";
+import { bootstrapCascade } from "./cascade-bootstrap.js";
+import { config } from "./config.js";
 
 export function createAllTools() {
   return [
@@ -85,6 +87,7 @@ export function createMCPServer() {
 }
 
 async function startServer() {
+  await bootstrapCascade(config);
   const server = createMCPServer();
   const transport = new StdioServerTransport();
   await server.connect(transport);

package/src/tools/read.js

@@ -16,6 +16,16 @@
  *
  * Note: authoring_session_step_intent in authoring.js still uses the CLI because
  * the NLP suggest ranking is not yet on the wasm surface.
+ *
+ * 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
+ * does not — components/relationships still come from config.componentsDir /
+ * config.relationshipsDir, 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 schemas, so this is left out of scope
+ * rather than guessed at; revisit if a platform manifest starts declaring components.
  */
 
 import { readFileSync, existsSync, readdirSync } from "fs";
@@ -23,6 +33,13 @@ import { join } from "path";
 import { loadDataset } from "@adobe/design-data/load";
 import { config } from "../config.js";
 
+// Note: this module intentionally never spawns the native binary — primer and
+// describe_component must keep working with no CLI on PATH at all (see the
+// structural test in read.test.js). Cascade resolution happens once at startup
+// in cascade-bootstrap.js (which does spawn the binary); by the time these
+// handlers run, a cascade dataset is just another local directory at
+// config.dataPath.
+
 let _wasm;
 /** Lazy-load and cache the wasm module (nodejs target, no init() required). */
 async function getWasm() {
@@ -32,15 +49,22 @@ async function getWasm() {
 
 let _dataset;
 /**
- * Return the embedded Spectrum dataset, caching it after first access.
+ * Return the active dataset, caching it after first access.
+ *
+ * When cascade-bootstrap.js resolved a `.design-data.toml` platform source at
+ * startup (config.cascadeActive), config.cascadeDataPath is a local dir holding
+ * the resolved cascade — load that instead of the embedded Spectrum snapshot,
+ * the same way resolve_token/query_tokens already do. cascadeActive is decided
+ * once at startup before any request runs, so caching here is safe.
  *
  * Dataset.embedded() clones the in-memory graph on every call; caching here
- * avoids that per-request cost.
+ * avoids that per-request cost either way.
  */
 async function getDataset() {
   if (!_dataset) {
-    const wasm = await getWasm();
-    _dataset = wasm.Dataset.embedded();
+    _dataset = config.cascadeActive
+      ? await loadDataset(config.cascadeDataPath)
+      : (await getWasm()).Dataset.embedded();
   }
   return _dataset;
 }
@@ -87,7 +111,7 @@ export function createReadTools() {
           // top-level source is the legacy skill-contract field; provenance.source
           // duplicates it intentionally — provenance is the richer metrics object
           // and consumers should prefer it going forward.
-          source: "embedded",
+          source: config.cascadeActive ? "cascade" : "embedded",
           tokenCount: ds.tokenCount(),
           modeSets: {
             colorScheme: wasm.getFieldValues("colorScheme") ?? [],
@@ -136,7 +160,9 @@ export function createReadTools() {
         additionalProperties: false,
       },
       async handler({ property, colorScheme, scale, contrast }) {
-        const ds = await loadDataset(config.dataPath);
+        const ds = await loadDataset(
+          config.cascadeActive ? config.cascadeDataPath : config.dataPath,
+        );
         const context = {};
         if (colorScheme) context.colorScheme = colorScheme;
         if (scale) context.scale = scale;
@@ -167,7 +193,9 @@ export function createReadTools() {
         additionalProperties: false,
       },
       async handler({ filter }) {
-        const ds = await loadDataset(config.dataPath);
+        const ds = await loadDataset(
+          config.cascadeActive ? config.cascadeDataPath : config.dataPath,
+        );
         return ds.query(filter);
       },
     },

package/src/tools/validate.js

@@ -38,7 +38,9 @@ export function createValidateTools() {
         additionalProperties: false,
       },
       async handler({ path, strict, schema_path } = {}) {
-        const target = path ?? config.dataPath;
+        const target =
+          path ??
+          (config.cascadeActive ? config.cascadeDataPath : config.dataPath);
         const schemaPath = schema_path ?? config.schemaPath ?? null;
         // NOTE: exceptionsPath (DESIGN_DATA_EXCEPTIONS / --exceptions-path) applies to the
         // SPEC-007 naming rule in the relational layer. The in-process wasm validate() does