@adobe/design-data-agent-mcp 1.9.14-beta.0 → 1.10.0-beta.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/) 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).
+MCP server and Claude Code skill for the [Spectrum Design Data](../../packages/design-data/) agent surface. Read tools (`primer`, `resolve_token`, `query_tokens`, `describe_component`, `describe_guideline`) 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
 
@@ -66,6 +66,7 @@ node tools/design-data-agent-mcp/src/index.js
 | `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_GUIDELINES` | —             | Override guidelines directory                                                  |
 | `DESIGN_DATA_FIELDS`     | —             | Override fields directory                                                      |
 | `DESIGN_DATA_SCHEMAS`    | —             | Override schema path (for `validate`)                                          |
 | `DESIGN_DATA_EXCEPTIONS` | —             | Override exceptions path (for `validate`)                                      |
@@ -77,8 +78,9 @@ node tools/design-data-agent-mcp/src/index.js
 > 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
+> snapshot. `describe_component` / `describe_guideline` are unaffected — they always
+> read components/guidelines 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.
 
@@ -100,8 +102,8 @@ node tools/design-data-agent-mcp/src/index.js
 >    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.
+>    `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.
@@ -150,6 +152,7 @@ node tools/design-data-agent-mcp/src/index.js
 | `resolve_token`      | Resolve a token property to its literal value                   |
 | `query_tokens`       | Filter tokens by expression                                     |
 | `describe_component` | Fetch component schema and token bindings                       |
+| `describe_guideline` | Fetch guideline documentBlocks content and metadata             |
 | `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            |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/design-data-agent-mcp",
-  "version": "1.9.14-beta.0",
+  "version": "1.10.0-beta.1",
   "description": "MCP server and Claude Code skill for the design-data agent surface — read tools run in-process via wasm",
   "type": "module",
   "main": "./src/index.js",
@@ -30,9 +30,9 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
-    "@adobe/design-data": "3.0.9",
+    "@adobe/design-data": "3.1.0-beta.0",
     "@adobe/design-data-wasm": "0.9.0",
-    "@adobe/spectrum-design-data": "3.3.0-beta.0"
+    "@adobe/spectrum-design-data": "3.3.0-beta.1"
   },
   "devDependencies": {
     "ava": "^6.0.1"

package/skills/design-data/SKILL.md

@@ -6,7 +6,7 @@ description: >
   system, token lookup, spec-conformance, drift detection, or token authoring on custom data.
 metadata:
   author: adobe
-  version: "1.9.14-beta.0"
+  version: "1.10.0-beta.1"
 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,

package/src/config.js

@@ -74,6 +74,10 @@ export const config = {
     anchorPath(process.env.DESIGN_DATA_RELATIONSHIPS) ??
     resolveDataPackageDir("relationships") ??
     null,
+  guidelinesDir:
+    anchorPath(process.env.DESIGN_DATA_GUIDELINES) ??
+    resolveDataPackageDir("guidelines") ??
+    null,
   fieldsDir:
     anchorPath(process.env.DESIGN_DATA_FIELDS) ??
     resolveDataPackageDir("fields") ??

package/src/tools/read.js

@@ -13,6 +13,12 @@
  *
  * All read tools run fully in-process via @adobe/design-data-wasm — no CLI binary
  * required. primer and describe_component were migrated in issue m1r.
+ * describe_guideline (spectrum-design-data-9fe.7) is the read-back counterpart to
+ * data_create/data_edit's "guidelines" category, closing the same read/write
+ * asymmetry describe_component already closes for components. Its guideline-loading
+ * logic (including the path-traversal guard) is shared with the sibling
+ * @adobe/design-data-mcp package's `design-data-guideline` tool via the
+ * `@adobe/design-data/guideline` module, rather than duplicated here.
  *
  * Note: authoring_session_step_intent in authoring.js still uses the CLI because
  * the NLP suggest ranking is not yet on the wasm surface.
@@ -20,17 +26,19 @@
  * Cascade scope (see cascade-bootstrap.js / spectrum-design-data-h890.14): once a
  * `.design-data.toml` cascade is resolved, primer/resolve_token/query_tokens/
  * validate_usage all reflect it (they read config.cascadeDataPath instead of
- * config.dataPath when config.cascadeActive). describe_component
- * does not — components/relationships still come from config.componentsDir /
- * config.relationshipsDir, which resolve from the embedded @adobe/spectrum-design-data
- * package regardless of cascade state. A platform source repo generally carries a
- * token cascade only, not its own component schemas, so this is left out of scope
- * rather than guessed at; revisit if a platform manifest starts declaring components.
+ * config.dataPath when config.cascadeActive). describe_component/describe_guideline
+ * do not — components/relationships/guidelines still come from config.componentsDir /
+ * config.relationshipsDir / config.guidelinesDir, which resolve from the embedded
+ * @adobe/spectrum-design-data package regardless of cascade state. A platform source
+ * repo generally carries a token cascade only, not its own component/guideline
+ * schemas, so this is left out of scope rather than guessed at; revisit if a platform
+ * manifest starts declaring components or guidelines.
  */
 
 import { readFileSync, existsSync, readdirSync } from "fs";
 import { join } from "path";
 import { loadDataset } from "@adobe/design-data/load";
+import { loadGuideline } from "@adobe/design-data/guideline";
 import { config } from "../config.js";
 import { checkDatasetFreshness } from "../dataset-freshness.js";
 
@@ -71,19 +79,27 @@ async function getDataset() {
 }
 
 /**
- * Validate a component ID against the same rule as the Rust SDK.
+ * Validate a kebab-case ID against the same rule as the Rust SDK.
  * See sdk/core/src/component.rs:validate_id — prevents path traversal.
  */
-const COMPONENT_ID_RE = /^[a-z][a-z0-9-]*$/;
-function validateComponentId(id) {
-  if (!COMPONENT_ID_RE.test(id)) {
+const KEBAB_ID_RE = /^[a-z][a-z0-9-]*$/;
+function validateKebabId(id, kind) {
+  if (!KEBAB_ID_RE.test(id)) {
     throw new Error(
-      `Invalid component ID "${id}". IDs must be kebab-case: start with a lowercase ` +
+      `Invalid ${kind} ID "${id}". IDs must be kebab-case: start with a lowercase ` +
         `letter and contain only lowercase letters, digits, and hyphens.`,
     );
   }
 }
 
+function validateComponentId(id) {
+  validateKebabId(id, "component");
+}
+
+function validateGuidelineId(id) {
+  validateKebabId(id, "guideline");
+}
+
 export function createReadTools() {
   return [
     {
@@ -265,5 +281,56 @@ export function createReadTools() {
         return component;
       },
     },
+
+    {
+      name: "describe_guideline",
+      description:
+        "Return the full documentBlocks content and metadata for a Spectrum design " +
+        "guideline by its slug ID — the read-back counterpart to data_create/data_edit " +
+        "for the guidelines category. Guideline IDs are kebab-case, e.g. colors, motion, " +
+        "typography-fundamentals.",
+      inputSchema: {
+        type: "object",
+        required: ["id"],
+        properties: {
+          id: {
+            type: "string",
+            description: "Guideline ID (kebab-case slug), e.g. colors, motion",
+          },
+        },
+        additionalProperties: false,
+      },
+      async handler({ id }) {
+        validateGuidelineId(id);
+        const guidelinesDir = config.guidelinesDir;
+        if (!guidelinesDir) {
+          throw new Error(
+            `@adobe/spectrum-design-data is not installed — cannot load guideline "${id}". ` +
+              `Install it with: pnpm add @adobe/spectrum-design-data`,
+          );
+        }
+        try {
+          return loadGuideline(guidelinesDir, id);
+        } catch (err) {
+          if (err.message.startsWith("Not found:")) {
+            let available;
+            try {
+              available = readdirSync(guidelinesDir)
+                .filter((f) => f.endsWith(".json") && f !== "manifest.json")
+                .map((f) => f.replace(/\.json$/, ""))
+                .sort()
+                .join(", ");
+            } catch {
+              available = null;
+            }
+            const hint = available
+              ? `Available guidelines: ${available}`
+              : `Check packages/design-data/guidelines/manifest.json for available IDs.`;
+            throw new Error(`Guideline not found: "${id}". ${hint}`);
+          }
+          throw err;
+        }
+      },
+    },
   ];
 }