@decantr/mcp-server 2.1.0 → 2.2.0

package/README.md

@@ -12,7 +12,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
+- **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
@@ -133,9 +133,10 @@ 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" }` |
@@ -170,12 +171,13 @@ 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
-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
+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.
 

package/dist/bin.js

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

package/dist/{chunk-FEXPLJKB.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") {
@@ -490,7 +536,10 @@ function mcpStatusFromCounts(counts) {
   return "healthy";
 }
 function mcpScoreFromCounts(counts) {
-  return Math.max(0, Math.min(100, 100 - counts.errorCount * 15 - counts.warnCount * 5 - counts.infoCount));
+  return Math.max(
+    0,
+    Math.min(100, 100 - counts.errorCount * 15 - counts.warnCount * 5 - counts.infoCount)
+  );
 }
 function mcpCommandsForFinding(source) {
   switch (source) {
@@ -507,7 +556,11 @@ function mcpCommandsForFinding(source) {
     case "interaction":
       return ["decantr check --strict", "decantr health"];
     case "pack":
-      return ["decantr refresh", "decantr registry get-pack review --write-context", "decantr health"];
+      return [
+        "decantr refresh",
+        "decantr registry get-pack review --write-context",
+        "decantr health"
+      ];
     case "runtime":
       return ["npm run build", "decantr health"];
     default:
@@ -908,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"]
@@ -1105,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",
@@ -1506,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}` };
@@ -2251,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");
@@ -2747,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-FEXPLJKB.js";
+import "./chunk-SVLMT45O.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decantr/mcp-server",
-  "version": "2.1.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": [
@@ -50,8 +50,8 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@decantr/essence-spec": "2.0.1",
-    "@decantr/verifier": "2.1.0",
-    "@decantr/registry": "2.0.0"
+    "@decantr/verifier": "2.2.0",
+    "@decantr/registry": "2.2.0"
   },
   "scripts": {
     "build": "tsup",