@decantr/mcp-server 2.0.0 → 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,6 +139,10 @@ 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.
@@ -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-MUNBODQK.js";
+import "./chunk-FEXPLJKB.js";

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

@@ -469,6 +469,326 @@ 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
   {
@@ -940,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) {
@@ -2102,6 +2498,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}` };
   }

package/dist/index.js

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

package/package.json

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