Zeplin MCP Server for AI-Assisted UI Implementation

Zeplin MCP 服务：AI 辅助 UI 开发

将 Cursor、Windsurf 和 VS Code（搭配 Copilot）等 AI Agent 连接到 Zeplin。借助 MCP 服务，AI Agent 可以使用：

• 组件和屏幕规范： 组件和完整屏幕的详细规范与资源，帮助 Agent 生成与设计高度匹配的 UI 代码。
• 文档： 添加到屏幕中的注释可提供额外上下文，例如功能应如何表现或实现建议，让 Agent 不再局限于静态视觉效果，还能构建真实的交互。
• 设计令牌： 项目中使用的颜色、排版、间距和其他设计变量，让你的 Agent 尽可能复用现有令牌。

目录

• 先决条件
• 安装
• 配置
• 开发
• 与 MCP 客户端配合使用（例如 Cursor）
• 编写有效的提示词
  • 示例提示词 1：小幅修改／添加
  • 示例提示词 2：复杂实现（组件优先）

先决条件

• Node.js（v20 或更高版本）
• Zeplin 账号。
• Zeplin 个人访问令牌。你可以在 Zeplin 个人资料的“Developer” > “Personal access tokens”中生成令牌。

安装

一键安装

Cursor 用户：

VS Code 用户：

手动安装

要开始使用 MCP 服务，首先需要配置客户端（例如 Cursor、VS Code、Windsurf、Claude Code）。大多数客户端都提供添加新 MCP 服务的选项。出现提示时，输入以下命令：

npx @zeplin/mcp-server@latest

此外，你还需要通过 ZEPLIN_ACCESS_TOKEN 环境变量提供 Zeplin 访问令牌。

例如，如果你使用 Cursor，MCP 设置应如下所示：

{
  "mcpServers": {
    "zeplin": {
      "command": "npx",
      "args": ["@zeplin/mcp-server@latest"],
      "env": {
        "ZEPLIN_ACCESS_TOKEN": "<YOUR_ZEPLIN_PERSONAL_ACCESS_TOKEN>" // Replace with your actual token
      }
    }
  }
}

开发

项目包含多个 npm 脚本，可帮助进行开发：

# Run TypeScript compiler in watch mode for development
npm run dev

# Build the project for production
npm run build

# Run ESLint on source files
npm run lint

# Automatically fix ESLint issues where possible
npm run lint:fix

# Test the MCP server locally with the inspector tool
npm run inspect

要运行 npm run inspect，请先在根目录中创建 .env 文件：

ZEPLIN_ACCESS_TOKEN=<YOUR_ZEPLIN_PERSONAL_ACCESS_TOKEN>

代码风格和 lint 检查

本项目使用 ESLint 来确保代码质量和一致性。配置位于 eslint.config.js。主要风格规范包括：

• 使用 2 个空格缩进
• 字符串使用双引号
• 必须使用分号
• 不留尾随空格
• 整理导入语句

为本项目做贡献时，请在提交更改前运行 npm run lint:fix，确保代码符合这些规范。

编写有效的提示词

提示词的质量和具体程度会显著影响 AI 生成准确且实用代码的能力。以下内容并非强制要求，但肯定能提高输出质量。

示例提示词 1：小幅修改／添加

当你需要根据新版 Zeplin 设计，对现有屏幕或组件进行小幅更新或添加时使用。

The latest design for the following screen includes a new addition: a Checkbox component has been added to the MenuItem component, here is the short url of the screen <zeplin short url of the screen, e.g., https://zpl.io/abc123X>. Focus on the MenuItem component.

The Checkbox component can be found under the path/to/your/checkbox/component directory.
The relevant screen file is located at path/to/your/screen/file.tsx.
The MenuItem component, which needs to be modified, is located at path/to/your/menuitem/component.
Please implement this new addition.

此提示词的有效之处：

• 说明变更背景： 清楚指出新增内容。
• 提供 Zeplin 链接： 让 MCP 服务能够获取最新的设计数据。
• 提供文件路径： 帮助 AI 定位要修改的现有代码。
• 指定涉及的组件： 缩小工作范围。

示例提示词 2：较大型设计（组件优先）

实现较大型的屏幕或功能时，通常最好先构建各个组件，再将它们组合起来。

Implement this component: <zeplin short url of the first component, e.g., https://zpl.io/def456Y>. Use Zeplin for design specifications.

(AI generates the first component...)

Implement this other component: <zeplin short url of the second component, e.g., https://zpl.io/ghi789Z>. Use Zeplin for design specifications.

(AI generates the second component...)

...

Now, using the components you just implemented (and any other existing components), implement the following screen: <zeplin short url of the screen, e.g., https://zpl.io/jkl012A>. Use Zeplin for the screen layout and any direct elements.

这种做法有效的原因：

• 化繁为简： 先处理较小且易于管理的部分。
• 迭代式方法： 允许在每个步骤进行审核和修正。
• 基于先前成果： AI 可以使用刚刚创建的组件。
• 清晰的 Zeplin 参考： 确保每个部分都基于正确的设计。

应对上下文窗口限制的策略

处理复杂的 Zeplin 屏幕或包含许多变体和图层的组件时，获取的设计数据有时会非常庞大。这可能超出所用 AI 模型的上下文窗口限制，导致信息被截断或代码生成效果不佳。以下是几种管理发送给模型的信息量的策略：

1. 限制屏幕变体（includeVariants: false）：

   • 工作原理： 使用 get_screen 工具时，可以指示模型仅获取 URL 链接的特定屏幕版本，而不是获取该屏幕的所有变体（例如，不同状态、尺寸、主题）。在调用工具时将 includeVariants 参数设为 false 即可。
   • 适用场景： 如果提示词只针对某个特定版本的屏幕，或者当前任务暂不涉及这些变体，就可以使用此方法。这样可以大幅减少与变体属性及其对应图层结构相关的数据量。
   • 提示词示例： “请根据此屏幕实现登录表单：https://zpl.io/abc123X。我只需要链接指向的特定版本，不需要所有变体。” 调用 get_screen 时，AI Agent 最好使用 includeVariants: false。

2. 聚焦于特定图层／组件（targetLayerName 或针对性提示词）：

   • 工作原理（使用 targetLayerName）： get_screen 工具有一个 targetLayerName 参数。如果模型能从提示词中识别出特定图层名称（例如“‘Submit Button’”），就可以使用此参数。服务随后主要返回该图层及其子图层的数据，而不是整个屏幕的图层树。
   • 工作原理（使用针对性提示词）： 即使调用工具时没有显式使用 targetLayerName，非常具体的提示词也能引导模型优先处理或总结与提及元素相关的信息。
   • 适用场景： 任务涉及较大屏幕中的特定部分时，例如单个按钮、图标或文本块。
   • 提示词示例： “请聚焦于此屏幕中的 ‘UserProfileHeader’ 组件：https://zpl.io/screenXYZ。我需要实现它的布局和文本样式。” 如果 AI 使用 get_screen，可以设置 targetLayerName: "UserProfileHeader"。

3. 迭代式、组件优先的实现：

   • 工作原理： 如示例提示词 2：较大型设计（组件优先）所述，将复杂屏幕的实现拆分为较小的组件级任务。
   • 适用场景： 任何并非简单的屏幕。此方法能自然地将每次 get_component 或 get_screen 调用的范围限制在易于管理的大小。
   • 优势： 每次对 Zeplin MCP 服务的请求都会获取更小、更聚焦的数据集，更容易控制在上下文限制内，也能让模型一次专注于一个部分。