Tmall Design Wiki MCP Server

一个为AI编程工具（如Cursor、Claude Desktop、VS Code等）提供天猫设计系统组件库访问的MCP服务器。

快速开始

新用户？查看 快速开始指南 5分钟上手！

功能特性

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

安装和配置

Wiki包依赖配置（必需）

在使用MCP Server之前，需要先配置 tmall-design-ai wiki包。有多种配置方式可选：

快速开始（推荐） 选择以下任一方式：

1. 通过环境变量指定路径（适合开发环境）：

{
  "mcpServers": {
    "tmall-design-wiki": {
      "command": "npx",
      "args": ["tmall-design-wiki-mcp-server@latest"],
      "env": {
        "TMALL_DESIGN_AI_PATH": "/path/to/your/tmall-design-ai"
      }
    }
  }
}

2. 放置到约定路径（最简单）：

   • 将 wiki 包放到 ~/Desktop/tmall-design-ai 或 ~/Desktop/tmall-design-wiki
   • 无需其他配置，自动识别

3. 通过npm包（适合生产环境）：

   • 需要将 tmall-design-ai 发布到 npm
   • 自动安装依赖，无需额外配置

详细配置方式请查看：DEPENDENCY_GUIDE.md

MCP客户端配置

配置完wiki包后，在您的MCP客户端中添加配置：

Cursor配置 在您的项目中创建或编辑 .cursor/mcp.json：

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

Claude Desktop配置 编辑您的Claude Desktop配置文件 ~/Library/Application Support/Claude/claude_desktop_config.json：

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

VS Code配置 VS Code通过Continue扩展支持MCP协议。请按以下步骤配置：

1. 安装Continue扩展：在VS Code扩展商店搜索并安装"Continue"
2. 在您的项目根目录创建或编辑 .continue/config.json：

{
  "models": [
    {
      "title": "Claude 3.5 Sonnet",
      "provider": "anthropic", 
      "model": "claude-3-5-sonnet-20241022",
      "apiKey": "your-anthropic-api-key"
    }
  ],
  "mcpServers": {
    "tmall-design-wiki": {
      "command": "npx",
      "args": ["tmall-design-wiki-mcp-server@latest"]
    }
  }
}

3. 或者编辑全局配置文件 ~/.continue/config.json：

{
  "models": [
    {
      "title": "Claude 3.5 Sonnet",
      "provider": "anthropic",
      "model": "claude-3-5-sonnet-20241022", 
      "apiKey": "your-anthropic-api-key"
    }
  ],
  "mcpServers": {
    "tmall-design-wiki": {
      "command": "npx",
      "args": ["tmall-design-wiki-mcp-server@latest"]
    }
  }
}

备选配置（全局安装方式）

如果您已全局安装，可以使用：

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

第二步：重启MCP客户端 配置完成后，重启客户端。

第三步：验证配置

# 运行环境检测
npx tmall-design-wiki-mcp-server@latest --check-env

检测会告诉你：

• Node.js环境状态
• MCP Server安装状态
• Wiki包依赖状态（新增）
• 推荐的配置方案

第四步：开始使用 在MCP客户端中就可以调用天猫设计系统的各种功能了

重要提醒：

• ❌ 不要直接在命令行运行 npx tmall-design-wiki-mcp-server@latest
• ✅ 应该通过MCP客户端配置后自动调用
• 💡 如果直接运行，只会显示配置说明然后等待MCP连接

故障排除

常见问题1：Wiki包未找到 错误信息：Tmall Design AI not found

解决方案：

1. 检查wiki包是否已配置（运行 --check-env）
2. 按照 DEPENDENCY_GUIDE.md 配置wiki包
3. 确认路径正确且文件夹结构完整

常见问题2：运行 npx tmall-design-wiki-mcp-server@latest 时没反应 这是正常现象！MCP服务器启动后会等待MCP客户端的连接。在命令行直接运行时：

• 程序会显示配置说明
• 然后等待MCP协议输入
• 按 Ctrl+C 可退出

环境检测： 如果遇到其他问题，运行环境检测：

npx tmall-design-wiki-mcp-server@latest --check-env

这会检查：

• Node.js环境
• MCP Server安装
• Wiki包依赖（新增）
• 生成配置建议

API功能

MCP Server 提供 12 个核心工具，符合天猫设计系统的完整工作流。

1. search - 语义搜索

search({ query: "商品卡片", limit: 10 })

基于已加载的设计知识库进行语义搜索。

2. runWorkflow - 主入口（4智能体链路）

// 方式1：完整工作流（推荐）
runWorkflow({ requirement: "我需要一个商品列表页面" })

// 方式2：指定类型（兼容旧版本）
runWorkflow({ type: "component", input: { componentName: "productcard" } })

执行完整的 4 智能体链路：需求识别 → 知识检索 → 设计合成 → 代码生成

3. getDesignToken - 设计令牌

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

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

4. listComponents - 组件列表

// 列出所有组件
listComponents()

// 按分类过滤
listComponents({ category: "navigation" })

5. getComponentCode - 组件源码

// 获取组件源码（标准用法代码）
getComponentCode({ name: "productcard" })
// 返回: ProductCard.tsx, ProductCard.scss, ProductCard.md

6. getComponentDemo - 组件演示

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

7. getAssets - 资产列表

// 获取所有资产
getAssets({ type: "all" })

// 获取图标资产
getAssets({ type: "icon" })

// 获取图片资产
getAssets({ type: "image", category: "product" })

8. getAsset - 特定资产详情

// 获取特定资产的详情或URL
getAsset({ id: "icon-cart" })
getAsset({ id: "product-placeholder" })

9. listCases - 标准案例列表

// 列出所有页面模板/金样案例
listCases()

// 按分类过滤
listCases({ category: "shopping" })

10. getCaseCode - 案例完整代码

// 获取标准案例的完整代码
getCaseCode({ caseId: "SearchPage" })
getCaseCode({ caseId: "ShoppingFeed" })

11. validate - 质量验证

// 验证代码
validate({ 
  code: "你的React组件代码",
  type: "component" 
})

// 验证schema
validate({ 
  schema: { name: "Button", type: "component" },
  type: "component"
})

将质量验证智能体的能力独立暴露为工具。

12. generateCase - 生成完整页面

// 专门用于生成完整页面的工作流
generateCase({ 
  description: "需要一个商品导购页面，包含商品列表和筛选功能",
  type: "guide-page"
})

// 带配置参数
generateCase({ 
  description: "电商首页",
  type: "home",
  config: { layout: "grid", columns: 2 }
})

类似 runWorkflow，但针对页面级场景优化。

可用组件列表

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)：统一的圆角规范

系统要求

• Node.js >= 18.0.0
• Cursor、Claude Desktop 或 VS Code（通过Continue扩展） 支持MCP协议
• Wiki包: tmall-design-ai 或 tmall-design-wiki（必需）

相关文档

• 快速开始指南 - 5分钟上手
• Wiki包依赖配置 - 详细配置说明
• 版本迁移指南 - v1.x 升级到 v2.0
• 更新日志 - 版本历史

许可证

MIT License