@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, suggest_token, describe_component, describe_guideline, list_guidelines) run fully in-process via @adobe/design-data-wasm — no CLI binary required for those. suggest_token uses the wasm suggest API directly; authoring_session_step_intent still invokes the native binary for session-state-aware ranking within an authoring flow.

Testing guideline content

Run moon run design-data-agent-mcp:test. For the packaged content contracts only, after moon run sdk-wasm:build, run:

pnpm --filter @adobe/design-data-agent-mcp exec ava test/packaged-guidelines.test.js

The suite uses pnpm pack to test the agent's publishable files, extracts the tarball into a fresh private tree, and vendors local runtime dependencies using the MCPB packaging allowlists. It initializes the packed server over stdio with no data overrides, checks the catalog against the canonical manifest, compares every guideline response to source JSON, and checks invalid-slug errors. An import guard rejects ESM imports and CommonJS requires outside the private tree.

Dependencies come from the local build, not registry tarballs, so this is not a registry-install test. It does not assess model answer quality. The tests remove private staging trees afterward.

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 design-data CLI binary (0.13.0 or newer) is needed for authoring_session_step_intent and whenever DESIGN_DATA_CONFIG is set, because the platform cascade runs design-data catalog export. All other tools run in-process. Install it with Homebrew:

brew tap adobe/spectrum-design-data https://github.com/adobe/spectrum-design-data
brew install adobe/spectrum-design-data/design-data

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

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 either its top-level manifest cascade or, if DESIGN_DATA_PLATFORM is also set, that named [platforms.<id>] entry's manifest — mirroring the CLI's own --platform/DESIGN_DATA_PLATFORM, then materializes the result to a temp dir and points primer / resolve_token / query_tokens / validate_usage / describe_component / describe_guideline / list_guidelines at it instead of the embedded Spectrum snapshot. Component and guideline catalogs come from design-data catalog export --out <dir> [--platform <id>], so extension components, implementation rows, and replacements come from the SDK cascade (this needs a design-data newer than 0.12.1). Relationships are still copied from the fallback dataset and overlaid with platform manifest extensions. 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 / describe_guideline 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

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