内容
# coss-ui-mcp
一款适用于 [coss ui](https://coss.com/ui) 组件系统的**设计上下文 MCP 服务器** — 您构建应用的基础。
它为 coss ui 做的事情类似于 Atlassian 的 ADS MCP 为其设计系统所做的事情：与其将整个组件库粘贴到每个提示中（成本高且容易过时），您的编码代理调用**工具**按需获取所需的组件、安装命令、属性和设计令牌。
- **零依赖。** 纯 JS，仅 `node:*` 内置。不需要安装步骤 — 在 Node 18+、Bun 或 Deno 上运行。
- **始终保持最新。** 随时重新运行 `sync` 脚本，以从 `coss.com/ui` 重新快照实时文档。
- **您可以拥有。** 与 coss ui 本身相同的精神 — 复制、粘贴、自定义。
---
## 为什么按需加载优于静态文件
单个大型的 `DESIGN.md`（或粘贴的组件列表）每次加载*所有内容* — 高令牌成本、较慢的响应和影响准确性的上下文截断。MCP 服务器按需加载上下文：代理调用 `coss_plan("一个设置页面…")` 以获取短列表，然后调用 `coss_get_component("tabs")` 仅获取实际构建所需的内容。这就是 Atlassian 测量的模式，其成本和准确性明显优于加载所有内容的单个文件。
---
## 工具
| 工具 | 功能 |
|------|--------------|
| `coss_plan` | 描述屏幕/功能 → 排名组件短列表 + 安装命令 + 基础设置。**从这里开始。** |
| `coss_search` | 按名称、关键词或用例查找组件/钩子（“日期范围选择器”，“toast”）。 |
| `coss_get_component` | 一个组件/钩子的完整文档：安装（CLI + 手动 npm 依赖 + CSS 令牌）、用法、**属性/API 参考**、示例。 |
| `coss_get_doc` | 概览指南：`introduction`、`get-started`、`styling`、`roadmap`。 |
| `coss_theme` | 设计令牌 + 字体系统：shadcn 样式的 CSS 变量、额外的 `--info/--success/--warning/--destructive-foreground` 令牌、 `--font-*`，以及完整的 `@theme` 块。用于设置或**重新品牌化**。 |
| `coss_list_components` | 所有内容（组件/钩子/概览）的廉价目录。 |
---
## 安装
需要具有 `node:*` 内置支持的 JS 运行时 — **Node 18+**、Bun 或 Deno。无依赖。
### 1. 获取文件并快照文档
```bash
cd coss-ui-mcp
# 使用 npm（或交换为 pnpm/yarn/bun 的等效“run”语法）
npm run sync # 下载 coss ui 文档到 ./data（重新运行以刷新）
npm run smoke # 可选：验证服务器端到端
# 或直接使用任何运行时调用脚本，无需包管理器
node scripts/sync.mjs
node scripts/smoke.mjs
# bun scripts/sync.mjs / deno run --allow-read --allow-write --allow-net scripts/sync.mjs
pwd # 记录以下配置的绝对路径
```
> 包自带 `./data` 快照，因此开箱即用。运行 `sync` 只要 coss ui 更新即可。
### 2. 将您的代理指向它（stdio）
替换 `/ABS/PATH` 为 `pwd` 的路径。
**Claude Code** — `.mcp.json`（项目根目录）或 `claude mcp add`：
```json
{
"mcpServers": {
"coss-ui": { "command": "node", "args": ["/ABS/PATH/coss-ui-mcp/server.mjs"] }
}
}
```
**Cursor** — `~/.cursor/mcp.json`（全局）或 `.cursor/mcp.json`（项目）：
```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`（设置 → 开发者 → 编辑配置）：与 Claude Code 相同的 `mcpServers` 形状。
> 上面的 `"command": "node"` 只是默认值 — 如果您选择其他运行时，请替换为 `"bun"` 或 `"deno"`（参数为 `"args": ["run", "--allow-read", "/ABS/PATH/coss-ui-mcp/server.mjs"]`）。运行服务器本身不需要包管理器。（`sync.mjs` 还需要网络 + 写访问权限来快照文档。）
重启客户端，您应该会看到可用的 `coss_*` 工具。
### 3. 使用它
只需正常提示 — 代理将调用工具：
> “使用 coss ui 构建一个计费设置页面。首先计划组件，然后使用实际属性。”
一个好的代理将调用 `coss_plan` → `coss_get_component` 每个 → `coss_theme`，并生成使用您的实际组件和令牌而不是通用“填充”的代码。
---
## 保持更新
```bash
npm run sync
# 或：node scripts/sync.mjs （适用于任何包管理器或根本不需要包管理器）
```
重新下载 `coss.com/ui/llms.txt` 和每个引用的 `.md`，重建 `data/index.json`。差异 `data/meta.json` 以查看更改内容。（两个上游链接 — `radix-shadcn-migration` 和 `sidebar` — 目前为 404 且自动跳过。）
---
## 使其成为*您的*设计系统
您以 **coss ui** 作为**起点**进行构建 — 因此扩展它以编码*您的*约定：
1. **重新品牌化令牌。** 保留 CSS 变量*名称*，在 `globals.css` 中更改其*值*。询问代理：“调用 `coss_theme`，然后给我一个深海蓝品牌调色板的 `globals.css`。” 每个组件都会立即更新。
2. **添加您自己的组件。** 将额外的 `.md` 文件放入 `data/docs/components/`（相同的 frontmatter 形状：`title`、`description`、`## 安装`块）并在 `data/index.json` 中添加匹配的条目。它们将立即出现在搜索/计划中 — 您的内部模式成为一流的上下文。
3. **添加内部规则。** 扩展 `coss_get_doc`（或在 `server.mjs` 中添加 `coss_conventions` 工具），返回*您的*指导方针 — 间距比例、何时使用 Dialog 而不是 Sheet、表单模式。这是一个通用系统变成*您的*系统的地方。
4. **发布 `DESIGN.md`。** 对于不支持 MCP 的工具中的蓝天原型设计，从相同的数据生成一个便携的 `DESIGN.md`。MCP 用于日常驾驶（廉价、按需）；`DESIGN.md` 用于可移植性。
---
## 文件
```
coss-ui-mcp/
├─ server.mjs # MCP 服务器（stdio，零依赖）
├─ scripts/
│ ├─ sync.mjs # 快照 coss.com/ui 文档 -> ./data
│ └─ smoke.mjs # 像真正的 MCP 客户端一样驱动服务器
├─ data/
│ ├─ index.json # 目录：slug、name、description、install、tokens、keywords
│ ├─ meta.json # 同步时间戳 + 计数
│ └─ docs/**/*.md # 快照的组件/钩子/概览 markdown
├─ package.json
└─ README.md
```
## 工作原理（30 秒）
`server.mjs` 直接使用 MCP 的 stdio 传输 — 在 stdin/stdout 上使用换行符分隔的 JSON-RPC 2.0（`initialize`、`tools/list`、`tools/call`）。它在启动时加载 `data/index.json`，并且仅在工具请求时才从磁盘读取单个 markdown 文档。这就是诀窍：**廉价发现，按需详细。**
coss ui 是 [Base UI](https://base-ui.com) + [Tailwind CSS v4](https://tailwindcss.com)，通过 `@coss/*` 注册表与 shadcn-CLI 兼容。此服务器不重新实现任何这些 — 它只是使官方文档对您的代理可读。
## 许可证
MIT — 请参阅 [LICENSE](LICENSE)。 `./data` 中快照的文档来自 [coss ui](https://github.com/cosscom/coss) (`apps/ui/`)，它是以 [MIT 许可](https://github.com/cosscom/coss/blob/main/LICENSING.md) 授权的（父 monorepo 默认使用 AGPLv3，但 `apps/ui/` — 文档和组件注册表所在 — 被切出为 MIT）。
