@adobe/design-data-agent-mcp 1.3.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "design-data-agent",
+  "description": "Spec-conformant design token lookup, validation, diff, and authoring for any dataset via the design-data CLI.",
+  "author": {
+    "name": "Adobe"
+  },
+  "homepage": "https://github.com/adobe/spectrum-design-data/tree/main/tools/design-data-agent-mcp",
+  "repository": "https://github.com/adobe/spectrum-design-data",
+  "license": "Apache-2.0"
+}

package/LICENSE

@@ -0,0 +1,201 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation
+source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but
+not limited to compiled object code, generated documentation,
+and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or
+Object form, made available under the License, as indicated by a
+copyright notice that is included in or attached to the work
+(an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including
+the original version of the Work and any modifications or additions
+to that Work or Derivative Works thereof, that is intentionally
+submitted to Licensor for inclusion in the Work by the copyright owner
+or by an individual or Legal Entity authorized to submit on behalf of
+the copyright owner. For the purposes of this definition, "submitted"
+means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor and
+subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the
+Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except as stated in this section) patent license to make, have made,
+use, offer to sell, sell, import, and otherwise transfer the Work,
+where such license applies only to those patent claims licensable
+by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s)
+with the Work to which such Contribution(s) was submitted. If You
+institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work
+or a Contribution incorporated within the Work constitutes direct
+or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate
+as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+Work or Derivative Works thereof in any medium, with or without
+modifications, and in Source or Object form, provided that You
+meet the following conditions:
+
+(a) You must give any other recipients of the Work or
+Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices
+stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works
+that You distribute, all copyright, patent, trademark, and
+attribution notices from the Source form of the Work,
+excluding those notices that do not pertain to any part of
+the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its
+distribution, then any Derivative Works that You distribute must
+include a readable copy of the attribution notices contained
+within such NOTICE file, excluding those notices that do not
+pertain to any part of the Derivative Works, in at least one
+of the following places: within a NOTICE text file distributed
+as part of the Derivative Works; within the Source form or
+documentation, if provided along with the Derivative Works; or,
+within a display generated by the Derivative Works, if and
+wherever such third-party notices normally appear. The contents
+of the NOTICE file are for informational purposes only and
+do not modify the License. You may add Your own attribution
+notices within Derivative Works that You distribute, alongside
+or as an addendum to the NOTICE text from the Work, provided
+that such additional attribution notices cannot be construed
+as modifying the License.
+
+You may add Your own copyright statement to Your modifications and
+may provide additional or different license terms and conditions
+for use, reproduction, or distribution of Your modifications, or
+for any such Derivative Works as a whole, provided Your use,
+reproduction, and distribution of the Work otherwise complies with
+the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+any Contribution intentionally submitted for inclusion in the Work
+by You to the Licensor shall be under the terms and conditions of
+this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify
+the terms of any separate license agreement you may have executed
+with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+names, trademarks, service marks, or product names of the Licensor,
+except as required for reasonable and customary use in describing the
+origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+agreed to in writing, Licensor provides the Work (and each
+Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied, including, without limitation, any warranties or conditions
+of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any
+risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+whether in tort (including negligence), contract, or otherwise,
+unless required by applicable law (such as deliberate and grossly
+negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special,
+incidental, or consequential damages of any character arising as a
+result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all
+other commercial damages or losses), even if such Contributor
+has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+the Work or Derivative Works thereof, You may choose to offer,
+and charge a fee for, acceptance of support, warranty, indemnity,
+or other liability obligations and/or rights consistent with this
+License. However, in accepting such obligations, You may act only
+on Your own behalf and on Your sole responsibility, not on behalf
+of any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason
+of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following
+boilerplate notice, with the fields enclosed by brackets "{}"
+replaced with your own identifying information. (Don't include
+the brackets!)  The text should be enclosed in the appropriate
+comment syntax for the file format. We also recommend that a
+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.
+
+Licensed 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 CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,114 @@
+# `@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.
+
+## Install
+
+### Claude Code (skill + optional MCP)
+
+Add the Spectrum Design Data marketplace, then install the spec-generic skill:
+
+```
+/plugin marketplace add adobe/spectrum-design-data
+/plugin install design-data-agent@spectrum-design-data
+```
+
+For Spectrum tokens with zero setup (embedded snapshot), install `design-data@spectrum-design-data` instead — see [`tools/design-data-skill/`](../design-data-skill/).
+
+### Cursor (skill)
+
+Cursor Settings → Rules → **Add Rule** → **Remote Rule (GitHub)** → paste:
+
+```
+https://github.com/adobe/spectrum-design-data/tree/main/tools/design-data-agent-mcp/skills/design-data
+```
+
+### npm (MCP server)
+
+```sh
+npx @adobe/design-data-agent-mcp
+```
+
+Requires the `@adobe/design-data` CLI on `PATH` (or set `DESIGN_DATA_BIN`).
+
+## MCP server
+
+Configure your MCP client to run:
+
+```sh
+npx -y @adobe/design-data-agent-mcp
+```
+
+Or from a repo clone:
+
+```bash
+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`) |
+
+### Example (Cursor `.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"
+      }
+    }
+  }
+}
+```
+
+### Example (Claude Desktop `claude_desktop_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "design-data-agent": {
+      "command": "npx",
+      "args": ["-y", "@adobe/design-data-agent-mcp"],
+      "env": {
+        "DESIGN_DATA_BIN": "design-data",
+        "DESIGN_DATA_PATH": "/path/to/your/dataset"
+      }
+    }
+  }
+}
+```
+
+## Tools exposed
+
+| Tool                 | Description                                                     |
+| -------------------- | --------------------------------------------------------------- |
+| `primer`             | Load full token taxonomy, component list, and field definitions |
+| `resolve_token`      | Resolve a token property to its literal value                   |
+| `query_tokens`       | Filter tokens by expression                                     |
+| `describe_component` | Fetch component schema and token bindings                       |
+| `validate_usage`     | Validate token usage and return a diagnostic report             |
+| `diff_datasets`      | Compare two datasets and return a semantic diff                 |
+| `write`              | Write agent-generated product context to the dataset            |
+
+## Skill
+
+The Claude Code skill lives at [`skills/design-data/SKILL.md`](skills/design-data/SKILL.md). It shells out to `npx @adobe/design-data` for validate, query, resolve, diff, and write operations against local datasets.
+
+## License
+
+Apache-2.0

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@adobe/design-data-agent-mcp",
+  "version": "1.3.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",
+  "bin": {
+    "design-data-agent-mcp": "./src/index.js"
+  },
+  "files": [
+    "src/",
+    ".claude-plugin/",
+    "skills/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node src/index.js",
+    "test": "ava"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adobe/spectrum-design-data.git",
+    "directory": "tools/design-data-agent-mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/adobe/spectrum-design-data/issues"
+  },
+  "homepage": "https://github.com/adobe/spectrum-design-data/tree/main/tools/design-data-agent-mcp#readme",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "provenance": true
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1"
+  },
+  "devDependencies": {
+    "ava": "^6.0.1"
+  },
+  "engines": {
+    "node": ">=20.12.0"
+  },
+  "keywords": [
+    "mcp",
+    "design-system",
+    "design-tokens",
+    "design-data",
+    "agent-surface",
+    "cli"
+  ],
+  "author": "Adobe",
+  "license": "Apache-2.0"
+}

package/skills/design-data/SKILL.md

@@ -0,0 +1,187 @@
+---
+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
+  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 *)
+---
+
+# 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.
+
+Set two path variables once and reference them throughout. The token dataset and the spec catalog (components, fields, dimensions) live in separate directories:
+
+```bash
+export DESIGN_DATA_PATH=./packages/tokens/src
+export DESIGN_DATA_SPEC_PATH=./packages/design-data-spec
+```
+
+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:
+
+```
+npx @adobe/design-data --version
+```
+
+***
+
+## 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`.
+
+***
+
+## 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:
+
+```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
+
+```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`).
+
+Filter syntax examples:
+
+```
+property=background-color
+property=*background*
+component=button
+component=button,state=hover
+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.
+
+***
+
+## Component info
+
+```bash
+npx @adobe/design-data component <id> --components-dir "$DESIGN_DATA_SPEC_PATH/components"
+```
+
+Returns the component contract: `name`, `displayName`, `options`, `anatomy`, `states`, and `tokenBindings`. Output is always JSON; there is no `--format` flag on this subcommand.
+
+Pass `--components-dir` explicitly for the same reason as `primer` — the default probes CWD-relative paths that won't resolve in agent contexts.
+
+Example:
+
+```bash
+npx @adobe/design-data component button --components-dir "$DESIGN_DATA_SPEC_PATH/components"
+```
+
+***
+
+## Validation
+
+```bash
+npx @adobe/design-data validate "$DESIGN_DATA_PATH" --format json \
+  [--schema-path <path>] \
+  [--exceptions-path <path>] \
+  [--strict]
+```
+
+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.
+
+***
+
+## Dataset diff
+
+```bash
+npx @adobe/design-data diff <old-path> <new-path> --format json [--filter <expr>]
+```
+
+> **Exit codes:** `0` = no changes; `1` = differences found (returns JSON diff — not an error); `>1` = error.
+
+***
+
+## Product-layer authoring
+
+Write or update the product context document in the dataset:
+
+```bash
+npx @adobe/design-data write \
+  --output "$DESIGN_DATA_PATH/product-context.json" \
+  --rationale "Why these overrides exist"
+```
+
+Always pass `--output` with an explicit path inside the dataset. The default resolves relative to CWD, which is rarely correct in agent contexts.
+
+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.
+
+***
+
+## Gotchas
+
+* **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.
+
+## When working in Cursor
+
+Cursor Settings → Rules → **Add Rule** → **Remote Rule (GitHub)** → paste this URL:
+
+```
+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

@@ -0,0 +1,40 @@
+// 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.
+
+import { spawn } from "child_process";
+import { config } from "./config.js";
+
+export function runCli(args, { timeout = 10_000 } = {}) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(config.bin, args, {
+      // isolates CLI stdout from the MCP JSON-RPC stream on the parent's stdout
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    proc.stdout.on("data", (d) => {
+      stdout += d;
+    });
+    proc.stderr.on("data", (d) => {
+      stderr += d;
+    });
+
+    const timer = setTimeout(() => {
+      proc.kill();
+      reject(new Error(`design-data timed out after ${timeout}ms`));
+    }, timeout);
+
+    proc.on("close", (code) => {
+      clearTimeout(timer);
+      resolve({ exitCode: code, stdout: stdout.trim(), stderr: stderr.trim() });
+    });
+    proc.on("error", reject);
+  });
+}

package/src/config.js

@@ -0,0 +1,19 @@
+// 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.
+
+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,
+};

package/src/index.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+// 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.
+
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { resolve, dirname } from "path";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { createAuthoringTools } from "./tools/authoring.js";
+import { createReadTools } from "./tools/read.js";
+import { createValidateTools } from "./tools/validate.js";
+import { createDiffTools } from "./tools/diff.js";
+import { createWriteTools } from "./tools/write.js";
+
+export function createAllTools() {
+  return [
+    ...createReadTools(),
+    ...createValidateTools(),
+    ...createDiffTools(),
+    ...createWriteTools(),
+    ...createAuthoringTools(),
+  ];
+}
+
+export function createMCPServer() {
+  const pkg = JSON.parse(
+    readFileSync(
+      resolve(dirname(fileURLToPath(import.meta.url)), "../package.json"),
+      "utf8",
+    ),
+  );
+  const allTools = createAllTools();
+  const server = new Server(
+    { name: "design-data-agent-mcp", version: pkg.version },
+    { capabilities: { tools: {} } },
+  );
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: allTools.map(({ name, description, inputSchema }) => ({
+      name,
+      description,
+      inputSchema,
+    })),
+  }));
+  server.setRequestHandler(
+    CallToolRequestSchema,
+    async ({ params: { name, arguments: args } }) => {
+      const tool = allTools.find((t) => t.name === name);
+      if (!tool) throw new Error(`Unknown tool: ${name}`);
+      try {
+        const result = await tool.handler(args ?? {});
+        return {
+          content: [
+            {
+              type: "text",
+              text:
+                typeof result === "string"
+                  ? result
+                  : JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text", text: err.message }],
+          isError: true,
+        };
+      }
+    },
+  );
+  return server;
+}
+
+async function startServer() {
+  const server = createMCPServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("design-data-agent-mcp started");
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  startServer().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}

package/src/tools/authoring.js

@@ -0,0 +1,313 @@
+// 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.
+
+//! 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.
+
+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 [
+    {
+      name: "start_authoring_session",
+      description:
+        "Start a new token authoring session. Returns a session_id and the initial wizard state. " +
+        "The session persists across calls — use the returned session_id in subsequent steps.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          dataset_path: {
+            type: "string",
+            description:
+              "Path to the token dataset directory. Defaults to DESIGN_DATA_PATH.",
+          },
+        },
+        additionalProperties: false,
+      },
+      async handler({ dataset_path } = {}) {
+        const path = dataset_path ?? config.dataPath;
+        if (!path) {
+          throw new Error(
+            "dataset_path is required (or set DESIGN_DATA_PATH in the environment)",
+          );
+        }
+        return callCli(["authoring-session", "start", path]);
+      },
+    },
+
+    {
+      name: "authoring_session_step_intent",
+      description:
+        "Update the intent for a session and get ranked existing-token suggestions. " +
+        "Returns suggestions and can_alias (true when a high-confidence match exists).",
+      inputSchema: {
+        type: "object",
+        required: ["session_id", "intent"],
+        properties: {
+          session_id: { type: "string" },
+          intent: {
+            type: "string",
+            description:
+              "Natural-language description of what the token is for, e.g. 'accent background color'.",
+          },
+        },
+        additionalProperties: false,
+      },
+      async handler({ session_id, intent }) {
+        return callCli([
+          "authoring-session",
+          "step",
+          "intent",
+          "--session-id",
+          session_id,
+          "--intent",
+          intent,
+        ]);
+      },
+    },
+
+    {
+      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.",
+      inputSchema: {
+        type: "object",
+        required: ["session_id", "layer", "property"],
+        properties: {
+          session_id: { type: "string" },
+          layer: {
+            type: "string",
+            enum: ["foundation", "platform", "product"],
+            description: "Token layer.",
+          },
+          property: {
+            type: "string",
+            description: "Token property, e.g. 'background-color'.",
+          },
+          name_fields: {
+            type: "array",
+            items: {
+              type: "object",
+              required: ["key", "value"],
+              properties: {
+                key: { type: "string" },
+                value: { type: "string" },
+              },
+            },
+            description: "Additional name-object fields beyond property.",
+          },
+        },
+        additionalProperties: false,
+      },
+      async handler({ session_id, layer, property, name_fields = [] }) {
+        const args = [
+          "authoring-session",
+          "step",
+          "classification",
+          "--session-id",
+          session_id,
+          "--layer",
+          layer,
+          "--property",
+          property,
+        ];
+        for (const { key, value } of name_fields) {
+          args.push("--name-field", `${key}=${value}`);
+        }
+        return callCli(args);
+      },
+    },
+
+    {
+      name: "authoring_session_step_values",
+      description:
+        "Set the value rows for the token. Each row specifies mode conditions and either " +
+        "a literal value or an alias target. Most tokens need one row with empty mode_combo.",
+      inputSchema: {
+        type: "object",
+        required: ["session_id", "rows"],
+        properties: {
+          session_id: { type: "string" },
+          rows: {
+            type: "array",
+            description:
+              "Value rows. Each: { mode_combo: [[key,val],...], kind: 'Literal'|'Alias', " +
+              "alias_target: string, literal: string }",
+            items: {
+              type: "object",
+              required: ["mode_combo", "kind", "alias_target", "literal"],
+              properties: {
+                mode_combo: {
+                  type: "array",
+                  items: {
+                    type: "array",
+                    items: { type: "string" },
+                    minItems: 2,
+                    maxItems: 2,
+                  },
+                },
+                kind: { type: "string", enum: ["Literal", "Alias"] },
+                alias_target: { type: "string" },
+                literal: { type: "string" },
+              },
+            },
+          },
+        },
+        additionalProperties: false,
+      },
+      async handler({ session_id, rows }) {
+        return callCli([
+          "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).",
+      inputSchema: {
+        type: "object",
+        required: ["session_id", "schema_url", "target"],
+        properties: {
+          session_id: { type: "string" },
+          schema_url: {
+            type: "string",
+            description:
+              "The $schema URL for the token type, e.g. https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color.json",
+          },
+          target: {
+            type: "string",
+            description:
+              "Target legacy JSON file to write to (created if absent, merged if present).",
+          },
+          rationale: {
+            type: "string",
+            description: "Why this token is being created.",
+          },
+          product_context: {
+            type: "string",
+            description: "Path to product-context.json for rationale capture.",
+          },
+          schema_path: {
+            type: "string",
+            description:
+              "Path to schemas directory. Defaults to packages/tokens/schemas relative to target.",
+          },
+          is_override: {
+            type: "boolean",
+            description:
+              "True when this token overrides an existing foundation/platform token.",
+          },
+        },
+        additionalProperties: false,
+      },
+      async handler({
+        session_id,
+        schema_url,
+        target,
+        rationale = "",
+        product_context,
+        schema_path,
+        is_override = false,
+      }) {
+        const args = [
+          "authoring-session",
+          "commit",
+          "--session-id",
+          session_id,
+          "--schema-url",
+          schema_url,
+          "--target",
+          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);
+      },
+    },
+
+    {
+      name: "authoring_session_cancel",
+      description: "Cancel a session and delete its on-disk file.",
+      inputSchema: {
+        type: "object",
+        required: ["session_id"],
+        properties: {
+          session_id: { type: "string" },
+        },
+        additionalProperties: false,
+      },
+      async handler({ session_id }) {
+        return callCli([
+          "authoring-session",
+          "cancel",
+          "--session-id",
+          session_id,
+        ]);
+      },
+    },
+
+    {
+      name: "authoring_session_get",
+      description: "Get the current state of an authoring session.",
+      inputSchema: {
+        type: "object",
+        required: ["session_id"],
+        properties: {
+          session_id: { type: "string" },
+        },
+        additionalProperties: false,
+      },
+      async handler({ session_id }) {
+        return callCli([
+          "authoring-session",
+          "get",
+          "--session-id",
+          session_id,
+        ]);
+      },
+    },
+
+    {
+      name: "authoring_session_list",
+      description: "List all active authoring sessions.",
+      inputSchema: {
+        type: "object",
+        properties: {},
+        additionalProperties: false,
+      },
+      async handler() {
+        return callCli(["authoring-session", "list"]);
+      },
+    },
+  ];
+}

package/src/tools/diff.js

@@ -0,0 +1,48 @@
+// 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.
+
+import { runCli } from "../cli.js";
+
+export function createDiffTools() {
+  return [
+    {
+      name: "diff_datasets",
+      description:
+        "Compare two design data datasets and return a JSON diff of added, removed, and changed tokens.",
+      inputSchema: {
+        type: "object",
+        required: ["oldPath", "newPath"],
+        properties: {
+          oldPath: {
+            type: "string",
+            description: "Path to the old/baseline dataset",
+          },
+          newPath: {
+            type: "string",
+            description: "Path to the new/updated dataset",
+          },
+          filter: {
+            type: "string",
+            description: "Optional filter expression to narrow results",
+          },
+        },
+        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);
+      },
+    },
+  ];
+}

package/src/tools/read.js

@@ -0,0 +1,135 @@
+// 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.
+
+import { runCli } from "../cli.js";
+import { config } from "../config.js";
+
+export function createReadTools() {
+  return [
+    {
+      name: "primer",
+      description:
+        "Load the design data primer: full token taxonomy, resolved values, component list, and field definitions. Call this at the start of an agent session.",
+      inputSchema: {
+        type: "object",
+        properties: {},
+        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);
+        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:
+        "Resolve a design token property to its final value for a given color scheme, scale, and contrast level.",
+      inputSchema: {
+        type: "object",
+        required: ["property"],
+        properties: {
+          property: {
+            type: "string",
+            description:
+              "Token property name, e.g. accent-background-color-default",
+          },
+          colorScheme: {
+            type: "string",
+            description: "Color scheme: light or dark",
+          },
+          scale: {
+            type: "string",
+            enum: ["desktop", "mobile"],
+            description: "Scale: desktop or mobile",
+          },
+          contrast: {
+            type: "string",
+            enum: ["regular", "high"],
+            description: "Contrast: regular or high",
+          },
+        },
+        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);
+      },
+    },
+    {
+      name: "query_tokens",
+      description:
+        "Query design tokens using a filter expression. Returns matching token entries.",
+      inputSchema: {
+        type: "object",
+        required: ["filter"],
+        properties: {
+          filter: {
+            type: "string",
+            description: 'Filter expression, e.g. "category=color"',
+          },
+        },
+        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);
+      },
+    },
+    {
+      name: "describe_component",
+      description:
+        "Return the JSON schema and token bindings for a design system component by its ID.",
+      inputSchema: {
+        type: "object",
+        required: ["id"],
+        properties: {
+          id: { type: "string", description: "Component ID, e.g. button" },
+        },
+        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);
+      },
+    },
+  ];
+}

package/src/tools/validate.js

@@ -0,0 +1,49 @@
+// 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.
+
+import { runCli } from "../cli.js";
+import { config } from "../config.js";
+
+export function createValidateTools() {
+  return [
+    {
+      name: "validate_usage",
+      description:
+        "Validate design token usage in a dataset. Returns a JSON report of violations and warnings.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          path: {
+            type: "string",
+            description:
+              "Path to dataset to validate (defaults to DESIGN_DATA_PATH)",
+          },
+          strict: { type: "boolean", description: "Treat warnings as errors" },
+        },
+        additionalProperties: false,
+      },
+      async handler({ path, strict } = {}) {
+        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);
+      },
+    },
+  ];
+}

package/src/tools/write.js

@@ -0,0 +1,48 @@
+// 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.
+
+import { join } from "path";
+import { runCli } from "../cli.js";
+import { config } from "../config.js";
+
+export function createWriteTools() {
+  return [
+    {
+      name: "write",
+      description:
+        "Write agent-generated design context to the dataset (e.g. product-context.json). Returns a confirmation message.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          output: {
+            type: "string",
+            description:
+              "Output file path (defaults to product-context.json inside DESIGN_DATA_PATH)",
+          },
+          rationale: {
+            type: "string",
+            description: "Rationale or summary to embed in the written file",
+          },
+        },
+        additionalProperties: false,
+      },
+      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;
+      },
+    },
+  ];
+}