@adobe/design-data-mcp 1.6.0 → 1.7.1

package/README.md

@@ -1,8 +1,18 @@
-# [**@adobe/design-data-mcp**](https://github.com/adobe/design-data-mcp)
+# [**@adobe/design-data-mcp**](https://github.com/adobe/spectrum-design-data/tree/main/tools/design-data-mcp)
 
-MCP server for [Adobe Spectrum](https://spectrum.adobe.com) design tokens and component schemas, powered by the [`@adobe/design-data`](https://www.npmjs.com/package/@adobe/design-data) CLI.
+MCP server for [Adobe Spectrum](https://spectrum.adobe.com) design tokens, component schemas,
+and design guidelines. Runs fully in-process via an embedded Spectrum snapshot — no network
+access, no CLI binary, and no configuration required.
 
-## Setup
+## Install in Claude Desktop (Extension)
+
+Download the latest `design-data.mcpb` from the
+[releases page](https://github.com/adobe/spectrum-design-data/releases) and drag it into
+**Claude Desktop → Settings → Extensions**.
+
+No API keys or configuration needed. The extension installs and runs offline.
+
+## Setup via npx (Cursor / Claude Desktop manual config)
 
 ### Cursor
 
@@ -19,7 +29,7 @@ Add to `.cursor/mcp-servers.json` in your project root:
 }
 ```
 
-### Claude Desktop
+### Claude Desktop (manual config)
 
 Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
@@ -36,26 +46,15 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
 ## Tools
 
-| Tool                    | Description                                                                |
-| ----------------------- | -------------------------------------------------------------------------- |
-| `design-data-primer`    | Session-start overview: token count, mode-sets, components, provenance     |
-| `design-data-query`     | Filter tokens by query expression (`component=button`, `property=color-*`) |
-| `design-data-suggest`   | Natural-language token suggestions with confidence scores                  |
-| `design-data-component` | Full component schema (variants, sizes, states, props)                     |
-| `design-data-resolve`   | Resolve a token's concrete value for a mode context                        |
-
-## Custom dataset
-
-Add a `.design-data.toml` to your project root to use a specific Spectrum version or a custom fork:
-
-```toml
-[source]
-type = "github"
-repo = "adobe/spectrum-design-data"
-tag = "@adobe/spectrum-tokens@14.11.0"
-```
-
-Without a config file the embedded Spectrum snapshot is used automatically (offline, zero-setup).
+| Tool                         | Description                                                                        |
+| ---------------------------- | ---------------------------------------------------------------------------------- |
+| `design-data-primer`         | Session-start overview: token count, mode-sets, components, guidelines, provenance |
+| `design-data-query`          | Filter tokens by query expression (`component=button`, `property=color-*`)         |
+| `design-data-suggest`        | Natural-language token suggestions with Jaccard similarity confidence scores       |
+| `design-data-component`      | Full component schema (variants, sizes, states, props) by kebab-case ID            |
+| `design-data-resolve`        | Resolve a token's concrete value for a mode context (colorScheme, scale, contrast) |
+| `design-data-guideline-list` | List available Spectrum design guideline pages, optionally filtered by category    |
+| `design-data-guideline`      | Full guideline document by slug ID (purpose, rules, accessibility, examples)       |
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@adobe/design-data-mcp",
-  "version": "1.6.0",
-  "description": "MCP server for Spectrum design tokens and component schemas via the design-data CLI",
+  "version": "1.7.1",
+  "description": "MCP server for Spectrum design tokens, component schemas, and design guidelines (embedded, offline)",
   "type": "module",
   "main": "./src/index.js",
   "bin": {
@@ -32,7 +32,9 @@
     "@adobe/spectrum-design-data": "0.7.0"
   },
   "devDependencies": {
-    "ava": "^6.0.1"
+    "@anthropic-ai/mcpb": "^2.1.2",
+    "ava": "^6.0.1",
+    "sharp": "^0.35.1"
   },
   "engines": {
     "node": ">=20.12.0"
@@ -40,9 +42,10 @@
   "keywords": [
     "mcp",
     "spectrum",
+    "adobe",
     "design-system",
     "design-tokens",
-    "cli"
+    "design-data"
   ],
   "author": "Adobe",
   "license": "Apache-2.0",

package/src/index.js

@@ -11,12 +11,10 @@
 /**
  * @adobe/design-data-mcp — MCP server for Spectrum design tokens and components.
  *
- * Wraps the @adobe/design-data CLI as five MCP tools, making Spectrum design
- * data available to any MCP-compatible agent (Cursor, Claude Desktop, etc.)
- * without requiring a Rust toolchain or monorepo checkout.
- *
- * The CLI resolves data automatically: it uses the embedded Spectrum snapshot
- * for zero-config offline use, or a `.design-data.toml` config for custom sources.
+ * Exposes seven read-only MCP tools backed by @adobe/design-data-wasm running
+ * in-process (no CLI binary or npx required). The embedded Spectrum snapshot
+ * powers zero-config offline use across Claude Desktop, Cursor, and any
+ * MCP-compatible agent.
  */
 
 import { readFileSync } from "fs";
@@ -45,10 +43,11 @@ export function createMCPServer() {
   const tools = createDesignDataTools();
 
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
-    tools: tools.map(({ name, description, inputSchema }) => ({
+    tools: tools.map(({ name, description, inputSchema, annotations }) => ({
       name,
       description,
       inputSchema,
+      annotations,
     })),
   }));
 

package/src/tools/design-data.js

@@ -18,7 +18,7 @@
 
 import { createRequire } from "module";
 import { readFileSync, existsSync } from "fs";
-import { join, dirname } from "path";
+import { join, dirname, resolve, sep } from "path";
 
 let _wasm;
 /** Lazy-load and cache the wasm module (nodejs target, no init() required). */
@@ -56,6 +56,10 @@ function resolveSpectrumDataPackage() {
  * Load a JSON file from a subdirectory of the design-data package.
  * Throws descriptive errors when the package or file is absent.
  *
+ * Path safety: the resolved absolute path is asserted to stay within
+ * `<pkgRoot>/<subdir>/` so that a crafted `id` value (e.g. `../../etc/passwd`)
+ * cannot read files outside the intended data directory.
+ *
  * @param {string} subdir - e.g. "components" or "guidelines"
  * @param {string} id - kebab-case slug, e.g. "button" or "colors"
  */
@@ -67,7 +71,12 @@ function loadDataFile(subdir, id) {
         `Install it with: pnpm add @adobe/spectrum-design-data`,
     );
   }
-  const filePath = join(pkgRoot, subdir, `${id}.json`);
+  const baseDir = resolve(pkgRoot, subdir);
+  const filePath = resolve(baseDir, `${id}.json`);
+  // Containment check: reject any path that escapes the intended subdirectory.
+  if (!filePath.startsWith(baseDir + sep)) {
+    throw new Error(`Invalid ${subdir} id: "${id}"`);
+  }
   if (!existsSync(filePath)) {
     throw new Error(
       `Not found: "${id}" in ${subdir}/. ` +
@@ -96,6 +105,11 @@ export function createDesignDataTools() {
     // ── primer ─────────────────────────────────────────────────────────────
     {
       name: "design-data-primer",
+      annotations: {
+        title: "Design Data: Primer",
+        readOnlyHint: true,
+        openWorldHint: false,
+      },
       description:
         "Get a structural overview of the Spectrum design dataset: token count, " +
         "available mode-sets (color-scheme, scale, contrast), component list, " +
@@ -119,7 +133,14 @@ export function createDesignDataTools() {
             }
           : null;
 
+        // Provenance carries source + designDataVersion (the @adobe/spectrum-design-data
+        // package version baked into the wasm at build time via EMBEDDED_DATA_VERSION).
+        const { provenance } = ds.primer();
+
         return {
+          // top-level source is the legacy skill-contract field; provenance.source
+          // duplicates it intentionally — provenance is the richer metrics object
+          // and consumers should prefer it going forward.
           source: "embedded",
           tokenCount: ds.tokenCount(),
           modeSets: {
@@ -134,6 +155,7 @@ export function createDesignDataTools() {
           components: wasm.getFieldValues("component") ?? [],
           properties: wasm.getFieldValues("property") ?? [],
           guidelines: guidelinesSummary,
+          provenance,
         };
       },
     },
@@ -141,6 +163,11 @@ export function createDesignDataTools() {
     // ── query ───────────────────────────────────────────────────────────────
     {
       name: "design-data-query",
+      annotations: {
+        title: "Design Data: Query Tokens",
+        readOnlyHint: true,
+        openWorldHint: false,
+      },
       description:
         "Filter Spectrum tokens by a query expression. " +
         "Expression syntax: `component=button`, `component=button,state=hover`, " +
@@ -167,6 +194,11 @@ export function createDesignDataTools() {
     // ── suggest ─────────────────────────────────────────────────────────────
     {
       name: "design-data-suggest",
+      annotations: {
+        title: "Design Data: Suggest Tokens",
+        readOnlyHint: true,
+        openWorldHint: false,
+      },
       description:
         "Suggest Spectrum tokens matching a natural-language intent using Jaccard similarity " +
         "scoring over token name segments, name-object fields, and description text. " +
@@ -198,6 +230,11 @@ export function createDesignDataTools() {
     // ── component ───────────────────────────────────────────────────────────
     {
       name: "design-data-component",
+      annotations: {
+        title: "Design Data: Get Component",
+        readOnlyHint: true,
+        openWorldHint: false,
+      },
       description:
         "Get the full component declaration for a Spectrum component by ID. " +
         "Returns the component's displayName, description, and all available options " +
@@ -223,6 +260,11 @@ export function createDesignDataTools() {
     // ── resolve ─────────────────────────────────────────────────────────────
     {
       name: "design-data-resolve",
+      annotations: {
+        title: "Design Data: Resolve Token",
+        readOnlyHint: true,
+        openWorldHint: false,
+      },
       description:
         "Resolve the concrete value of a Spectrum token property for a given " +
         "mode-set context (color-scheme, scale, contrast). " +
@@ -270,6 +312,11 @@ export function createDesignDataTools() {
     // ── guideline-list ──────────────────────────────────────────────────────
     {
       name: "design-data-guideline-list",
+      annotations: {
+        title: "Design Data: List Guidelines",
+        readOnlyHint: true,
+        openWorldHint: false,
+      },
       description:
         "List available Spectrum design guideline pages. " +
         "Returns catalog entries with slug, title, category, status, and sourceUrl. " +
@@ -306,6 +353,11 @@ export function createDesignDataTools() {
     // ── guideline ───────────────────────────────────────────────────────────
     {
       name: "design-data-guideline",
+      annotations: {
+        title: "Design Data: Get Guideline",
+        readOnlyHint: true,
+        openWorldHint: false,
+      },
       description:
         "Get the full guideline document for a Spectrum design page by ID. " +
         "Returns the guideline's title, category, metadata, and documentBlocks body " +