@decantr/mcp-server 2.0.0 → 2.2.0

package/README.md

@@ -12,7 +12,8 @@ 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
+- **Structured design context** -- gives your AI assistant patterns, layouts, component specs, and Brownfield task-time context 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
 
@@ -132,12 +133,17 @@ The server exposes Decantr registry, context, benchmark, and verification tools.
 | `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_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_suggest_patterns` | Given a page description plus optional route/source excerpt, get ranked pattern suggestions | `{ "description": "recipe feed with avatars and infinite scroll", "route": "/feed" }` |
 | `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" }` |
 | `decantr_get_execution_pack` | Read compiled scaffold, section, page, review, or mutation execution packs, with hosted fallback when local context is missing | `{ "pack_type": "page", "id": "overview", "format": "json" }` |
+| `decantr_prepare_task_context` | Resolve compact route/task context before editing a Brownfield or Essence route | `{ "route": "/feed", "task": "improve recipe card loading" }` |
 | `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.
@@ -165,12 +171,15 @@ The AI assistant calls these tools behind the scenes:
 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_get_execution_pack` -- loads the compiled scaffold/page/review packs as the task contract, falling back to hosted compilation when local pack artifacts are missing
-6. `decantr_compile_execution_packs` -- compiles the hosted pack bundle when the task needs a fresh remote contract from the essence document
-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
-
-The AI now generates code with the right layout structure, correct components, and consistent styling -- not a generic guess.
+6. `decantr_prepare_task_context` -- resolves route-local Brownfield context, visual evidence, and theme inventory before editing an existing app
+7. `decantr_compile_execution_packs` -- compiles the hosted pack bundle when the task needs a fresh remote contract from the essence document
+8. `decantr_check_drift` -- validates the generated code against the Essence spec before presenting it
+9. `decantr_critique` -- critiques a specific file, falling back to the hosted verifier when the local review pack is missing
+10. `decantr_audit_project` -- runs the stronger project-level audit once the implementation is in place
+11. `decantr_get_evidence_bundle` -- returns the local evidence bundle for the AI repair loop
+12. `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, 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-MUNBODQK.js";
+import "./chunk-SVLMT45O.js";

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

@@ -8,7 +8,12 @@ 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, isV4 as isV42, validateEssence } from "@decantr/essence-spec";
-import { isContentIntelligenceSource, resolvePatternPreset } from "@decantr/registry";
+import {
+  isContentIntelligenceSource,
+  patternToDiscoveryCandidate,
+  rankPatternCandidates,
+  resolvePatternPreset
+} from "@decantr/registry";
 
 // src/helpers.ts
 import { realpathSync } from "fs";
@@ -124,6 +129,47 @@ async function writeDriftLog(entries, projectRoot) {
 }
 
 // src/tools.ts
+function readJsonIfExists(path) {
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function extractPatternIdsFromLayoutItem(item, ids) {
+  if (typeof item === "string") {
+    ids.add(item);
+    return;
+  }
+  if (!item || typeof item !== "object") return;
+  const record = item;
+  if (typeof record.pattern === "string") ids.add(record.pattern);
+  if (Array.isArray(record.cols)) {
+    for (const col of record.cols) extractPatternIdsFromLayoutItem(col, ids);
+  }
+}
+function extractPagePatternIds(page) {
+  if (!page) return [];
+  const ids = /* @__PURE__ */ new Set();
+  for (const item of page.layout ?? []) extractPatternIdsFromLayoutItem(item, ids);
+  return [...ids].sort();
+}
+function summarizePackJson(pack) {
+  if (!pack || typeof pack !== "object") {
+    return { directives: [], patterns: [], visualTarget: null, sharedComponents: [] };
+  }
+  const record = pack;
+  const data = record.data && typeof record.data === "object" ? record.data : record;
+  const patterns = Array.isArray(data.patterns) ? data.patterns : [];
+  const directives = Array.isArray(data.directives) ? data.directives : [];
+  const sharedComponents = Array.isArray(data.sharedComponents) ? data.sharedComponents : Array.isArray(data.shared_components) ? data.shared_components : [];
+  const visualTarget = typeof data.visualTarget === "string" ? data.visualTarget : typeof data.visual_target === "string" ? data.visual_target : null;
+  return { directives, patterns, visualTarget, sharedComponents };
+}
+function routeSlug(route) {
+  return route.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "root";
+}
 async function getShowcaseBenchmarkPayload(view) {
   const client = getPublicAPIClient();
   if (view === "manifest") {
@@ -469,6 +515,333 @@ 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
   {
@@ -588,6 +961,14 @@ var TOOLS = [
         description: {
           type: "string",
           description: 'Description of the page or section (e.g. "dashboard with metrics and charts", "settings form with toggles")'
+        },
+        route: {
+          type: "string",
+          description: 'Optional route context, for example "/feed" or "/settings".'
+        },
+        source_code: {
+          type: "string",
+          description: "Optional local source excerpt to rank against actual code evidence."
         }
       },
       required: ["description"]
@@ -785,7 +1166,31 @@ var TOOLS = [
     },
     annotations: READ_ONLY
   },
-  // 16. decantr_get_execution_pack — local read
+  // 16. decantr_prepare_task_context — local read
+  {
+    name: "decantr_prepare_task_context",
+    title: "Prepare Task Context",
+    description: "Resolve compact Brownfield/Essence task-time context for a route or page before editing. Returns route, section, page pack, directives, patterns, shared components, visual target, health evidence, and local screenshot references when available.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        route: {
+          type: "string",
+          description: 'Route being edited, for example "/feed". Preferred when known.'
+        },
+        page_id: {
+          type: "string",
+          description: "Page ID when route is unknown."
+        },
+        task: {
+          type: "string",
+          description: "Short task description used to rank relevant patterns and context."
+        }
+      }
+    },
+    annotations: READ_ONLY
+  },
+  // 17. decantr_get_execution_pack — local read
   {
     name: "decantr_get_execution_pack",
     title: "Get Execution Pack",
@@ -940,6 +1345,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) {
@@ -1110,78 +1591,59 @@ async function handleTool(name, args) {
     case "decantr_suggest_patterns": {
       const err = validateStringArg(args, "description");
       if (err) return { error: err };
-      const desc = args.description.toLowerCase();
+      const desc = args.description;
+      const route = typeof args.route === "string" ? args.route : void 0;
+      const sourceCode = typeof args.source_code === "string" ? args.source_code : void 0;
       try {
         const patternsResponse = await apiClient.listContent("patterns", {
           namespace: "@official",
-          limit: 100
+          limit: 250
         });
-        const prelimScores = [];
-        for (const p of patternsResponse.items) {
-          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(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) {
-            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 preliminary = rankPatternCandidates(
+          { query: desc, route, code: sourceCode, limit: 12 },
+          patternsResponse.items.map(
+            (item) => patternToDiscoveryCandidate({
+              id: item.slug || item.name || "pattern",
+              slug: item.slug,
+              name: item.name,
+              description: item.description
+            })
+          )
+        );
+        const fullCandidates = await Promise.all(
+          preliminary.map(async (match) => {
+            const slug = match.candidate.slug || match.candidate.id;
+            try {
+              const fetched = await apiClient.getPattern("@official", slug);
+              return patternToDiscoveryCandidate(fetched, { slug, source: "hosted" });
+            } catch {
+              return match.candidate;
             }
-          }
-          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);
+          })
+        );
+        const suggestions = rankPatternCandidates(
+          { query: desc, route, code: sourceCode, limit: 5 },
+          fullCandidates
+        ).map((match) => {
+          const pattern = match.candidate.pattern;
+          const preset = pattern?.presets ? Object.values(pattern.presets)[0] : null;
+          return {
+            id: match.candidate.slug || match.candidate.id,
+            score: match.score,
+            name: match.candidate.name || match.candidate.slug || match.candidate.id,
+            description: match.candidate.description || "",
+            components: match.candidate.components || [],
+            interactions: match.candidate.interactions || [],
+            layout: preset?.layout ? preset.layout.layout : "unknown",
+            reasons: match.reasons,
+            matched_terms: match.matchedTerms
+          };
+        });
         return {
           query: args.description,
-          suggestions: suggestions.slice(0, 5),
-          total: prelimScores.length
+          route,
+          suggestions,
+          total: preliminary.length
         };
       } catch (e) {
         return { error: `Could not fetch patterns: ${e.message}` };
@@ -1855,6 +2317,118 @@ async function handleTool(name, args) {
         hosted_fallback_error: hostedFallbackError ?? void 0
       };
     }
+    case "decantr_prepare_task_context": {
+      const routeArg = typeof args.route === "string" ? args.route : void 0;
+      const pageArg = typeof args.page_id === "string" ? args.page_id : void 0;
+      const task = typeof args.task === "string" ? args.task : "";
+      if (!routeArg && !pageArg) {
+        return { error: "Provide route or page_id." };
+      }
+      let essence;
+      try {
+        const result = await readEssenceFile();
+        essence = result.essence;
+      } catch {
+        return { error: "No valid essence file found. Run decantr init first." };
+      }
+      if (!isV42(essence)) {
+        return {
+          error: "Task context requires Essence v4.0.0. Run `decantr migrate --to v4` first."
+        };
+      }
+      const routeEntry = routeArg ? essence.blueprint.routes?.[routeArg] : null;
+      const sectionId = routeEntry?.section;
+      const pageId = pageArg || routeEntry?.page;
+      const section = sectionId ? essence.blueprint.sections.find((entry) => entry.id === sectionId) : essence.blueprint.sections.find(
+        (entry) => entry.pages.some((page2) => page2.id === pageId)
+      );
+      const page = section?.pages.find((entry) => entry.id === pageId) ?? null;
+      if (!section || !page || !pageId) {
+        return {
+          error: "Could not resolve route/page to an Essence section page.",
+          available_routes: Object.keys(essence.blueprint.routes ?? {}).sort(),
+          available_pages: essence.blueprint.sections.flatMap(
+            (entry) => entry.pages.map((pageEntry) => ({ section_id: entry.id, page_id: pageEntry.id }))
+          )
+        };
+      }
+      const contextDir = join2(process.cwd(), ".decantr", "context");
+      const manifest = readJsonIfExists(join2(contextDir, "pack-manifest.json"));
+      const pageManifest = manifest?.pages.find((entry) => entry.id === pageId) ?? null;
+      const sectionManifest = manifest?.sections.find((entry) => entry.id === section.id) ?? null;
+      const pagePackJson = pageManifest ? readJsonIfExists(join2(contextDir, pageManifest.json)) : null;
+      const sectionPackJson = sectionManifest ? readJsonIfExists(join2(contextDir, sectionManifest.json)) : null;
+      const pagePackMarkdown = pageManifest && existsSync(join2(contextDir, pageManifest.markdown)) ? readFileSync(join2(contextDir, pageManifest.markdown), "utf-8") : null;
+      const sectionContextPath = join2(contextDir, `section-${section.id}.md`);
+      const sectionContext = existsSync(sectionContextPath) ? readFileSync(sectionContextPath, "utf-8") : null;
+      const pagePackSummary = summarizePackJson(pagePackJson);
+      const sectionPackSummary = summarizePackJson(sectionPackJson);
+      const visualManifest = readJsonIfExists(join2(process.cwd(), ".decantr", "evidence", "visual-manifest.json"));
+      const visualRoute = visualManifest?.routes?.find((entry) => entry.route === routeArg) ?? visualManifest?.routes?.find(
+        (entry) => entry.screenshot?.includes(routeSlug(routeArg ?? pageId))
+      ) ?? null;
+      const health = readJsonIfExists(join2(process.cwd(), ".decantr", "health-baseline-diff.json"));
+      const themeInventory = readJsonIfExists(
+        join2(process.cwd(), ".decantr", "theme-inventory.json")
+      );
+      const patternIds = extractPagePatternIds(page);
+      const ranked = rankPatternCandidates(
+        {
+          query: [task, routeArg, page.description, ...patternIds].filter(Boolean).join(" "),
+          limit: 5
+        },
+        patternIds.map((id) => patternToDiscoveryCandidate({ id, name: id, description: id }))
+      );
+      return {
+        route: routeArg ?? null,
+        page_id: pageId,
+        section_id: section.id,
+        section_role: section.role,
+        shell: section.shell,
+        task,
+        visual_target: pagePackSummary.visualTarget ?? sectionPackSummary.visualTarget ?? essence.dna.personality?.join(". ") ?? null,
+        directives: pagePackSummary.directives,
+        patterns: pagePackSummary.patterns.length > 0 ? pagePackSummary.patterns : patternIds,
+        ranked_patterns: ranked.map((match) => ({
+          id: match.candidate.slug || match.candidate.id,
+          score: match.score,
+          reasons: match.reasons
+        })),
+        shared_components: pagePackSummary.sharedComponents,
+        section_context: sectionContext,
+        page_pack_excerpt: pagePackMarkdown ? pagePackMarkdown.slice(0, 12e3) : null,
+        health_evidence: health ? {
+          baseline_path: health.baselinePath,
+          saved_at: health.savedAt,
+          status_changed: health.statusChanged,
+          score_delta: health.scoreDelta,
+          added_findings: health.addedFindings?.slice(0, 8) ?? [],
+          resolved_findings: health.resolvedFindings?.slice(0, 8) ?? [],
+          changed_routes: health.changedRoutes ?? [],
+          changed_screenshots: health.changedScreenshots ?? [],
+          contract_drift: health.contractDrift ?? []
+        } : null,
+        visual_evidence: visualRoute ? {
+          screenshot: visualRoute.screenshot ?? null,
+          screenshot_hash: visualRoute.screenshotHash ?? null,
+          status: visualRoute.status ?? null,
+          error: visualRoute.error ?? null
+        } : null,
+        theme_inventory: themeInventory ? {
+          modes: themeInventory.modes,
+          variants: themeInventory.variants,
+          path: ".decantr/theme-inventory.json"
+        } : null,
+        local_files: {
+          page_pack: pageManifest?.markdown ?? null,
+          section_pack: sectionManifest?.markdown ?? null,
+          section_context: existsSync(sectionContextPath) ? `.decantr/context/section-${section.id}.md` : null,
+          visual_manifest: existsSync(
+            join2(process.cwd(), ".decantr", "evidence", "visual-manifest.json")
+          ) ? ".decantr/evidence/visual-manifest.json" : null
+        }
+      };
+    }
     case "decantr_get_execution_pack": {
       const contextDir = join2(process.cwd(), ".decantr", "context");
       const manifestPath = join2(contextDir, "pack-manifest.json");
@@ -2102,6 +2676,96 @@ 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}` };
   }
@@ -2261,7 +2925,7 @@ function describeUpdate(operation, payload) {
 }
 
 // src/index.ts
-var VERSION = "2.0.0";
+var VERSION = "2.2.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-MUNBODQK.js";
+import "./chunk-SVLMT45O.js";

package/package.json

@@ -1,9 +1,11 @@
 {
   "name": "@decantr/mcp-server",
-  "version": "2.0.0",
+  "version": "2.2.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/registry": "2.0.0",
-    "@decantr/verifier": "2.0.0",
-    "@decantr/essence-spec": "2.0.1"
+    "@decantr/essence-spec": "2.0.1",
+    "@decantr/verifier": "2.2.0",
+    "@decantr/registry": "2.2.0"
   },
   "scripts": {
     "build": "tsup",