@decantr/mcp-server 1.0.6 → 2.1.0

package/README.md

@@ -13,6 +13,7 @@ Design intelligence for AI-generated UI. Make Claude, Cursor, and Windsurf gener
 ![Decantr MCP demo](https://raw.githubusercontent.com/decantr-ai/decantr/main/packages/mcp-server/assets/decantr-demo.gif)
 
 - **Structured design context** -- gives your AI assistant patterns, layouts, and component specs instead of letting it guess
+- **Evidence-backed repair loops** -- gives AI agents Project Health, Evidence Bundles, workspace health, and scoped repair prompts without uploading source
 - **Drift detection** -- catches when generated code deviates from your design intent
 - **Zero config** -- run with `npx`, no API keys or accounts required
 
@@ -138,13 +139,17 @@ The server exposes Decantr registry, context, benchmark, and verification tools.
 | `decantr_compile_execution_packs` | Compile a hosted execution-pack bundle from a local or inline essence document | `{ "path": "./decantr.essence.json", "namespace": "@official" }` |
 | `decantr_audit_project` | Run the schema-backed Decantr project audit against essence and compiled packs, with hosted fallback when local pack artifacts are missing | `{ "namespace": "@official" }` |
 | `decantr_critique` | Critique a file against the compiled review contract, with hosted fallback when local review packs are missing | `{ "file_path": "./src/pages/Overview.tsx", "namespace": "@official" }` |
+| `decantr_get_evidence_bundle` | Generate the local privacy-redacted Evidence Bundle for a project | `{ "project_path": "apps/web" }` |
+| `decantr_workspace_health` | Discover Decantr projects and return aggregate workspace health | `{ "workspace_root": ".", "max_projects": 100 }` |
+| `decantr_get_repair_prompt` | Return the scoped repair prompt for a health finding | `{ "finding_id": "assertion-contract-context-pack-manifest" }` |
+| `decantr_run_health_loop` | Run health, evidence, and next repair prompt in one local agent loop | `{ "project_path": "apps/web" }` |
 | `decantr_get_showcase_benchmarks` | Read the audited showcase corpus manifest, shortlist, or verification report | `{ "view": "verification" }` |
 
 For the broader product surface and support policy, see the root Decantr docs and package support matrix.
 
 ## 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
@@ -169,8 +174,10 @@ The AI assistant calls these tools behind the scenes:
 7. `decantr_check_drift` -- validates the generated code against the Essence spec before presenting it
 8. `decantr_critique` -- critiques a specific file, falling back to the hosted verifier when the local review pack is missing
 9. `decantr_audit_project` -- runs the stronger project-level audit once the implementation is in place
+10. `decantr_get_evidence_bundle` -- returns the local evidence bundle for the AI repair loop
+11. `decantr_get_repair_prompt` -- gives the assistant exact finding evidence, constraints to preserve, and commands to rerun
 
-The AI now generates code with the right layout structure, correct components, and consistent styling -- not a generic guess.
+The AI now generates code with the right layout structure, correct components, and consistent styling, then gets a scoped evidence-backed repair loop instead of a generic guess.
 
 ## License
 

package/dist/bin.js

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

package/dist/{chunk-A4ZCCVQR.js → chunk-FEXPLJKB.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 };
 }
@@ -464,12 +469,332 @@ var WRITE_TOOL = {
   idempotentHint: false,
   openWorldHint: false
 };
+var MCP_PROJECT_HEALTH_SCHEMA_URL = "https://decantr.ai/schemas/project-health-report.v1.json";
+var MCP_WORKSPACE_HEALTH_SCHEMA_URL = "https://decantr.ai/schemas/workspace-health-report.v1.json";
+var MCP_WORKSPACE_IGNORES = /* @__PURE__ */ new Set([
+  ".git",
+  ".next",
+  ".turbo",
+  ".vercel",
+  "coverage",
+  "dist",
+  "node_modules",
+  "playwright-report"
+]);
+function mcpSlug(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80);
+}
+function mcpStatusFromCounts(counts) {
+  if (counts.errorCount > 0) return "error";
+  if (counts.warnCount > 0) return "warning";
+  return "healthy";
+}
+function mcpScoreFromCounts(counts) {
+  return Math.max(0, Math.min(100, 100 - counts.errorCount * 15 - counts.warnCount * 5 - counts.infoCount));
+}
+function mcpCommandsForFinding(source) {
+  switch (source) {
+    case "assertion":
+      return ["decantr refresh", "decantr health --evidence"];
+    case "brownfield":
+      return ["decantr analyze", "decantr init --existing --merge-proposal", "decantr health"];
+    case "browser":
+      return ["decantr health --browser", "decantr health --evidence"];
+    case "check":
+      return ["decantr check", "decantr health"];
+    case "design-token":
+      return ["decantr export --to figma-tokens", "decantr health --evidence"];
+    case "interaction":
+      return ["decantr check --strict", "decantr health"];
+    case "pack":
+      return ["decantr refresh", "decantr registry get-pack review --write-context", "decantr health"];
+    case "runtime":
+      return ["npm run build", "decantr health"];
+    default:
+      return ["decantr audit", "decantr health"];
+  }
+}
+function mcpSourceFromFinding(finding) {
+  const category = finding.category.toLowerCase();
+  const id = finding.id.toLowerCase();
+  const rule = finding.rule?.toLowerCase() ?? "";
+  if (category.includes("runtime") || category.includes("document") || category.includes("performance")) {
+    return "runtime";
+  }
+  if (category.includes("pack") || category.includes("review contract")) {
+    return "pack";
+  }
+  if (category.includes("interaction") || id.includes("interaction") || rule.includes("interaction")) {
+    return "interaction";
+  }
+  return "audit";
+}
+function mcpBuildRepairPrompt(input) {
+  return [
+    "You are fixing one Decantr Project Health finding in this local workspace.",
+    "",
+    "Read `DECANTR.md`, `decantr.essence.json`, and `.decantr/context/scaffold-pack.md` if they exist. For route or page work, read the matching page/section packs before editing.",
+    "",
+    `Finding: ${input.id}`,
+    `Source: ${input.source}`,
+    `Severity: ${input.severity}`,
+    `Category: ${input.category}`,
+    `Message: ${input.message}`,
+    input.evidence.length > 0 ? `Evidence:
+${input.evidence.map((entry) => `- ${entry}`).join("\n")}` : null,
+    input.suggestedFix ? `Suggested fix: ${input.suggestedFix}` : null,
+    "",
+    "Make the smallest coherent code or contract change that resolves this finding. Preserve the existing framework, routing, styling system, and Decantr workflow mode unless the finding explicitly requires a contract update.",
+    "Do not rewrite unrelated routes, replace the styling system, remove existing product behavior, or regenerate Decantr artifacts unless the finding is about stale or missing generated context.",
+    "",
+    `After the fix, run:
+${input.commands.map((command) => `- ${command}`).join("\n")}`
+  ].filter((line) => Boolean(line)).join("\n");
+}
+function mcpHealthFinding(input) {
+  const id = `${input.source}-${mcpSlug(input.baseId || input.rule || `${input.category}-${input.message}`)}`;
+  const commands = mcpCommandsForFinding(input.source);
+  return {
+    id,
+    source: input.source,
+    category: input.category,
+    severity: input.severity,
+    message: input.message,
+    evidence: input.evidence ?? [],
+    target: input.target,
+    file: input.file,
+    rule: input.rule,
+    suggestedFix: input.suggestedFix,
+    remediation: {
+      summary: input.suggestedFix || `Resolve ${input.category.toLowerCase()} finding.`,
+      commands,
+      prompt: mcpBuildRepairPrompt({
+        id,
+        source: input.source,
+        category: input.category,
+        severity: input.severity,
+        message: input.message,
+        evidence: input.evidence ?? [],
+        suggestedFix: input.suggestedFix,
+        commands
+      })
+    }
+  };
+}
+function mcpCollectDeclaredRoutes(essence) {
+  if (!essence || !isV42(essence)) return [];
+  return Object.keys(essence.blueprint.routes ?? {}).sort();
+}
+function mcpReportFromAudit(projectRoot, audit, assertions) {
+  const findings = [];
+  const seen = /* @__PURE__ */ new Set();
+  const pushUnique = (finding) => {
+    const key = `${finding.rule ?? finding.id}|${finding.message}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    findings.push(finding);
+  };
+  for (const finding of audit.findings) {
+    pushUnique(
+      mcpHealthFinding({
+        source: mcpSourceFromFinding(finding),
+        category: finding.category,
+        severity: finding.severity,
+        message: finding.message,
+        evidence: finding.evidence,
+        target: finding.target,
+        file: finding.file,
+        rule: finding.rule,
+        suggestedFix: finding.suggestedFix,
+        baseId: finding.id
+      })
+    );
+  }
+  for (const assertion of assertions) {
+    if (assertion.status !== "failed") continue;
+    pushUnique(
+      mcpHealthFinding({
+        source: "assertion",
+        category: `Contract ${assertion.category}`,
+        severity: assertion.severity,
+        message: assertion.message,
+        evidence: assertion.evidence,
+        target: assertion.target,
+        rule: assertion.rule,
+        suggestedFix: assertion.suggestedFix,
+        baseId: assertion.id
+      })
+    );
+  }
+  if (!audit.valid && findings.every((finding) => finding.severity !== "error")) {
+    pushUnique(
+      mcpHealthFinding({
+        source: "audit",
+        category: "Project Contract",
+        severity: "error",
+        message: "Project audit is not valid.",
+        evidence: ["The verifier returned valid=false."],
+        rule: "project-audit-invalid",
+        suggestedFix: "Resolve blocking audit findings and rerun `decantr health`."
+      })
+    );
+  }
+  const counts = {
+    errorCount: findings.filter((finding) => finding.severity === "error").length,
+    warnCount: findings.filter((finding) => finding.severity === "warn").length,
+    infoCount: findings.filter((finding) => finding.severity === "info").length
+  };
+  const manifest = audit.packManifest;
+  return {
+    $schema: MCP_PROJECT_HEALTH_SCHEMA_URL,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    projectRoot,
+    status: mcpStatusFromCounts(counts),
+    score: mcpScoreFromCounts(counts),
+    summary: {
+      ...counts,
+      findingCount: findings.length,
+      workflowMode: null,
+      adoptionMode: null,
+      essenceVersion: audit.summary.essenceVersion,
+      pageCount: audit.summary.pageCount,
+      runtimeAuditChecked: audit.summary.runtimeAuditChecked,
+      runtimePassed: audit.summary.runtimePassed,
+      packManifestPresent: audit.summary.packManifestPresent,
+      reviewPackPresent: audit.summary.reviewPackPresent
+    },
+    routes: {
+      declared: mcpCollectDeclaredRoutes(audit.essence),
+      runtimeChecked: audit.runtimeAudit.routeHintsChecked,
+      runtimeMatched: audit.runtimeAudit.routeHintsMatched,
+      runtimeCoverageOk: audit.summary.runtimeAuditChecked ? audit.runtimeAudit.routeHintsCoverageOk : null,
+      issues: findings.filter(
+        (finding) => finding.category.toLowerCase().includes("route") || finding.rule?.toLowerCase().includes("route") || finding.id.toLowerCase().includes("route")
+      ).map((finding) => finding.message)
+    },
+    packs: {
+      manifestPresent: Boolean(manifest),
+      reviewPackPresent: Boolean(manifest?.review ?? audit.reviewPack),
+      scaffoldPackPresent: Boolean(manifest?.scaffold),
+      sectionPackCount: manifest?.sections.length ?? 0,
+      pagePackCount: manifest?.pages.length ?? 0,
+      mutationPackCount: manifest?.mutations?.length ?? 0,
+      generatedAt: typeof manifest?.generatedAt === "string" ? manifest.generatedAt : null
+    },
+    ci: {
+      recommendedCommand: "decantr health --ci --fail-on error",
+      failOn: "error"
+    },
+    findings
+  };
+}
+function resolveMcpProjectRoot(value) {
+  if (value == null) return process.cwd();
+  if (typeof value !== "string") {
+    throw new Error("project_path must be a string when provided.");
+  }
+  return resolveWorkspacePath(value);
+}
+async function getMcpHealthState(projectRoot) {
+  const { auditProject, createContractAssertions, createEvidenceBundle } = await import("@decantr/verifier");
+  const audit = await auditProject(projectRoot);
+  const assertions = createContractAssertions(projectRoot, audit);
+  const report = mcpReportFromAudit(projectRoot, audit, assertions);
+  const evidence = createEvidenceBundle({
+    projectRoot,
+    audit,
+    assertions,
+    report,
+    workspaceConfigPath: existsSync(join2(projectRoot, ".decantr", "workspace.json")) ? join2(projectRoot, ".decantr", "workspace.json") : null
+  });
+  return { audit, assertions, report, evidence };
+}
+function discoverMcpWorkspaceProjects(root, maxProjects = 500) {
+  const projects = [];
+  function walk(dir, depth) {
+    if (projects.length >= maxProjects || depth > 6) return;
+    if (existsSync(join2(dir, "decantr.essence.json"))) {
+      const path = relative2(root, dir).replace(/\\/g, "/") || ".";
+      projects.push({
+        id: path.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "project",
+        path,
+        absolutePath: dir
+      });
+      return;
+    }
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
+      if (MCP_WORKSPACE_IGNORES.has(entry.name)) continue;
+      walk(join2(dir, entry.name), depth + 1);
+      if (projects.length >= maxProjects) return;
+    }
+  }
+  walk(root, 0);
+  return projects.sort((a, b) => a.path.localeCompare(b.path));
+}
+async function getMcpWorkspaceHealth(args) {
+  const root = args.workspace_root == null ? process.cwd() : resolveMcpProjectRoot(args.workspace_root);
+  const maxProjects = typeof args.max_projects === "number" && Number.isFinite(args.max_projects) ? Math.max(1, Math.floor(args.max_projects)) : 500;
+  const discovered = discoverMcpWorkspaceProjects(root, maxProjects);
+  const projects = [];
+  for (const project of discovered) {
+    const startedAt = Date.now();
+    try {
+      const state = await getMcpHealthState(project.absolutePath);
+      projects.push({
+        id: project.id,
+        path: project.path,
+        status: state.report.status,
+        score: state.report.score,
+        errorCount: state.report.summary.errorCount,
+        warnCount: state.report.summary.warnCount,
+        infoCount: state.report.summary.infoCount,
+        findingCount: state.report.summary.findingCount,
+        durationMs: Date.now() - startedAt,
+        changed: false,
+        source: "auto",
+        error: null
+      });
+    } catch (error) {
+      projects.push({
+        id: project.id,
+        path: project.path,
+        status: "failed",
+        score: 0,
+        errorCount: 1,
+        warnCount: 0,
+        infoCount: 0,
+        findingCount: 1,
+        durationMs: Date.now() - startedAt,
+        changed: false,
+        source: "auto",
+        error: error.message
+      });
+    }
+  }
+  return {
+    $schema: MCP_WORKSPACE_HEALTH_SCHEMA_URL,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    workspaceRoot: "<workspace>",
+    changedOnly: false,
+    since: null,
+    summary: {
+      projectCount: discovered.length,
+      checkedCount: projects.length,
+      healthyCount: projects.filter((project) => project.status === "healthy").length,
+      warningCount: projects.filter((project) => project.status === "warning").length,
+      errorCount: projects.filter((project) => project.status === "error").length,
+      failedCount: projects.filter((project) => project.status === "failed").length
+    },
+    projects
+  };
+}
 var TOOLS = [
   // 1. decantr_read_essence — local read
   {
     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 +805,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 +815,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 +918,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 +944,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 +1005,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: {
@@ -935,6 +1260,82 @@ var TOOLS = [
       required: ["file_path"]
     },
     annotations: READ_ONLY_NETWORK
+  },
+  // 22. decantr_get_evidence_bundle — local reliability artifact
+  {
+    name: "decantr_get_evidence_bundle",
+    title: "Get Evidence Bundle",
+    description: "Generate a local Evidence Bundle for the current Decantr project. The bundle redacts source, prompts, secrets, absolute paths, repo names, and screenshots by default.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        project_path: {
+          type: "string",
+          description: "Optional relative project path inside the active workspace. Defaults to the current working directory."
+        }
+      }
+    },
+    annotations: READ_ONLY
+  },
+  // 23. decantr_workspace_health — local workspace reliability scan
+  {
+    name: "decantr_workspace_health",
+    title: "Workspace Health",
+    description: "Discover Decantr projects in the active workspace and return deterministic aggregate health for monorepos with many Decantr apps.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        workspace_root: {
+          type: "string",
+          description: "Optional relative workspace root inside the active workspace. Defaults to the current working directory."
+        },
+        max_projects: {
+          type: "number",
+          description: "Optional cap on discovered projects. Defaults to 500."
+        }
+      }
+    },
+    annotations: READ_ONLY
+  },
+  // 24. decantr_get_repair_prompt — local AI repair loop
+  {
+    name: "decantr_get_repair_prompt",
+    title: "Get Repair Prompt",
+    description: "Return an AI-ready repair prompt for a Project Health finding, including exact finding evidence, preserved constraints, do-not-change guidance, and rerun commands.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        project_path: {
+          type: "string",
+          description: "Optional relative project path inside the active workspace. Defaults to the current working directory."
+        },
+        finding_id: {
+          type: "string",
+          description: "Optional finding id. Defaults to the first error or warning, then the first finding."
+        }
+      }
+    },
+    annotations: READ_ONLY
+  },
+  // 25. decantr_run_health_loop — local evidence + repair loop
+  {
+    name: "decantr_run_health_loop",
+    title: "Run Health Loop",
+    description: "Run Project Health, produce evidence, and return the next repair prompt for AI agents without uploading project source.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        project_path: {
+          type: "string",
+          description: "Optional relative project path inside the active workspace. Defaults to the current working directory."
+        },
+        finding_id: {
+          type: "string",
+          description: "Optional finding id to target. Defaults to the first error or warning, then the first finding."
+        }
+      }
+    },
+    annotations: READ_ONLY
   }
 ];
 async function handleTool(name, args) {
@@ -946,7 +1347,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 +1381,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 +1595,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 +1663,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 +1685,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 +1737,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 +1792,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 +1815,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 +1881,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 +1921,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 +2051,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);
@@ -2092,10 +2498,122 @@ async function handleTool(name, args) {
       }
       return auditProject(projectRoot);
     }
+    case "decantr_get_evidence_bundle": {
+      try {
+        const projectRoot = resolveMcpProjectRoot(args.project_path);
+        const state = await getMcpHealthState(projectRoot);
+        return state.evidence;
+      } catch (error) {
+        return { error: error.message };
+      }
+    }
+    case "decantr_workspace_health": {
+      if (args.workspace_root != null && typeof args.workspace_root !== "string") {
+        return { error: "Invalid workspace_root. Must be a string when provided." };
+      }
+      if (args.max_projects != null && (typeof args.max_projects !== "number" || !Number.isFinite(args.max_projects))) {
+        return { error: "Invalid max_projects. Must be a finite number when provided." };
+      }
+      try {
+        return await getMcpWorkspaceHealth(args);
+      } catch (error) {
+        return { error: error.message };
+      }
+    }
+    case "decantr_get_repair_prompt": {
+      if (args.finding_id != null && typeof args.finding_id !== "string") {
+        return { error: "Invalid finding_id. Must be a string when provided." };
+      }
+      try {
+        const projectRoot = resolveMcpProjectRoot(args.project_path);
+        const state = await getMcpHealthState(projectRoot);
+        const finding = (typeof args.finding_id === "string" ? state.report.findings.find((entry) => entry.id === args.finding_id) : void 0) ?? state.report.findings.find((entry) => entry.severity === "error") ?? state.report.findings.find((entry) => entry.severity === "warn") ?? state.report.findings[0] ?? null;
+        if (!finding) {
+          return {
+            project: state.evidence.project,
+            health: state.evidence.health,
+            prompt: null,
+            message: "No Project Health findings require repair.",
+            commands: ["decantr health --evidence"]
+          };
+        }
+        return {
+          project: state.evidence.project,
+          health: state.evidence.health,
+          finding: {
+            id: finding.id,
+            source: finding.source,
+            severity: finding.severity,
+            category: finding.category,
+            message: finding.message
+          },
+          prompt: finding.remediation.prompt,
+          commands: finding.remediation.commands
+        };
+      } catch (error) {
+        return { error: error.message };
+      }
+    }
+    case "decantr_run_health_loop": {
+      if (args.finding_id != null && typeof args.finding_id !== "string") {
+        return { error: "Invalid finding_id. Must be a string when provided." };
+      }
+      try {
+        const projectRoot = resolveMcpProjectRoot(args.project_path);
+        const state = await getMcpHealthState(projectRoot);
+        const finding = (typeof args.finding_id === "string" ? state.report.findings.find((entry) => entry.id === args.finding_id) : void 0) ?? state.report.findings.find((entry) => entry.severity === "error") ?? state.report.findings.find((entry) => entry.severity === "warn") ?? state.report.findings[0] ?? null;
+        return {
+          project: state.evidence.project,
+          health: state.evidence.health,
+          report: state.report,
+          evidence: state.evidence,
+          repair: finding === null ? {
+            finding: null,
+            prompt: null,
+            commands: ["decantr health --evidence"],
+            message: "No Project Health findings require repair."
+          } : {
+            finding: {
+              id: finding.id,
+              source: finding.source,
+              severity: finding.severity,
+              category: finding.category,
+              message: finding.message
+            },
+            prompt: finding.remediation.prompt,
+            commands: finding.remediation.commands
+          }
+        };
+      } catch (error) {
+        return { error: error.message };
+      }
+    }
     default:
       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 +2627,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 +2653,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 +2670,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 +2681,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 +2701,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 +2747,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-FEXPLJKB.js";

package/package.json

@@ -1,9 +1,11 @@
 {
   "name": "@decantr/mcp-server",
-  "version": "1.0.6",
+  "version": "2.1.0",
   "mcpName": "io.github.decantr-ai/mcp-server",
   "description": "MCP server for Decantr — exposes design intelligence, packs, and verification to AI coding assistants",
   "keywords": [
+    "decantr",
+    "decantr-ai",
     "mcp",
     "mcp-server",
     "model-context-protocol",
@@ -15,6 +17,7 @@
     "windsurf",
     "design-system",
     "design-intelligence",
+    "project-health",
     "ui-generation",
     "drift-detection"
   ],
@@ -46,9 +49,9 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@decantr/essence-spec": "1.0.6",
-    "@decantr/registry": "1.0.4",
-    "@decantr/verifier": "1.0.6"
+    "@decantr/essence-spec": "2.0.1",
+    "@decantr/verifier": "2.1.0",
+    "@decantr/registry": "2.0.0"
   },
   "scripts": {
     "build": "tsup",