@urbicon-ui/mcp-server

Model Context Protocol server for the Urbicon UI design system. Gives LLMs first-class access to the component catalog, design tokens, recipes, and implementation guidance.

Status (Option B, 2026-07-10): built, green, not advertised. The consumer-facing surface is the urbicon CLI in @urbicon-ui/design — one dev-dependency, version-pinned, covers the full knowledge/judgment/memory surface locally. This server is the thin remote adapter over the same engine (@urbicon-ui/design-engine) and content bundle (@urbicon-ui/design-content), kept for the launch decision of hosting a public endpoint (evaluation/reach: "point your agent at Urbicon without installing anything"). It is deliberately absent from the public docs until that endpoint exists, and a local install is not a supported consumer path: manifest read/write is a working-directory concern and lives in the CLI, so a locally installed copy of this stateless server would offer strictly less than the dev-dependency it duplicates.

Transports: stdio (default, for in-repo development) and streamable HTTP (the intended remote deployment).

Installation

This package ships inside the Urbicon UI monorepo. Install from repo root:

bun install

Runtime dependencies: @modelcontextprotocol/sdk, zod.

Bun is required (declared via engines.bun). package.json#main points at ./src/index.ts directly — there is no build or transpilation step, and deliberately no bin: the server is launched via bun run (see Quick Start), in-repo, with the hosted HTTP endpoint as the only planned deployment. Node-only setups (npm i -g, npx) will not work. If a local-install consumer path ever becomes supported, the launch decision reintroduces a dist build plus a node-runnable bin.

Quick Start

Stdio (IDE integration)

From the repo root:

bun run mcp:start

Or directly:

bun run packages/mcp-server/src/index.ts

HTTP (remote)

bun run mcp:start:http
# listens on http://localhost:3001 with streamable transport

Connect from Claude Code

Add to ~/.claude/mcp.json (or project .claude/mcp.json):

{
  "mcpServers": {
    "urbicon-ui": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/urbicon-ui/packages/mcp-server/src/index.ts"]
    }
  }
}

For Cursor: see Cursor's MCP docs.

Tools

All tools are read-only (readOnlyHint: true) — this server never touches the consumer's filesystem. Queries are Zod-validated. (Manifest read/write moved to the urbicon CLI in @urbicon-ui/design; a stateless remote server cannot reach a consumer's repo.)

| Tool | Purpose | | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | find_components | Fuzzy search across component names, tags, and descriptions. Filterable by package (blocks, table, auth). A hit needs a whole, distinctive query word, or two ordinary ones meeting on one component: when none lands, the answer is "no components found" plus the weak near misses that still scored, which are also listed beside the matches when one of them outranks the lot. | | get_component | Full per-component documentation: props, variants, slots, examples, source link. Optional section argument for streamed chunks (overview / examples / variants / api / slots). | | get_recipe | Full production-ready recipe (login-form, dashboard, settings-page, etc.) with component tree, code, and notes. | | suggest_implementation | Takes a natural-language goal and returns a component-tree suggestion, relevant recipes, Style-Patterns guide, and the implementation checklist. | | get_implementation_checklist | Design-Quality checklist (visual weight, intent semantics, spacing, radius, data-driven styling, dominance, identity) — embedded directly so the LLM can self-verify. | | get_css_reference | Full token reference — surface, text, border, intent, feedback tokens, radii, z-index. Includes an explicit "do not invent tokens" guardrail. | | find_icons | Browse the 315-icon catalog by keyword, category, or name. | | get_design_principles | Design heuristics (Layer 5): visual hierarchy, interaction, component selection, layout, accessibility, theming (paradigms, change decision tree). Call first when generating UI. as="rubric" returns the 8-criterion 1–5 scoring rubric for judging a generated UI. | | get_pattern | Composition patterns (Layer 4) for page archetypes. Call it without a name to list what the bundle ships. | | validate_design | Lint generated markup on two axes — correctness (raw colours, dark:/focus: misuse, hardcoded z-index, broken dynamic classes, hallucinated tokens, foreign-library component APIs, unlabelled icon buttons; the blocking gate) and the craft axis (20 system-agnostic "looks generic" heuristics: generic fonts, animated dimensions, grey-on-colour, touch targets, …; advisory). Returns a correctness score + a craft score and per-finding fixes for a generate → validate → fix loop. |

Resources

| URI | Purpose | | -------------------------------- | -------------------------------------------------------------------------------------------------- | | urbicon://catalog | Full component catalog in Markdown — used as the LLM's default context | | urbicon://guide/api-grammar | Canonical prop conventions (intent, variant, size, callbacks) | | urbicon://guide/design-quality | AVOID/INSTEAD design-quality patterns — spacing, hierarchy, colour and shape discipline | | urbicon://guide/component-families | Six-family component taxonomy - ARIA roles and per-family border-token source | | urbicon://guide/customization | unstyled / slotClasses / preset override system + BlocksProvider overrides | | urbicon://guide/auth | Complete auth reference - served verbatim from the bundled, tarball-canonical AUTH.md | | urbicon://guide/style-patterns | Reusable style presets and composition templates | | urbicon://guide/tokens | OKLCH token reference, same data as get_css_reference |

Prompts

The full design-verb table (DESIGN-MCP-V2 §8) — client-agnostic workflows you invoke from any MCP client to run a multi-step recipe over the four design planes rather than a single-shot generation. Each recipe is the same text the local @urbicon-ui/design skill ships (single source, bundled via @urbicon-ui/design-content): it opens by reading the project's design.manifest.md, does the work through the read-only tools above, and closes by writing the decision back.

| Prompt | Arguments | Purpose | | ---------- | ------------------------------ | ------------------------------------------------------------------------------------------ | | onboard | brief? | Greenfield: interview product intent + intake, seed the manifest. | | adopt | brief? | Brownfield: infer the design language from code, measure drift, seed the manifest. | | compose | brief?, variants? | New page via generate → validate → judge → synthesise (variants + rubric + linter gate). | | redesign | brief?, code?, variants? | Diagnose with linter + rubric, fix exactly the flagged weaknesses, preserve behaviour. | | polish | brief?, code? | Small token-level fixes that raise the craft score without restructuring. | | critique | brief?, code? | Judge without changing: correctness + craft + rubric → a prioritised, verb-tagged fix-list. | | fix | brief?, code? | Repair correctness defects (raw colours, dark:/focus:, z-index, hallucinated tokens). | | retheme | brief? | Rebrand: change the token layer once, propagate across every affected file. | | audit | brief? | App-wide sweep: validate the tree, check pattern cohorts, report drift over time. | | migrate | brief? | Roll out a pattern/library change across every site, gated per file. |

Server Options

The entry point is run via Bun (no installed binary):

bun run src/index.ts [--transport <stdio|http>] [--port <n>] [--content-dir <path>]

| Flag | Default | Purpose | | --------------- | ------------- | -------------------------------------------------------------- | | --transport | stdio | Transport mode | | --port | 3001 | HTTP port (ignored for stdio) | | --content-dir | auto-discover | Override the design-content bundle dir (URBICON_CONTENT_DIR) |

Architecture

src/
├── index.ts                 CLI entry + arg parsing, pre-loads catalog/templates/principles
├── server.ts                MCP server construction (registers resources + tools)
├── transports/
│   ├── stdio.ts             Stdio transport
│   └── http.ts              Streamable HTTP transport (per-session)
├── tools/                   10 tools, each self-contained
│                            (validate_design calls @urbicon-ui/design-engine)
├── resources/               Catalog + guide resources
├── data/                    Loaders with in-process caching (read the design-content bundle)
│   ├── catalog-loader.ts    component-catalog.json (components + recipes)
│   ├── template-loader.ts   guide template sections
│   ├── design-system-loader.ts  principles.md + patterns/*.md
│   ├── component-loader.ts  per-component llm.txt
│   └── icon-loader.ts       icons.json
└── utils/                   search, format-catalog

The server reads its data from the version-pinned @urbicon-ui/design-content bundle (built by @urbicon-ui/docs-gen: component-catalog.json with recipes, per-component llm.txt, design-system, guide template, icons.json). That means JSDoc in a component's index.ts is the single source of truth: one edit propagates to the docs site, llms-full.txt, and every MCP tool.

Development

bun --filter='@urbicon-ui/mcp-server' run dev        # watch mode (stdio)
bun --filter='@urbicon-ui/mcp-server' run start      # stdio, one-shot
bun --filter='@urbicon-ui/mcp-server' run start:http # HTTP on port 3001
bun --filter='@urbicon-ui/mcp-server' run check      # tsc --noEmit

Bun runs TypeScript directly — no build step.

Roadmap

Next steps:

• compose_layout — takes natural-language intent and returns a full component tree with props (v1.x)
• llm.json per component — structured, token-efficient sibling of llm.txt (v1.x)

Smoke tests for catalog loading, tool wiring, and fuzzy search are already in place (bunx --bun vitest run in this package).

Related

• @urbicon-ui/docs-gen — produces the catalog and llms.txt files this server reads