@decantr/mcp-server 1.0.0-beta.10 → 1.0.0-beta.12

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Decantr AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -64,17 +64,16 @@ Add to your Windsurf MCP config (`~/.windsurf/mcp.json`):
 | `decantr_create_essence` | Generate an Essence spec skeleton from a project description | `{ "description": "SaaS dashboard with analytics and billing", "framework": "react" }` |
 | `decantr_read_essence` | Read the current `decantr.essence.json` from the working directory | `{}` or `{ "path": "./custom.essence.json" }` |
 | `decantr_validate` | Validate an Essence file against the schema and guard rules | `{ "path": "./decantr.essence.json" }` |
-| `decantr_search_registry` | Search the community registry for patterns, archetypes, recipes, and styles | `{ "query": "kanban", "type": "pattern" }` |
+| `decantr_search_registry` | Search the community registry for patterns, archetypes, themes, and shells | `{ "query": "kanban", "type": "pattern" }` |
 | `decantr_resolve_pattern` | Get full pattern details: layout spec, components, presets, code examples | `{ "id": "data-table", "preset": "product" }` |
 | `decantr_resolve_archetype` | Get archetype details: default pages, layouts, features, suggested theme | `{ "id": "saas-dashboard" }` |
-| `decantr_resolve_recipe` | Get recipe decoration rules: shell styles, spatial hints, visual effects | `{ "id": "auradecantism" }` |
 | `decantr_resolve_blueprint` | Get a full app composition with page structure and personality traits | `{ "id": "ecommerce" }` |
 | `decantr_suggest_patterns` | Given a page description, get ranked pattern suggestions | `{ "description": "dashboard with metrics and charts" }` |
 | `decantr_check_drift` | Check if generated code violates the design intent in the Essence spec | `{ "page_id": "overview", "components_used": ["Card", "LineChart"], "theme_used": "auradecantism" }` |
 
 ## How It Works
 
-An Essence spec (`decantr.essence.json`) captures your design intent -- archetype, theme, page structure, patterns, and guard rules -- in a single declarative file. The MCP server exposes this spec and the Decantr registry to your AI assistant, giving it concrete layout specs, component lists, and decoration rules instead of relying on the model's generic training data. The result is generated code that follows a coherent design system, and drift detection that catches deviations before they ship.
+An Essence spec (`decantr.essence.json`) captures your design intent -- archetype, theme, page structure, patterns, and guard rules -- in a single declarative file. The MCP server exposes this spec and the Decantr registry to your AI assistant, giving it concrete layout specs, component lists, and visual treatments instead of relying on the model's generic training data. The result is generated code that follows a coherent design system, and drift detection that catches deviations before they ship.
 
 ## Example Workflow
 
@@ -86,8 +85,7 @@ The AI assistant calls these tools behind the scenes:
 2. `decantr_resolve_archetype` -- pulls default pages, layouts, and features for a SaaS dashboard
 3. `decantr_suggest_patterns` -- recommends `kpi-grid`, `chart-grid`, `data-table`, and `form-sections` for the described pages
 4. `decantr_resolve_pattern` -- fetches layout specs and component lists for each pattern
-5. `decantr_resolve_recipe` -- loads decoration rules (spacing, borders, effects) for the theme
-6. `decantr_check_drift` -- validates the generated code against the Essence spec before presenting it
+5. `decantr_check_drift` -- validates the generated code against the Essence spec before presenting it
 
 The AI now generates code with the right layout structure, correct components, and consistent styling -- not a generic guess.
 

package/dist/bin.js

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-import "./chunk-A5IEC7O2.js";
+import "./chunk-YOFQYTEC.js";

package/dist/{chunk-A5IEC7O2.js → chunk-YOFQYTEC.js}

@@ -893,12 +893,12 @@ var TOOLS = [
   {
     name: "decantr_search_registry",
     title: "Search Registry",
-    description: "Search the Decantr community content registry for patterns, archetypes, recipes, and styles.",
+    description: "Search the Decantr community content registry for patterns, archetypes, themes, and shells.",
     inputSchema: {
       type: "object",
       properties: {
         query: { type: "string", description: 'Search query (e.g. "kanban", "neon", "dashboard")' },
-        type: { type: "string", description: "Filter by type: pattern, archetype, recipe, style" }
+        type: { type: "string", description: "Filter by type: pattern, archetype, theme, shell" }
       },
       required: ["query"]
     },
@@ -935,22 +935,7 @@ var TOOLS = [
     },
     annotations: READ_ONLY_NETWORK
   },
-  // 6. decantr_resolve_recipe — network
-  {
-    name: "decantr_resolve_recipe",
-    title: "Resolve Recipe",
-    description: "Get recipe visual treatment overrides, decoration rules, shell styles, spatial hints, visual effects, and pattern preferences.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        id: { type: "string", description: 'Recipe ID (e.g. "auradecantism")' },
-        namespace: { type: "string", description: 'Namespace (default: "@official")' }
-      },
-      required: ["id"]
-    },
-    annotations: READ_ONLY_NETWORK
-  },
-  // 7. decantr_resolve_blueprint — network
+  // 6. decantr_resolve_blueprint — network
   {
     name: "decantr_resolve_blueprint",
     title: "Resolve Blueprint",
@@ -1075,7 +1060,7 @@ var TOOLS = [
   {
     name: "decantr_get_section_context",
     title: "Get Section Context",
-    description: "Get the self-contained context for a specific section of the project. Returns guard rules, theme tokens, visual treatments, recipe decorators, pattern specs, zone context, and pages \u2014 everything an AI needs to work on that section.",
+    description: "Get the self-contained context for a specific section of the project. Returns guard rules, theme tokens, visual treatments, pattern specs, zone context, and pages \u2014 everything an AI needs to work on that section.",
     inputSchema: {
       type: "object",
       properties: {
@@ -1106,6 +1091,20 @@ var TOOLS = [
       required: ["component"]
     },
     annotations: READ_ONLY
+  },
+  // 15. decantr_critique — local read
+  {
+    name: "decantr_critique",
+    title: "Design Critique",
+    description: "Evaluate generated code against the essence spec for visual quality. Returns a scorecard covering treatment usage, decorator coverage, personality alignment, motion, accessibility, and responsiveness.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        file_path: { type: "string", description: "Path to the component file to critique" }
+      },
+      required: ["file_path"]
+    },
+    annotations: READ_ONLY
   }
 ];
 async function handleTool(name, args) {
@@ -1206,17 +1205,6 @@ async function handleTool(name, args) {
         return { found: false, message: `Archetype "${args.id}" not found in ${namespace}.` };
       }
     }
-    case "decantr_resolve_recipe": {
-      const err = validateStringArg(args, "id");
-      if (err) return { error: err };
-      const namespace = args.namespace || "@official";
-      try {
-        const recipe = await apiClient.getRecipe(namespace, args.id);
-        return { found: true, ...recipe };
-      } catch {
-        return { found: false, message: `Recipe "${args.id}" not found in ${namespace}.` };
-      }
-    }
     case "decantr_resolve_blueprint": {
       const err = validateStringArg(args, "id");
       if (err) return { error: err };
@@ -1224,14 +1212,14 @@ async function handleTool(name, args) {
       try {
         const blueprint = await apiClient.getBlueprint(namespace, args.id);
         let topology = null;
-        const composeEntries = blueprint.compose || blueprint.data?.compose;
+        const composeEntries = blueprint.compose;
         if (composeEntries && Array.isArray(composeEntries) && composeEntries.length > 0) {
           const zoneInputs = [];
           const archetypePromises = composeEntries.map(async (entry) => {
             const arcId = typeof entry === "string" ? entry : entry.archetype;
             try {
               const arch = await apiClient.getContent("archetypes", namespace, arcId);
-              const archData = arch.data || arch;
+              const archData = arch;
               const explicitRole = typeof entry === "object" ? entry.role : void 0;
               zoneInputs.push({
                 archetypeId: arcId,
@@ -1278,50 +1266,72 @@ async function handleTool(name, args) {
           namespace: "@official",
           limit: 100
         });
-        const suggestions = [];
+        const prelimScores = [];
         for (const p of patternsResponse.items) {
-          const searchable = [
-            p.name || "",
-            p.description || "",
-            ...p.components || [],
-            ...p.tags || []
-          ].join(" ").toLowerCase();
+          const slug = p.slug || "";
+          const name2 = p.name || slug;
+          const description = p.description || "";
+          const searchable = [name2, description].join(" ").toLowerCase();
           let score = 0;
           const words = desc.split(/\s+/);
           for (const word of words) {
             if (word.length < 3) continue;
             if (searchable.includes(word)) score += 10;
           }
-          if (desc.includes("dashboard") && ["kpi-grid", "chart-grid", "data-table", "filter-bar"].includes(p.id)) score += 20;
-          if (desc.includes("metric") && p.id === "kpi-grid") score += 15;
-          if (desc.includes("chart") && p.id === "chart-grid") score += 15;
-          if (desc.includes("table") && p.id === "data-table") score += 15;
-          if (desc.includes("form") && p.id === "form-sections") score += 15;
-          if (desc.includes("setting") && p.id === "form-sections") score += 15;
-          if (desc.includes("landing") && ["hero", "cta-section", "card-grid"].includes(p.id)) score += 20;
-          if (desc.includes("hero") && p.id === "hero") score += 20;
-          if (desc.includes("ecommerce") && ["card-grid", "filter-bar", "detail-header"].includes(p.id)) score += 15;
-          if (desc.includes("product") && p.id === "card-grid") score += 15;
-          if (desc.includes("feed") && p.id === "activity-feed") score += 15;
-          if (desc.includes("filter") && p.id === "filter-bar") score += 15;
-          if (desc.includes("search") && p.id === "filter-bar") score += 10;
+          if (desc.includes("dashboard") && ["kpi-grid", "chart-grid", "data-table", "filter-bar"].includes(slug)) score += 20;
+          if (desc.includes("metric") && slug === "kpi-grid") score += 15;
+          if (desc.includes("chart") && slug === "chart-grid") score += 15;
+          if (desc.includes("table") && slug === "data-table") score += 15;
+          if (desc.includes("form") && slug === "form-sections") score += 15;
+          if (desc.includes("setting") && slug === "form-sections") score += 15;
+          if (desc.includes("landing") && ["hero", "cta-section", "card-grid"].includes(slug)) score += 20;
+          if (desc.includes("hero") && slug === "hero") score += 20;
+          if (desc.includes("ecommerce") && ["card-grid", "filter-bar", "detail-header"].includes(slug)) score += 15;
+          if (desc.includes("product") && slug === "card-grid") score += 15;
+          if (desc.includes("feed") && slug === "activity-feed") score += 15;
+          if (desc.includes("filter") && slug === "filter-bar") score += 15;
+          if (desc.includes("search") && slug === "filter-bar") score += 10;
           if (score > 0) {
-            const preset = p.presets ? Object.values(p.presets)[0] : null;
-            suggestions.push({
-              id: p.id,
-              score,
-              name: p.name || p.id,
-              description: p.description || "",
-              components: p.components || [],
-              layout: preset?.layout ? preset.layout.layout : "grid"
-            });
+            prelimScores.push({ slug, score, name: name2, description });
           }
         }
+        prelimScores.sort((a, b) => b.score - a.score);
+        const top10 = prelimScores.slice(0, 10);
+        const suggestions = [];
+        for (const candidate of top10) {
+          let fullPattern = null;
+          try {
+            const fetched = await apiClient.getPattern("@official", candidate.slug);
+            fullPattern = fetched;
+          } catch {
+          }
+          let score = candidate.score;
+          if (fullPattern) {
+            const fullSearchable = [
+              ...fullPattern.components || [],
+              ...fullPattern.tags || []
+            ].join(" ").toLowerCase();
+            const words = desc.split(/\s+/);
+            for (const word of words) {
+              if (word.length < 3) continue;
+              if (fullSearchable.includes(word)) score += 10;
+            }
+          }
+          const preset = fullPattern?.presets ? Object.values(fullPattern.presets)[0] : null;
+          suggestions.push({
+            id: candidate.slug,
+            score,
+            name: fullPattern?.name || candidate.name,
+            description: fullPattern?.description || candidate.description,
+            components: fullPattern?.components || [],
+            layout: preset?.layout ? preset.layout.layout : "grid"
+          });
+        }
         suggestions.sort((a, b) => b.score - a.score);
         return {
           query: args.description,
           suggestions: suggestions.slice(0, 5),
-          total: suggestions.length
+          total: prelimScores.length
         };
       } catch (e) {
         return { error: `Could not fetch patterns: ${e.message}` };
@@ -1343,10 +1353,10 @@ async function handleTool(name, args) {
       if (args.theme_used && typeof args.theme_used === "string") {
         let expectedStyle;
         if (isV32(essence)) {
-          expectedStyle = essence.dna.theme.style;
+          expectedStyle = essence.dna.theme.id;
         } else {
           const expectedTheme = essence.theme;
-          expectedStyle = expectedTheme?.style;
+          expectedStyle = expectedTheme?.id ?? expectedTheme?.style;
         }
         if (expectedStyle && args.theme_used !== expectedStyle) {
           violations.push({
@@ -1504,9 +1514,8 @@ async function handleTool(name, args) {
         version: "3.0.0",
         dna: {
           theme: {
-            style: "auradecantism",
+            id: "auradecantism",
             mode: "dark",
-            recipe: "auradecantism",
             shape: "rounded"
           },
           spacing: {
@@ -1585,14 +1594,14 @@ async function handleTool(name, args) {
       }
       const hasDnaViolation = violations.some((v) => {
         const rule = v.rule;
-        return ["style", "recipe", "density", "theme-mode", "accessibility", "theme-match"].includes(rule);
+        return ["style", "density", "theme-mode", "accessibility", "theme-match"].includes(rule);
       });
       if (hasDnaViolation && resolution !== "reject" && resolution !== "defer" && !args.confirm_dna) {
         return {
           error: "DNA-layer violations detected. Set confirm_dna: true to accept changes to design axioms (theme, style, density, etc.).",
           requires_confirmation: true,
           dna_rules_affected: violations.filter(
-            (v) => ["style", "recipe", "density", "theme-mode", "accessibility", "theme-match"].includes(v.rule)
+            (v) => ["style", "density", "theme-mode", "accessibility", "theme-match"].includes(v.rule)
           ).map((v) => v.rule)
         };
       }
@@ -1773,6 +1782,11 @@ async function handleTool(name, args) {
       }
       return { content: lines.join("\n") };
     }
+    case "decantr_critique": {
+      const { critiqueFile } = await import("./critique-DKY4NB2O.js");
+      const result = await critiqueFile(args.file_path, process.cwd());
+      return result;
+    }
     default:
       return { error: `Unknown tool: ${name}` };
   }
@@ -1782,7 +1796,7 @@ function applyDriftAcceptance(essence, violation, resolution, scope) {
     case "theme-match":
     case "style": {
       if (violation.details) {
-        essence.dna.theme.style = violation.details;
+        essence.dna.theme.id = violation.details;
       }
       break;
     }
@@ -1802,12 +1816,6 @@ function applyDriftAcceptance(essence, violation, resolution, scope) {
     case "layout": {
       break;
     }
-    case "recipe": {
-      if (violation.details) {
-        essence.dna.theme.recipe = violation.details;
-      }
-      break;
-    }
     case "density": {
       break;
     }

package/dist/critique-DKY4NB2O.js

@@ -0,0 +1,74 @@
+// src/critique.ts
+import { readFile } from "fs/promises";
+import { join } from "path";
+async function critiqueFile(filePath, projectRoot) {
+  const code = await readFile(filePath, "utf-8");
+  const codeLower = code.toLowerCase();
+  let treatments = "";
+  try {
+    treatments = await readFile(join(projectRoot, "src", "styles", "treatments.css"), "utf-8");
+  } catch {
+  }
+  const scores = [];
+  const treatmentClasses = ["d-interactive", "d-surface", "d-data", "d-control", "d-section", "d-annotation", "d-label"];
+  const usedTreatments = treatmentClasses.filter((t) => code.includes(t));
+  scores.push({
+    category: "Treatment Usage",
+    score: Math.min(5, Math.max(1, Math.round(usedTreatments.length / treatmentClasses.length * 5))),
+    details: `${usedTreatments.length}/${treatmentClasses.length} base treatments used: ${usedTreatments.join(", ") || "none"}`,
+    suggestions: treatmentClasses.filter((t) => !code.includes(t)).map((t) => `Consider using \`${t}\` where appropriate`)
+  });
+  const decoratorMatches = treatments.match(/\.([\w-]+)\s*\{/g) || [];
+  const decoratorNames = decoratorMatches.map((m) => m.slice(1).replace(/\s*\{$/, "")).filter((n) => !n.startsWith("d-") && !["neon-glow", "neon-glow-hover", "neon-text-glow", "neon-border-glow", "mono-data", "status-ring", "entrance-fade"].includes(n));
+  const usedDecorators = decoratorNames.filter((d) => code.includes(d));
+  const decTarget = Math.min(decoratorNames.length, 5);
+  scores.push({
+    category: "Decorator Usage",
+    score: decTarget > 0 ? Math.min(5, Math.max(1, Math.round(usedDecorators.length / decTarget * 5))) : 3,
+    details: `${usedDecorators.length}/${decoratorNames.length} theme decorators used`,
+    suggestions: decoratorNames.filter((d) => !code.includes(d)).slice(0, 3).map((d) => `Theme decorator \`${d}\` available but unused`)
+  });
+  const personalityUtils = ["neon-glow", "neon-text-glow", "neon-border-glow", "mono-data", "status-ring", "entrance-fade"];
+  const availableUtils = personalityUtils.filter((u) => treatments.includes(u));
+  const usedUtils = availableUtils.filter((u) => code.includes(u));
+  const utilTarget = Math.min(availableUtils.length, 3);
+  scores.push({
+    category: "Personality Alignment",
+    score: utilTarget > 0 ? Math.min(5, Math.max(1, Math.round(usedUtils.length / utilTarget * 5))) : 3,
+    details: `${usedUtils.length}/${availableUtils.length} personality utilities used`,
+    suggestions: availableUtils.filter((u) => !code.includes(u)).map((u) => `Personality utility \`${u}\` defined but not used`)
+  });
+  const hasTransition = codeLower.includes("transition") || codeLower.includes("animate") || codeLower.includes("keyframe") || codeLower.includes("framer");
+  const hasHover = codeLower.includes(":hover") || codeLower.includes("onmouseenter") || codeLower.includes("hover:");
+  scores.push({
+    category: "Motion & Interaction",
+    score: Math.min(5, (hasTransition ? 3 : 1) + (hasHover ? 1 : 0)),
+    details: `Transitions: ${hasTransition ? "yes" : "no"}, Hover states: ${hasHover ? "yes" : "no"}`,
+    suggestions: hasTransition ? [] : ["Add transition effects for interactive elements"]
+  });
+  const hasAria = codeLower.includes("aria-") || codeLower.includes("role=");
+  const hasFocus = codeLower.includes("focus-visible") || codeLower.includes("focusvisible");
+  const hasKeyboard = codeLower.includes("onkeydown") || codeLower.includes("onkeyup");
+  scores.push({
+    category: "Accessibility",
+    score: Math.min(5, 1 + (hasAria ? 2 : 0) + (hasFocus ? 1 : 0) + (hasKeyboard ? 1 : 0)),
+    details: `ARIA: ${hasAria}, Focus: ${hasFocus}, Keyboard: ${hasKeyboard}`,
+    suggestions: [
+      ...!hasAria ? ["Add ARIA attributes to interactive regions"] : [],
+      ...!hasKeyboard ? ["Add keyboard event handlers"] : []
+    ]
+  });
+  const hasMedia = codeLower.includes("@media") || codeLower.includes("usemediaquery") || codeLower.includes("breakpoint");
+  const hasResponsive = codeLower.includes("sm:") || codeLower.includes("md:") || codeLower.includes("lg:") || codeLower.includes("_sm_") || codeLower.includes("_md_");
+  scores.push({
+    category: "Responsive Design",
+    score: Math.min(5, (hasMedia ? 3 : 1) + (hasResponsive ? 2 : 0)),
+    details: `Media queries: ${hasMedia}, Responsive classes: ${hasResponsive}`,
+    suggestions: !hasMedia && !hasResponsive ? ["Add responsive breakpoint handling"] : []
+  });
+  const overall = Math.round(scores.reduce((s, c) => s + c.score, 0) / scores.length * 10) / 10;
+  return { file: filePath, overall, scores };
+}
+export {
+  critiqueFile
+};

package/dist/index.js

@@ -1 +1 @@
-import "./chunk-A5IEC7O2.js";
+import "./chunk-YOFQYTEC.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decantr/mcp-server",
-  "version": "1.0.0-beta.10",
+  "version": "1.0.0-beta.12",
   "description": "MCP server for Decantr — exposes design intelligence tools to AI coding assistants",
   "license": "MIT",
   "repository": {
@@ -15,18 +15,20 @@
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@decantr/essence-spec": "1.0.0-beta.11",
+    "@decantr/registry": "1.0.0-beta.11"
+  },
   "scripts": {
     "build": "tsup",
     "test": "vitest run",
     "test:watch": "vitest"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
-    "@decantr/essence-spec": "workspace:*",
-    "@decantr/registry": "workspace:*"
   }
-}
+}