Design Data Agent

@adobe/design-data-agent-mcp

MCP server and Claude Code skill for the Spectrum 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

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/.

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)

npx @adobe/design-data-agent-mcp

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

Configure your MCP client to run:

npx -y @adobe/design-data-agent-mcp

Or from a repo clone:

node tools/design-data-agent-mcp/src/index.js

Environment variables

Variable	Default	Description
DESIGN_DATA_BIN	design-data	Path to the design-data binary (authoring only)
DESIGN_DATA_ROOT	—	Absolute root that relative paths are anchored to
DESIGN_DATA_PATH	.	Dataset root path
DESIGN_DATA_COMPONENTS	—	Override components directory
DESIGN_DATA_FIELDS	—	Override fields directory
DESIGN_DATA_SCHEMAS	—	Override schema path (for validate)
DESIGN_DATA_EXCEPTIONS	—	Override exceptions path (for validate)

Path resolution. The MCP client launches this server with the working directory inherited from wherever the editor was opened — which may be a subdirectory of your repo (e.g. sdk/), not the repo root. To stay independent of that working directory, each data path is resolved in this order:

1. Explicit env override. If DESIGN_DATA_PATH / DESIGN_DATA_COMPONENTS / DESIGN_DATA_FIELDS is set, it is used. Relative values are anchored to DESIGN_DATA_ROOT (absolute, recommended when launching via npx) or, if that is unset, to the server package's own location in the monorepo. Absolute values are used as-is.
2. Resolved @adobe/spectrum-design-data package (zero config). When no env override is set, the server resolves the installed @adobe/spectrum-design-data package via Node module resolution and reads its tokens/, components/, and fields/ directories. In a pnpm workspace this follows the symlink to packages/design-data; when published it uses the installed dependency. This is independent of the working directory.
3. Fallback. dataPath falls back to the (anchored) current directory; the component/field overrides fall back to 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.

Example (Cursor .cursor/mcp.json)

{
  "mcpServers": {
    "design-data-agent": {
      "command": "npx",
      "args": ["-y", "@adobe/design-data-agent-mcp"],
      "env": {
        "DESIGN_DATA_ROOT": "/abs/path/to/your/repo",
        "DESIGN_DATA_PATH": "packages/design-data/tokens",
        "DESIGN_DATA_COMPONENTS": "packages/design-data/components",
        "DESIGN_DATA_FIELDS": "packages/design-data/fields"
      }
    }
  }
}

Example (Claude Desktop claude_desktop_config.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. It shells out to npx @adobe/design-data for validate, query, resolve, diff, and write operations against local datasets.

License

Apache-2.0