Tmall Design Wiki MCP Server

一个为AI编程工具（如Cursor、Claude Desktop等）提供天猫设计系统组件库访问的MCP服务器。让AI能够像shadcn/ui一样，成为"百科式组件库"。

功能特性

• 设计令牌访问 - 获取颜色、间距、圆角、字重等全局设计变量
• 组件库 - 访问7个完整的React+TypeScript组件
• 页面模板 - 基于实际案例的页面生成
• 智能搜索 - 快速查找设计规范和组件代码
• 工作流自动化 - 集成提示词扩写和代码验证
• 移动优先 - 专为手机天猫App设计的组件体系

快速开始

安装

npm install -g tmall-design-wiki-mcp-server

注意: tmall-design-wiki 知识库会作为依赖自动安装，无需手动安装。

环境兼容性检查

如果遇到MCP红点连接问题，使用自动环境检测：

# 运行环境检测（会自动诊断并提供配置建议）
npx tmall-design-wiki-mcp-server@latest --check-env

# 或手动检查
tmall-design-wiki-mcp-server --help

检测脚本会自动：

• ✅ 检查Node.js环境和版本管理工具
• ✅ 验证MCP server安装和权限
• ✅ 生成适合你环境的Cursor配置
• ✅ 提供具体的修复建议

在Cursor中配置

1. 打开Cursor设置
2. 找到MCP服务器配置
3. 添加以下配置到.cursor/mcp.json：

{
  "mcpServers": {
    "tmall-design-wiki": {
      "command": "tmall-design-wiki-mcp-server",
      "args": []
    }
  }
}

在Claude Desktop中配置

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "tmall-design-wiki": {
      "command": "tmall-design-wiki-mcp-server",
      "args": []
    }
  }
}

API功能

设计令牌 (Design Tokens)

// 获取所有设计令牌
getDesignToken()

// 获取特定类别的令牌
getDesignToken({ category: "colors" })    // 颜色相关 (33个token)
getDesignToken({ category: "spacing" })   // 间距相关
getDesignToken({ category: "typography" }) // 字体相关
getDesignToken({ category: "borders" })   // 圆角边框相关

组件功能

// 列出所有组件
listComponents()
// 返回: capsuletabbar, price, productcard, productgrid, scrollloading, tabbar, topbar

// 获取组件源码
getComponentCode({ name: "productcard" })
// 返回: ProductCard.tsx, ProductCard.scss, ProductCard.md

// 获取组件演示
getComponentDemo({ name: "productcard" })
// 返回: 完整的HTML演示文件

页面功能

// 列出页面模板
listPages()

// 获取页面代码
getPageCode({ name: "guide-page" })

// 生成页面
generatePage({ 
  type: "guide-page", 
  config: { title: "商品导购", theme: "default" }
})

工作流功能

// 执行组件工作流
runWorkflow({ 
  type: "component", 
  input: { componentName: "productcard" }
})

// 执行页面工作流
runWorkflow({ 
  type: "page", 
  input: { pageType: "guide", config: {...} }
})

// 代码验证工作流
runWorkflow({ 
  type: "validation", 
  input: { code: "...", type: "component" }
})

// 提示词扩写工作流
runWorkflow({ 
  type: "prompt-expansion", 
  input: { userInput: "我需要一个商品列表页面" }
})

搜索功能

// 搜索知识库
search({ query: "商品卡片", limit: 10 })

代码验证

// 验证代码是否符合天猫设计规范
validate({ 
  code: "你的React组件代码",
  type: "component" 
})

使用示例

在Cursor中使用

1. 获取设计令牌：

   请帮我获取天猫设计系统的颜色token

2. 获取组件代码：

   我需要ProductCard组件的完整代码，包括TypeScript和样式

3. 生成页面：

   基于天猫设计规范，帮我生成一个商品导购页面

4. 验证代码：

   请验证我的组件代码是否符合天猫设计规范

可用组件列表

1. CapsuleTabBar - 胶囊式标签栏
2. Price - 价格显示组件
3. ProductCard - 商品卡片（支持1:1和3:4比例）
4. ProductGrid - 商品瀑布流布局
5. ScrollLoading - 滚动加载组件
6. TabBar - 底部标签栏
7. TopBar - 顶部导航栏

设计令牌类别

• 颜色系统 (33个token)：品牌色、文本色、背景色等
• 间距系统 (16个token)：基于8px网格的间距变量
• 字体系统 (28个token)：字体家族、大小、行高、字重
• 圆角系统 (10个token)：统一的圆角规范

开发

本地开发

# 克隆项目
git clone https://github.com/tmall-design/tmall-design-wiki-mcp-server.git
cd tmall-design-wiki-mcp-server

# 安装依赖
npm install

# 构建项目
npm run build

# 测试
npm test

目录结构

tmall-design-wiki-mcp-server/
├── src/
│   ├── index.ts        # MCP服务器入口
│   ├── handlers.ts     # API处理器
│   └── utils.ts        # 工具函数
├── dist/               # 编译输出
├── package.json
└── README.md

系统要求

• Node.js >= 18.0.0
• Cursor 或 Claude Desktop 支持MCP协议

贡献

欢迎提交Issue和Pull Request！

开发流程

1. Fork项目
2. 创建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启Pull Request

许可证

MIT License - 详见 LICENSE 文件

相关链接

• 天猫设计官网
• MCP协议文档
• Cursor编辑器

故障排除

常见问题

1. MCP红点/连接失败

原因：使用了Node.js版本管理工具（如Volta、nvm、n等），导致Cursor无法找到命令。

诊断步骤：

# 1. 检查命令是否存在
tmall-design-wiki-mcp-server --help

# 2. 如果步骤1失败，查看实际路径
which tmall-design-wiki-mcp-server

# 3. 检查当前Node.js管理方式
which node
which npm

解决方案：

# 方案A：使用系统Node.js重新安装（推荐）
# 首先卸载当前版本
npm uninstall -g tmall-design-wiki-mcp-server

# 使用系统Node.js安装
sudo /usr/local/bin/npm install -g tmall-design-wiki-mcp-server

# 方案B：如果方案A不可行，在Cursor配置中使用完整路径
# 将 which tmall-design-wiki-mcp-server 的输出路径替换到配置中

2. 命令找不到

• 确认Node.js版本 >= 18.0.0
• 检查npm全局路径配置
• 重启Cursor/Claude Desktop

3. 权限错误

• macOS/Linux: 使用 sudo npm install -g
• Windows: 以管理员身份运行

支持

如有问题或建议，请提交 GitHub Issues

让AI像shadcn/ui一样，成为你的设计系统百科全书！