@zeplin/mcp-server 1.0.1 → 1.0.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +62 -60
- package/dist/index.js +14 -7
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,10 +1,13 @@
|
|
|
1
|
-
# Zeplin MCP
|
|
1
|
+
# Zeplin MCP server: AI-assisted UI development
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Connect AI agents like Cursor, Windsurf, and VS Code (w/ Copilot) to Zeplin. Using the MCP server, AI agents can tap into:
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
- **Component and screen specs:** Detailed specs and assets for both components and entire screens — helping agents generate UI code that closely matches the designs.
|
|
6
|
+
- **Documentation:** Annotations added to screens that provide extra context, like how things should behave or tips for implementation — letting the agent go beyond static visuals and build real interactions.
|
|
7
|
+
- **Design tokens:** Colors, typography, spacing, and other design variables used across the project, so your agent can reuse existing tokens where possible.
|
|
8
|
+
|
|
9
|
+
## Table of contents
|
|
6
10
|
|
|
7
|
-
- [Features](#features)
|
|
8
11
|
- [Prerequisites](#prerequisites)
|
|
9
12
|
- [Installation](#installation)
|
|
10
13
|
- [Configuration](#configuration)
|
|
@@ -14,38 +17,36 @@ This project is a Model Context Protocol server designed to assist developers in
|
|
|
14
17
|
- [Example Prompt 1: Minor Changes/Additions](#example-prompt-1-minor-changesadditions)
|
|
15
18
|
- [Example Prompt 2: Complex Implementations (Component-First)](#example-prompt-2-complex-implementations-component-first)
|
|
16
19
|
|
|
17
|
-
## Features
|
|
18
|
-
|
|
19
|
-
* **Seamless Zeplin Integration**: Fetch detailed design data for components and screens using simple Zeplin URLs (including `zpl.io` shortlinks).
|
|
20
|
-
* **Code Generation Ready**: Provides AI models with structured data for conciseness and relevance.
|
|
21
|
-
* **Asset Handling**: Automatically identifies and provides information for assets within designs. AI agents can then decide to download these assets (SVG, PNG, PDF, JPG) as needed for implementation.
|
|
22
|
-
* **Targeted Implementation**: Facilitates implementation of entire screens or individual components, including their variants, layers, and annotations, directly from Zeplin specifications.
|
|
23
|
-
|
|
24
20
|
## Prerequisites
|
|
25
21
|
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
22
|
+
- [Node.js](https://nodejs.org/) (v20 or later)
|
|
23
|
+
- A Zeplin account.
|
|
24
|
+
- A Zeplin personal access token. You can generate one from your Zeplin profile, under "Developer" > "Personal access tokens".
|
|
29
25
|
|
|
30
26
|
## Installation
|
|
31
27
|
|
|
32
|
-
###
|
|
28
|
+
### Cursor one-click installation
|
|
33
29
|
|
|
34
|
-
[](https://cursor.com/install-mcp?name=zeplin
|
|
30
|
+
[](https://cursor.com/install-mcp?name=zeplin&config=eyJjb21tYW5kIjoibnB4IC15IEB6ZXBsaW4vbWNwLXNlcnZlckBsYXRlc3QiLCJlbnYiOnsiWkVQTElOX0FDQ0VTU19UT0tFTiI6IiJ9fQ%3D%3D)
|
|
35
31
|
|
|
36
32
|
### Manual installation
|
|
37
33
|
|
|
38
|
-
To
|
|
34
|
+
To start using the MCP server, you first need to configure your client (e.g. Cursor, VS Code, Windsurf, Claude Code). Most clients have an option to add a new MCP server. When prompted, enter the following command:
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
npx @zeplin/mcp-server@latest
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
In addition, you also need to provide your Zeplin access token using the `ZEPLIN_ACCESS_TOKEN` environment variable.
|
|
41
|
+
|
|
42
|
+
For example, if you’re using Cursor, here’s how your MCP settings should look like:
|
|
39
43
|
|
|
40
44
|
```jsonc
|
|
41
|
-
// In your MCP client's configuration (e.g., Cursor's settings.json)
|
|
42
45
|
{
|
|
43
46
|
"mcpServers": {
|
|
44
|
-
"zeplin
|
|
47
|
+
"zeplin": {
|
|
45
48
|
"command": "npx",
|
|
46
|
-
"args": [
|
|
47
|
-
"@zeplin/mcp-server@latest"
|
|
48
|
-
],
|
|
49
|
+
"args": ["@zeplin/mcp-server@latest"],
|
|
49
50
|
"env": {
|
|
50
51
|
"ZEPLIN_ACCESS_TOKEN": "<YOUR_ZEPLIN_PERSONAL_ACCESS_TOKEN>" // Replace with your actual token
|
|
51
52
|
}
|
|
@@ -56,7 +57,7 @@ To integrate this server with an MCP client, you need to configure the client to
|
|
|
56
57
|
|
|
57
58
|
## Development
|
|
58
59
|
|
|
59
|
-
|
|
60
|
+
The project includes several npm scripts to help with development:
|
|
60
61
|
|
|
61
62
|
```bash
|
|
62
63
|
# Run TypeScript compiler in watch mode for development
|
|
@@ -75,15 +76,13 @@ npm run lint:fix
|
|
|
75
76
|
npm run inspect
|
|
76
77
|
```
|
|
77
78
|
|
|
78
|
-
|
|
79
|
+
To run `npm run inspect`, create an `.env` file first in the root directory:
|
|
79
80
|
|
|
80
81
|
```bash
|
|
81
|
-
ZEPLIN_ACCESS_TOKEN
|
|
82
|
+
ZEPLIN_ACCESS_TOKEN=<YOUR_ZEPLIN_PERSONAL_ACCESS_TOKEN>
|
|
82
83
|
```
|
|
83
84
|
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
### Code Style and Linting
|
|
85
|
+
### Code style and linting
|
|
87
86
|
|
|
88
87
|
This project uses ESLint to enforce code quality and consistency. The configuration is in `eslint.config.js`. Key style guidelines include:
|
|
89
88
|
|
|
@@ -95,11 +94,11 @@ This project uses ESLint to enforce code quality and consistency. The configurat
|
|
|
95
94
|
|
|
96
95
|
When contributing to this project, please ensure your code follows these guidelines by running `npm run lint:fix` before submitting changes.
|
|
97
96
|
|
|
98
|
-
## Crafting
|
|
97
|
+
## Crafting effective prompts
|
|
99
98
|
|
|
100
|
-
The quality and specificity of your prompts significantly impact the AI
|
|
99
|
+
The quality and specificity of your prompts significantly impact the AI’s ability to generate accurate and useful code. These are not mandatory but will definitely increase the output quality.
|
|
101
100
|
|
|
102
|
-
### Example
|
|
101
|
+
### Example prompt 1: Minor changes/additions
|
|
103
102
|
|
|
104
103
|
When you need to implement a small update or addition to an existing screen or component based on a new Zeplin design version.
|
|
105
104
|
|
|
@@ -112,15 +111,16 @@ The MenuItem component, which needs to be modified, is located at path/to/your/m
|
|
|
112
111
|
Please implement this new addition.
|
|
113
112
|
```
|
|
114
113
|
|
|
115
|
-
|
|
116
|
-
* **Contextualizes the change:** Clearly states what's new.
|
|
117
|
-
* **Provides the Zeplin link:** Allows the MCP server to fetch the latest design data.
|
|
118
|
-
* **Gives file paths:** Helps the AI locate existing code to modify.
|
|
119
|
-
* **Specifies components involved:** Narrows down the scope of work.
|
|
114
|
+
Why this is effective:
|
|
120
115
|
|
|
121
|
-
|
|
116
|
+
- **Contextualizes the change:** Clearly states what’s new.
|
|
117
|
+
- **Provides the Zeplin link:** Allows the MCP server to fetch the latest design data.
|
|
118
|
+
- **Gives file paths:** Helps the AI locate existing code to modify.
|
|
119
|
+
- **Specifies components involved:** Narrows down the scope of work.
|
|
122
120
|
|
|
123
|
-
|
|
121
|
+
### Example prompt 2: Larger designs (Component-first)
|
|
122
|
+
|
|
123
|
+
For implementing larger screens or features, it’s often best to build individual components first and then assemble them.
|
|
124
124
|
|
|
125
125
|
```
|
|
126
126
|
Implement this component: <zeplin short url of the first component, e.g., https://zpl.io/def456Y>. Use Zeplin for design specifications.
|
|
@@ -136,31 +136,33 @@ Implement this other component: <zeplin short url of the second component, e.g.,
|
|
|
136
136
|
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.
|
|
137
137
|
```
|
|
138
138
|
|
|
139
|
-
|
|
139
|
+
Why this is effective:
|
|
140
140
|
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
141
|
+
- **Breaks down complexity:** Tackles smaller, manageable pieces first.
|
|
142
|
+
- **Iterative approach:** Allows for review and correction at each step.
|
|
143
|
+
- **Builds on previous work:** The AI can use the components it just created.
|
|
144
|
+
- **Clear Zeplin references:** Ensures each piece is based on the correct design.
|
|
145
145
|
|
|
146
146
|
### Strategies to deal with context window limitations
|
|
147
147
|
|
|
148
148
|
When dealing with complex Zeplin screens or components with many variants and layers, the amount of design data fetched can sometimes be extensive. This can potentially exceed the context window limitations of the AI model you are using, leading to truncated information or less effective code generation. Here are several strategies to manage the amount of information sent to the model:
|
|
149
149
|
|
|
150
|
-
1. **Limit
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
150
|
+
1. **Limit screen variants (`includeVariants: false`):**
|
|
151
|
+
|
|
152
|
+
- **How it works:** When using the `get_screen` tool, the model can be instructed to fetch only the specific screen version linked in the URL, rather than all its variants (e.g., different states, sizes, themes). This is done by setting the `includeVariants` parameter to `false` during the tool call.
|
|
153
|
+
- **When to use:** If your prompt is focused on a single specific version of a screen, or if the variants are not immediately relevant to the task at hand. This significantly reduces the amount of data related to variant properties and their respective layer structures.
|
|
154
|
+
- **Example prompt:** “Implement the login form from this screen: `https://zpl.io/abc123X`. I only need the specific version linked, not all its variants.”
|
|
155
|
+
_The AI agent, when calling `get_screen`, should then ideally use `includeVariants: false`._
|
|
156
|
+
|
|
157
|
+
2. **Focus on specific layers/components (`targetLayerName` or targeted prompts):**
|
|
158
|
+
|
|
159
|
+
- **How it works (using `targetLayerName`):** The `get_screen` tool has a `targetLayerName` parameter. If the model can identify a specific layer name from your prompt (e.g., "the 'Submit Button'"), it can use this parameter. The server will then return data primarily for that layer and its children, rather than the entire screen's layer tree.
|
|
160
|
+
- **How it works (targeted prompts):** Even without explicitly using `targetLayerName` in the tool call, very specific prompts can guide the model to internally prioritize or summarize information related to the mentioned element.
|
|
161
|
+
- **When to use:** When your task involves a specific part of a larger screen, like a single button, an icon, or a text block.
|
|
162
|
+
- **Example prompt:** “Focus on the 'UserProfileHeader' component within this screen: `https://zpl.io/screenXYZ`. I need to implement its layout and text styles.”
|
|
163
|
+
_If the AI uses `get_screen`, it could populate `targetLayerName: "UserProfileHeader"`._
|
|
164
|
+
|
|
165
|
+
3. **Iterative, component-first implementation:**
|
|
166
|
+
- **How it works:** As detailed in [Example prompt 2: Larger designs (Component-first)](#example-prompt-2-larger-designs-component-first), break down the implementation of a complex screen into smaller, component-sized tasks.
|
|
167
|
+
- **When to use:** For any non-trivial screen. This approach naturally limits the scope of each `get_component` or `get_screen` call to a manageable size.
|
|
168
|
+
- **Benefit:** Each request to the Zeplin MCP server will fetch a smaller, more focused dataset, making it easier to stay within context limits and allowing the model to concentrate on one piece at a time.
|
package/dist/index.js
CHANGED
|
@@ -33,13 +33,20 @@ export async function getScreenData(url, includeVariants, targetLayerName) {
|
|
|
33
33
|
const variantGroupId = screen.variant.group.id;
|
|
34
34
|
const variantGroupResponse = await api.screens.getScreenVariant(projectId, variantGroupId);
|
|
35
35
|
const variantGroup = variantGroupResponse.data;
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
36
|
+
if (variantGroup) {
|
|
37
|
+
name = variantGroup.name;
|
|
38
|
+
screenIds = variantGroup.variants
|
|
39
|
+
.map((variant) => variant.screenId)
|
|
40
|
+
.filter((id) => id !== undefined);
|
|
41
|
+
variantNames = variantGroup.variants
|
|
42
|
+
.map((variant) => variant.value)
|
|
43
|
+
.filter((name) => name !== undefined);
|
|
44
|
+
}
|
|
45
|
+
else {
|
|
46
|
+
name = screen.name || "Unnamed Screen";
|
|
47
|
+
screenIds = [screenId];
|
|
48
|
+
variantNames = [screen.name || "Unnamed Screen"];
|
|
49
|
+
}
|
|
43
50
|
}
|
|
44
51
|
else {
|
|
45
52
|
name = screen.name || "Unnamed Screen";
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@zeplin/mcp-server",
|
|
3
|
-
"version": "1.0.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "1.0.3",
|
|
4
|
+
"description": "Zeplin’s official MCP server for AI-assisted UI development",
|
|
5
5
|
"author": "Zeplin",
|
|
6
6
|
"license": "MIT",
|
|
7
7
|
"repository": {
|