@adobe/design-data-agent-mcp 1.7.1 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/design-data-agent-mcp",
-  "version": "1.7.1",
+  "version": "1.8.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": "2.0.3",
+    "@adobe/design-data": "3.0.0",
     "@adobe/design-data-wasm": "0.4.0",
-    "@adobe/spectrum-design-data": "0.7.0"
+    "@adobe/spectrum-design-data": "0.8.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.7.1"
+  version: "1.8.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/cli.js

@@ -11,7 +11,7 @@
 import { spawn } from "child_process";
 import { config } from "./config.js";
 
-export function runCli(args, { timeout = 10_000 } = {}) {
+export function runCli(args, { timeout = 10_000, stdin } = {}) {
   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
@@ -19,8 +19,12 @@ export function runCli(args, { timeout = 10_000 } = {}) {
       // 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"],
+      stdio: [stdin != null ? "pipe" : "ignore", "pipe", "pipe"],
     });
+    if (stdin != null) {
+      proc.stdin.write(stdin);
+      proc.stdin.end();
+    }
     let stdout = "";
     let stderr = "";
     proc.stdout.on("data", (d) => {

package/src/index.js

@@ -19,6 +19,7 @@ import {
   ListToolsRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
 import { createAuthoringTools } from "./tools/authoring.js";
+import { createDataTools } from "./tools/data.js";
 import { createReadTools } from "./tools/read.js";
 import { createValidateTools } from "./tools/validate.js";
 import { createDiffTools } from "./tools/diff.js";
@@ -31,6 +32,7 @@ export function createAllTools() {
     ...createDiffTools(),
     ...createWriteTools(),
     ...createAuthoringTools(),
+    ...createDataTools(),
   ];
 }
 

package/src/tools/authoring.js

@@ -9,28 +9,45 @@
 // governing permissions and limitations under the License.
 
 /**
- * Authoring-session tools for design-data-agent-mcp.
+ * Authoring-session, lifecycle, and mode-set 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.
+ * All operations delegate to the `design-data` CLI, which is already a hard
+ * prerequisite of this server (every read tool shells out the same way). This
+ * guarantees output byte-identical to the CLI by construction and avoids a
+ * parallel JS reimplementation of the Rust cascade write path.
+ *
+ * The one exception — authoring_session_step_intent — was the original CLI
+ * shell-out; it is left unchanged.
+ *
+ * CLI surface used:
+ *   design-data authoring-session {start | step intent|classification|values |
+ *                                   commit | cancel | get | list}
+ *   design-data lifecycle {edit | deprecate | rename | rewire-alias | remove}
+ *   design-data mode-set  {add-mode | rename-mode | remove-mode |
+ *                           create-mode-set | remove-mode-set}
  */
 
-import {
-  startSession,
-  getSession,
-  listSessions,
-  stepClassification,
-  stepValues,
-  commitSession,
-  cancelSession,
-} from "@adobe/design-data/session";
 import { runCli } from "../cli.js";
 import { config } from "../config.js";
 
+/**
+ * Run CLI args, throw on non-zero exit, return parsed JSON.
+ *
+ * @param {string[]} args
+ * @param {{ timeout?: number }} [opts]
+ * @returns {Promise<unknown>}
+ */
+async function runJson(args, { timeout = 30_000 } = {}) {
+  const { exitCode, stdout, stderr } = await runCli(args, { timeout });
+  if (exitCode !== 0)
+    throw new Error(stderr || `design-data ${args[0]} exited ${exitCode}`);
+  return JSON.parse(stdout);
+}
+
 export function createAuthoringTools() {
   return [
+    // ── Authoring session ──────────────────────────────────────────────────
+
     {
       name: "start_authoring_session",
       description:
@@ -54,7 +71,7 @@ export function createAuthoringTools() {
             "dataset_path is required (or set DESIGN_DATA_PATH in the environment)",
           );
         }
-        return startSession(path);
+        return runJson(["authoring-session", "start", path]);
       },
     },
 
@@ -77,9 +94,8 @@ export function createAuthoringTools() {
         additionalProperties: false,
       },
       async handler({ session_id, 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(
+        // step_intent uses CLI for NLP suggest ranking (not yet on wasm surface).
+        return runJson(
           [
             "authoring-session",
             "step",
@@ -91,11 +107,6 @@ export function createAuthoringTools() {
           ],
           { timeout: 30_000 },
         );
-        if (exitCode !== 0)
-          throw new Error(
-            stderr || `authoring-session step intent exited ${exitCode}`,
-          );
-        return JSON.parse(stdout);
       },
     },
 
@@ -103,7 +114,8 @@ export function createAuthoringTools() {
       name: "authoring_session_step_classification",
       description:
         "Set the layer, property, and name-object fields for the token. " +
-        "name_fields is an array of {key, value} objects.",
+        "name_fields is an array of {key, value} objects. " +
+        "Classification is validated against the active fields catalog.",
       inputSchema: {
         type: "object",
         required: ["session_id", "layer", "property"],
@@ -134,11 +146,22 @@ export function createAuthoringTools() {
         additionalProperties: false,
       },
       async handler({ session_id, layer, property, name_fields = [] }) {
-        return stepClassification(session_id, {
+        const args = [
+          "authoring-session",
+          "step",
+          "classification",
+          "--session-id",
+          session_id,
+          "--layer",
           layer,
+          "--property",
           property,
-          nameFields: name_fields,
-        });
+        ];
+        for (const { key, value } of name_fields) {
+          // ponytail: CLI parse_name_fields uses split_once('=') — values with '=' are safe.
+          args.push("--name-field", `${key}=${value}`);
+        }
+        return runJson(args);
       },
     },
 
@@ -180,15 +203,24 @@ export function createAuthoringTools() {
         additionalProperties: false,
       },
       async handler({ session_id, rows }) {
-        return stepValues(session_id, rows);
+        return runJson([
+          "authoring-session",
+          "step",
+          "values",
+          "--session-id",
+          session_id,
+          "--rows",
+          JSON.stringify(rows),
+        ]);
       },
     },
 
     {
       name: "authoring_session_commit",
       description:
-        "Build and write the token to disk, then remove the session. " +
-        "Requires schema_url (the JSON Schema URL for the token type) and target (output file path).",
+        "Build and write the token to disk as a cascade array element, then remove the session. " +
+        "Requires schema_url (the JSON Schema URL for the token type) and target " +
+        "(the *.tokens.json cascade file to write into).",
       inputSchema: {
         type: "object",
         required: ["session_id", "schema_url", "target"],
@@ -202,7 +234,7 @@ export function createAuthoringTools() {
           target: {
             type: "string",
             description:
-              "Target legacy JSON file to write to (created if absent, merged if present).",
+              "Target *.tokens.json cascade file to write into (created if absent, upserted if present).",
           },
           rationale: {
             type: "string",
@@ -216,7 +248,6 @@ export function createAuthoringTools() {
             type: "string",
             description:
               "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: {
@@ -236,15 +267,22 @@ export function createAuthoringTools() {
         schema_path,
         is_override = false,
       }) {
-        return commitSession({
-          sessionId: session_id,
-          schemaUrl: schema_url,
+        const args = [
+          "authoring-session",
+          "commit",
+          "--session-id",
+          session_id,
+          "--schema-url",
+          schema_url,
+          "--target",
           target,
+          "--rationale",
           rationale,
-          productContext: product_context,
-          schemaPath: schema_path ?? null,
-          isOverride: is_override,
-        });
+        ];
+        if (schema_path) args.push("--schema-path", schema_path);
+        if (product_context) args.push("--product-context", product_context);
+        if (is_override) args.push("--is-override");
+        return runJson(args, { timeout: 60_000 });
       },
     },
 
@@ -258,7 +296,12 @@ export function createAuthoringTools() {
         additionalProperties: false,
       },
       async handler({ session_id }) {
-        return cancelSession(session_id);
+        return runJson([
+          "authoring-session",
+          "cancel",
+          "--session-id",
+          session_id,
+        ]);
       },
     },
 
@@ -272,7 +315,12 @@ export function createAuthoringTools() {
         additionalProperties: false,
       },
       async handler({ session_id }) {
-        return getSession(session_id);
+        return runJson([
+          "authoring-session",
+          "get",
+          "--session-id",
+          session_id,
+        ]);
       },
     },
 
@@ -285,7 +333,534 @@ export function createAuthoringTools() {
         additionalProperties: false,
       },
       async handler() {
-        return listSessions();
+        return runJson(["authoring-session", "list"]);
+      },
+    },
+
+    // ── Token lifecycle ────────────────────────────────────────────────────
+
+    {
+      name: "edit_token",
+      description:
+        "Merge field updates into an already-committed cascade token, then re-validate. " +
+        "The token's uuid is always preserved and silently ignored if included in updates.",
+      inputSchema: {
+        type: "object",
+        required: ["uuid", "target", "updates"],
+        properties: {
+          uuid: { type: "string", description: "UUID of the token to edit." },
+          target: {
+            type: "string",
+            description:
+              "Path to the *.tokens.json cascade file containing the token.",
+          },
+          updates: {
+            type: "object",
+            description:
+              'Fields to merge into the token object, e.g. { "value": "#ff0000" }.',
+          },
+          rationale: { type: "string", description: "Why the token changed." },
+          tokens_root: {
+            type: "string",
+            description:
+              "Root tokens directory — required when updates contains a $ref.",
+          },
+          schema_path: {
+            type: "string",
+            description:
+              "Schemas directory for validation (default: auto-resolved from target).",
+          },
+        },
+        additionalProperties: false,
+      },
+      async handler({
+        uuid,
+        target,
+        updates,
+        rationale = "",
+        tokens_root,
+        schema_path,
+      }) {
+        const args = [
+          "lifecycle",
+          "edit",
+          "--uuid",
+          uuid,
+          "--target",
+          target,
+          "--updates",
+          JSON.stringify(updates),
+          "--rationale",
+          rationale,
+        ];
+        if (tokens_root) args.push("--tokens-root", tokens_root);
+        if (schema_path) args.push("--schema-path", schema_path);
+        return runJson(args);
+      },
+    },
+
+    {
+      name: "deprecate_token",
+      description:
+        "Stamp a deprecation marker onto a cascade token. Optionally record a replacement UUID " +
+        "and a planned-removal spec version.",
+      inputSchema: {
+        type: "object",
+        required: ["uuid", "target", "spec_version"],
+        properties: {
+          uuid: {
+            type: "string",
+            description: "UUID of the token to deprecate.",
+          },
+          target: {
+            type: "string",
+            description:
+              "Path to the *.tokens.json cascade file containing the token.",
+          },
+          spec_version: {
+            type: "string",
+            description:
+              "Dataset specVersion string to stamp into the deprecated value, e.g. '1.0.0'.",
+          },
+          deprecated_comment: {
+            type: "string",
+            description:
+              "Human-readable deprecation explanation / migration guidance.",
+          },
+          replaced_by: {
+            type: "string",
+            description:
+              "Replacement token UUID (string) or JSON array of UUIDs.",
+          },
+          planned_removal: {
+            type: "string",
+            description: "Spec version at which the token will be removed.",
+          },
+          rationale: {
+            type: "string",
+            description: "Why the token was deprecated.",
+          },
+          schema_path: {
+            type: "string",
+            description: "Schemas directory for validation.",
+          },
+        },
+        additionalProperties: false,
+      },
+      async handler({
+        uuid,
+        target,
+        spec_version,
+        deprecated_comment,
+        replaced_by,
+        planned_removal,
+        rationale = "",
+        schema_path,
+      }) {
+        const args = [
+          "lifecycle",
+          "deprecate",
+          "--uuid",
+          uuid,
+          "--target",
+          target,
+          "--spec-version",
+          spec_version,
+          "--rationale",
+          rationale,
+        ];
+        if (deprecated_comment)
+          args.push("--deprecated-comment", deprecated_comment);
+        if (replaced_by) args.push("--replaced-by", replaced_by);
+        if (planned_removal) args.push("--planned-removal", planned_removal);
+        if (schema_path) args.push("--schema-path", schema_path);
+        return runJson(args);
+      },
+    },
+
+    {
+      name: "rename_token",
+      description:
+        "Assign a new name object to a cascade token, preserving its UUID. " +
+        "Optionally set a replaced_by pointer on the token being renamed.",
+      inputSchema: {
+        type: "object",
+        required: ["uuid", "target", "new_name"],
+        properties: {
+          uuid: { type: "string", description: "UUID of the token to rename." },
+          target: {
+            type: "string",
+            description:
+              "Path to the *.tokens.json cascade file containing the token.",
+          },
+          new_name: {
+            description:
+              'New name — either a JSON object ({"property":"…","component":"…"}) or a plain string.',
+          },
+          replaced_by_target: {
+            type: "string",
+            description:
+              "UUID to set as the replaced_by pointer (for retiring the old name).",
+          },
+          rationale: {
+            type: "string",
+            description: "Why the token was renamed.",
+          },
+          schema_path: {
+            type: "string",
+            description: "Schemas directory for validation.",
+          },
+        },
+        additionalProperties: false,
+      },
+      async handler({
+        uuid,
+        target,
+        new_name,
+        replaced_by_target,
+        rationale = "",
+        schema_path,
+      }) {
+        if (
+          new_name === null ||
+          new_name === undefined ||
+          (typeof new_name !== "string" && typeof new_name !== "object")
+        ) {
+          throw new Error(
+            "new_name must be a string or object, got: " +
+              JSON.stringify(new_name),
+          );
+        }
+        const newNameArg =
+          typeof new_name === "object" ? JSON.stringify(new_name) : new_name;
+        const args = [
+          "lifecycle",
+          "rename",
+          "--uuid",
+          uuid,
+          "--target",
+          target,
+          "--new-name",
+          newNameArg,
+          "--rationale",
+          rationale,
+        ];
+        if (replaced_by_target)
+          args.push("--replaced-by-target", replaced_by_target);
+        if (schema_path) args.push("--schema-path", schema_path);
+        return runJson(args);
+      },
+    },
+
+    {
+      name: "rewire_alias",
+      description:
+        "Change the $ref target on an alias token. The new ref target must resolve in the cascade. " +
+        "Rejects if the token is not an alias.",
+      inputSchema: {
+        type: "object",
+        required: ["uuid", "target", "new_ref", "tokens_root"],
+        properties: {
+          uuid: {
+            type: "string",
+            description: "UUID of the alias token to rewire.",
+          },
+          target: {
+            type: "string",
+            description:
+              "Path to the *.tokens.json cascade file containing the token.",
+          },
+          new_ref: {
+            type: "string",
+            description:
+              "New $ref value — must be a UUID that resolves in the cascade.",
+          },
+          tokens_root: {
+            type: "string",
+            description:
+              "Root tokens directory for ref-resolution verification.",
+          },
+          rationale: {
+            type: "string",
+            description: "Why the alias target changed.",
+          },
+          schema_path: {
+            type: "string",
+            description: "Schemas directory for validation.",
+          },
+        },
+        additionalProperties: false,
+      },
+      async handler({
+        uuid,
+        target,
+        new_ref,
+        tokens_root,
+        rationale = "",
+        schema_path,
+      }) {
+        const args = [
+          "lifecycle",
+          "rewire-alias",
+          "--uuid",
+          uuid,
+          "--target",
+          target,
+          "--new-ref",
+          new_ref,
+          "--tokens-root",
+          tokens_root,
+          "--rationale",
+          rationale,
+        ];
+        if (schema_path) args.push("--schema-path", schema_path);
+        return runJson(args);
+      },
+    },
+
+    {
+      name: "remove_token",
+      description:
+        "Delete a token from a cascade file. Aborts if any other token in the dataset " +
+        "holds a $ref pointing at this token's UUID.",
+      inputSchema: {
+        type: "object",
+        required: ["uuid", "target", "tokens_root"],
+        properties: {
+          uuid: { type: "string", description: "UUID of the token to remove." },
+          target: {
+            type: "string",
+            description:
+              "Path to the *.tokens.json cascade file containing the token.",
+          },
+          tokens_root: {
+            type: "string",
+            description: "Root tokens directory for inbound-reference guard.",
+          },
+        },
+        additionalProperties: false,
+      },
+      async handler({ uuid, target, tokens_root }) {
+        return runJson([
+          "lifecycle",
+          "remove",
+          "--uuid",
+          uuid,
+          "--target",
+          target,
+          "--tokens-root",
+          tokens_root,
+        ]);
+      },
+    },
+
+    // ── Mode-set ───────────────────────────────────────────────────────────
+
+    {
+      name: "add_mode",
+      description: "Append a new mode to an existing mode-set file.",
+      inputSchema: {
+        type: "object",
+        required: ["mode_set_file", "mode"],
+        properties: {
+          mode_set_file: {
+            type: "string",
+            description: "Path to the mode-set JSON file.",
+          },
+          mode: {
+            type: "string",
+            description: "Name of the new mode to add.",
+          },
+          make_default: {
+            type: "boolean",
+            description: "Make this the default mode.",
+          },
+        },
+        additionalProperties: false,
+      },
+      async handler({ mode_set_file, mode, make_default = false }) {
+        const args = [
+          "mode-set",
+          "add-mode",
+          "--mode-set-file",
+          mode_set_file,
+          "--mode",
+          mode,
+        ];
+        if (make_default) args.push("--make-default");
+        return runJson(args);
+      },
+    },
+
+    {
+      name: "rename_mode",
+      description:
+        "Rename a mode in a mode-set file and propagate the change to all token files " +
+        "under tokens_root that use that mode value.",
+      inputSchema: {
+        type: "object",
+        required: ["mode_set_file", "tokens_root", "old", "new"],
+        properties: {
+          mode_set_file: {
+            type: "string",
+            description: "Path to the mode-set JSON file.",
+          },
+          tokens_root: {
+            type: "string",
+            description: "Root tokens directory for propagation.",
+          },
+          old: {
+            type: "string",
+            description: "Existing mode name to rename.",
+          },
+          new: {
+            type: "string",
+            description: "Replacement mode name.",
+          },
+        },
+        additionalProperties: false,
+      },
+      async handler({ mode_set_file, tokens_root, old, new: new_mode }) {
+        return runJson([
+          "mode-set",
+          "rename-mode",
+          "--mode-set-file",
+          mode_set_file,
+          "--tokens-root",
+          tokens_root,
+          "--old",
+          old,
+          "--new",
+          new_mode,
+        ]);
+      },
+    },
+
+    {
+      name: "remove_mode",
+      description:
+        "Remove a mode from a mode-set file. Aborts if any token references that mode value " +
+        "or if the mode is the current default.",
+      inputSchema: {
+        type: "object",
+        required: ["mode_set_file", "tokens_root", "mode"],
+        properties: {
+          mode_set_file: {
+            type: "string",
+            description: "Path to the mode-set JSON file.",
+          },
+          tokens_root: {
+            type: "string",
+            description: "Root tokens directory for reference guard.",
+          },
+          mode: {
+            type: "string",
+            description: "Mode name to remove.",
+          },
+        },
+        additionalProperties: false,
+      },
+      async handler({ mode_set_file, tokens_root, mode }) {
+        return runJson([
+          "mode-set",
+          "remove-mode",
+          "--mode-set-file",
+          mode_set_file,
+          "--tokens-root",
+          tokens_root,
+          "--mode",
+          mode,
+        ]);
+      },
+    },
+
+    {
+      name: "create_mode_set",
+      description:
+        "Author a new mode-set file for a new cascade dimension. " +
+        "The file must not already exist. default must be a member of modes.",
+      inputSchema: {
+        type: "object",
+        required: ["mode_set_file", "name", "modes", "default"],
+        properties: {
+          mode_set_file: {
+            type: "string",
+            description:
+              "Destination path for the new mode-set JSON file (must not exist).",
+          },
+          name: {
+            type: "string",
+            description:
+              "Logical name used as the key in token name objects, e.g. 'colorScheme'.",
+          },
+          modes: {
+            type: "array",
+            items: { type: "string" },
+            description: "Ordered list of mode names, e.g. ['light', 'dark'].",
+          },
+          default: {
+            type: "string",
+            description: "Default mode — must be a member of modes.",
+          },
+          description: {
+            type: "string",
+            description: "Human-readable description embedded in the file.",
+          },
+        },
+        additionalProperties: false,
+      },
+      async handler({
+        mode_set_file,
+        name,
+        modes,
+        default: defaultMode,
+        description = "",
+      }) {
+        return runJson([
+          "mode-set",
+          "create-mode-set",
+          "--mode-set-file",
+          mode_set_file,
+          "--name",
+          name,
+          "--modes",
+          JSON.stringify(modes),
+          "--default",
+          defaultMode,
+          "--description",
+          description,
+        ]);
+      },
+    },
+
+    {
+      name: "remove_mode_set",
+      description:
+        "Delete a mode-set file. Aborts if any token in the dataset references this dimension.",
+      inputSchema: {
+        type: "object",
+        required: ["mode_set_file", "tokens_root"],
+        properties: {
+          mode_set_file: {
+            type: "string",
+            description: "Path to the mode-set JSON file to remove.",
+          },
+          tokens_root: {
+            type: "string",
+            description: "Root tokens directory for reference guard.",
+          },
+        },
+        additionalProperties: false,
+      },
+      async handler({ mode_set_file, tokens_root }) {
+        return runJson([
+          "mode-set",
+          "remove-mode-set",
+          "--mode-set-file",
+          mode_set_file,
+          "--tokens-root",
+          tokens_root,
+        ]);
       },
     },
   ];

package/src/tools/data.js

@@ -0,0 +1,162 @@
+// 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.
+
+/**
+ * create/edit tools for non-token data categories (components, fields, registry,
+ * mode-sets, guidelines) — Phase C authoring surface.
+ *
+ * All operations delegate to `design-data data create|edit`, which validates
+ * against the JSON schema before writing. Output is byte-identical to the CLI.
+ *
+ * CLI surface used:
+ *   design-data data create --category <c> --file -  [--dataset <dir>] [--spec-schemas <dir>]
+ *   design-data data edit   --category <c> --file -  [--dataset <dir>] [--spec-schemas <dir>]
+ */
+
+import { resolve } from "path";
+import { runCli } from "../cli.js";
+import { config } from "../config.js";
+
+const CATEGORIES = [
+  "components",
+  "fields",
+  "registry",
+  "mode-sets",
+  "guidelines",
+];
+
+/** Run CLI, throw on non-zero exit, return parsed JSON. */
+async function runJson(args, stdin, { timeout = 30_000 } = {}) {
+  const { exitCode, stdout, stderr } = await runCli(args, { timeout, stdin });
+  if (exitCode !== 0)
+    throw new Error(stderr || `design-data ${args[0]} exited ${exitCode}`);
+  return JSON.parse(stdout);
+}
+
+/**
+ * Build the base args for a data create/edit call, resolving dataset root and
+ * spec schemas dir from config / env.
+ */
+function baseArgs(subcommand, category, datasetOverride, specSchemasOverride) {
+  // Only use config.dataPath when it ends in /tokens — the bare-cwd fallback
+  // (anchorPath(".")) does not end in tokens and must not be stripped.
+  const dataPathTokens = config.dataPath?.match(/^(.*?)\/tokens\/?$/)
+    ? config.dataPath.replace(/\/tokens\/?$/, "")
+    : null;
+  const dataset =
+    datasetOverride ??
+    dataPathTokens ??
+    resolve(config.dataRoot, "packages/design-data");
+
+  const args = [
+    "data",
+    subcommand,
+    "--category",
+    category,
+    "--file",
+    "-",
+    "--dataset",
+    dataset,
+  ];
+
+  const specSchemas =
+    specSchemasOverride ??
+    (process.env.DESIGN_DATA_SPEC_SCHEMAS
+      ? resolve(process.env.DESIGN_DATA_SPEC_SCHEMAS)
+      : null);
+  if (specSchemas) args.push("--spec-schemas", specSchemas);
+
+  return { args, dataset };
+}
+
+export function createDataTools() {
+  return [
+    {
+      name: "data_create",
+      description:
+        "Create a new non-token data object (component, field, registry entry, mode-set, or " +
+        "guideline). Validates the JSON document against the category schema before writing. " +
+        "Fails if the file already exists — use data_edit to overwrite.",
+      inputSchema: {
+        type: "object",
+        required: ["category", "document"],
+        properties: {
+          category: {
+            type: "string",
+            enum: CATEGORIES,
+            description: "Data category to create in.",
+          },
+          document: {
+            type: "object",
+            description:
+              "Full JSON document to write. Must include the category's required fields " +
+              "(e.g. `name`, `$schema`, `specVersion`). The filename is derived from the `name` field.",
+            additionalProperties: true,
+          },
+          dataset: {
+            type: "string",
+            description:
+              "Path to the dataset root (packages/design-data). Defaults to DESIGN_DATA_PATH minus /tokens.",
+          },
+          spec_schemas: {
+            type: "string",
+            description:
+              "Path to the design-data-spec schemas dir. Defaults to DESIGN_DATA_SPEC_SCHEMAS or auto-probed.",
+          },
+        },
+        additionalProperties: false,
+      },
+      async handler({ category, document, dataset, spec_schemas }) {
+        const { args } = baseArgs("create", category, dataset, spec_schemas);
+        return runJson(args, JSON.stringify(document));
+      },
+    },
+
+    {
+      name: "data_edit",
+      description:
+        "Replace an existing non-token data object with a new JSON document. Validates the " +
+        "document against the category schema before writing. Fails if the file does not exist " +
+        "— use data_create to create it. Edit is a full document replace, not a patch.",
+      inputSchema: {
+        type: "object",
+        required: ["category", "document"],
+        properties: {
+          category: {
+            type: "string",
+            enum: CATEGORIES,
+            description: "Data category to edit in.",
+          },
+          document: {
+            type: "object",
+            description:
+              "Full replacement JSON document. The `name` field must match the existing file.",
+            additionalProperties: true,
+          },
+          dataset: {
+            type: "string",
+            description:
+              "Path to the dataset root (packages/design-data). Defaults to DESIGN_DATA_PATH minus /tokens.",
+          },
+          spec_schemas: {
+            type: "string",
+            description:
+              "Path to the design-data-spec schemas dir. Defaults to DESIGN_DATA_SPEC_SCHEMAS or auto-probed.",
+          },
+        },
+        additionalProperties: false,
+      },
+      async handler({ category, document, dataset, spec_schemas }) {
+        const { args } = baseArgs("edit", category, dataset, spec_schemas);
+        return runJson(args, JSON.stringify(document));
+      },
+    },
+  ];
+}

package/src/tools/write.js

@@ -9,7 +9,7 @@
 // governing permissions and limitations under the License.
 
 import { join } from "path";
-import { writeProductContext } from "@adobe/design-data/write";
+import { runCli } from "../cli.js";
 import { config } from "../config.js";
 
 export function createWriteTools() {
@@ -36,7 +36,12 @@ export function createWriteTools() {
       async handler({ output, rationale } = {}) {
         const resolvedOutput =
           output ?? join(config.dataPath, "product-context.json");
-        return writeProductContext({ output: resolvedOutput, rationale });
+        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 || `design-data write exited ${exitCode}`);
+        return stdout;
       },
     },
   ];