@adobe/design-data-mcp 1.7.35 → 1.7.37

package/README.md

@@ -51,6 +51,11 @@ package version — there's no separate data update to run. Pin `@latest` (as ab
 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. Call `design-data-primer` and
 check `provenance.designDataVersion` to see which dataset version is embedded.
+`design-data-primer` 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.
 
 ## Tools
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/design-data-mcp",
-  "version": "1.7.35",
+  "version": "1.7.37",
   "description": "MCP server for Spectrum design tokens, component schemas, and design guidelines (embedded, offline)",
   "type": "module",
   "main": "./src/index.js",
@@ -29,7 +29,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
     "@adobe/design-data-wasm": "0.7.0",
-    "@adobe/spectrum-design-data": "2.7.0"
+    "@adobe/spectrum-design-data": "3.0.0"
   },
   "devDependencies": {
     "@anthropic-ai/mcpb": "^2.1.2",

package/src/dataset-freshness.js

@@ -0,0 +1,95 @@
+// Copyright 2026 Adobe. All rights reserved.
+// This file is licensed to you under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License. You may obtain a copy
+// of the License at http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software distributed under
+// the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+// OF ANY KIND, either express or implied. See the License for the specific language
+// governing permissions and limitations under the License.
+
+/**
+ * Best-effort runtime check that the embedded dataset (provenance.designDataVersion,
+ * baked into @adobe/design-data-wasm at build time) isn't behind the latest published
+ * @adobe/spectrum-design-data. See spectrum-design-data-9fe.5 — a plain `npx -y <pkg>`
+ * (no @latest tag) can silently reuse a cached older wasm build.
+ *
+ * Deliberately silent on any failure (offline, registry down, timeout): this is a
+ * courtesy signal, never a reason to break the primer response.
+ */
+
+const REGISTRY_URL =
+  "https://registry.npmjs.org/@adobe/spectrum-design-data/latest";
+const TIMEOUT_MS = 1500;
+
+/**
+ * Numeric major.minor.patch compare. ponytail: ignores prerelease/build tags;
+ * add real semver only if a data prerelease ships.
+ */
+export function isBehind(embedded, latest) {
+  const a = String(embedded).split(".").map(Number);
+  const b = String(latest).split(".").map(Number);
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    const x = a[i] ?? 0;
+    const y = b[i] ?? 0;
+    if (x !== y) return x < y;
+  }
+  return false;
+}
+
+let warned = false;
+let cached; // Promise<status|null>, memoized per process — cleared on failure so a
+// transient network blip doesn't permanently disable the check (see fetchLatest).
+
+/**
+ * @param {string} embeddedVersion - provenance.designDataVersion from ds.primer()
+ * @returns {Promise<{latestVersion: string, isStale: boolean, message?: string}|null>}
+ */
+export function checkDatasetFreshness(embeddedVersion) {
+  if (!embeddedVersion || process.env.DESIGN_DATA_SKIP_VERSION_CHECK) {
+    return Promise.resolve(null);
+  }
+  if (!cached) {
+    cached = fetchLatest(embeddedVersion).then((status) => {
+      // A null result means the check failed (offline/timeout/registry error) —
+      // don't memoize failure, so the next primer call retries instead of being
+      // stuck with no freshness signal for the rest of the process.
+      if (status === null) cached = undefined;
+      return status;
+    });
+  }
+  return cached;
+}
+
+async function fetchLatest(embeddedVersion) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+  try {
+    const res = await fetch(REGISTRY_URL, { signal: controller.signal });
+    if (!res.ok) return null;
+    const { version: latestVersion } = await res.json();
+    const isStale = isBehind(embeddedVersion, latestVersion);
+    const status = { latestVersion, isStale };
+    if (isStale) {
+      status.message =
+        `Embedded dataset (${embeddedVersion}) is behind the latest published ` +
+        `@adobe/spectrum-design-data (${latestVersion}). Reinstall with ` +
+        `npx -y @adobe/design-data-mcp@latest to pick up the newer snapshot.`;
+      if (!warned) {
+        warned = true;
+        console.error(`[design-data] ${status.message}`);
+      }
+    }
+    return status;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Test-only: clear the memoized check + warn-once flag between cases. */
+export function __resetFreshnessCache() {
+  warned = false;
+  cached = undefined;
+}

package/src/tools/design-data.js

@@ -20,6 +20,8 @@ import { createRequire } from "module";
 import { readFileSync, existsSync } from "fs";
 import { join, dirname, resolve, sep } from "path";
 
+import { checkDatasetFreshness } from "../dataset-freshness.js";
+
 let _wasm;
 /** Lazy-load and cache the wasm module (nodejs target, no init() required). */
 async function getWasm() {
@@ -136,6 +138,11 @@ export function createDesignDataTools() {
         // 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();
+        // Best-effort staleness check (spectrum-design-data-9fe.5) — silent on
+        // failure, never blocks the primer response.
+        const datasetStatus = await checkDatasetFreshness(
+          provenance.designDataVersion,
+        );
 
         return {
           // top-level source is the legacy skill-contract field; provenance.source
@@ -155,7 +162,9 @@ export function createDesignDataTools() {
           components: wasm.getFieldValues("component") ?? [],
           properties: wasm.getFieldValues("property") ?? [],
           guidelines: guidelinesSummary,
-          provenance,
+          provenance: datasetStatus
+            ? { ...provenance, datasetStatus }
+            : provenance,
         };
       },
     },