@adobe/design-data-agent-mcp 1.3.0 → 1.4.1

package/README.md

@@ -1,6 +1,6 @@
 # `@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.
+MCP server and Claude Code skill for the [Spectrum Design Data](../../packages/design-data/) agent surface. Shells out to the `design-data` CLI — all logic stays in the Rust SDK.
 
 ## Install
 
@@ -47,15 +47,38 @@ 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`) |
+| Variable                 | Default       | Description                                       |
+| ------------------------ | ------------- | ------------------------------------------------- |
+| `DESIGN_DATA_BIN`        | `design-data` | Path to the `design-data` binary                  |
+| `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 the `design-data` binary's own
+>    discovery (including its embedded snapshot).
+>
+> 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`)
 
@@ -66,10 +89,10 @@ node tools/design-data-agent-mcp/src/index.js
       "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"
+        "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"
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/design-data-agent-mcp",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "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",
@@ -14,10 +14,6 @@
     "README.md",
     "LICENSE"
   ],
-  "scripts": {
-    "start": "node src/index.js",
-    "test": "ava"
-  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/adobe/spectrum-design-data.git",
@@ -33,7 +29,8 @@
     "provenance": true
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.27.1"
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@adobe/spectrum-design-data": "0.3.0"
   },
   "devDependencies": {
     "ava": "^6.0.1"
@@ -50,5 +47,9 @@
     "cli"
   ],
   "author": "Adobe",
-  "license": "Apache-2.0"
-}
+  "license": "Apache-2.0",
+  "scripts": {
+    "start": "node src/index.js",
+    "test": "ava"
+  }
+}

package/skills/design-data/SKILL.md

@@ -18,8 +18,8 @@ allowed-tools: Bash(npx @adobe/design-data *)
 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
+export DESIGN_DATA_PATH=./packages/design-data/tokens
+export DESIGN_DATA_SPEC_PATH=./packages/design-data
 ```
 
 For Spectrum tokens with zero setup (embedded snapshot), use the `design-data` skill instead — this skill targets custom or repo-local datasets.
@@ -41,13 +41,12 @@ Call `primer` at the start of every session that touches design data. It returns
 ```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"
+  --fields-dir     "$DESIGN_DATA_SPEC_PATH/fields"
 ```
 
-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`.
+Always pass `--components-dir` and `--fields-dir` explicitly. These directories live under `packages/design-data/`, alongside 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` and `taxonomyFields`.
 
-The payload includes `specVersion`, `manifest`, `dimensions`, `components`, `taxonomyFields`, and `tokenCount`.
+The payload includes `specVersion`, `manifest`, `components`, `taxonomyFields`, and `tokenCount`.
 
 ***
 
@@ -175,9 +174,8 @@ For always-available tool access (higher context cost), add `@adobe/design-data-
       "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"
+        "DESIGN_DATA_COMPONENTS": "./packages/design-data/components",
+        "DESIGN_DATA_FIELDS": "./packages/design-data/fields"
       }
     }
   }

package/src/cli.js

@@ -14,6 +14,10 @@ import { config } from "./config.js";
 export function runCli(args, { timeout = 10_000 } = {}) {
   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
+      // tier/probe logic (data_source::resolve, is_in_repo) resolves correctly
+      // 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"],
     });

package/src/config.js

@@ -8,12 +8,70 @@
 // OF ANY KIND, either express or implied. See the License for the specific language
 // governing permissions and limitations under the License.
 
+import { createRequire } from "module";
+import { fileURLToPath } from "url";
+import { dirname, isAbsolute, resolve } from "path";
+
+// The repo root relative to this file: src → package → tools → repo root.
+// Used as the self-anchoring fallback when DESIGN_DATA_ROOT is not provided
+// and the server is run from inside the monorepo checkout.
+const SERVER_ROOT = fileURLToPath(new URL("../../..", import.meta.url));
+
+// Claude Code launches the MCP server with the working directory inherited from
+// wherever the editor was opened (e.g. `sdk/`), not the repo root. Relative
+// DESIGN_DATA_* paths must therefore be anchored to a known root rather than the
+// process CWD. Prefer an explicit absolute DESIGN_DATA_ROOT (works even when the
+// server is launched via `npx` from the npm cache); fall back to SERVER_ROOT for
+// in-repo runs.
+const dataRoot = process.env.DESIGN_DATA_ROOT
+  ? resolve(process.env.DESIGN_DATA_ROOT)
+  : SERVER_ROOT;
+
+function anchorPath(p) {
+  return p && !isAbsolute(p) ? resolve(dataRoot, p) : p;
+}
+
+// Locate a directory inside the @adobe/spectrum-design-data package via Node's
+// module resolution. In a pnpm workspace this resolves through the symlink to
+// `packages/design-data`; when published it resolves the installed dependency.
+// Either way it is independent of the process working directory, so it provides
+// a zero-config default that does not depend on where the server was launched.
+// Returns null when the package is not installed (e.g. a standalone CLI install
+// that relies on the design-data binary's embedded snapshot instead).
+function resolveDataPackageDir(subdir) {
+  try {
+    const pkgJson = createRequire(import.meta.url).resolve(
+      "@adobe/spectrum-design-data/package.json",
+    );
+    return resolve(dirname(pkgJson), subdir);
+  } catch {
+    return null;
+  }
+}
+
+// Path precedence: explicit env override (anchored to dataRoot) wins, then the
+// resolved design-data package directory, then a final fallback.
+//
+// The fallback differs by field on purpose: `dataPath` is a required positional
+// CLI argument, so it falls back to the anchored current directory. `componentsDir`
+// and `fieldsDir` are optional `--components-dir`/`--fields-dir` flags, so they fall
+// back to `null` (flag omitted) and let the design-data binary's own discovery —
+// including its embedded snapshot — locate them.
 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,
+  dataRoot,
+  dataPath:
+    anchorPath(process.env.DESIGN_DATA_PATH) ??
+    resolveDataPackageDir("tokens") ??
+    anchorPath("."),
+  schemaPath: anchorPath(process.env.DESIGN_DATA_SCHEMAS ?? null),
+  exceptionsPath: anchorPath(process.env.DESIGN_DATA_EXCEPTIONS ?? null),
+  componentsDir:
+    anchorPath(process.env.DESIGN_DATA_COMPONENTS) ??
+    resolveDataPackageDir("components") ??
+    null,
+  fieldsDir:
+    anchorPath(process.env.DESIGN_DATA_FIELDS) ??
+    resolveDataPackageDir("fields") ??
+    null,
 };

package/src/index.js

@@ -9,7 +9,7 @@
 // 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 { readFileSync, realpathSync } from "fs";
 import { fileURLToPath } from "url";
 import { resolve, dirname } from "path";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -89,7 +89,21 @@ async function startServer() {
   console.error("design-data-agent-mcp started");
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
+// Resolve real paths so the entry-point check still matches when this module is
+// launched through a symlink (e.g. node_modules/.bin shim created by npx/pnpm).
+function isMainModule() {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  const here = fileURLToPath(import.meta.url);
+  if (entry === here) return true;
+  try {
+    return realpathSync(entry) === realpathSync(here);
+  } catch {
+    return false;
+  }
+}
+
+if (isMainModule()) {
   startServer().catch((err) => {
     console.error(err);
     process.exit(1);

package/src/tools/read.js

@@ -27,8 +27,6 @@ export function createReadTools() {
         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}`);
@@ -67,9 +65,6 @@ export function createReadTools() {
       },
       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);

package/src/tools/validate.js

@@ -35,9 +35,6 @@ export function createValidateTools() {
         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)