@decantr/mcp-server 1.0.5 → 2.0.0

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

@@ -144,7 +144,7 @@ For the broader product surface and support policy, see the root Decantr docs an
 
 ## Compatibility
 
-`@decantr/mcp-server` is stable in the `1.x` line for the documented MCP tool surface.
+`@decantr/mcp-server` is stable in the `2.x` line for the documented MCP tool surface.
 
 - new tools may be added in compatible releases
 - existing documented tool names and envelopes should not break without a major version

package/dist/bin.js

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

package/dist/{chunk-A4ZCCVQR.js → chunk-MUNBODQK.js}

@@ -7,14 +7,14 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprot
 import { existsSync, readdirSync, readFileSync } from "fs";
 import { readFile as readFile2 } from "fs/promises";
 import { basename as basename2, dirname as dirname2, join as join2, relative as relative2 } from "path";
-import { evaluateGuard, isV3 as isV32, validateEssence } from "@decantr/essence-spec";
+import { evaluateGuard, isV4 as isV42, validateEssence } from "@decantr/essence-spec";
 import { isContentIntelligenceSource, resolvePatternPreset } from "@decantr/registry";
 
 // src/helpers.ts
 import { realpathSync } from "fs";
 import { mkdir, readFile, writeFile } from "fs/promises";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "path";
-import { isV3, migrateV2ToV3 } from "@decantr/essence-spec";
+import { isV4 } from "@decantr/essence-spec";
 import { RegistryAPIClient } from "@decantr/registry";
 var MAX_INPUT_LENGTH = 1e3;
 function validateStringArg(args, field) {
@@ -95,8 +95,13 @@ async function writeEssenceFile(essencePath, essence) {
 }
 async function mutateEssenceFile(essencePath, mutate) {
   const { essence, path } = await readEssenceFile(essencePath);
-  const v3 = isV3(essence) ? structuredClone(essence) : migrateV2ToV3(essence);
-  const updated = mutate(v3);
+  if (!isV4(essence)) {
+    throw new Error(
+      "Active Decantr V2 workflows require Essence v4.0.0. Run `decantr migrate --to v4` for older essence files."
+    );
+  }
+  const v4 = structuredClone(essence);
+  const updated = mutate(v4);
   await writeEssenceFile(path, updated);
   return { essence: updated, path };
 }
@@ -469,7 +474,7 @@ var TOOLS = [
   {
     name: "decantr_read_essence",
     title: "Read Essence",
-    description: "Read and return the current decantr.essence.json file from the working directory. For v3 files, optionally filter by layer (dna, blueprint, or full).",
+    description: "Read and return the current Essence v4 decantr.essence.json file from the working directory. Optionally filter by layer (dna, blueprint, or full).",
     inputSchema: {
       type: "object",
       properties: {
@@ -480,7 +485,7 @@ var TOOLS = [
         layer: {
           type: "string",
           enum: ["dna", "blueprint", "full"],
-          description: "For v3 essences: return only the specified layer. Defaults to full."
+          description: "For Essence v4 files: return only the specified layer. Defaults to full."
         }
       }
     },
@@ -490,7 +495,7 @@ var TOOLS = [
   {
     name: "decantr_validate",
     title: "Validate Essence",
-    description: "Validate a decantr.essence.json file against the schema and guard rules. For v3, reports DNA vs Blueprint violations separately.",
+    description: "Validate an Essence v4 decantr.essence.json file against the schema and guard rules, reporting DNA vs Blueprint violations separately.",
     inputSchema: {
       type: "object",
       properties: {
@@ -593,7 +598,7 @@ var TOOLS = [
   {
     name: "decantr_check_drift",
     title: "Check Drift",
-    description: "Check if code changes violate the design intent captured in the Essence spec. For v3, returns separate dna_violations and blueprint_drift with autoFixable flags.",
+    description: "Check if code changes violate the design intent captured in the Essence v4 spec. Returns separate dna_violations and blueprint_drift with autoFixable flags.",
     inputSchema: {
       type: "object",
       properties: {
@@ -619,7 +624,7 @@ var TOOLS = [
   {
     name: "decantr_create_essence",
     title: "Create Essence",
-    description: "Generate a valid v3 Essence spec skeleton from a project description. Returns a structured essence.json template based on the closest matching archetype and blueprint.",
+    description: "Generate a valid Essence v4 skeleton from a project description. Returns a sectioned decantr.essence.json template based on the closest matching archetype and blueprint.",
     inputSchema: {
       type: "object",
       properties: {
@@ -680,7 +685,7 @@ var TOOLS = [
   {
     name: "decantr_update_essence",
     title: "Update Essence",
-    description: "Mutate the essence file: add/remove/update pages, update DNA or blueprint fields, add/remove features. Operates on v3 format (auto-migrates v2).",
+    description: "Mutate an Essence v4 file: add/remove/update pages, update DNA or blueprint fields, add/remove features. Older projects must run `decantr migrate --to v4` first.",
     inputSchema: {
       type: "object",
       properties: {
@@ -946,7 +951,12 @@ async function handleTool(name, args) {
         const raw = await readFile2(essencePath, "utf-8");
         const essence = JSON.parse(raw);
         const layer = args.layer;
-        if (layer && isV32(essence)) {
+        if (!isV42(essence)) {
+          return {
+            error: "Active Decantr V2 workflows require Essence v4.0.0. Run `decantr migrate --to v4` for older essence files."
+          };
+        }
+        if (layer) {
           if (layer === "dna") return essence.dna;
           if (layer === "blueprint") return essence.blueprint;
         }
@@ -975,13 +985,13 @@ async function handleTool(name, args) {
         } catch {
         }
       }
-      if (result.valid && typeof essence === "object" && essence !== null && isV32(essence)) {
+      if (result.valid && typeof essence === "object" && essence !== null && isV42(essence)) {
         const dnaViolations = guardViolations.filter((v) => v.layer === "dna");
         const blueprintViolations = guardViolations.filter((v) => v.layer === "blueprint");
         const otherViolations = guardViolations.filter((v) => !v.layer);
         return {
           ...result,
-          format: "v3",
+          format: "v4",
           dna_violations: dnaViolations,
           blueprint_violations: blueprintViolations,
           guardViolations: otherViolations
@@ -1189,51 +1199,43 @@ async function handleTool(name, args) {
       if (!validation.valid) {
         return { drifted: true, reason: "invalid_essence", errors: validation.errors };
       }
+      if (!isV42(essence)) {
+        return {
+          drifted: true,
+          reason: "legacy_essence",
+          errors: [
+            "Active Decantr V2 workflows require Essence v4.0.0. Run `decantr migrate --to v4` for older essence files."
+          ]
+        };
+      }
       const violations = [];
       if (args.theme_used && typeof args.theme_used === "string") {
-        let expectedThemeId;
-        if (isV32(essence)) {
-          expectedThemeId = essence.dna.theme.id;
-        } else {
-          const expectedTheme = essence.theme;
-          expectedThemeId = expectedTheme?.id ?? expectedTheme?.style;
-        }
+        const expectedThemeId = essence.dna.theme.id;
         if (expectedThemeId && args.theme_used !== expectedThemeId) {
           violations.push({
             rule: "theme-match",
             severity: "critical",
             message: `Theme drift: code uses "${args.theme_used}" but Essence specifies "${expectedThemeId}". Do not switch themes.`,
-            ...isV32(essence) ? { layer: "dna", autoFixable: false } : {}
+            layer: "dna",
+            autoFixable: false
           });
         }
       }
       if (args.page_id && typeof args.page_id === "string") {
-        let pages;
-        if (isV32(essence)) {
-          pages = essence.blueprint.pages;
-        } else {
-          pages = essence.structure || [];
-        }
+        const pages = listEssencePages(essence);
         if (!pages.find((p) => p.id === args.page_id)) {
           violations.push({
             rule: "page-exists",
             severity: "critical",
             message: `Page "${args.page_id}" not found in Essence structure. Add it to the Essence before generating code for it.`,
-            ...isV32(essence) ? {
-              layer: "blueprint",
-              autoFixable: true,
-              autoFix: { type: "add_page", patch: { id: args.page_id } }
-            } : {}
+            layer: "blueprint",
+            autoFixable: true,
+            autoFix: { type: "add_page", patch: { id: args.page_id } }
           });
         }
       }
       if (args.components_used && Array.isArray(args.components_used) && args.page_id && typeof args.page_id === "string") {
-        let pages;
-        if (isV32(essence)) {
-          pages = essence.blueprint.pages;
-        } else {
-          pages = essence.structure || [];
-        }
+        const pages = listEssencePages(essence);
         const page = pages.find((p) => p.id === args.page_id);
         if (page && page.layout) {
           const expectedPatterns = /* @__PURE__ */ new Set();
@@ -1265,7 +1267,8 @@ async function handleTool(name, args) {
               rule: "component-pattern-match",
               severity: "warning",
               message: `Components [${unmatchedComponents.join(", ")}] do not match any pattern in page "${args.page_id}" layout. Expected patterns: [${[...expectedPatterns].join(", ")}].`,
-              ...isV32(essence) ? { layer: "blueprint", autoFixable: false } : {}
+              layer: "blueprint",
+              autoFixable: false
             });
           }
         }
@@ -1286,21 +1289,11 @@ async function handleTool(name, args) {
         }
       } catch {
       }
-      if (isV32(essence)) {
-        const dnaViolations = violations.filter((v) => v.layer === "dna");
-        const blueprintDrift = violations.filter((v) => v.layer === "blueprint");
-        const other = violations.filter((v) => !v.layer);
-        return {
-          drifted: violations.length > 0,
-          dna_violations: dnaViolations,
-          blueprint_drift: blueprintDrift,
-          other_violations: other,
-          checkedAgainst: essencePath
-        };
-      }
       return {
         drifted: violations.length > 0,
-        violations,
+        dna_violations: violations.filter((v) => v.layer === "dna"),
+        blueprint_drift: violations.filter((v) => v.layer === "blueprint"),
+        other_violations: violations.filter((v) => !v.layer),
         checkedAgainst: essencePath
       };
     }
@@ -1348,8 +1341,17 @@ async function handleTool(name, args) {
       }
       const rawPages = pages || [{ id: "home", shell: "full-bleed", default_layout: ["hero"] }];
       const defaultShell = rawPages[0]?.shell || "sidebar-main";
+      const sectionPages = rawPages.map((p, index) => ({
+        id: p.id,
+        route: p.id === "home" || index === 0 ? "/" : `/${p.id}`,
+        ...p.shell !== defaultShell ? { shell_override: p.shell } : {},
+        layout: p.default_layout || []
+      }));
+      const routes = Object.fromEntries(
+        sectionPages.map((page) => [page.route, { section: bestMatch, page: page.id }])
+      );
       const essence = {
-        version: "3.0.0",
+        version: "4.0.0",
         dna: {
           theme: {
             id: "auradecantism",
@@ -1394,12 +1396,18 @@ async function handleTool(name, args) {
         },
         blueprint: {
           shell: defaultShell,
-          pages: rawPages.map((p) => ({
-            id: p.id,
-            ...p.shell !== defaultShell ? { shell_override: p.shell } : {},
-            layout: p.default_layout || []
-          })),
-          features
+          sections: [
+            {
+              id: bestMatch,
+              role: "primary",
+              shell: defaultShell,
+              features,
+              description: `${bestMatch} primary section`,
+              pages: sectionPages
+            }
+          ],
+          features,
+          routes
         },
         meta: {
           archetype: bestMatch,
@@ -1411,7 +1419,7 @@ async function handleTool(name, args) {
       return {
         essence,
         archetype: bestMatch,
-        format: "v3",
+        format: "v4",
         instructions: `Save this as decantr.essence.json in your project root. Review the dna (design tokens), blueprint (pages/features), and meta (project config) sections and adjust to match your needs. The guard rules will validate your code against this spec.`,
         _generated: {
           matched_archetype: bestMatch,
@@ -1477,11 +1485,11 @@ async function handleTool(name, args) {
         };
       }
       try {
-        const { essence, path } = await mutateEssenceFile(args.path, (v3) => {
+        const { essence, path } = await mutateEssenceFile(args.path, (v4) => {
           for (const v of violations) {
-            applyDriftAcceptance(v3, v, resolution, args.scope);
+            applyDriftAcceptance(v4, v, resolution, args.scope);
           }
-          return v3;
+          return v4;
         });
         return {
           status: resolution === "accept_scoped" ? "accepted_scoped" : "accepted",
@@ -1517,8 +1525,8 @@ async function handleTool(name, args) {
         };
       }
       try {
-        const { essence, path } = await mutateEssenceFile(args.path, (v3) => {
-          return applyEssenceUpdate(v3, operation, payload);
+        const { essence, path } = await mutateEssenceFile(args.path, (v4) => {
+          return applyEssenceUpdate(v4, operation, payload);
         });
         return {
           status: "updated",
@@ -1647,8 +1655,10 @@ async function handleTool(name, args) {
       } catch {
         return { error: "No valid essence file found. Run decantr init first." };
       }
-      if (!isV32(essence)) {
-        return { error: "Section context requires a v3 essence file. Run decantr migrate first." };
+      if (!isV42(essence)) {
+        return {
+          error: "Section context requires Essence v4.0.0. Run `decantr migrate --to v4` first."
+        };
       }
       const sections = essence.blueprint.sections || [];
       const section = sections.find((s) => s.id === sectionId);
@@ -2096,6 +2106,28 @@ async function handleTool(name, args) {
       return { error: `Unknown tool: ${name}` };
   }
 }
+function listEssencePages(essence) {
+  return essence.blueprint.sections.flatMap(
+    (section) => section.pages.map((page) => ({ ...page, sectionId: section.id }))
+  );
+}
+function getMutablePage(essence, id, sectionId) {
+  for (const section of essence.blueprint.sections) {
+    if (sectionId && section.id !== sectionId) continue;
+    const index = section.pages.findIndex((page) => page.id === id);
+    if (index !== -1) {
+      return { page: section.pages[index], section, index };
+    }
+  }
+  return null;
+}
+function getDefaultSection(essence) {
+  const section = essence.blueprint.sections.find((s) => s.role === "primary") ?? essence.blueprint.sections[0];
+  if (!section) {
+    throw new Error("Essence v4 requires at least one blueprint section.");
+  }
+  return section;
+}
 function applyDriftAcceptance(essence, violation, resolution, scope) {
   switch (violation.rule) {
     case "theme-match":
@@ -2109,9 +2141,10 @@ function applyDriftAcceptance(essence, violation, resolution, scope) {
     case "page-exists":
     case "structure": {
       if (violation.page_id) {
-        const existing = essence.blueprint.pages.find((p) => p.id === violation.page_id);
+        const section = getDefaultSection(essence);
+        const existing = getMutablePage(essence, violation.page_id);
         if (!existing) {
-          essence.blueprint.pages.push({
+          section.pages.push({
             id: violation.page_id,
             layout: []
           });
@@ -2134,11 +2167,15 @@ function applyEssenceUpdate(essence, operation, payload) {
     case "add_page": {
       const id = payload.id;
       if (!id) throw new Error('Payload must include "id" for add_page.');
-      const existing = essence.blueprint.pages.find((p) => p.id === id);
+      const sectionId = payload.section_id;
+      const section = sectionId ? essence.blueprint.sections.find((candidate) => candidate.id === sectionId) : getDefaultSection(essence);
+      if (!section) throw new Error(`Section "${sectionId}" not found.`);
+      const existing = getMutablePage(essence, id, section.id);
       if (existing) throw new Error(`Page "${id}" already exists.`);
-      essence.blueprint.pages.push({
+      section.pages.push({
         id,
         layout: payload.layout || [],
+        ...payload.route ? { route: payload.route } : {},
         ...payload.shell_override ? { shell_override: payload.shell_override } : {},
         ...payload.surface ? { surface: payload.surface } : {}
       });
@@ -2147,9 +2184,9 @@ function applyEssenceUpdate(essence, operation, payload) {
     case "remove_page": {
       const id = payload.id;
       if (!id) throw new Error('Payload must include "id" for remove_page.');
-      const idx = essence.blueprint.pages.findIndex((p) => p.id === id);
-      if (idx === -1) throw new Error(`Page "${id}" not found.`);
-      essence.blueprint.pages.splice(idx, 1);
+      const match = getMutablePage(essence, id, payload.section_id);
+      if (!match) throw new Error(`Page "${id}" not found.`);
+      match.section.pages.splice(match.index, 1);
       break;
     }
     case "update_page_layout": {
@@ -2158,9 +2195,9 @@ function applyEssenceUpdate(essence, operation, payload) {
       if (!id) throw new Error('Payload must include "id" for update_page_layout.');
       if (!layout || !Array.isArray(layout))
         throw new Error('Payload must include "layout" array for update_page_layout.');
-      const page = essence.blueprint.pages.find((p) => p.id === id);
-      if (!page) throw new Error(`Page "${id}" not found.`);
-      page.layout = layout;
+      const match = getMutablePage(essence, id, payload.section_id);
+      if (!match) throw new Error(`Page "${id}" not found.`);
+      match.page.layout = layout;
       break;
     }
     case "update_dna": {
@@ -2178,7 +2215,7 @@ function applyEssenceUpdate(essence, operation, payload) {
     }
     case "update_blueprint": {
       for (const [key, value] of Object.entries(payload)) {
-        if (key === "pages") continue;
+        if (key === "pages" || key === "sections") continue;
         essence.blueprint[key] = value;
       }
       break;
@@ -2224,7 +2261,7 @@ function describeUpdate(operation, payload) {
 }
 
 // src/index.ts
-var VERSION = "0.2.0";
+var VERSION = "2.0.0";
 var server = new Server({ name: "decantr", version: VERSION }, { capabilities: { tools: {} } });
 server.setRequestHandler(ListToolsRequestSchema, async () => {
   return { tools: TOOLS };

package/dist/index.js

@@ -1 +1 @@
-import "./chunk-A4ZCCVQR.js";
+import "./chunk-MUNBODQK.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decantr/mcp-server",
-  "version": "1.0.5",
+  "version": "2.0.0",
   "mcpName": "io.github.decantr-ai/mcp-server",
   "description": "MCP server for Decantr — exposes design intelligence, packs, and verification to AI coding assistants",
   "keywords": [
@@ -44,17 +44,16 @@
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@decantr/registry": "2.0.0",
+    "@decantr/verifier": "2.0.0",
+    "@decantr/essence-spec": "2.0.1"
+  },
   "scripts": {
     "build": "tsup",
     "test": "vitest run",
     "test:watch": "vitest",
-    "prepublishOnly": "pnpm build",
     "preversion": "pnpm build && pnpm test"
-  },
-  "dependencies": {
-    "@decantr/essence-spec": "workspace:*",
-    "@decantr/registry": "workspace:*",
-    "@decantr/verifier": "workspace:*",
-    "@modelcontextprotocol/sdk": "^1.29.0"
   }
-}
+}