@decantr/mcp-server 3.0.0-next.0 → 3.0.1

package/README.md

@@ -12,8 +12,8 @@ AI Frontend Governance for codebases touched by AI agents. Give Claude, Cursor,
 
 ![Decantr MCP demo](https://raw.githubusercontent.com/decantr-ai/decantr/main/packages/mcp-server/assets/decantr-demo.gif)
 
-- **Structured Contract context** -- gives your AI assistant patterns, layouts, component specs, typed graph context, Brownfield/Hybrid authority, local law, and task-time context instead of letting it guess
-- **Evidence-backed repair loops** -- gives AI agents Project Health, component reuse drift, accepted style bridge drift, stable diagnostic codes, typed repair IDs, graph-anchored Evidence Bundles, workspace health, and scoped repair prompts without uploading source
+- **Structured Contract context** -- gives your AI assistant patterns, layouts, component specs, typed graph context, Brownfield/Hybrid authority, local law, behavior obligations, and task-time context instead of letting it guess
+- **Evidence-backed repair loops** -- gives AI agents Project Health, component reuse drift, accepted behavior-obligation drift, accepted style bridge drift, stable diagnostic codes, typed repair IDs, graph-anchored 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
 
@@ -136,8 +136,8 @@ The server exposes Decantr vocabulary, context, benchmark, and verification tool
 | `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_get_project_state` | Read a compact typed summary of Essence, generated packs, graph artifacts, capsule source-handle bounds, source artifacts available for file impact, local snapshot history, typed diff counts, local law, style bridge, stable diagnostic catalog, and recommended next tools | `{ "project_path": "apps/web" }` |
-| `decantr_prepare_task_context` | Resolve compact route/task context, task-ranked typed route graph, optional graph-shaped changed-file impact, authority lane, local law, style bridge mappings, and evidence before editing a Brownfield, Hybrid, or Essence route | `{ "project_path": "apps/web", "route": "/feed", "task": "improve recipe card loading" }` |
+| `decantr_get_project_state` | Read a compact typed summary of Essence, generated packs, graph artifacts, capsule source-handle bounds, source artifacts available for file impact, local snapshot history, typed diff counts, local law, behavior obligations, style bridge, stable diagnostic catalog, and recommended next tools | `{ "project_path": "apps/web" }` |
+| `decantr_prepare_task_context` | Resolve compact route/task context, task-ranked typed route graph, optional graph-shaped changed-file impact, authority lane, local law, behavior obligations, style bridge mappings, and evidence before editing a Brownfield, Hybrid, or Essence route | `{ "project_path": "apps/web", "route": "/feed", "task": "improve recipe card loading" }` |
 | `decantr_get_contract_capsule` | Read the cache-friendly Contract capsule generated by `decantr graph`, including bounded SourceArtifact paths that can be reused as `file_path` handles | `{ "project_path": "apps/web" }` |
 | `decantr_get_graph_snapshot` | Read graph metadata with snapshot-history status and typed diff counts, a compact local history index, a route-scoped graph subgraph, node or source-file impact context, task-aware ranked context, a specific history snapshot, or a typed diff between local snapshots | `{ "project_path": "apps/web", "file_path": "src/app/page.tsx", "task": "edit source" }` |
 | `decantr_query_graph` | Query current or historical graph nodes, source files, payload fields, relations, and optional node-impact context without reading the full snapshot | `{ "project_path": "apps/web", "snapshot_id": "current", "file_path": "src/app/page.tsx", "include_impact": true }` |
@@ -184,8 +184,8 @@ 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_get_project_state` -- checks Essence, packs, graph readiness, capsule source-handle bounds, source artifacts available for file impact, local snapshot history, typed diff counts, local law, stable diagnostic codes, and the next useful tool calls
-7. `decantr_prepare_task_context` -- resolves route-local Brownfield/Hybrid context, task-ranked typed route graph context, graph-shaped changed-file impact when changed files resolve to SourceArtifact nodes, active authority, accepted local law, accepted style bridge mappings, visual evidence, and theme inventory before editing an existing app
+6. `decantr_get_project_state` -- checks Essence, packs, graph readiness, capsule source-handle bounds, source artifacts available for file impact, local snapshot history, typed diff counts, local law, accepted behavior obligations, stable diagnostic codes, and the next useful tool calls
+7. `decantr_prepare_task_context` -- resolves route-local Brownfield/Hybrid context, task-ranked typed route graph context, graph-shaped changed-file impact when changed files resolve to SourceArtifact nodes, active authority, accepted local law, accepted behavior obligations, accepted style bridge mappings, visual evidence, and theme inventory before editing an existing app
 8. `decantr_get_contract_capsule` -- loads the compact Contract graph capsule, including the bounded SourceArtifact path index, when `.decantr/graph` exists
 9. `decantr_get_graph_snapshot` -- reads graph metadata, snapshot-history status, optional compact history, typed diff counts, route-scoped graph nodes/edges with optional task-aware ranking, impact graph nodes/edges through `node_id` or `file_path`, specific history snapshots through `snapshot_id`, and local snapshot diffs through `compare_to`
 10. `decantr_query_graph` and `decantr_traverse_graph` -- answer typed follow-up questions against current or historical snapshots, such as which pages use a route, component, token, source file, rule, or diagnostic code; `decantr_query_graph` can include an impact subgraph for matched node IDs or a `file_path` SourceArtifact so agents can inspect blast radius before changing a component, token, rule, finding, or source artifact, and `decantr_traverse_graph` can resolve `file_path` into the SourceArtifact start node for relation walks

package/dist/bin.js

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

package/dist/{chunk-IB5HP7DE.js → chunk-PFLHZF35.js}

@@ -4,18 +4,18 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 
 // src/tools.ts
-import { createHash } from "crypto";
 import { execFileSync } from "child_process";
+import { createHash } from "crypto";
 import { existsSync, readdirSync, readFileSync } from "fs";
 import { readFile as readFile2 } from "fs/promises";
 import { basename as basename2, dirname as dirname2, isAbsolute as isAbsolute2, join as join2, relative as relative2 } from "path";
 import {
-  GRAPH_NODE_TYPES,
-  GRAPH_RELATIONS,
   buildGraphImpactContext,
   buildGraphRouteContext,
   createMemoryGraphStore,
   diffGraphSnapshots,
+  GRAPH_NODE_TYPES,
+  GRAPH_RELATIONS,
   graphPayloadString,
   sortGraphEdges,
   sortGraphNodes,
@@ -198,9 +198,7 @@ function readGraphSnapshotHistory(projectRoot, limit = 20) {
         parent_id: snapshot.parent_id ?? null,
         summary: snapshot.summary
       };
-    }).filter((entry) => Boolean(entry)).sort(
-      (a, b) => b.created_at.localeCompare(a.created_at) || a.id.localeCompare(b.id)
-    ).slice(0, Math.max(1, Math.min(100, limit)));
+    }).filter((entry) => Boolean(entry)).sort((a, b) => b.created_at.localeCompare(a.created_at) || a.id.localeCompare(b.id)).slice(0, Math.max(1, Math.min(100, limit)));
   } catch {
     return [];
   }
@@ -703,17 +701,51 @@ function impactedRoutesForFiles(projectRoot, files) {
   }
   return [...impacted].sort();
 }
+function stringArray(value) {
+  return Array.isArray(value) ? value.filter((entry) => typeof entry === "string" && entry.trim().length > 0) : [];
+}
+function behaviorObligationSummary(pattern) {
+  const contract = pattern.behavior_obligations;
+  if (!contract || !Array.isArray(contract.obligations)) return null;
+  const obligations = contract.obligations.map((entry, index) => {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) return null;
+    const record = entry;
+    const id = typeof record.id === "string" && record.id.trim() ? record.id.trim() : `obligation-${index + 1}`;
+    const label = typeof record.label === "string" && record.label.trim() ? record.label.trim() : id;
+    return {
+      id,
+      label,
+      severity: typeof record.severity === "string" ? record.severity : null,
+      evidence: typeof record.evidence === "string" ? record.evidence : null
+    };
+  }).filter((entry) => Boolean(entry));
+  if (obligations.length === 0) return null;
+  return {
+    pattern_id: pattern.id ?? "unknown",
+    pattern_role: contract.pattern_role ?? pattern.role ?? null,
+    intent: contract.intent ?? null,
+    modalities: stringArray(contract.modalities),
+    states: stringArray(contract.states),
+    risk_profile: stringArray(contract.risk_profile),
+    obligations,
+    test_hints: stringArray(contract.test_hints),
+    component_paths: pattern.componentPaths ?? []
+  };
+}
 function localLawSummary(projectRoot) {
   const patterns = readJsonIfExists(join2(projectRoot, ".decantr", "local-patterns.json"));
   const rules = readJsonIfExists(join2(projectRoot, ".decantr", "rules.json"));
+  const behaviorObligations = patterns?.patterns?.map((pattern) => behaviorObligationSummary(pattern)).filter((entry) => Boolean(entry)) ?? [];
   return {
     patterns_path: patterns ? ".decantr/local-patterns.json" : null,
     rules_path: rules ? ".decantr/rules.json" : null,
     patterns: patterns?.patterns?.map((pattern) => ({
       id: pattern.id ?? "unknown",
       role: pattern.role ?? null,
-      component_paths: pattern.componentPaths ?? []
+      component_paths: pattern.componentPaths ?? [],
+      behavior_obligations: behaviorObligationSummary(pattern)
     })) ?? [],
+    behavior_obligations: behaviorObligations,
     rules: rules?.rules?.map((rule) => ({
       id: rule.id ?? "unknown",
       enabled: rule.enabled ?? false,
@@ -2099,7 +2131,7 @@ var TOOLS = [
   {
     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.",
+    description: "Resolve compact Brownfield/Essence task-time context for a route or page before editing. Returns route, section, page pack, directives, local law, behavior obligations, style bridge mappings, typed graph context, health evidence, and local screenshot references when available.",
     inputSchema: {
       type: "object",
       properties: {
@@ -3237,7 +3269,9 @@ async function handleTool(name, args) {
         const capsule = readJsonIfExists(capsulePath);
         const graphFreshness = inspectMcpGraphFreshness(projectRoot);
         const projectConfig = readJsonIfExists(join2(projectRoot, ".decantr", "project.json"));
-        const localPatternsPresent = existsSync(join2(projectRoot, ".decantr", "local-patterns.json"));
+        const localPatternsPresent = existsSync(
+          join2(projectRoot, ".decantr", "local-patterns.json")
+        );
         const localRulesPresent = existsSync(join2(projectRoot, ".decantr", "rules.json"));
         const styleBridgePresent = existsSync(join2(projectRoot, ".decantr", "style-bridge.json"));
         const hasGraphArtifacts = existsSync(snapshotPath) && snapshotHistoryPresent && existsSync(manifestPath) && existsSync(diffPath) && existsSync(capsulePath);
@@ -4864,7 +4898,7 @@ function describeUpdate(operation, payload) {
 }
 
 // src/index.ts
-var VERSION = "3.0.0-next.0";
+var VERSION = "3.0.1";
 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-IB5HP7DE.js";
+import "./chunk-PFLHZF35.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decantr/mcp-server",
-  "version": "3.0.0-next.0",
+  "version": "3.0.1",
   "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": [
@@ -44,17 +44,17 @@
     "dist"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=20.19.0"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@decantr/core": "3.0.0-next.0",
-    "@decantr/verifier": "3.0.0-next.0",
-    "@decantr/registry": "3.0.0-next.0",
-    "@decantr/essence-spec": "3.0.0-next.0"
+    "@decantr/core": "3.0.1",
+    "@decantr/verifier": "3.0.1",
+    "@decantr/essence-spec": "3.0.1",
+    "@decantr/registry": "3.0.1"
   },
   "scripts": {
     "build": "tsup",