Design Systems Mcp

设计系统 MCP 服务

一个由 AI 驱动的模型上下文协议（MCP）服务，可智能访问权威设计系统知识。涵盖 395 条精选内容，包括 W3C 标准、WCAG 指南、设计系统实践，以及通用模型无法帮你解决的部分——2025–2026 年 Agent 界面协议。

🌐 在线演示： https://design-systems-mcp.southleft.com/

为什么要开发这个服务

前沿模型已经了解原子设计、BEM 和 WCAG 成功标准。但它无法可靠地获知 MCP Apps 已从 _meta["openai/outputTemplate"] 改为 _meta.ui.resourceUri，也不知道 A2UI 于 2026 年 6 月达到 v1.0 候选版。对于快速演进的规范，所有模型的训练数据都会过时，而且模型无法察觉——它们会自信地给出去年的字段名称。

这正是本服务的用途：提供带日期、带引用、从一手来源提取的内容，其效果优于小模型的猜测，也优于前沿模型昂贵的实时重新研究。

功能

核心能力

• 🎯 向量 + 关键词搜索 - Supabase pgvector，支持可插拔的嵌入模型（Cloudflare Workers AI bge-m3，原生运行于边缘环境，且在 Workers 计划内免费；也可选用 OpenAI），另有 Postgres 全文搜索路径，在嵌入不可用时仍可正常工作
• 📚 395 条精选内容 - W3C 标准、WCAG 2.2、ARIA 实践、主流设计系统和 Agent 界面协议
• 🚦 相关性下限 - 基于 IDF 加权的评分意味着，遇到未覆盖的主题时会返回空结果，而不是自信地给出相近内容
• 🚀 边缘优化 - 通过 Cloudflare Workers 部署并进行全球分发

最新更新

• 🤖 Agent 界面内容覆盖（2026 年 8 月） - A2UI v1.0、MCP Apps SEP-1865、AG-UI、Sentient Design、生成式/临时 UI、组件契约
• 🧪 评测工具 - scripts/eval-mcp.ts 在四个难度级别上评估检索和内容质量
• 🛡️ 来源可靠性徽章 - 每个答案都会标注主要 / 权威 / 参考 / 示例 / 社区来源
• 📖 通用 MCP 客户端支持 - 适用于任何支持 MCP 的客户端（Claude Desktop、Cursor、Windsurf、Codex 等）
• 🏛️ 深入解析主流设计系统 - Carbon、Polaris、Atlassian、Material 3、Fluent、Spectrum、Nord、Mantine、shadcn/ui、Radix、Untitled UI——提供指导原则和令牌架构，而不仅是属性表格

开发者体验

• 🌐 无需任何设置 - 可直接使用公开的 MCP 端点
• 🤖 AI 聊天界面 - 基于知识库的自然语言问答，通过 Cloudflare Workers AI（Llama 3.3 70B）流式传输——无需 OpenAI，也无需 API 额度
• 🧪 本地开发 - 完整的测试环境，支持热重载
• 📝 详尽文档 - 为所有主流 MCP 客户端提供更新后的设置指南

内容库

包含 395 条精选内容：

Agent 界面与 AI（2025-2026 年——通用模型容易理解错的内容）

• A2UI Protocol v1.0（Google）——邻接表组件、目录协商、A2A 绑定
• MCP Apps / SEP-1865——ui:// 资源、CSP 元数据、ui/ 方法命名空间、宿主主题变量
• AG-UI 事件参考；OpenAI Apps SDK → MCP Apps 的字段级迁移对照表
• Sentient Design（Josh Clark）——框架、三角形、彻底自适应体验
• 生成式与短暂 UI——Google Research 的生成式 UI 论文、内容与界面元素的区别
• 组件契约与数据化组件（Nathan Curtis、Christine Vallaure）
• AGENTS.md / SKILL.md / DESIGN.md——面向 Agent 的设计系统层
• Lovable、v0、Figma Make 和 Replit 各自如何接入设计系统
• 真相源之争：三个阵营，以及为什么“代码主导与设计主导”并非真正恰当的说法
• 基于上下文的设计系统、组件契约和机器可读文档
• 设计系统如何接入 Claude Code、Copilot、Cursor 和 Windsurf

标准与规范

• W3C 设计令牌社区组（DTCG）规范
• WCAG 2.2 指南（A、AA、AAA 级别）
• WAI-ARIA 编写实践指南（APG）
• W3C Web 内容无障碍指南
• W3C 的 W3C 移动无障碍指南

设计系统资源

• Material Design 3（Google）
• Fluent Design System（Microsoft）
• Ant Design（Alibaba）
• Carbon Design System（IBM）
• Polaris（Shopify）
• Lightning Design System（Salesforce）
• Atlassian Design System
• Adobe Spectrum
• GitHub Primer
• Shopify Polaris

工具与框架

• Figma 设计系统指南
• Style Dictionary 文档
• 设计令牌格式模块
• Storybook 最佳实践

方法与最佳实践

• 原子设计原则
• 设计系统手册
• 组件架构模式
• 无障碍实现指南

快速开始

使用公共 MCP 服务（推荐）

无需安装！将任意 MCP 客户端连接到我们的在线服务：

https://design-systems-mcp.southleft.com/mcp

详细设置说明请参阅下文的连接 MCP 客户端部分。

本地开发

1. 克隆并安装

   git clone https://github.com/southleft/design-systems-mcp.git
   cd design-systems-mcp
   npm install
   

2. 配置环境

   cp .dev.vars.example .dev.vars
   # Edit .dev.vars and add your credentials
   

3. 启动开发服务器

   npm run dev
   

   服务可通过以下地址访问：http://localhost:8787

连接到 MCP 客户端

请在下方选择你的 AI 编码工具，查看设置说明：

claude mcp add --transport http design-systems https://design-systems-mcp.southleft.com/mcp

{
  "mcpServers": {
    "design-systems": {
      "type": "http",
      "url": "https://design-systems-mcp.southleft.com/mcp"
    }
  }
}

claude mcp list

{
  "mcpServers": {
    "design-systems": {
      "url": "https://design-systems-mcp.southleft.com/mcp"
    }
  }
}

{
  "design-systems": {
    "url": "https://design-systems-mcp.southleft.com/mcp",
    "description": "Design systems knowledge and best practices"
  }
}

{
  "mcpServers": [
    {
      "name": "design-systems",
      "url": "https://design-systems-mcp.southleft.com/mcp",
      "description": "Design systems knowledge base"
    }
  ]
}

{
  "mcp": {
    "servers": {
      "design-systems": {
        "url": "https://design-systems-mcp.southleft.com/mcp"
      }
    }
  }
}

{
  "mcpServers": {
    "design-systems": {
      "url": "http://localhost:8787/mcp"
    }
  }
}

连接故障排查

服务无响应？

• 确认 URL 正确：https://design-systems-mcp.southleft.com/mcp
• 使用 curl 测试：curl https://design-systems-mcp.southleft.com/health
• 检查你的客户端是否支持远程 MCP 服务

工具未显示？

• 更改配置后，重启 MCP 客户端
• 检查客户端日志中是否有连接错误
• 确认 JSON 配置语法正确

需要帮助？

• 提交问题：GitHub Issues

可用的 MCP 工具

该服务为 AI 助手提供以下工具：

search_design_knowledge

以语义方式搜索完整知识库。

参数：

• query（string，必填）- 搜索查询
• category（string，可选）- 按类别筛选
• tags（array，可选）- 按标签筛选
• limit（number，可选）- 最大结果数（默认：15）

示例：

{
  "name": "search_design_knowledge",
  "arguments": {
    "query": "WCAG 2.2 color contrast requirements",
    "category": "guidelines",
    "limit": 5
  }
}

search_chunks

在内容分块中查找特定信息，以便提供详细答案。

参数：

• query（string，必填）- 搜索查询
• limit（number，可选）- 最大分块数（默认：8）

示例：

{
  "name": "search_chunks",
  "arguments": {
    "query": "W3C DTCG design tokens specification",
    "limit": 3
  }
}

browse_by_category

按类别浏览内容。

类别： components、tokens、patterns、guidelines、workflows、general

参数：

• category（字符串，必填）- 要浏览的类别

get_all_tags

获取所有可用于筛选和探索的内容标签。

API 示例

直接测试 API

健康检查：

curl https://design-systems-mcp.southleft.com/health

MCP 工具列表：

curl -X POST https://design-systems-mcp.southleft.com/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

搜索查询：

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": "design tokens", "limit": 3}
    }
  }'

AI 聊天界面（流式）：

/ai-chat 端点会返回 Server-Sent Events 流，因此内容会逐步显示。每个事件的格式为 data: {"t": "<chunk>"}\n\n，并以 event: done\ndata: {}\n\n 结束。

curl -N -X POST https://design-systems-mcp.southleft.com/ai-chat \
  -H "Content-Type: application/json" \
  -d '{"message":"What are the WCAG 2.2 contrast requirements?"}'

托管的 Web UI 会使用 / 处的此流，并逐步渲染 Markdown。

添加内容

摄取 Web 内容

# Single URL
npm run ingest:url https://material.io/components/buttons

# Bulk from CSV
npm run ingest:csv urls.csv

# Crawl entire website
npm run crawl:website https://polaris.shopify.com --max-depth 3

摄取 PDF 内容

npm run ingest:pdf path/to/design-guide.pdf

生成向量嵌入

npm run ingest:vectors

开发

可用脚本

• npm run dev - 启动本地开发服务器
• npm run deploy - 部署到 Cloudflare Workers
• npm run ingest:pdf <file> - 摄取 PDF 内容
• npm run ingest:url <url> - 摄取 Web 内容
• npm run ingest:csv <file> - 从 CSV 批量摄取
• npm run crawl:website <url> - 爬取整个网站
• npm run ingest:vectors - 为所有内容生成嵌入
• npm run setup:supabase - 初始化 Supabase 数据库
• npm run check:duplicates - 检查重复内容

项目结构

design-systems-mcp/
├── src/
│   ├── index.ts                    # Main MCP server, transports, tool dispatch, embedded chat UI
│   ├── sse-session.ts              # SSE transport (Durable Object)
│   ├── streamable-http-handler.ts  # Streamable HTTP transport (/mcp)
│   ├── oauth-handler.ts            # OAuth flow
│   └── lib/
│       ├── content-manager.ts      # Content management
│       ├── search-handler.ts       # Vector + keyword search dispatch
│       ├── source-authority.ts     # Reliability tiers & APG disclaimers
│       └── ... (chunker, formatters, ingestion helpers)
├── content/
│   └── entries/              # Ingested content (JSON)
├── supabase/
│   └── migrations/           # SQL schema + RPC functions
├── scripts/
│   ├── ingestion/            # Content ingestion pipeline (URL, PDF, HTML, CSV, crawler)
│   └── build/                # Build helpers (manifest generation)
├── types/
│   └── content.ts           # TypeScript definitions
├── wrangler.jsonc          # Cloudflare Workers config
└── .dev.vars              # Local environment variables

部署

部署到 Cloudflare Workers

1. 登录 Cloudflare

   npx wrangler login
   

2. 设置密钥

   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. 部署

   npm run deploy
   

详细说明请参阅 DEPLOYMENT.md。

向量搜索架构

此服务使用 Supabase 实现生产级向量搜索：

• 数据库： 使用 pgvector 扩展的 PostgreSQL
• 嵌入： Cloudflare Workers AI @cf/baai/bge-m3（1024 维、原生边缘运行、无需 API 密钥），通过 VECTOR_SEARCH_PROVIDER=cloudflare 使用；也支持 OpenAI text-embedding-3-small（1536 维）
• 阈值： 0.15，以实现最佳召回率
• 混合搜索： 将语义向量与文本匹配相结合
• 性能： 通过适当的索引，实现低于 100 毫秒的查询

统计数据：

• 生产数据库中有 395 条记录
• 4,800 多个内容块；通过 Cloudflare Workers AI 进行条目级向量搜索
• W3C 标准、WCAG 指南、设计系统文档
• 定期更新，纳入新的权威来源

故障排除

常见问题

向量搜索无法正常工作：

• 检查环境变量中的 Supabase 凭据
• 确认数据库表存在：npm run setup:supabase
• 查看日志：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 客户端

文档

• DEPLOYMENT.md - 生产环境部署
• CONTRIBUTING.md - 如何贡献和添加内容
• CREDITS.md - 内容来源和署名

许可证与署名

许可证： MIT License - 可免费用于个人和商业用途

内容署名： 本项目汇集了许多优秀创作者贡献的设计系统知识。所有原创内容仍归各自作者所有。

• 完整署名信息请参阅 CREDITS.md
• 分享见解时，请始终链接回原始来源
• 请访问原作者的网站，以支持他们的创作

安全与隐私

• 不存储敏感数据——仅包含公开的设计系统知识
• 环境变量使用 Cloudflare secrets
• 开源且可审计
• 注重隐私——不收集用户数据
• 定期进行安全更新

请通过 GitHub 安全 报告安全问题。

贡献

欢迎贡献！您可以：

• 报告 Bug 或问题
• 提出新功能建议
• 添加更多设计系统内容
• 改进代码库
• 完善文档

请：

1. 查看现有的 问题
2. 提交新问题进行讨论
3. 提交拉取请求
4. 遵循贡献指南

支持

• 问题：GitHub 问题
• 讨论：GitHub 讨论
• 在线演示：https://design-systems-mcp.southleft.com/

致谢

感谢设计系统社区分享知识：

• 感谢 Brad Frost 提出原子设计方法
• W3C 设计令牌社区组
• Web 无障碍倡议（WAI）
• 所有公开分享其工作的设计团队
• 整个设计系统社区

请查看 CREDITS.md 获取完整列表。

使用 Cloudflare Workers 和 Model Context Protocol 倾情打造 ❤️