coss-ui-mcp

A design-context MCP server for the coss ui component system — the base you build your apps on.

It does for coss ui what Atlassian's ADS MCP does for their design system: instead of pasting the whole component library into every prompt (expensive, and it goes stale), your coding agent calls tools to fetch only the components, install commands, props, and design tokens it needs, on demand.

• Zero dependencies. Pure JS, only node:* built-ins. No install step — runs on Node 18+, Bun, or Deno.
• Always current. Re-run the sync script any time to re-snapshot the live docs from coss.com/ui.
• Yours to own. Same spirit as coss ui itself — copy, paste, customize.

---

Why on-demand beats a static file

A single big DESIGN.md (or a pasted component list) loads everything, every time — high token cost, slower responses, and context truncation that hurts accuracy. An MCP server loads context on demand: the agent calls coss_plan("a settings page…") to get a shortlist, then coss_get_component("tabs") only for what it's actually building. That's the pattern Atlassian measured as materially cheaper and more accurate than a load-everything file.

---

Tools

Tool	What it does
coss_plan	Describe a screen/feature → ranked component shortlist + install commands + base setup. Start here.
coss_search	Find components/hooks by name, keyword, or use case ("date range picker", "toast").
coss_get_component	Full docs for one component/hook: install (CLI + manual npm deps + CSS tokens), usage, props/API reference, examples.
coss_get_doc	Overview guides: introduction, get-started, styling, roadmap.
coss_theme	The design-token + font system: shadcn-style CSS variables, the extra --info/--success/--warning/--destructive-foreground tokens, --font-*, and the full @theme block. Use to set up or rebrand.
coss_list_components	Cheap catalog of everything (components / hooks / overview).

---

Install

Requires a JS runtime with node:* built-in support — Node 18+, Bun, or Deno. No dependencies.

1. Get the files & snapshot the docs

cd coss-ui-mcp

# with npm (or swap in pnpm/yarn/bun's equivalent "run" syntax)
npm run sync      # downloads the coss ui docs into ./data (re-run to refresh)
npm run smoke     # optional: verifies the server end-to-end

# or invoke the scripts directly with any runtime, no package manager needed
node scripts/sync.mjs
node scripts/smoke.mjs
# bun scripts/sync.mjs / deno run --allow-read --allow-write --allow-net scripts/sync.mjs

pwd               # note this absolute path for the configs below

The package ships with a ./data snapshot already, so it works offline out of the box. Run sync whenever coss ui updates.

2. Point your agent at it (stdio)

Replace /ABS/PATH with the path from pwd.

Claude Code — .mcp.json (project root) or claude mcp add:

{
  "mcpServers": {
    "coss-ui": { "command": "node", "args": ["/ABS/PATH/coss-ui-mcp/server.mjs"] }
  }
}

Cursor — ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{
  "mcpServers": {
    "coss-ui": { "command": "node", "args": ["/ABS/PATH/coss-ui-mcp/server.mjs"] }
  }
}

VS Code (GitHub Copilot) — .vscode/mcp.json:

{
  "servers": {
    "coss-ui": { "type": "stdio", "command": "node", "args": ["/ABS/PATH/coss-ui-mcp/server.mjs"] }
  }
}

Claude Desktop — claude_desktop_config.json (Settings → Developer → Edit Config): same mcpServers shape as Claude Code.

"command": "node" above is just the default — swap in "bun" or "deno" (with "args": ["run", "--allow-read", "/ABS/PATH/coss-ui-mcp/server.mjs"]) if that's your runtime of choice. No package manager is required to run the server itself. (sync.mjs additionally needs network + write access to re-snapshot the docs.)

Restart the client, and you should see the coss_* tools available.

3. Use it

Just prompt normally — the agent will call the tools:

"Build a billing settings page with coss ui. Plan the components first, then use the real props."

A good agent will call coss_plan → coss_get_component for each → coss_theme, and generate code that uses your actual components and tokens instead of generic "slop".

---

Keep it fresh

npm run sync
# or: node scripts/sync.mjs   (works with any package manager, or none at all)

Re-downloads coss.com/ui/llms.txt and every referenced .md, rebuilds data/index.json. Diff data/meta.json to see what changed. (Two upstream links — radix-shadcn-migration and sidebar — currently 404 and are skipped automatically.)

---

Make it your design system

You build off coss ui as a starting point — so extend this to encode your conventions:

1. Rebrand tokens. Keep the CSS variable names, change their values in globals.css. Ask the agent: "call coss_theme, then give me a globals.css in a deep-navy brand palette." Every component updates at once.
2. Add your own components. Drop extra .md files into data/docs/components/ (same frontmatter shape: title, description, an ## Installation block) and add matching entries to data/index.json. They'll show up in search/plan immediately — your in-house patterns become first-class context.
3. Add house rules. Extend coss_get_doc (or add a coss_conventions tool in server.mjs) that returns your do/don't guidance — spacing scale, when to use Dialog vs Sheet, form patterns. This is where a generic system becomes your system.
4. Ship a DESIGN.md too. For blue-sky prototyping in tools that don't speak MCP, generate a portable DESIGN.md from the same data. MCP for daily driving (cheap, on-demand); DESIGN.md for portability.

---

Files

coss-ui-mcp/
├─ server.mjs          # the MCP server (stdio, zero deps)
├─ scripts/
│  ├─ sync.mjs         # snapshot coss.com/ui docs -> ./data
│  └─ smoke.mjs        # drive the server like a real MCP client
├─ data/
│  ├─ index.json       # catalog: slug, name, description, install, tokens, keywords
│  ├─ meta.json        # sync timestamp + counts
│  └─ docs/**/*.md      # snapshotted component/hook/overview markdown
├─ package.json
└─ README.md

How it works (30s)

server.mjs speaks MCP's stdio transport directly — newline-delimited JSON-RPC 2.0 on stdin/stdout (initialize, tools/list, tools/call). It loads data/index.json at startup and reads individual markdown docs from disk only when a tool asks for them. That's the whole trick: cheap discovery, on-demand detail.

coss ui is Base UI + Tailwind CSS v4, shadcn-CLI compatible via the @coss/* registry. This server doesn't reimplement any of that — it just makes the official docs legible to your agent.

License

MIT — see LICENSE. The snapshotted docs in ./data are sourced from coss ui (apps/ui/), which is MIT-licensed (the parent monorepo defaults to AGPLv3, but apps/ui/ — where the docs and component registry live — is carved out as MIT).