@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@latest

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.

Staying current

The embedded Spectrum snapshot is baked into the wasm at build time and travels with the package version — there's no separate data update to run. Pin @latest (as above) so npx fetches the newest published version rather than reusing whatever it last cached; -y alone only skips the install confirmation, it doesn't force a re-fetch. Already on /plugin? Run /plugin update design-data-agent@spectrum-design-data. Call the primer tool and check provenance.designDataVersion to see which dataset version is embedded. The primer tool also does a best-effort check against the latest published @adobe/spectrum-design-data version — if the embedded dataset is behind, it adds a provenance.datasetStatus field and logs a one-line warning to stderr. This is silent on any network failure (offline/air-gapped use is unaffected); set DESIGN_DATA_SKIP_VERSION_CHECK=1 to disable the check entirely.

MCP server

Configure your MCP client to run:

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

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) | | DESIGN_DATA_CONFIG | — | Path to a .design-data.toml (or its directory) to resolve a platform cascade |

Platform cascade. If DESIGN_DATA_CONFIG is set, the server shells out to the design-data CLI once at startup (design-data query --filter "" --format json, run from the config's directory) to resolve its .design-data.toml source (path/npm/github/git) and any top-level manifest cascade, then materializes the result to a temp dir and points primer / resolve_token / query_tokens / validate_usage at it instead of the embedded Spectrum snapshot. describe_component is unaffected — it always reads components from @adobe/spectrum-design-data regardless of cascade state. If resolution fails (e.g. no network for a github source), the server logs a warning and falls back to the embedded/local dataset rather than crashing.

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@latest"],
      "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@latest"],
      "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