@decantr/mcp-server 1.0.0-beta.1

package/README.md

@@ -0,0 +1,96 @@
+# @decantr/mcp-server
+
+Design intelligence for AI-generated UI. Make Claude, Cursor, and Windsurf generate better code.
+
+- **Structured design context** -- gives your AI assistant patterns, layouts, and component specs instead of letting it guess
+- **Drift detection** -- catches when generated code deviates from your design intent
+- **Zero config** -- run with `npx`, no API keys or accounts required
+
+## Quick Setup
+
+### Claude Desktop
+
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "decantr": {
+      "command": "npx",
+      "args": ["@decantr/mcp-server"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The Decantr tools will appear automatically.
+
+### Cursor
+
+Create `.cursor/mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "decantr": {
+      "command": "npx",
+      "args": ["@decantr/mcp-server"]
+    }
+  }
+}
+```
+
+Restart Cursor. The tools are available in Agent mode.
+
+### Windsurf
+
+Add to your Windsurf MCP config (`~/.windsurf/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "decantr": {
+      "command": "npx",
+      "args": ["@decantr/mcp-server"]
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Description | Example Input |
+|------|-------------|---------------|
+| `decantr_create_essence` | Generate an Essence spec skeleton from a project description | `{ "description": "SaaS dashboard with analytics and billing", "framework": "react" }` |
+| `decantr_read_essence` | Read the current `decantr.essence.json` from the working directory | `{}` or `{ "path": "./custom.essence.json" }` |
+| `decantr_validate` | Validate an Essence file against the schema and guard rules | `{ "path": "./decantr.essence.json" }` |
+| `decantr_search_registry` | Search the community registry for patterns, archetypes, recipes, and styles | `{ "query": "kanban", "type": "pattern" }` |
+| `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_recipe` | Get recipe decoration rules: shell styles, spatial hints, visual effects | `{ "id": "auradecantism" }` |
+| `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_check_drift` | Check if generated code violates the design intent in the Essence spec | `{ "page_id": "overview", "components_used": ["Card", "LineChart"], "theme_used": "auradecantism" }` |
+
+## How It Works
+
+An Essence spec (`decantr.essence.json`) captures your design intent -- archetype, theme, page structure, patterns, and guard rules -- in a single declarative file. The MCP server exposes this spec and the Decantr registry to your AI assistant, giving it concrete layout specs, component lists, and decoration rules instead of relying on the model's generic training data. The result is generated code that follows a coherent design system, and drift detection that catches deviations before they ship.
+
+## Example Workflow
+
+**Prompt:** "Build me a SaaS dashboard with user analytics, a data table of recent signups, and a settings page."
+
+The AI assistant calls these tools behind the scenes:
+
+1. `decantr_create_essence` -- generates a spec skeleton matched to the `saas-dashboard` archetype
+2. `decantr_resolve_archetype` -- pulls default pages, layouts, and features for a SaaS dashboard
+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_resolve_recipe` -- loads decoration rules (spacing, borders, effects) for the theme
+6. `decantr_check_drift` -- validates the generated code against the Essence spec before presenting it
+
+The AI now generates code with the right layout structure, correct components, and consistent styling -- not a generic guess.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/index.js

@@ -0,0 +1,510 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+
+// src/tools.ts
+import { readFile } from "fs/promises";
+import { join as join2 } from "path";
+import { validateEssence, evaluateGuard } from "@decantr/essence-spec";
+import { createRegistryClient, resolvePatternPreset } from "@decantr/registry";
+
+// src/helpers.ts
+import { createResolver } from "@decantr/registry";
+import { join } from "path";
+var MAX_INPUT_LENGTH = 1e3;
+function validateStringArg(args, field) {
+  const val = args[field];
+  if (!val || typeof val !== "string") {
+    return `Required parameter "${field}" must be a non-empty string.`;
+  }
+  if (val.length > MAX_INPUT_LENGTH) {
+    return `Parameter "${field}" exceeds maximum length of ${MAX_INPUT_LENGTH} characters.`;
+  }
+  return null;
+}
+var _resolver = null;
+function getResolver() {
+  if (!_resolver) {
+    const envRoot = process.env.DECANTR_CONTENT_ROOT;
+    const bundledRoot = join(import.meta.dirname, "..", "..", "..", "content");
+    const npmRoot = join(process.cwd(), "node_modules", "@decantr", "content");
+    _resolver = createResolver({
+      contentRoot: envRoot || bundledRoot,
+      overridePaths: envRoot ? [] : [npmRoot]
+    });
+  }
+  return _resolver;
+}
+
+// src/tools.ts
+var READ_ONLY = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false
+};
+var TOOLS = [
+  {
+    name: "decantr_read_essence",
+    title: "Read Essence",
+    description: "Read and return the current decantr.essence.json file from the working directory.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Optional path to essence file. Defaults to ./decantr.essence.json." }
+      }
+    },
+    annotations: READ_ONLY
+  },
+  {
+    name: "decantr_validate",
+    title: "Validate Essence",
+    description: "Validate a decantr.essence.json file against the schema and guard rules. Returns errors and warnings.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Path to essence file. Defaults to ./decantr.essence.json." }
+      }
+    },
+    annotations: READ_ONLY
+  },
+  {
+    name: "decantr_search_registry",
+    title: "Search Registry",
+    description: "Search the Decantr community content registry for patterns, archetypes, recipes, and styles.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: 'Search query (e.g. "kanban", "neon", "dashboard")' },
+        type: { type: "string", description: "Filter by type: pattern, archetype, recipe, style" }
+      },
+      required: ["query"]
+    },
+    annotations: READ_ONLY
+  },
+  {
+    name: "decantr_resolve_pattern",
+    title: "Resolve Pattern",
+    description: "Get full pattern details including layout spec, components, presets, and code examples.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: 'Pattern ID (e.g. "hero", "data-table", "kpi-grid")' },
+        preset: { type: "string", description: 'Optional preset name (e.g. "product", "content")' }
+      },
+      required: ["id"]
+    },
+    annotations: READ_ONLY
+  },
+  {
+    name: "decantr_resolve_archetype",
+    title: "Resolve Archetype",
+    description: "Get archetype details including default pages, layouts, features, and suggested theme.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: 'Archetype ID (e.g. "saas-dashboard", "ecommerce")' }
+      },
+      required: ["id"]
+    },
+    annotations: READ_ONLY
+  },
+  {
+    name: "decantr_resolve_recipe",
+    title: "Resolve Recipe",
+    description: "Get recipe decoration rules including shell styles, spatial hints, visual effects, and pattern preferences.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: 'Recipe ID (e.g. "auradecantism")' }
+      },
+      required: ["id"]
+    },
+    annotations: READ_ONLY
+  },
+  {
+    name: "decantr_resolve_blueprint",
+    title: "Resolve Blueprint",
+    description: "Get a blueprint (app composition) with its archetype list, suggested theme, personality traits, and full page structure.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: 'Blueprint ID (e.g. "saas-dashboard", "ecommerce", "portfolio")' }
+      },
+      required: ["id"]
+    },
+    annotations: READ_ONLY
+  },
+  {
+    name: "decantr_suggest_patterns",
+    title: "Suggest Patterns",
+    description: "Given a page description, suggest appropriate patterns from the registry. Returns ranked pattern matches with layout specs and component lists.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        description: { type: "string", description: 'Description of the page or section (e.g. "dashboard with metrics and charts", "settings form with toggles")' }
+      },
+      required: ["description"]
+    },
+    annotations: READ_ONLY
+  },
+  {
+    name: "decantr_check_drift",
+    title: "Check Drift",
+    description: "Check if code changes violate the design intent captured in the Essence spec. Returns guard rule violations with severity and fix suggestions.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Path to essence file. Defaults to ./decantr.essence.json." },
+        page_id: { type: "string", description: 'Page ID being modified (e.g. "overview", "settings")' },
+        components_used: {
+          type: "array",
+          items: { type: "string" },
+          description: "List of component names used in the generated code"
+        },
+        theme_used: { type: "string", description: "Theme/style name used in the generated code" }
+      }
+    },
+    annotations: READ_ONLY
+  },
+  {
+    name: "decantr_create_essence",
+    title: "Create Essence",
+    description: "Generate a valid Essence spec skeleton from a project description. Returns a structured essence.json template based on the closest matching archetype and blueprint.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        description: { type: "string", description: 'Natural language project description (e.g. "SaaS dashboard with analytics, user management, and billing")' },
+        framework: { type: "string", description: 'Target framework (e.g. "react", "vue", "svelte"). Defaults to "react".' }
+      },
+      required: ["description"]
+    },
+    annotations: READ_ONLY
+  }
+];
+async function handleTool(name, args) {
+  switch (name) {
+    case "decantr_read_essence": {
+      const essencePath = args.path || join2(process.cwd(), "decantr.essence.json");
+      try {
+        const raw = await readFile(essencePath, "utf-8");
+        return JSON.parse(raw);
+      } catch (e) {
+        return { error: `Could not read essence file: ${e.message}` };
+      }
+    }
+    case "decantr_validate": {
+      const essencePath = args.path || join2(process.cwd(), "decantr.essence.json");
+      let essence;
+      try {
+        essence = JSON.parse(await readFile(essencePath, "utf-8"));
+      } catch (e) {
+        return { valid: false, errors: [`Could not read: ${e.message}`], guardViolations: [] };
+      }
+      const result = validateEssence(essence);
+      let guardViolations = [];
+      if (result.valid && typeof essence === "object" && essence !== null) {
+        try {
+          guardViolations = evaluateGuard(essence, {});
+        } catch {
+        }
+      }
+      return { ...result, guardViolations };
+    }
+    case "decantr_search_registry": {
+      const err = validateStringArg(args, "query");
+      if (err) return { error: err };
+      try {
+        const client = createRegistryClient();
+        const results = await client.search(args.query, args.type);
+        return {
+          total: results.length,
+          results: results.map((r) => ({
+            type: r.type,
+            id: r.id,
+            name: r.name,
+            description: r.description,
+            install: `decantr registry add ${r.type}/${r.id}`
+          }))
+        };
+      } catch (e) {
+        return { error: `Search failed: ${e.message}` };
+      }
+    }
+    case "decantr_resolve_pattern": {
+      const err = validateStringArg(args, "id");
+      if (err) return { error: err };
+      const resolver = getResolver();
+      const resolved = await resolver.resolve("pattern", args.id);
+      if (!resolved) {
+        return { found: false, message: `Pattern "${args.id}" not found.` };
+      }
+      const result = { found: true, ...resolved.item };
+      if (args.preset && typeof args.preset === "string") {
+        const preset = resolvePatternPreset(resolved.item, args.preset);
+        if (preset) result.resolvedPreset = preset;
+      }
+      return result;
+    }
+    case "decantr_resolve_archetype": {
+      const err = validateStringArg(args, "id");
+      if (err) return { error: err };
+      const resolver = getResolver();
+      const resolved = await resolver.resolve("archetype", args.id);
+      if (!resolved) {
+        return { found: false, message: `Archetype "${args.id}" not found.` };
+      }
+      return { found: true, ...resolved.item };
+    }
+    case "decantr_resolve_recipe": {
+      const err = validateStringArg(args, "id");
+      if (err) return { error: err };
+      const resolver = getResolver();
+      const resolved = await resolver.resolve("recipe", args.id);
+      if (!resolved) {
+        return { found: false, message: `Recipe "${args.id}" not found.` };
+      }
+      return { found: true, ...resolved.item };
+    }
+    case "decantr_resolve_blueprint": {
+      const err = validateStringArg(args, "id");
+      if (err) return { error: err };
+      const resolver = getResolver();
+      const resolved = await resolver.resolve("blueprint", args.id);
+      if (!resolved) {
+        return { found: false, message: `Blueprint "${args.id}" not found.` };
+      }
+      return { found: true, ...resolved.item };
+    }
+    case "decantr_suggest_patterns": {
+      const err = validateStringArg(args, "description");
+      if (err) return { error: err };
+      const desc = args.description.toLowerCase();
+      const resolver = getResolver();
+      const patternIds = [
+        "hero",
+        "kpi-grid",
+        "data-table",
+        "card-grid",
+        "chart-grid",
+        "filter-bar",
+        "form-sections",
+        "detail-header",
+        "activity-feed",
+        "cta-section"
+      ];
+      const suggestions = [];
+      for (const id of patternIds) {
+        const resolved = await resolver.resolve("pattern", id);
+        if (!resolved) continue;
+        const p = resolved.item;
+        const searchable = [
+          p.name || "",
+          p.description || "",
+          ...p.components || [],
+          ...p.tags || []
+        ].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(id)) score += 20;
+        if (desc.includes("metric") && id === "kpi-grid") score += 15;
+        if (desc.includes("chart") && id === "chart-grid") score += 15;
+        if (desc.includes("table") && id === "data-table") score += 15;
+        if (desc.includes("form") && id === "form-sections") score += 15;
+        if (desc.includes("setting") && id === "form-sections") score += 15;
+        if (desc.includes("landing") && ["hero", "cta-section", "card-grid"].includes(id)) score += 20;
+        if (desc.includes("hero") && id === "hero") score += 20;
+        if (desc.includes("ecommerce") && ["card-grid", "filter-bar", "detail-header"].includes(id)) score += 15;
+        if (desc.includes("product") && id === "card-grid") score += 15;
+        if (desc.includes("feed") && id === "activity-feed") score += 15;
+        if (desc.includes("filter") && id === "filter-bar") score += 15;
+        if (desc.includes("search") && id === "filter-bar") score += 10;
+        if (score > 0) {
+          const preset = p.presets && typeof p.presets === "object" ? Object.values(p.presets)[0] : null;
+          suggestions.push({
+            id,
+            score,
+            name: p.name || id,
+            description: p.description || "",
+            components: p.components || [],
+            layout: preset?.layout ? preset.layout.layout || "grid" : "grid"
+          });
+        }
+      }
+      suggestions.sort((a, b) => b.score - a.score);
+      return {
+        query: args.description,
+        suggestions: suggestions.slice(0, 5),
+        total: suggestions.length
+      };
+    }
+    case "decantr_check_drift": {
+      const essencePath = args.path || join2(process.cwd(), "decantr.essence.json");
+      let essence;
+      try {
+        essence = JSON.parse(await readFile(essencePath, "utf-8"));
+      } catch (e) {
+        return { error: `Could not read essence: ${e.message}` };
+      }
+      const validation = validateEssence(essence);
+      if (!validation.valid) {
+        return { drifted: true, reason: "invalid_essence", errors: validation.errors };
+      }
+      const violations = [];
+      if (args.theme_used && typeof args.theme_used === "string") {
+        const expectedTheme = essence.theme;
+        if (expectedTheme?.style && args.theme_used !== expectedTheme.style) {
+          violations.push({
+            rule: "theme-match",
+            severity: "critical",
+            message: `Theme drift: code uses "${args.theme_used}" but Essence specifies "${expectedTheme.style}". Do not switch themes.`
+          });
+        }
+      }
+      if (args.page_id && typeof args.page_id === "string") {
+        const structure = essence.structure;
+        if (structure && !structure.find((p) => p.id === args.page_id)) {
+          violations.push({
+            rule: "page-exists",
+            severity: "critical",
+            message: `Page "${args.page_id}" not found in Essence structure. Add it to the Essence before generating code for it.`
+          });
+        }
+      }
+      try {
+        const guardViolations = evaluateGuard(essence, {
+          pageId: args.page_id
+        });
+        for (const gv of guardViolations) {
+          violations.push({
+            rule: gv.rule || "guard",
+            severity: gv.severity || "warning",
+            message: gv.message || "Guard violation"
+          });
+        }
+      } catch {
+      }
+      return {
+        drifted: violations.length > 0,
+        violations,
+        checkedAgainst: essencePath
+      };
+    }
+    case "decantr_create_essence": {
+      const err = validateStringArg(args, "description");
+      if (err) return { error: err };
+      const desc = args.description.toLowerCase();
+      const framework = args.framework || "react";
+      const archetypeScores = [];
+      const archetypeIds = [
+        "saas-dashboard",
+        "ecommerce",
+        "portfolio",
+        "content-site",
+        "financial-dashboard",
+        "cloud-platform",
+        "gaming-platform",
+        "ecommerce-admin",
+        "workbench"
+      ];
+      const resolver = getResolver();
+      for (const id of archetypeIds) {
+        let score = 0;
+        if (desc.includes("dashboard") && id.includes("dashboard")) score += 20;
+        if (desc.includes("saas") && id.includes("saas")) score += 20;
+        if (desc.includes("ecommerce") && id.includes("ecommerce")) score += 20;
+        if (desc.includes("shop") && id.includes("ecommerce")) score += 15;
+        if (desc.includes("portfolio") && id.includes("portfolio")) score += 20;
+        if (desc.includes("blog") && id.includes("content")) score += 15;
+        if (desc.includes("content") && id.includes("content")) score += 15;
+        if (desc.includes("finance") && id.includes("financial")) score += 20;
+        if (desc.includes("cloud") && id.includes("cloud")) score += 15;
+        if (desc.includes("game") && id.includes("gaming")) score += 15;
+        if (desc.includes("admin") && id.includes("admin")) score += 15;
+        if (desc.includes("analytics") && id.includes("dashboard")) score += 10;
+        if (desc.includes("tool") && id === "workbench") score += 10;
+        if (score > 0) archetypeScores.push({ id, score });
+      }
+      archetypeScores.sort((a, b) => b.score - a.score);
+      const bestMatch = archetypeScores[0]?.id || "saas-dashboard";
+      const archetypeResult = await resolver.resolve("archetype", bestMatch);
+      const archetype = archetypeResult?.item;
+      const pages = archetype?.pages;
+      const structure = (pages || [{ id: "home", shell: "full-bleed", default_layout: ["hero"] }]).map((p) => ({
+        id: p.id,
+        shell: p.shell || "sidebar-main",
+        layout: p.default_layout || []
+      }));
+      const essence = {
+        version: "2.0.0",
+        archetype: bestMatch,
+        theme: {
+          style: "auradecantism",
+          mode: "dark",
+          recipe: "auradecantism",
+          shape: "rounded"
+        },
+        personality: ["professional"],
+        platform: { type: "spa", routing: "hash" },
+        structure,
+        features: archetype?.features || [],
+        guard: { enforce_style: true, enforce_recipe: true, mode: "strict" },
+        density: { level: "comfortable", content_gap: "_gap4" },
+        target: framework,
+        _generated: {
+          matched_archetype: bestMatch,
+          confidence: archetypeScores[0]?.score || 0,
+          alternatives: archetypeScores.slice(1, 4).map((a) => a.id),
+          description: args.description
+        }
+      };
+      return {
+        essence,
+        archetype: bestMatch,
+        instructions: `Save this as decantr.essence.json in your project root. Review the structure (pages, patterns) and adjust to match your needs. The guard rules will validate your code against this spec.`
+      };
+    }
+    default:
+      return { error: `Unknown tool: ${name}` };
+  }
+}
+
+// src/index.ts
+var VERSION = "0.1.0";
+var server = new Server(
+  { name: "decantr", version: VERSION },
+  { capabilities: { tools: {} } }
+);
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return { tools: TOOLS };
+});
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  try {
+    const result = await handleTool(name, args ?? {});
+    const response = {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+    };
+    if (result && typeof result === "object" && "error" in result) {
+      response.isError = true;
+    }
+    return response;
+  } catch (err) {
+    return {
+      content: [{ type: "text", text: JSON.stringify({ error: err.message }) }],
+      isError: true
+    };
+  }
+});
+var transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@decantr/mcp-server",
+  "version": "1.0.0-beta.1",
+  "description": "MCP server for Decantr — exposes design intelligence tools to AI coding assistants",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/decantr-ai/decantr.git",
+    "directory": "packages/mcp-server"
+  },
+  "homepage": "https://decantr.ai",
+  "type": "module",
+  "bin": {
+    "decantr-mcp": "./dist/index.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@decantr/essence-spec": "workspace:*",
+    "@decantr/registry": "workspace:*"
+  }
+}