内容
# 设计系统 MCP 服务器
由人工智能驱动的模型上下文协议（MCP）服务器，提供对权威设计系统知识的智能访问。由 Supabase 矢量搜索提供支持，包含 188+ 个精选条目，包括 W3C 标准、WCAG 指南和设计系统最佳实践。
🌐 **在线演示：** [https://design-systems-mcp.southleft.com/](https://design-systems-mcp.southleft.com/)
## 功能
### 核心能力
- 🎯 **生产级矢量搜索** - Supabase pgvector 与 OpenAI 嵌入，实现语义理解
- 📚 **188+ 精选条目** - W3C 标准、WCAG 2.2、ARIA 实践和 10+ 主要设计系统
- 🔍 **混合搜索架构** - 结合矢量相似性与关键词匹配（阈值 0.15）
- 🚀 **边缘优化** - Cloudflare Workers 部署，全球分布
### 最新更新
- ✨ **36 个新权威来源** - 来自 Style Dictionary、Figma 文档、CSS 规范等的新鲜内容
- 🔧 **生产级矢量搜索** - 现已完全运行，具备适当的 Supabase 集成
- 📖 **通用 MCP 客户端支持** - 为 7+ 个流行 AI 编程工具预配置设置
- 🎨 **丰富的内容格式化** - 增强的 Markdown 渲染，支持语法高亮
### 开发体验
- 🌐 **零设置要求** - 公共 MCP 端点即用
- 🤖 **AI 聊天界面** - 自然语言查询，集成 GPT-4o
- 🧪 **本地开发** - 完整的测试环境，支持热重载
- 📝 **全面文档** - 每个主要 MCP 客户端的更新设置指南
## 内容库
### 188+ 精选条目，包括：
**标准和规范**
- W3C 设计令牌社区组（DTCG）规范
- WCAG 2.2 指南（A、AA、AAA 级别）
- WAI-ARIA 作者实践指南（APG）
- W3C 网络内容无障碍指南
- W3C 移动无障碍
**设计系统资源**
- Material Design 3（谷歌）
- Fluent 设计系统（微软）
- Ant Design（阿里巴巴）
- Carbon 设计系统（IBM）
- Polaris（Shopify）
- Lightning 设计系统（Salesforce）
- Atlassian 设计系统
- Adobe Spectrum
- GitHub Primer
- Shopify Polaris
**工具和框架**
- Figma 设计系统指南
- Style Dictionary 文档
- 设计令牌格式模块
- Storybook 最佳实践
**方法和最佳实践**
- 原子设计原则
- 设计系统手册
- 组件架构模式
- 无障碍实施指南
## 快速入门
### 使用公共 MCP 服务器（推荐）
无需安装！将任何 MCP 客户端连接到我们的在线服务器：
```
https://design-systems-mcp.southleft.com/mcp
```
参见下面的“连接到 MCP 客户端”部分，获取详细的设置说明。
### 本地开发
1. **克隆并安装**
```bash
git clone https://github.com/southleft/design-systems-mcp.git
cd design-systems-mcp
npm install
```
2. **配置环境**
```bash
cp .dev.vars.example .dev.vars
# 编辑 .dev.vars 并添加您的凭证
```
3. **启动开发服务器**
```bash
npm run dev
```
服务器可在：`http://localhost:8787`
## 连接到 MCP 客户端
选择下面的 AI 编程工具，获取设置说明：
<details>
<summary><b>Claude Desktop</b> - 点击展开配置</summary>
**通过自定义连接器 UI 添加（推荐 - 无需编辑 JSON！）**
1. **打开 Claude Desktop** 并导航到 **设置** → **连接器**
2. **点击“添加自定义连接器”** 在连接器列表底部
3. **填写连接器详细信息：**
- **名称**：`设计系统助手`（或您喜欢的任何名称）
- **网址**：`https://design-systems-mcp.southleft.com/mcp`
4. **点击“添加”** 以保存连接器
5. **开始使用！** 连接器将出现在您的连接器列表中，包含 4 个可用的工具：
- `search_design_knowledge`
- `search_chunks`
- `browse_by_category`
- `get_all_tags`
**就是这样！** 您现在可以在 Claude Desktop 对话中使用设计系统助手。
**注意：** 自定义连接器适用于 Claude Pro、Team 和 Enterprise 计划。
</details>
<details>
<summary><b>Claude Code（CLI）</b> - 点击展开配置</summary>
**通过 CLI 快速设置：**
```bash
claude mcp add --transport http design-systems https://design-systems-mcp.southleft.com/mcp
```
**或手动编辑 `.mcp.json`：**
```json
{
"mcpServers": {
"design-systems": {
"type": "http",
"url": "https://design-systems-mcp.southleft.com/mcp"
}
}
}
```
**验证连接：**
```bash
claude mcp list
```
</details>
<details>
<summary><b>Cursor IDE</b> - 点击展开配置</summary>
**位置：** `~/.cursor/mcp_config.json` 或 `~/.config/cursor/mcp_config.json`
```json
{
"mcpServers": {
"design-systems": {
"url": "https://design-systems-mcp.southleft.com/mcp"
}
}
}
```
**重启 Cursor** 以更新配置。
</details>
<details>
<summary><b>Cline（VSCode 扩展）</b> - 点击展开配置</summary>
**位置：** VSCode 设置 → 扩展 → Cline → MCP 设置
**添加到 MCP 服务器配置：**
```json
{
"design-systems": {
"url": "https://design-systems-mcp.southleft.com/mcp",
"description": "设计系统知识和最佳实践"
}
}
```
**或通过命令面板添加：** `Cline: Add MCP Server`
**重启 VSCode** 以更新配置。
</details>
<details>
<summary><b>Continue（VSCode 扩展）</b> - 点击展开配置</summary>
**位置：** VSCode 设置 → 扩展 → Continue → config.json
```json
{
"mcpServers": [
{
"name": "design-systems",
"url": "https://design-systems-mcp.southleft.com/mcp",
"description": "设计系统知识库"
}
]
}
```
</details>
<details>
<summary><b>Zed 编辑器</b> - 点击展开配置</summary>
**位置：** `~/.config/zed/settings.json`
```json
{
"mcp": {
"servers": {
"design-systems": {
"url": "https://design-systems-mcp.southleft.com/mcp"
}
}
}
}
```
</details>
<details>
<summary><b>通用 MCP 客户端</b> - 点击展开配置</summary>
对于支持远程服务器的任何 MCP 客户端：
**端点：** `https://design-systems-mcp.southleft.com/mcp`
**协议：** JSON-RPC 2.0，基于 HTTP/HTTPS
**传输：** 标准 MCP 传输（stdio、SSE 或 HTTP）
</details>
<details>
<summary><b>本地开发设置</b> - 点击展开配置</summary>
要连接到本地开发服务器而不是公共端点：
```json
{
"mcpServers": {
"design-systems": {
"url": "http://localhost:8787/mcp"
}
}
}
```
**注意：** 本地服务器需要先运行 `npm run dev`。
</details>
### 连接故障排除
**服务器无响应？**
- 验证 URL 是否正确：`https://design-systems-mcp.southleft.com/mcp`
- 使用 curl 测试：`curl https://design-systems-mcp.southleft.com/health`
- 检查您的客户端是否支持远程 MCP 服务器
**工具未出现？**
- 在配置更改后重启您的 MCP 客户端
- 检查客户端日志中的连接错误
- 验证 JSON 配置语法是否正确
**需要帮助？**
- 打开问题：[GitHub 问题](../../issues)
- 查看文档：[连接指南](docs/CONNECTION_GUIDE.md)
## 可用的 MCP 工具
服务器为 AI 助手提供这些工具：
### search_design_knowledge
搜索完整的知识库，具有语义理解。
**参数：**
- `query`（字符串，必填）- 搜索查询
- `category`（字符串，可选）- 按类别筛选
- `tags`（数组，可选）- 按标签筛选
- `limit`（数字，可选）- 最大结果数（默认：15）
**示例：**
```json
{
"name": "search_design_knowledge",
"arguments": {
"query": "WCAG 2.2 色对比要求",
"category": "guidelines",
"limit": 5
}
}
```
### search_chunks
在内容块中查找特定信息以获取详细答案。
**参数：**
- `query`（字符串，必填）- 搜索查询
- `limit`（数字，可选）- 最大块数（默认：8）
**示例：**
```json
{
"name": "search_chunks",
"arguments": {
"query": "W3C DTCG 设计令牌规范",
"limit": 3
}
}
```
### browse_by_category
按类别浏览内容。
**类别：** components、tokens、patterns、guidelines、tools、general
**参数：**
- `category`（字符串，必填）- 要浏览的类别
### get_all_tags
获取所有可用的内容标签用于筛选和探索。
## API 示例
### 直接 API 测试
**健康检查：**
```bash
curl https://design-systems-mcp.southleft.com/health
```
**MCP 工具列表：**
```bash
curl -X POST https://design-systems-mcp.southleft.com/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```
**搜索查询：**
```bash
curl -X POST https://design-systems-mcp.southleft.com/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "search_chunks",
"arguments": {"query": "设计令牌", "limit": 3}
}
}'
```
**AI 聊天界面：**
```bash
curl -X POST https://design-systems-mcp.southleft.com/ai-chat \
-H "Content-Type: application/json" \
-d '{"message":"WCAG 2.2 的对比度要求是什么？"}'
```
## 添加内容
### 抓取网页内容
```bash
# 单个 URL
npm run ingest:url https://material.io/components/buttons
# 批量抓取 CSV
npm run ingest:csv urls.csv
# 抓取整个网站
npm run crawl:website https://polaris.shopify.com --max-depth 3
```
### 抓取 PDF 内容
```bash
npm run ingest:pdf path/to/design-guide.pdf
```
### 生成矢量嵌入
```bash
npm run ingest:vectors
```
查看 [内容抓取指南](docs/CONTENT_INGESTION.md) 获取详细说明。
## 开发
### 可用脚本
- `npm run dev` - 启动本地开发服务器
- `npm run deploy` - 部署到 Cloudflare Workers
- `npm run ingest:pdf <file>` - 抓取 PDF 内容
- `npm run ingest:url <url>` - 抓取网页内容
- `npm run ingest:csv <file>` - 批量抓取 CSV
- `npm run crawl:website <url>` - 抓取整个网站
- `npm run ingest:vectors` - 为所有内容生成嵌入
- `npm run setup:database` - 初始化 Supabase 数据库
- `npm run check:duplicates` - 检查重复内容
### 项目结构
```
design-systems-mcp/
├── src/
│ ├── index.ts # 主 MCP 服务器
│ ├── lib/
│ │ ├── content-manager.ts # 内容管理
│ │ ├── search-handler.ts # 矢量搜索
│ │ └── vector-search.ts # Supabase 集成
│ └── tools/ # MCP 工具定义
├── content/
│ ├── entries/ # 抓取的内容（JSON）
│ └── raw/ # 原始源文件
├── scripts/
│ ├── ingestion/ # 内容抓取工具
│ └── setup/ # 数据库设置脚本
├── types/
│ └── content.ts # TypeScript 定义
├── docs/ # 附加文档
├── wrangler.jsonc # Cloudflare Workers 配置
└── .dev.vars # 本地环境变量
```
## 部署
### 部署到 Cloudflare Workers
1. **登录 Cloudflare**
```bash
npx wrangler login
```
2. **设置密钥**
```bash
npx wrangler secret put OPENAI_API_KEY
npx wrangler secret put SUPABASE_URL
npx wrangler secret put SUPABASE_SERVICE_KEY
npx wrangler secret put SUPABASE_ANON_KEY
```
3. **部署**
```bash
npm run deploy
```
查看 [部署指南](docs/DEPLOYMENT.md) 获取详细说明。
## 矢量搜索架构
该服务器使用 Supabase 进行生产级矢量搜索：
- **数据库：** PostgreSQL，带有 pgvector 扩展
- **嵌入：** OpenAI text-embedding-3-small（1536 维）
- **阈值：** 0.15 以实现最佳召回率
- **混合搜索：** 将语义矢量与文本匹配相结合
- **性能：** 查询在 100ms 以内
**统计数据：**
- 生产数据库中有 188+ 条记录
- 761+ 内容块嵌入
- W3C 标准、WCAG 指南、设计系统文档
- 定期更新新的权威来源
查看 [矢量搜索设置](docs/VECTOR_SEARCH_SETUP.md) 获取架构详情。
## 故障排除
### 常见问题
**矢量搜索无法正常工作：**
- 检查环境变量中的 Supabase 凭证
- 验证数据库表是否存在：`npm run setup:database`
- 检查日志：`npx wrangler tail`
**内容找不到：**
- 验证内容是否存在：`npm run check:duplicates`
- 检查是否生成了嵌入：查看内容记录中的 `embedding` 字段
- 本地测试搜索：`npm run dev` 并使用 curl 命令
**MCP 连接失败：**
- 验证 URL 是否正确且可访问
- 检查客户端是否支持远程 MCP 服务器
- 使用 curl 测试：`curl https://design-systems-mcp.southleft.com/health`
- 配置更改后重启 MCP 客户端
查看 [故障排除指南](docs/TROUBLESHOOTING.md) 获取详细解决方案。
## 文档
- [连接指南](docs/CONNECTION_GUIDE.md) - 详细的 MCP 客户端设置
- [内容抓取](docs/CONTENT_INGESTION.md) - 添加新内容
- [矢量搜索设置](docs/VECTOR_SEARCH_SETUP.md) - 数据库配置
- [部署指南](docs/DEPLOYMENT.md) - 生产部署
- [贡献](docs/CONTRIBUTING.md) - 如何贡献
- [安全](docs/SECURITY.md) - 安全最佳实践
## 许可证和归属
**许可证：** MIT 许可证 - 免费用于个人和商业用途
**内容归属：** 该项目汇编了许多优秀创作者的设计系统知识。所有原始内容仍为其各自作者的知识产权。
- 查看 [CREDITS.md](CREDITS.md) 获取完整归属信息
- 在分享见解时始终链接到原始来源
- 通过访问创作者的网站支持原创创作者
## 安全和隐私
- 无敏感数据存储 - 仅公开的设计系统知识
- 环境变量使用 Cloudflare 机密
- 开源且可审计
- 注重隐私 - 无用户数据收集
- 定期安全更新
通过 [GitHub 安全](../../security/advisories) 报告安全问题。
## 贡献
我们欢迎贡献！无论您想：
- 报告错误或问题
- 建议新功能
- 添加更多设计系统内容
- 改进代码库
- 增强文档
请：
1. 查看现有 [问题](../../issues)
2. 打开新问题进行讨论
3. 提交拉取请求
4. 遵循 [贡献指南](docs/CONTRIBUTING.md)
## 支持
- 问题：[GitHub 问题](../../issues)
- 讨论：[GitHub 讨论](../../discussions)
- 在线演示：[https://design-systems-mcp.southleft.com/](https://design-systems-mcp.southleft.com/)
## 致谢
感谢设计系统社区分享知识：
- Brad Frost 的原子设计方法论
- W3C 设计令牌社区组
- Web 无障碍倡议（WAI）
- 所有公开分享其工作的设计团队
- 整个设计系统社区
查看 [CREDITS.md](CREDITS.md) 获取完整列表。
---
使用 Cloudflare Workers 和模型上下文协议构建 ❤️
