@adobe/design-data-agent-mcp 1.4.1 → 1.6.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/) 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. Read tools (`primer`, `resolve_token`, `query_tokens`, `describe_component`) 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
 
@@ -29,7 +29,7 @@ https://github.com/adobe/spectrum-design-data/tree/main/tools/design-data-agent-
 npx @adobe/design-data-agent-mcp
 ```
 
-Requires the `@adobe/design-data` CLI on `PATH` (or set `DESIGN_DATA_BIN`).
+The `@adobe/design-data` CLI binary is **only** needed for `authoring_session_step_intent`. All other tools run in-process. Set `DESIGN_DATA_BIN` if the binary is not on `PATH`.
 
 ## MCP server
 
@@ -49,7 +49,7 @@ node tools/design-data-agent-mcp/src/index.js
 
 | Variable                 | Default       | Description                                       |
 | ------------------------ | ------------- | ------------------------------------------------- |
-| `DESIGN_DATA_BIN`        | `design-data` | Path to the `design-data` binary                  |
+| `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                     |
@@ -74,8 +74,9 @@ node tools/design-data-agent-mcp/src/index.js
 >    `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).
+>    component/field overrides fall back to `null` (not supplied), which means
+>    `describe_component` will throw an error if `@adobe/spectrum-design-data` is
+>    not resolvable.
 >
 > In a monorepo checkout you typically need no `DESIGN_DATA_*` env vars at all —
 > resolution via the workspace package handles it.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@adobe/design-data-agent-mcp",
-  "version": "1.4.1",
-  "description": "MCP server and Claude Code skill for the design-data agent surface — shells out to the design-data CLI",
+  "version": "1.6.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",
   "bin": {
@@ -30,6 +30,8 @@
   },
   "dependencies": {
     "@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": {

package/skills/design-data/SKILL.md

@@ -2,20 +2,22 @@
 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/design-data/tokens
@@ -26,55 +28,50 @@ For Spectrum tokens with zero setup (embedded snapshot), use the `design-data` s
 
 ## 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"
-```
-
-Always pass `--components-dir` and `--fields-dir` explicitly. These directories live under `packages/design-data/`, alongside 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` and `taxonomyFields`.
-
-The payload includes `specVersion`, `manifest`, `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
-
-```bash
-npx @adobe/design-data resolve <property> "$DESIGN_DATA_PATH" --format json \
-  [--color-scheme light|dark] \
-  [--scale desktop|mobile] \
-  [--contrast regular|high]
-```
-
-Example:
+### Resolve a token to its literal value — `resolve_token`
 
-```bash
-npx @adobe/design-data resolve accent-background-color-default "$DESIGN_DATA_PATH" \
-  --format json --color-scheme dark --scale desktop
-```
+Required: `property` (string) — e.g. `"accent-background-color-default"`
+Optional: `colorScheme` (`"light"` or `"dark"`), `scale` (`"desktop"` or `"mobile"`),
+`contrast` (`"regular"` or `"high"`)
 
-### Query tokens by filter expression
+### Query tokens by filter expression — `query_tokens`
 
-```bash
-npx @adobe/design-data query "$DESIGN_DATA_PATH" --filter "<expr>" --format json
-```
+Required: `filter` (string)
 
-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:
 
@@ -87,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.
 
 ***
 
@@ -152,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
 
@@ -163,23 +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/components",
-        "DESIGN_DATA_FIELDS": "./packages/design-data/fields"
-      }
-    }
-  }
-}
-```
-
-Adjust paths to match your dataset layout.

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,9 +8,57 @@
 // 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";
+/**
+ * Read tools for design-data-agent-mcp.
+ *
+ * All read tools run fully in-process via @adobe/design-data-wasm — no CLI binary
+ * required. primer and describe_component were migrated in issue m1r.
+ *
+ * Note: authoring_session_step_intent in authoring.js still uses the CLI because
+ * the NLP suggest ranking is not yet on the wasm surface.
+ */
+
+import { readFileSync, existsSync, readdirSync } from "fs";
+import { join } from "path";
+import { loadDataset } from "@adobe/design-data/load";
 import { config } from "../config.js";
 
+let _wasm;
+/** Lazy-load and cache the wasm module (nodejs target, no init() required). */
+async function getWasm() {
+  if (!_wasm) _wasm = await import("@adobe/design-data-wasm");
+  return _wasm;
+}
+
+let _dataset;
+/**
+ * Return the embedded Spectrum dataset, caching it after first access.
+ *
+ * Dataset.embedded() clones the in-memory graph on every call; caching here
+ * avoids that per-request cost.
+ */
+async function getDataset() {
+  if (!_dataset) {
+    const wasm = await getWasm();
+    _dataset = wasm.Dataset.embedded();
+  }
+  return _dataset;
+}
+
+/**
+ * Validate a component ID against the same rule as the Rust SDK.
+ * See sdk/core/src/component.rs:validate_id — prevents path traversal.
+ */
+const COMPONENT_ID_RE = /^[a-z][a-z0-9-]*$/;
+function validateComponentId(id) {
+  if (!COMPONENT_ID_RE.test(id)) {
+    throw new Error(
+      `Invalid component ID "${id}". IDs must be kebab-case: start with a lowercase ` +
+        `letter and contain only lowercase letters, digits, and hyphens.`,
+    );
+  }
+}
+
 export function createReadTools() {
   return [
     {
@@ -23,16 +71,34 @@ export function createReadTools() {
         additionalProperties: false,
       },
       async handler() {
-        const args = ["primer", config.dataPath, "--format", "json"];
-        if (config.componentsDir)
-          args.push("--components-dir", config.componentsDir);
-        if (config.fieldsDir) args.push("--fields-dir", config.fieldsDir);
-        const { exitCode, stdout, stderr } = await runCli(args);
-        if (exitCode !== 0)
-          throw new Error(stderr || `primer exited ${exitCode}`);
-        return JSON.parse(stdout);
+        // 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[],
+        // taxonomyFields.{indexed,advisory}. CLI-only fields (specVersion, manifest,
+        // provenance) are not present — no SKILL.md reference or consumer relies on them.
+        const wasm = await getWasm();
+        const ds = await getDataset();
+        return {
+          source: "embedded",
+          tokenCount: ds.tokenCount(),
+          modeSets: {
+            colorScheme: wasm.getFieldValues("colorScheme") ?? [],
+            scale: wasm.getFieldValues("scale") ?? [],
+            contrast: wasm.getFieldValues("contrast") ?? [],
+          },
+          taxonomyFields: {
+            indexed: wasm.getIndexedFields(),
+            advisory: wasm.getAdvisoryFields() ?? [],
+          },
+          components: wasm.getFieldValues("component") ?? [],
+          properties: wasm.getFieldValues("property") ?? [],
+        };
       },
     },
+
     {
       name: "resolve_token",
       description:
@@ -64,16 +130,21 @@ export function createReadTools() {
         additionalProperties: false,
       },
       async handler({ property, colorScheme, scale, contrast }) {
-        const args = ["resolve", property, config.dataPath, "--format", "json"];
-        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:
@@ -90,20 +161,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:
@@ -117,13 +179,32 @@ export function createReadTools() {
         additionalProperties: false,
       },
       async handler({ id }) {
-        const args = ["component", id];
-        if (config.componentsDir)
-          args.push("--components-dir", config.componentsDir);
-        const { exitCode, stdout, stderr } = await runCli(args);
-        if (exitCode !== 0)
-          throw new Error(stderr || `component exited ${exitCode}`);
-        return JSON.parse(stdout);
+        validateComponentId(id);
+        const componentsDir = config.componentsDir;
+        if (!componentsDir) {
+          throw new Error(
+            `@adobe/spectrum-design-data is not installed — cannot load component "${id}". ` +
+              `Install it with: pnpm add @adobe/spectrum-design-data`,
+          );
+        }
+        const componentFile = join(componentsDir, `${id}.json`);
+        if (!existsSync(componentFile)) {
+          let available;
+          try {
+            available = readdirSync(componentsDir)
+              .filter((f) => f.endsWith(".json"))
+              .map((f) => f.replace(/\.json$/, ""))
+              .sort()
+              .join(", ");
+          } catch {
+            available = null;
+          }
+          const hint = available
+            ? `Available components: ${available}`
+            : `Call primer to see available component IDs.`;
+          throw new Error(`Component not found: "${id}". ${hint}`);
+        }
+        return JSON.parse(readFileSync(componentFile, "utf-8"));
       },
     },
   ];

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,20 +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);
-        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 });
       },
     },
   ];