# coss-ui-mcp

A **design-context MCP server** for the [coss ui](https://coss.com/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

```bash
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`:
```json
{
  "mcpServers": {
    "coss-ui": { "command": "node", "args": ["/ABS/PATH/coss-ui-mcp/server.mjs"] }
  }
}
```

**Cursor** — `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):
```json
{
  "mcpServers": {
    "coss-ui": { "command": "node", "args": ["/ABS/PATH/coss-ui-mcp/server.mjs"] }
  }
}
```

**VS Code (GitHub Copilot)** — `.vscode/mcp.json`:
```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

```bash
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](https://base-ui.com) + [Tailwind CSS v4](https://tailwindcss.com), 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](LICENSE). The snapshotted docs in `./data` are sourced from [coss ui](https://github.com/cosscom/coss) (`apps/ui/`), which is [MIT-licensed](https://github.com/cosscom/coss/blob/main/LICENSING.md) (the parent monorepo defaults to AGPLv3, but `apps/ui/` — where the docs and component registry live — is carved out as MIT).