@decantr/mcp-server 3.4.0 → 3.5.0

package/README.md

@@ -131,9 +131,9 @@ The server exposes a hard 8-tool MCP surface. Pass an `action` to select the rou
 | `decantr_context` | Read scaffold, section, page, task, and execution-pack context | `{ "action": "task", "project_path": "apps/web", "route": "/feed", "task": "improve recipe card loading" }` |
 | `decantr_graph` | Read graph snapshots, query graph nodes/edges, or traverse graph relations | `{ "action": "query", "project_path": "apps/web", "file_path": "src/app/page.tsx", "include_impact": true }` |
 | `decantr_registry` | Search and resolve hosted registry content, benchmarks, and execution packs | `{ "action": "resolve_pattern", "id": "data-table", "preset": "product" }` |
-| `decantr_verify` | Run audit, critique, findings, evidence, or health-loop reads | `{ "action": "critique", "file_path": "./src/pages/Overview.tsx" }` |
-| `decantr_repair` | Return typed findings, repair plans, repair prompts, and repair loop guidance | `{ "action": "repair_plan", "project_path": "apps/web", "code": "TOKEN010" }` |
-| `decantr_contract_write` | Explicit write surface for accepting drift or mutating Essence v4 | `{ "action": "update_essence", "operation": "add_feature", "payload": { "feature": "billing" } }` |
+| `decantr_verify` | Run audit, critique, findings, v2 evidence bundles, or health-loop reads | `{ "action": "evidence_bundle", "project_path": "apps/web" }` |
+| `decantr_repair` | Return typed findings, repair plans, repair prompts, and v2 health-loop guidance | `{ "action": "health_loop", "project_path": "apps/web" }` |
+| `decantr_contract_write` | Explicit write surface for accepting drift, deferring drift to the drift log, or mutating Essence v4 | `{ "action": "update_essence", "operation": "add_feature", "payload": { "feature": "billing" } }` |
 
 For the broader product surface and support policy, see the root Decantr docs and package support matrix.
 
@@ -141,7 +141,7 @@ For Decantr 3 assistant prompt migration, see the MCP migration guide: https://d
 
 ## Security And Permissions
 
-The MCP server reads Decantr files, including `.decantr/graph` typed graph artifacts, and selected project files from the active workspace. Write access is limited to the explicit `decantr_contract_write` tool with `accept_drift` and `update_essence` actions, and paths are contained to the active workspace root.
+The MCP server reads Decantr files, including `.decantr/graph` typed graph artifacts, and selected project files from the active workspace. Write access is limited to the explicit `decantr_contract_write` tool with `accept_drift` and `update_essence` actions. `accept_drift` may defer a finding to `.decantr/drift-log.json` when the caller explicitly requests that resolution. Paths are contained to the active workspace root.
 
 Registry and pack-resolution tools may call the configured Decantr API. Source upload fallbacks for hosted critique/audit are disabled unless the tool call explicitly passes `allow_hosted_upload: true`. The MCP server does not emit Decantr telemetry. See [security permissions](https://decantr.ai/reference/security-permissions.md).
 
@@ -155,7 +155,7 @@ Registry and pack-resolution tools may call the configured Decantr API. Source u
 
 ### 3.4 Tool Surface Migration
 
-Decantr 3.4 consolidates legacy MCP tool names into the eight action-based tools above. For example, `decantr_get_project_state` becomes `decantr_project` with `{ "action": "state" }`, `decantr_get_graph_snapshot` becomes `decantr_graph` with `{ "action": "snapshot" }`, and the legacy write tools become `decantr_contract_write` with `{ "action": "accept_drift" }` or `{ "action": "update_essence" }`.
+Decantr 3.4 consolidated legacy MCP tool names into the eight action-based tools above. Decantr 3.5 keeps that surface and upgrades task, evidence, workspace health, and health-loop responses to v2 loop/evidence contracts. For example, `decantr_get_project_state` becomes `decantr_project` with `{ "action": "state" }`, `decantr_get_graph_snapshot` becomes `decantr_graph` with `{ "action": "snapshot" }`, and the legacy write tools become `decantr_contract_write` with `{ "action": "accept_drift" }` or `{ "action": "update_essence" }`.
 
 ## How It Works
 
@@ -172,8 +172,8 @@ The AI assistant calls these tools behind the scenes:
 3. `decantr_context` with `execution_pack` or `task` actions to load the compact task contract before editing
 4. `decantr_project` with `state` to check Essence, packs, graph readiness, local law, diagnostics, and next useful action calls
 5. `decantr_contract` with `capsule` and `decantr_graph` with `snapshot`, `query`, or `traverse` to read typed graph context
-6. `decantr_verify` with `critique`, `audit_project`, or `evidence_bundle` to produce local evidence; hosted upload remains opt-in with `allow_hosted_upload: true`
-7. `decantr_repair` with `findings`, `repair_plan`, or `repair_prompt` to enter a scoped evidence-backed repair loop
+6. `decantr_verify` with `critique`, `audit_project`, or `evidence_bundle` to produce local v2 evidence; hosted upload remains opt-in with `allow_hosted_upload: true`
+7. `decantr_repair` with `findings`, `repair_plan`, `repair_prompt`, or `health_loop` to enter a scoped evidence-backed repair loop
 
 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.
 

package/dist/bin.js

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

package/dist/{chunk-BXY4AIGA.js → chunk-PE63BVJB.js}

@@ -31,8 +31,14 @@ import {
 import {
   anchorFindingsToGraph,
   buildProjectHealthRepairPlan,
+  createAuthorityResolution,
+  createEvidenceTier,
+  createLoopReadiness,
   deriveVerificationDiagnostic,
-  KNOWN_VERIFICATION_DIAGNOSTICS
+  KNOWN_VERIFICATION_DIAGNOSTICS,
+  LOOP_READINESS_V2_SCHEMA_URL,
+  PROJECT_HEALTH_REPORT_V2_SCHEMA_URL,
+  WORKSPACE_HEALTH_REPORT_V2_SCHEMA_URL
 } from "@decantr/verifier";
 
 // src/helpers.ts
@@ -1232,8 +1238,8 @@ 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_PROJECT_HEALTH_SCHEMA_URL = PROJECT_HEALTH_REPORT_V2_SCHEMA_URL;
+var MCP_WORKSPACE_HEALTH_SCHEMA_URL = WORKSPACE_HEALTH_REPORT_V2_SCHEMA_URL;
 var MCP_WORKSPACE_IGNORES = /* @__PURE__ */ new Set([
   ".git",
   ".next",
@@ -1504,7 +1510,8 @@ function mcpReportFromAudit(projectRoot, audit, assertions) {
     infoCount: anchoredFindings.filter((finding) => finding.severity === "info").length
   };
   const manifest = audit.packManifest;
-  return {
+  const projectJson = readJsonIfExists(join2(projectRoot, ".decantr", "project.json"));
+  const baseReport = {
     $schema: MCP_PROJECT_HEALTH_SCHEMA_URL,
     generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
     projectRoot,
@@ -1513,8 +1520,8 @@ function mcpReportFromAudit(projectRoot, audit, assertions) {
     summary: {
       ...counts,
       findingCount: anchoredFindings.length,
-      workflowMode: null,
-      adoptionMode: null,
+      workflowMode: projectJson?.initialized?.workflowMode ?? null,
+      adoptionMode: projectJson?.initialized?.adoptionMode ?? null,
       essenceVersion: audit.summary.essenceVersion,
       pageCount: audit.summary.pageCount,
       runtimeAuditChecked: audit.summary.runtimeAuditChecked,
@@ -1547,6 +1554,30 @@ function mcpReportFromAudit(projectRoot, audit, assertions) {
     },
     findings: anchoredFindings
   };
+  const evidenceTier = createEvidenceTier(baseReport);
+  const authority = createAuthorityResolution(baseReport);
+  const loop = createLoopReadiness(baseReport, authority, evidenceTier);
+  return {
+    ...baseReport,
+    evidenceTier,
+    authority,
+    loop,
+    findings: anchoredFindings.map((finding) => {
+      const conflict = authority.conflicts.find((entry) => entry.id === finding.id);
+      return {
+        ...finding,
+        evidenceTier,
+        authorityLane: conflict?.lane ?? authority.activeLane,
+        resolutionActions: conflict?.recommendedActions,
+        privacy: {
+          sourceIncluded: false,
+          redacted: true,
+          localOnly: true
+        },
+        loopVerdict: loop.state
+      };
+    })
+  };
 }
 function resolveMcpProjectRoot(value) {
   if (value == null) return process.cwd();
@@ -1585,6 +1616,11 @@ function compactMcpFinding(finding, includePrompt) {
     graph: finding.graph,
     repair: finding.repair,
     repairPlan: finding.repairPlan,
+    evidenceTier: finding.evidenceTier,
+    authorityLane: finding.authorityLane,
+    resolutionActions: finding.resolutionActions,
+    privacy: finding.privacy,
+    loopVerdict: finding.loopVerdict,
     remediation: {
       summary: finding.remediation.summary,
       commands: finding.remediation.commands,
@@ -1777,7 +1813,9 @@ async function getMcpWorkspaceHealth(args) {
         durationMs: Date.now() - startedAt,
         changed: false,
         source: "auto",
-        error: null
+        error: null,
+        loopState: state.report.loop.state,
+        loopNextAction: state.report.loop.nextActions[0] ?? null
       });
     } catch (error) {
       projects.push({
@@ -1792,23 +1830,43 @@ async function getMcpWorkspaceHealth(args) {
         durationMs: Date.now() - startedAt,
         changed: false,
         source: "auto",
-        error: error.message
+        error: error.message,
+        loopState: "blocked_missing_context",
+        loopNextAction: "Fix the project health failure, then rerun workspace health."
       });
     }
   }
+  const 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
+  };
+  const blockedCount = projects.filter(
+    (project) => typeof project.loopState === "string" && (project.loopState.startsWith("blocked") || project.loopState === "human_resolution_required")
+  ).length;
+  const repairRequiredCount = projects.filter(
+    (project) => project.loopState === "repair_required"
+  ).length;
+  const loopState = projects.length === 0 ? "needs_context" : blockedCount > 0 ? "human_resolution_required" : repairRequiredCount > 0 || summary.errorCount > 0 || summary.warningCount > 0 ? "repair_required" : "verified";
   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
+    summary,
+    loop: {
+      state: loopState,
+      status: loopState === "human_resolution_required" || loopState.startsWith("blocked") ? "blocked" : summary.errorCount > 0 || summary.failedCount > 0 ? "error" : summary.warningCount > 0 ? "warning" : "healthy",
+      projectCount: projects.length,
+      blockedCount,
+      repairRequiredCount,
+      nextActions: [
+        loopState === "verified" ? "Workspace loop verified." : "Open the highest-risk project, prepare task context, repair, and rerun verification."
+      ]
     },
     projects
   };
@@ -3513,6 +3571,85 @@ async function handleLegacyTool(name, args) {
         },
         patternIds.map((id) => patternToDiscoveryCandidate({ id, name: id, description: id }))
       );
+      const typedGraph = buildTaskTypedGraphContext(projectRoot, resolvedRoute, task, changedFiles);
+      const verifyCommand = projectArg ? `decantr verify --project ${projectArg} --brownfield --local-patterns` : "decantr verify --brownfield --local-patterns";
+      const loopState = typedGraph?.route_context ? "ready_to_edit" : "blocked_missing_graph";
+      const loop = {
+        $schema: LOOP_READINESS_V2_SCHEMA_URL,
+        schemaVersion: 2,
+        state: loopState,
+        status: loopState === "ready_to_edit" ? "healthy" : "blocked",
+        verdict: loopState === "ready_to_edit" ? "Task context is ready for an agent edit." : "Task context is missing route graph evidence.",
+        summary: `${resolvedRoute ?? pageId} task context for ${task || "unspecified task"}.`,
+        authority: {
+          activeLane: projectJson?.initialized?.workflowMode === "brownfield-attach" ? "production-source" : "essence-contract",
+          summary: "Use production source first in Brownfield, accepted local law/style bridge next, Essence V4 structure after that, and hosted packs as advisory.",
+          stopRule: "If runtime source and Decantr context disagree, stop and report drift instead of guessing."
+        },
+        evidenceTier: {
+          schemaVersion: 2,
+          stage: typedGraph?.route_context ? "graph" : "static",
+          status: loopState === "ready_to_edit" ? "healthy" : "incomplete",
+          capabilities: typedGraph?.route_context ? ["static-audit", "project-health", "typed-graph"] : ["static-audit", "project-health"],
+          coverage: {
+            declaredRoutes: 1,
+            runtimeRoutesChecked: 0,
+            findingsAnchored: typedGraph?.route_context?.summary.openFindings ?? 0,
+            findingsWithRepairPlan: 0,
+            runtimeProbeCount: 0,
+            visualArtifactCount: visualRoute ? 1 : 0
+          },
+          confidence: {
+            level: typedGraph?.route_context ? "moderate" : "low",
+            score: typedGraph?.route_context ? 0.64 : 0.32,
+            reasons: [
+              typedGraph?.route_context ? "route graph context is present" : "route graph context is missing",
+              visualRoute ? "visual evidence reference is available" : "no visual evidence reference was found"
+            ]
+          }
+        },
+        blockingReasons: loopState === "ready_to_edit" ? [] : ["Route graph context is missing."],
+        nextActions: loopState === "ready_to_edit" ? ["Edit only after reading the returned context, then run the verify command."] : ["Run `decantr graph`, then request task context again."],
+        maker: {
+          title: "Maker instructions",
+          instructions: [
+            "Read returned route, section, local-law, style-bridge, and graph context before editing.",
+            "Preserve the active authority lane and production behavior outside this task.",
+            "Stop and report drift when runtime source and Decantr context disagree."
+          ]
+        },
+        checker: {
+          title: "Checker instructions",
+          instructions: [
+            "Rerun the verify command after edits.",
+            "Use typed graph impact to decide whether nearby routes need review.",
+            "Treat advisory critique as warning-level unless runtime evidence proves a failure."
+          ]
+        },
+        readTargets: [
+          pageManifest ? join2(".decantr", "context", pageManifest.markdown) : null,
+          sectionManifest ? join2(".decantr", "context", sectionManifest.markdown) : null,
+          ".decantr/context/scaffold.md",
+          "DECANTR.md",
+          displayedLocalLaw.patterns_path,
+          displayedLocalLaw.rules_path,
+          displayedStyleBridge.path,
+          typedGraph ? ".decantr/graph/graph.snapshot.json" : null
+        ].filter(Boolean),
+        graphImpact: {
+          status: typedGraph?.route_context ? "ready" : typedGraph ? "stale" : "missing",
+          snapshotId: typedGraph?.snapshot_id ?? null,
+          sourceHash: typedGraph?.source_hash ?? null,
+          sourceArtifactCount: typedGraph?.route_context?.summary.sourceArtifacts ?? 0,
+          staleArtifacts: typedGraph?.stale_sources ?? []
+        },
+        stopConditions: [
+          "Runtime source and Decantr context disagree.",
+          "The route graph cannot resolve a source file affected by the edit.",
+          "A fix requires contract/source/local-law mutation outside the explicit workflow."
+        ],
+        verifyCommand
+      };
       return {
         route: resolvedRoute,
         page_id: pageId,
@@ -3568,8 +3705,9 @@ async function handleLegacyTool(name, args) {
           changed_file_count: changedFiles.length,
           impacted_routes: changedRoutes
         },
-        typed_graph: buildTaskTypedGraphContext(projectRoot, resolvedRoute, task, changedFiles),
-        verify_command: projectArg ? `decantr verify --project ${projectArg} --brownfield --local-patterns` : "decantr verify --brownfield --local-patterns",
+        typed_graph: typedGraph,
+        loop,
+        verify_command: verifyCommand,
         local_files: {
           page_pack: displayProjectFile(
             projectRoot,
@@ -4001,6 +4139,9 @@ async function handleLegacyTool(name, args) {
         return {
           project: state.evidence.project,
           health: state.evidence.health,
+          loop: state.report.loop,
+          authority_resolution: state.report.authority,
+          evidence_tier: state.report.evidenceTier,
           report: state.report,
           evidence: state.evidence,
           repair_plan: buildMcpRepairPlan({
@@ -4188,7 +4329,7 @@ function describeUpdate(operation, payload) {
 }
 
 // src/index.ts
-var VERSION = "3.4.0";
+var VERSION = "3.5.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-BXY4AIGA.js";
+import "./chunk-PE63BVJB.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decantr/mcp-server",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "mcpName": "io.github.decantr-ai/mcp-server",
   "description": "MCP server for Decantr — exposes Contract context, typed graph artifacts, and verification evidence to AI coding assistants",
   "keywords": [
@@ -51,9 +51,9 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@decantr/core": "3.4.0",
-    "@decantr/verifier": "3.4.0",
+    "@decantr/core": "3.5.0",
     "@decantr/essence-spec": "3.4.0",
+    "@decantr/verifier": "3.5.0",
     "@decantr/registry": "3.4.0"
   },
   "scripts": {