# @decantr/mcp-server

[![npm version](https://img.shields.io/npm/v/@decantr/mcp-server?style=flat-square)](https://www.npmjs.com/package/@decantr/mcp-server)
[![npm downloads](https://img.shields.io/npm/dm/@decantr/mcp-server?style=flat-square)](https://www.npmjs.com/package/@decantr/mcp-server)
[![license](https://img.shields.io/npm/l/@decantr/mcp-server?style=flat-square)](./LICENSE)
[![MCP compatible](https://img.shields.io/badge/MCP-compatible-0096FF?style=flat-square)](https://modelcontextprotocol.io)

Support status: `core-supported`  
Release channel: `stable`

Design intelligence for AI-generated UI. Make Claude, Cursor, and Windsurf generate better code.

![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, component specs, Brownfield/Hybrid authority, local law, and 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

## 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"]
    }
  }
}
```

### VS Code

Create `.vscode/mcp.json` in your workspace (or add to your user profile `mcp.json`):

```json
{
  "servers": {
    "decantr": {
      "command": "npx",
      "args": ["-y", "@decantr/mcp-server"]
    }
  }
}
```

MCP tools are available in VS Code Copilot Chat agent mode.

### Zed

Add to your Zed `settings.json`:

```json
{
  "context_servers": {
    "decantr": {
      "command": "npx",
      "args": ["-y", "@decantr/mcp-server"],
      "env": {}
    }
  }
}
```

### Continue.dev

Create `.continue/mcpServers/decantr.yaml` in your workspace:

```yaml
name: Decantr MCP Server
version: 0.0.1
schema: v1
mcpServers:
  - name: Decantr
    type: stdio
    command: npx
    args:
      - "-y"
      - "@decantr/mcp-server"
```

MCP tools are only available in Continue.dev agent mode.

## Key Tools

The server exposes Decantr registry, context, benchmark, and verification tools. Highlights:

| 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, themes, and shells | `{ "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_blueprint` | Get a full app composition with page structure and personality traits | `{ "id": "ecommerce" }` |
| `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, authority lane, local law, style bridge mappings, evidence, and changed-file impact before editing a Brownfield, Hybrid, 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" }` |
| `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.

## Security And Permissions

The MCP server reads Decantr files and selected project files from the active workspace. Write access is limited to explicit write tools such as `decantr_update_essence` and `decantr_accept_drift`, and 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).

## Compatibility

`@decantr/mcp-server` is stable in the `2.x` line for the documented MCP tool surface.

- new tools may be added in compatible releases
- existing documented tool names and envelopes should not break without a major version
- breaking changes to established tool contracts require a major version and migration note

## 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 visual treatments 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_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_prepare_task_context` -- resolves route-local Brownfield/Hybrid context, active authority, accepted local law, accepted style bridge mappings, changed-file impact, 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.

## License

MIT
