coss-ui-mcp

# 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).