@adobe/design-data-agent-mcp 1.3.1 → 1.5.0

package/LICENSE

@@ -186,7 +186,7 @@ file or class name and description of purpose be included on the
 same "printed page" as the copyright notice for easier
 identification within third-party archives.
 
-Copyright 2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+Copyright 2026 Adobe
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

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-spec/) agent surface. Shells out to the `design-data` CLI — all logic stays in the Rust SDK.
+MCP server and Claude Code skill for the [Spectrum Design Data](../../packages/design-data/) agent surface. Shells out to the `design-data` CLI — all logic stays in the Rust SDK.
 
 ## Install
 
@@ -47,15 +47,38 @@ 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          |
-| `DESIGN_DATA_PATH`       | `.`           | Dataset root path                         |
-| `DESIGN_DATA_COMPONENTS` | —             | Override components directory             |
-| `DESIGN_DATA_FIELDS`     | —             | Override fields directory                 |
-| `DESIGN_DATA_DIMENSIONS` | —             | Override dimensions 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                  |
+| `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`)         |
+
+> **Path resolution.** The MCP client launches this server with the working
+> directory inherited from wherever the editor was opened — which may be a
+> subdirectory of your repo (e.g. `sdk/`), not the repo root. To stay independent
+> of that working directory, each data path is resolved in this order:
+>
+> 1. **Explicit env override.** If `DESIGN_DATA_PATH` / `DESIGN_DATA_COMPONENTS` /
+>    `DESIGN_DATA_FIELDS` is set, it is used. Relative values are anchored to
+>    `DESIGN_DATA_ROOT` (absolute, recommended when launching via `npx`) or, if
+>    that is unset, to the server package's own location in the monorepo. Absolute
+>    values are used as-is.
+> 2. **Resolved `@adobe/spectrum-design-data` package** (zero config). When no env
+>    override is set, the server resolves the installed `@adobe/spectrum-design-data`
+>    package via Node module resolution and reads its `tokens/`, `components/`, and
+>    `fields/` directories. In a pnpm workspace this follows the symlink to
+>    `packages/design-data`; when published it uses the installed dependency. This
+>    is independent of the working directory.
+> 3. **Fallback.** `dataPath` falls back to the (anchored) current directory; the
+>    component/field overrides fall back to the `design-data` binary's own
+>    discovery (including its embedded snapshot).
+>
+> In a monorepo checkout you typically need no `DESIGN_DATA_*` env vars at all —
+> resolution via the workspace package handles it.
 
 ### Example (Cursor `.cursor/mcp.json`)
 
@@ -66,10 +89,10 @@ node tools/design-data-agent-mcp/src/index.js
       "command": "npx",
       "args": ["-y", "@adobe/design-data-agent-mcp"],
       "env": {
-        "DESIGN_DATA_PATH": "./packages/tokens/src",
-        "DESIGN_DATA_COMPONENTS": "./packages/design-data-spec/components",
-        "DESIGN_DATA_FIELDS": "./packages/design-data-spec/fields",
-        "DESIGN_DATA_DIMENSIONS": "./packages/design-data-spec/dimensions"
+        "DESIGN_DATA_ROOT": "/abs/path/to/your/repo",
+        "DESIGN_DATA_PATH": "packages/design-data/tokens",
+        "DESIGN_DATA_COMPONENTS": "packages/design-data/components",
+        "DESIGN_DATA_FIELDS": "packages/design-data/fields"
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/design-data-agent-mcp",
-  "version": "1.3.1",
+  "version": "1.5.0",
   "description": "MCP server and Claude Code skill for the design-data agent surface — shells out to the design-data CLI",
   "type": "module",
   "main": "./src/index.js",
@@ -29,7 +29,10 @@
     "provenance": true
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.27.1"
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@adobe/design-data": "2.0.0",
+    "@adobe/design-data-wasm": "0.1.0",
+    "@adobe/spectrum-design-data": "0.3.0"
   },
   "devDependencies": {
     "ava": "^6.0.1"

package/skills/design-data/SKILL.md

@@ -2,80 +2,76 @@
 name: design-data-agent
 description: >
   Validate, query, resolve, diff, and author spec-conformant design tokens and components using the
-  design-data CLI against a local dataset. Use when the user asks about design tokens, a design
+  design-data MCP tools against a local dataset. Use when the user asks about design tokens, a design
   system, token lookup, spec-conformance, drift detection, or token authoring on custom data.
 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: Bash(npx @adobe/design-data *)
+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
 ---
 
 # design-data agent skill
 
-`design-data` is the reference CLI for the Spectrum Design Data specification. It validates, queries, resolves, and authors spec-conformant tokens and components from any dataset on the local filesystem.
+`@adobe/design-data-agent-mcp` provides in-process wasm tools for validating, querying,
+resolving, diffing, and authoring spec-conformant tokens and components from any dataset
+on the local filesystem.
 
-Set two path variables once and reference them throughout. The token dataset and the spec catalog (components, fields, dimensions) live in separate directories:
+Set two path variables once and reference them throughout:
 
 ```bash
-export DESIGN_DATA_PATH=./packages/tokens/src
-export DESIGN_DATA_SPEC_PATH=./packages/design-data-spec
+export DESIGN_DATA_PATH=./packages/design-data/tokens
+export DESIGN_DATA_SPEC_PATH=./packages/design-data
 ```
 
 For Spectrum tokens with zero setup (embedded snapshot), use the `design-data` skill instead — this skill targets custom or repo-local datasets.
 
 ## Bootstrap
 
-On first use, ensure the CLI is available:
+Add `@adobe/design-data-agent-mcp` to your `.cursor/mcp.json`:
 
+```json
+{
+  "mcpServers": {
+    "design-data-agent": {
+      "command": "npx",
+      "args": ["-y", "@adobe/design-data-agent-mcp"],
+      "env": {
+        "DESIGN_DATA_PATH": "./packages/tokens/src",
+        "DESIGN_DATA_COMPONENTS": "./packages/design-data/components",
+        "DESIGN_DATA_FIELDS": "./packages/design-data/fields"
+      }
+    }
+  }
+}
 ```
-npx @adobe/design-data --version
-```
+
+Adjust paths to match your dataset layout.
 
 ***
 
 ## Session start — call `primer` first
 
-Call `primer` at the start of every session that touches design data. It returns the active dimensions, component list, taxonomy fields, and token count — structural context that scopes all subsequent lookups.
-
-```bash
-npx @adobe/design-data primer "$DESIGN_DATA_PATH" --format json \
-  --components-dir "$DESIGN_DATA_SPEC_PATH/components" \
-  --fields-dir     "$DESIGN_DATA_SPEC_PATH/fields" \
-  --dimensions-dir "$DESIGN_DATA_SPEC_PATH/dimensions"
-```
-
-Always pass `--components-dir`, `--fields-dir`, and `--dimensions-dir` explicitly. These directories live under `packages/design-data-spec/`, not under the token dataset. The CLI defaults probe those paths relative to CWD, so omitting the flags when running from an arbitrary directory (or with an absolute `DESIGN_DATA_PATH`) produces empty `components`, `taxonomyFields`, and `dimensions`.
-
-The payload includes `specVersion`, `manifest`, `dimensions`, `components`, `taxonomyFields`, and `tokenCount`.
+Call `primer` at the start of every session that touches design data. It returns the active
+dimensions, component list, taxonomy fields, and token count — structural context that scopes
+all subsequent lookups. No inputs required.
 
 ***
 
 ## Token lookup
 
-### Resolve a token to its literal value
+### Resolve a token to its literal value — `resolve_token`
 
-```bash
-npx @adobe/design-data resolve <property> "$DESIGN_DATA_PATH" --format json \
-  [--color-scheme light|dark] \
-  [--scale desktop|mobile] \
-  [--contrast regular|high]
-```
+Required: `property` (string) — e.g. `"accent-background-color-default"`
+Optional: `colorScheme` (`"light"` or `"dark"`), `scale` (`"desktop"` or `"mobile"`),
+`contrast` (`"regular"` or `"high"`)
 
-Example:
+### Query tokens by filter expression — `query_tokens`
 
-```bash
-npx @adobe/design-data resolve accent-background-color-default "$DESIGN_DATA_PATH" \
-  --format json --color-scheme dark --scale desktop
-```
-
-### Query tokens by filter expression
+Required: `filter` (string)
 
-```bash
-npx @adobe/design-data query "$DESIGN_DATA_PATH" --filter "<expr>" --format json
-```
-
-Valid filter keys: `property`, `component`, `variant`, `state`, `colorScheme`, `scale`, `contrast`, `uuid`, `$schema`. Any other key is a parse error. The dimension keys (`colorScheme`, `scale`, `contrast`) accept the same enum values as the `resolve` flags (`light`/`dark`, `desktop`/`mobile`, `regular`/`high`).
+Valid filter keys: `property`, `component`, `variant`, `state`, `colorScheme`, `scale`,
+`contrast`, `uuid`, `$schema`.
 
 Filter syntax examples:
 
@@ -88,64 +84,71 @@ property=background-color|property=border-color
 $schema=https://spectrum.adobe.com/page/design-token/
 ```
 
-> **Exit codes:** `0` = matches found; `1` = no matches (returns `[]` — not an error); `>1` = error.
+> **Exit codes:** `0` = matches found; empty array = no matches (not an error).
 
 ***
 
-## Component info
+## Component info — `describe_component`
 
-```bash
-npx @adobe/design-data component <id> --components-dir "$DESIGN_DATA_SPEC_PATH/components"
-```
+Required: `id` (string) — kebab-case component ID, e.g. `button`, `action-button`
 
-Returns the component contract: `name`, `displayName`, `options`, `anatomy`, `states`, and `tokenBindings`. Output is always JSON; there is no `--format` flag on this subcommand.
+Returns the component contract: `name`, `displayName`, `options`, `anatomy`, `states`,
+and `tokenBindings`.
 
-Pass `--components-dir` explicitly for the same reason as `primer` — the default probes CWD-relative paths that won't resolve in agent contexts.
+***
 
-Example:
+## Validation — `validate_usage`
 
-```bash
-npx @adobe/design-data component button --components-dir "$DESIGN_DATA_SPEC_PATH/components"
-```
+Optional inputs:
+
+* `path` — dataset path (defaults to `DESIGN_DATA_PATH`)
+* `strict` (boolean) — treat warnings as errors
+* `schema_path` — override schemas directory (defaults to `@adobe/spectrum-tokens` schemas)
+
+Runs Layer-1 JSON-Schema structural validation and Layer-2 relational rules.
+Returns `{ valid, errors, warnings }`.
+
+> **Note:** `--exceptions-path` (SPEC-007 naming allowlist) is not supported in the
+> in-process path. Use the `design-data` CLI directly if you need exceptions support.
 
 ***
 
-## Validation
+## Dataset diff — `diff_datasets`
 
-```bash
-npx @adobe/design-data validate "$DESIGN_DATA_PATH" --format json \
-  [--schema-path <path>] \
-  [--exceptions-path <path>] \
-  [--strict]
-```
+Required: `oldPath`, `newPath`
+Optional: `filter` (substring to narrow results by token name)
 
-Returns a `ValidationReport` object: `{ layer: 1|2, errors: [...], warnings: [...] }` where each diagnostic has `rule_id` (e.g. `"SPEC-002"`), `severity` (`"error"` | `"warning"`), and `message`. Layer 1 is schema validation; Layer 2 is cascade-rule validation. `--strict` treats warnings as errors.
+Returns `{ renamed, deprecated, reverted, added, deleted, updated }`.
 
 ***
 
-## Dataset diff
+## Product-layer authoring — `write`
 
-```bash
-npx @adobe/design-data diff <old-path> <new-path> --format json [--filter <expr>]
-```
+Write or update the product context document in the dataset.
 
-> **Exit codes:** `0` = no changes; `1` = differences found (returns JSON diff — not an error); `>1` = error.
+Optional inputs: `output` (defaults to `$DESIGN_DATA_PATH/product-context.json`),
+`rationale` (string)
 
 ***
 
-## Product-layer authoring
+## Token authoring session
 
-Write or update the product context document in the dataset:
+Use the following tools in sequence to create a new token through the wizard:
 
-```bash
-npx @adobe/design-data write \
-  --output "$DESIGN_DATA_PATH/product-context.json" \
-  --rationale "Why these overrides exist"
-```
+1. **`start_authoring_session`** — start a session (returns `session_id`)
+2. **`authoring_session_step_intent`** — provide natural-language intent; get token suggestions
+3. **`authoring_session_step_classification`** — set layer, property, name fields
+4. **`authoring_session_step_values`** — set mode-specific value rows
+5. **`authoring_session_commit`** — validate and write the token to disk
+6. **`authoring_session_cancel`** — cancel without writing
 
-Always pass `--output` with an explicit path inside the dataset. The default resolves relative to CWD, which is rarely correct in agent contexts.
+Helper tools: `authoring_session_get` (inspect state), `authoring_session_list` (all active sessions).
 
-Generates a product-context scaffold at the output path (`specVersion`, `layer: "product"`, `rationale`, attribution metadata). Creates the file if absent; overwrites if it already exists. The confirmation string returned to stdout on success is a plain text message — not JSON.
+`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.
 
 ***
 
@@ -153,9 +156,8 @@ Generates a product-context scaffold at the output path (`specVersion`, `layer:
 
 * **Scale values:** `desktop` and `mobile` — not `medium`/`large`.
 * **Contrast values:** `regular` and `high` — not `standard`/`high`.
-* **`query` exit 1** means no matches and still emits `[]`. Only `>1` is an error.
-* **`diff` exit 1** means changes were found. The JSON diff is in stdout — still a success result.
-* **`--format json`** — always pass this in agent and script contexts; the CLI pretty-prints when stdout is a TTY.
+* **`query_tokens` returns `[]`** when no tokens match — not an error.
+* **`diff_datasets` filter** matches by token name substring (case-insensitive).
 
 ## When working in Cursor
 
@@ -164,24 +166,3 @@ Cursor Settings → Rules → **Add Rule** → **Remote Rule (GitHub)** → past
 ```
 https://github.com/adobe/spectrum-design-data/tree/main/tools/design-data-agent-mcp/skills/design-data
 ```
-
-For always-available tool access (higher context cost), add `@adobe/design-data-agent-mcp` to `.cursor/mcp.json`:
-
-```json
-{
-  "mcpServers": {
-    "design-data-agent": {
-      "command": "npx",
-      "args": ["-y", "@adobe/design-data-agent-mcp"],
-      "env": {
-        "DESIGN_DATA_PATH": "./packages/tokens/src",
-        "DESIGN_DATA_COMPONENTS": "./packages/design-data-spec/components",
-        "DESIGN_DATA_FIELDS": "./packages/design-data-spec/fields",
-        "DESIGN_DATA_DIMENSIONS": "./packages/design-data-spec/dimensions"
-      }
-    }
-  }
-}
-```
-
-Adjust paths to match your dataset layout.

package/src/cli.js

@@ -14,6 +14,10 @@ import { config } from "./config.js";
 export function runCli(args, { timeout = 10_000 } = {}) {
   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,
       // isolates CLI stdout from the MCP JSON-RPC stream on the parent's stdout
       stdio: ["ignore", "pipe", "pipe"],
     });

package/src/config.js

@@ -8,12 +8,70 @@
 // OF ANY KIND, either express or implied. See the License for the specific language
 // governing permissions and limitations under the License.
 
+import { createRequire } from "module";
+import { fileURLToPath } from "url";
+import { dirname, isAbsolute, resolve } from "path";
+
+// The repo root relative to this file: src → package → tools → repo root.
+// Used as the self-anchoring fallback when DESIGN_DATA_ROOT is not provided
+// and the server is run from inside the monorepo checkout.
+const SERVER_ROOT = fileURLToPath(new URL("../../..", import.meta.url));
+
+// Claude Code launches the MCP server with the working directory inherited from
+// wherever the editor was opened (e.g. `sdk/`), not the repo root. Relative
+// DESIGN_DATA_* paths must therefore be anchored to a known root rather than the
+// process CWD. Prefer an explicit absolute DESIGN_DATA_ROOT (works even when the
+// server is launched via `npx` from the npm cache); fall back to SERVER_ROOT for
+// in-repo runs.
+const dataRoot = process.env.DESIGN_DATA_ROOT
+  ? resolve(process.env.DESIGN_DATA_ROOT)
+  : SERVER_ROOT;
+
+function anchorPath(p) {
+  return p && !isAbsolute(p) ? resolve(dataRoot, p) : p;
+}
+
+// Locate a directory inside the @adobe/spectrum-design-data package via Node's
+// module resolution. In a pnpm workspace this resolves through the symlink to
+// `packages/design-data`; when published it resolves the installed dependency.
+// Either way it is independent of the process working directory, so it provides
+// a zero-config default that does not depend on where the server was launched.
+// Returns null when the package is not installed (e.g. a standalone CLI install
+// that relies on the design-data binary's embedded snapshot instead).
+function resolveDataPackageDir(subdir) {
+  try {
+    const pkgJson = createRequire(import.meta.url).resolve(
+      "@adobe/spectrum-design-data/package.json",
+    );
+    return resolve(dirname(pkgJson), subdir);
+  } catch {
+    return null;
+  }
+}
+
+// Path precedence: explicit env override (anchored to dataRoot) wins, then the
+// resolved design-data package directory, then a final fallback.
+//
+// The fallback differs by field on purpose: `dataPath` is a required positional
+// CLI argument, so it falls back to the anchored current directory. `componentsDir`
+// and `fieldsDir` are optional `--components-dir`/`--fields-dir` flags, so they fall
+// back to `null` (flag omitted) and let the design-data binary's own discovery —
+// including its embedded snapshot — locate them.
 export const config = {
   bin: process.env.DESIGN_DATA_BIN ?? "design-data",
-  dataPath: process.env.DESIGN_DATA_PATH ?? ".",
-  schemaPath: process.env.DESIGN_DATA_SCHEMAS ?? null,
-  exceptionsPath: process.env.DESIGN_DATA_EXCEPTIONS ?? null,
-  componentsDir: process.env.DESIGN_DATA_COMPONENTS ?? null,
-  fieldsDir: process.env.DESIGN_DATA_FIELDS ?? null,
-  dimensionsDir: process.env.DESIGN_DATA_DIMENSIONS ?? null,
+  dataRoot,
+  dataPath:
+    anchorPath(process.env.DESIGN_DATA_PATH) ??
+    resolveDataPackageDir("tokens") ??
+    anchorPath("."),
+  schemaPath: anchorPath(process.env.DESIGN_DATA_SCHEMAS ?? null),
+  exceptionsPath: anchorPath(process.env.DESIGN_DATA_EXCEPTIONS ?? null),
+  componentsDir:
+    anchorPath(process.env.DESIGN_DATA_COMPONENTS) ??
+    resolveDataPackageDir("components") ??
+    null,
+  fieldsDir:
+    anchorPath(process.env.DESIGN_DATA_FIELDS) ??
+    resolveDataPackageDir("fields") ??
+    null,
 };

package/src/tools/authoring.js

@@ -8,21 +8,27 @@
 // OF ANY KIND, either express or implied. See the License for the specific language
 // governing permissions and limitations under the License.
 
-//! MCP authoring-session tools (RFC #973 Q4).
-//!
-//! Each tool maps to one `design-data authoring-session` CLI subcommand.
-//! State is held on disk (one JSON file per session); the CLI is stateless.
+/**
+ * Authoring-session tools for design-data-agent-mcp.
+ *
+ * Most operations use @adobe/design-data (on-disk session store) and run
+ * fully in-process. The exception is authoring_session_step_intent, which still
+ * delegates to the CLI because the NLP `suggest` ranking is not yet on the wasm
+ * surface. When that API is added, step_intent can be migrated here too.
+ */
 
+import {
+  startSession,
+  getSession,
+  listSessions,
+  stepClassification,
+  stepValues,
+  commitSession,
+  cancelSession,
+} from "@adobe/design-data/session";
 import { runCli } from "../cli.js";
 import { config } from "../config.js";
 
-async function callCli(args) {
-  const { exitCode, stdout, stderr } = await runCli(args, { timeout: 30_000 });
-  if (exitCode !== 0)
-    throw new Error(stderr || `authoring-session exited ${exitCode}`);
-  return JSON.parse(stdout);
-}
-
 export function createAuthoringTools() {
   return [
     {
@@ -48,7 +54,7 @@ export function createAuthoringTools() {
             "dataset_path is required (or set DESIGN_DATA_PATH in the environment)",
           );
         }
-        return callCli(["authoring-session", "start", path]);
+        return startSession(path);
       },
     },
 
@@ -71,15 +77,25 @@ export function createAuthoringTools() {
         additionalProperties: false,
       },
       async handler({ session_id, intent }) {
-        return callCli([
-          "authoring-session",
-          "step",
-          "intent",
-          "--session-id",
-          session_id,
-          "--intent",
-          intent,
-        ]);
+        // step_intent requires NLP suggest ranking — still uses the CLI.
+        // Will be migrated when suggest is added to the wasm surface.
+        const { exitCode, stdout, stderr } = await runCli(
+          [
+            "authoring-session",
+            "step",
+            "intent",
+            "--session-id",
+            session_id,
+            "--intent",
+            intent,
+          ],
+          { timeout: 30_000 },
+        );
+        if (exitCode !== 0)
+          throw new Error(
+            stderr || `authoring-session step intent exited ${exitCode}`,
+          );
+        return JSON.parse(stdout);
       },
     },
 
@@ -118,21 +134,11 @@ export function createAuthoringTools() {
         additionalProperties: false,
       },
       async handler({ session_id, layer, property, name_fields = [] }) {
-        const args = [
-          "authoring-session",
-          "step",
-          "classification",
-          "--session-id",
-          session_id,
-          "--layer",
+        return stepClassification(session_id, {
           layer,
-          "--property",
           property,
-        ];
-        for (const { key, value } of name_fields) {
-          args.push("--name-field", `${key}=${value}`);
-        }
-        return callCli(args);
+          nameFields: name_fields,
+        });
       },
     },
 
@@ -174,15 +180,7 @@ export function createAuthoringTools() {
         additionalProperties: false,
       },
       async handler({ session_id, rows }) {
-        return callCli([
-          "authoring-session",
-          "step",
-          "values",
-          "--session-id",
-          session_id,
-          "--rows",
-          JSON.stringify(rows),
-        ]);
+        return stepValues(session_id, rows);
       },
     },
 
@@ -217,7 +215,9 @@ export function createAuthoringTools() {
           schema_path: {
             type: "string",
             description:
-              "Path to schemas directory. Defaults to packages/tokens/schemas relative to target.",
+              "Path to schemas directory containing token-types/ and token-file.json. " +
+              "Used for Layer-1 JSON-Schema validation before writing. " +
+              "Defaults to @adobe/spectrum-tokens schemas when omitted.",
           },
           is_override: {
             type: "boolean",
@@ -236,22 +236,15 @@ export function createAuthoringTools() {
         schema_path,
         is_override = false,
       }) {
-        const args = [
-          "authoring-session",
-          "commit",
-          "--session-id",
-          session_id,
-          "--schema-url",
-          schema_url,
-          "--target",
+        return commitSession({
+          sessionId: session_id,
+          schemaUrl: schema_url,
           target,
-          "--rationale",
           rationale,
-        ];
-        if (product_context) args.push("--product-context", product_context);
-        if (schema_path) args.push("--schema-path", schema_path);
-        if (is_override) args.push("--is-override");
-        return callCli(args);
+          productContext: product_context,
+          schemaPath: schema_path ?? null,
+          isOverride: is_override,
+        });
       },
     },
 
@@ -261,18 +254,11 @@ export function createAuthoringTools() {
       inputSchema: {
         type: "object",
         required: ["session_id"],
-        properties: {
-          session_id: { type: "string" },
-        },
+        properties: { session_id: { type: "string" } },
         additionalProperties: false,
       },
       async handler({ session_id }) {
-        return callCli([
-          "authoring-session",
-          "cancel",
-          "--session-id",
-          session_id,
-        ]);
+        return cancelSession(session_id);
       },
     },
 
@@ -282,18 +268,11 @@ export function createAuthoringTools() {
       inputSchema: {
         type: "object",
         required: ["session_id"],
-        properties: {
-          session_id: { type: "string" },
-        },
+        properties: { session_id: { type: "string" } },
         additionalProperties: false,
       },
       async handler({ session_id }) {
-        return callCli([
-          "authoring-session",
-          "get",
-          "--session-id",
-          session_id,
-        ]);
+        return getSession(session_id);
       },
     },
 
@@ -306,7 +285,7 @@ export function createAuthoringTools() {
         additionalProperties: false,
       },
       async handler() {
-        return callCli(["authoring-session", "list"]);
+        return listSessions();
       },
     },
   ];

package/src/tools/diff.js

@@ -8,7 +8,32 @@
 // OF ANY KIND, either express or implied. See the License for the specific language
 // governing permissions and limitations under the License.
 
-import { runCli } from "../cli.js";
+import { loadDataset } from "@adobe/design-data/load";
+
+/**
+ * Filter a diff result by a substring match against token names.
+ *
+ * The diff() return shape uses camelCase (per wasm serde rename_all = "camelCase"):
+ *   - renamed entries: { oldName, newName, ... }
+ *   - all other entries: { name, ... }
+ *
+ * @param {object} diff - DiffResult from Dataset.diff().
+ * @param {string} filter - Substring to match (case-insensitive).
+ * @returns {object} Filtered diff with the same top-level keys.
+ */
+export function filterDiffByName(diff, filter) {
+  const f = filter.toLowerCase();
+  const matchName = (t) =>
+    [t.name, t.oldName, t.newName].some((n) => n?.toLowerCase().includes(f));
+  return {
+    renamed: diff.renamed.filter(matchName),
+    deprecated: diff.deprecated.filter(matchName),
+    reverted: diff.reverted.filter(matchName),
+    added: diff.added.filter(matchName),
+    deleted: diff.deleted.filter(matchName),
+    updated: diff.updated.filter(matchName),
+  };
+}
 
 export function createDiffTools() {
   return [
@@ -36,12 +61,13 @@ export function createDiffTools() {
         additionalProperties: false,
       },
       async handler({ oldPath, newPath, filter }) {
-        const args = ["diff", oldPath, newPath, "--format", "json"];
-        if (filter) args.push("--filter", filter);
-        const { exitCode, stdout, stderr } = await runCli(args);
-        // exit code 1 means differences found — that is a valid result, not an error
-        if (exitCode > 1) throw new Error(stderr || `diff exited ${exitCode}`);
-        return JSON.parse(stdout);
+        const [oldDs, newDs] = await Promise.all([
+          loadDataset(oldPath),
+          loadDataset(newPath),
+        ]);
+        const diff = oldDs.diff(newDs);
+        if (!filter) return diff;
+        return filterDiffByName(diff, filter);
       },
     },
   ];

package/src/tools/read.js

@@ -8,6 +8,19 @@
 // OF ANY KIND, either express or implied. See the License for the specific language
 // governing permissions and limitations under the License.
 
+/**
+ * Read tools for design-data-agent-mcp.
+ *
+ * query_tokens and resolve_token use @adobe/design-data (loadDataset) + the
+ * wasm Dataset to run in-process without spawning the CLI binary.
+ *
+ * primer and describe_component still invoke the CLI: primer aggregates complex
+ * catalog metadata (components, fields) not yet on the wasm surface, and
+ * describe_component requires the components catalog path resolution that the CLI
+ * handles. These will be ported when those APIs are added to the wasm surface.
+ */
+
+import { loadDataset } from "@adobe/design-data/load";
 import { runCli } from "../cli.js";
 import { config } from "../config.js";
 
@@ -27,14 +40,13 @@ export function createReadTools() {
         if (config.componentsDir)
           args.push("--components-dir", config.componentsDir);
         if (config.fieldsDir) args.push("--fields-dir", config.fieldsDir);
-        if (config.dimensionsDir)
-          args.push("--dimensions-dir", config.dimensionsDir);
         const { exitCode, stdout, stderr } = await runCli(args);
         if (exitCode !== 0)
           throw new Error(stderr || `primer exited ${exitCode}`);
         return JSON.parse(stdout);
       },
     },
+
     {
       name: "resolve_token",
       description:
@@ -66,19 +78,21 @@ export function createReadTools() {
         additionalProperties: false,
       },
       async handler({ property, colorScheme, scale, contrast }) {
-        const args = ["resolve", property, config.dataPath, "--format", "json"];
-        // resolve uses --dimensions-path (old flag name, not --dimensions-dir)
-        if (config.dimensionsDir)
-          args.push("--dimensions-path", config.dimensionsDir);
-        if (colorScheme) args.push("--color-scheme", colorScheme);
-        if (scale) args.push("--scale", scale);
-        if (contrast) args.push("--contrast", contrast);
-        const { exitCode, stdout, stderr } = await runCli(args);
-        if (exitCode !== 0)
-          throw new Error(stderr || `resolve exited ${exitCode}`);
-        return JSON.parse(stdout);
+        const ds = await loadDataset(config.dataPath);
+        const context = {};
+        if (colorScheme) context.colorScheme = colorScheme;
+        if (scale) context.scale = scale;
+        if (contrast) context.contrast = contrast;
+        const result = ds.resolve(property, context);
+        if (!result) {
+          throw new Error(
+            `No token found for property "${property}" in context ${JSON.stringify(context)}`,
+          );
+        }
+        return result;
       },
     },
+
     {
       name: "query_tokens",
       description:
@@ -95,20 +109,11 @@ export function createReadTools() {
         additionalProperties: false,
       },
       async handler({ filter }) {
-        const args = [
-          "query",
-          config.dataPath,
-          "--filter",
-          filter,
-          "--format",
-          "json",
-        ];
-        const { exitCode, stdout, stderr } = await runCli(args);
-        // exit code 1 means no matches — still valid JSON []
-        if (exitCode > 1) throw new Error(stderr || `query exited ${exitCode}`);
-        return JSON.parse(stdout);
+        const ds = await loadDataset(config.dataPath);
+        return ds.query(filter);
       },
     },
+
     {
       name: "describe_component",
       description:

package/src/tools/validate.js

@@ -8,7 +8,7 @@
 // OF ANY KIND, either express or implied. See the License for the specific language
 // governing permissions and limitations under the License.
 
-import { runCli } from "../cli.js";
+import { validateDataset } from "@adobe/design-data/validate";
 import { config } from "../config.js";
 
 export function createValidateTools() {
@@ -16,7 +16,8 @@ export function createValidateTools() {
     {
       name: "validate_usage",
       description:
-        "Validate design token usage in a dataset. Returns a JSON report of violations and warnings.",
+        "Validate design token usage in a dataset. Runs Layer-1 JSON-Schema structural " +
+        "validation and Layer-2 relational rules. Returns a JSON report of violations and warnings.",
       inputSchema: {
         type: "object",
         properties: {
@@ -26,23 +27,24 @@ export function createValidateTools() {
               "Path to dataset to validate (defaults to DESIGN_DATA_PATH)",
           },
           strict: { type: "boolean", description: "Treat warnings as errors" },
+          schema_path: {
+            type: "string",
+            description:
+              "Path to schemas directory containing token-types/ and token-file.json. " +
+              "Defaults to @adobe/spectrum-tokens schemas. Set DESIGN_DATA_SCHEMAS env var or " +
+              "pass explicitly for custom schema sets.",
+          },
         },
         additionalProperties: false,
       },
-      async handler({ path, strict } = {}) {
+      async handler({ path, strict, schema_path } = {}) {
         const target = path ?? config.dataPath;
-        const args = ["validate", target, "--format", "json"];
-        if (config.schemaPath) args.push("--schema-path", config.schemaPath);
-        if (config.exceptionsPath)
-          args.push("--exceptions-path", config.exceptionsPath);
-        // validate uses --dimensions-path (old flag name, not --dimensions-dir)
-        if (config.dimensionsDir)
-          args.push("--dimensions-path", config.dimensionsDir);
-        if (strict === true) args.push("--strict");
-        const { exitCode, stdout, stderr } = await runCli(args);
-        if (exitCode !== 0 && !stdout)
-          throw new Error(stderr || `validate exited ${exitCode}`);
-        return JSON.parse(stdout);
+        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
+        // not consume it. Passing exceptionsPath here would throw an explicit error from
+        // validateDataset — omit it and document the limitation.
+        return validateDataset(target, { schemaPath, strict: strict ?? false });
       },
     },
   ];

package/src/tools/write.js

@@ -9,7 +9,7 @@
 // governing permissions and limitations under the License.
 
 import { join } from "path";
-import { runCli } from "../cli.js";
+import { writeProductContext } from "@adobe/design-data/write";
 import { config } from "../config.js";
 
 export function createWriteTools() {
@@ -36,12 +36,7 @@ export function createWriteTools() {
       async handler({ output, rationale } = {}) {
         const resolvedOutput =
           output ?? join(config.dataPath, "product-context.json");
-        const args = ["write", "--output", resolvedOutput];
-        if (rationale) args.push("--rationale", rationale);
-        const { exitCode, stdout, stderr } = await runCli(args);
-        if (exitCode !== 0)
-          throw new Error(stderr || `write exited ${exitCode}`);
-        return stdout;
+        return writeProductContext({ output: resolvedOutput, rationale });
       },
     },
   ];