@zeplin/mcp-server 0.2.0

package/README.md

@@ -0,0 +1,195 @@
+# Zeplin MCP Server for AI-Assisted UI Implementation
+
+This project implements a Model Context Protocol (MCP) server designed to assist developers in implementing UI screens and components directly from Zeplin designs. By providing Zeplin shortlinks (e.g., `https://zpl.io/...`) in your prompts to AI agents, this server fetches the necessary design specifications and asset details, enabling the models to generate corresponding code for your target framework.
+
+The primary goal is to streamline the developer workflow by bridging the gap between design specifications in Zeplin and actual code implementation.
+
+## Table of Contents
+
+- [Features](#features)
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Development](#development)
+- [Usage with MCP Clients (e.g., Cursor)](#usage-with-mcp-clients-eg-cursor)
+- [Crafting Effective Prompts](#crafting-effective-prompts)
+  - [Example Prompt 1: Minor Changes/Additions](#example-prompt-1-minor-changesadditions)
+  - [Example Prompt 2: Complex Implementations (Component-First)](#example-prompt-2-complex-implementations-component-first)
+
+## Features
+
+*   **Seamless Zeplin Integration**: Fetch detailed design data for components and screens using simple Zeplin URLs (including `zpl.io` shortlinks).
+*   **Code Generation Ready**: Provides AI models with structured data for conciseness and relevance.
+*   **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.
+*   **Targeted Implementation**: Facilitates implementation of entire screens or individual components, including their variants, layers, and annotations, directly from Zeplin specifications.
+
+## Prerequisites
+
+*   [Node.js](https://nodejs.org/) (v20.x or later recommended)
+*   A Zeplin account.
+*   A Zeplin Personal Access Token (PAT). You can generate one from your Zeplin profile settings under "Developer" > "Personal access tokens". This token will need `read` permissions for the projects/styleguides you want to access.
+
+## Installation
+
+1.  **Clone the repository:**
+    ```bash
+    git clone https://github.com/zeplin/zeplin-mcp.git
+    ```
+
+2.  **Install dependencies:**
+    Using npm:
+    ```bash
+    npm install
+    ```
+
+3.  **Build the project:**
+    The TypeScript code needs to be compiled to JavaScript. Assuming you have a build script in your `package.json` (e.g., `tsc` or `esbuild`):
+    ```bash
+    npm run build
+    ```
+
+    This will typically create a `dist` directory with the compiled JavaScript files (e.g., `dist/index.js`).
+
+## Configuration
+
+Create a `.env` file in the root directory of the project with the following content:
+
+```bash
+ZEPLIN_ACCESS_TOKEN=your_zeplin_personal_access_token
+```
+
+Replace `your_zeplin_personal_access_token` with your actual Zeplin Personal Access Token.
+
+## Development
+
+This project includes several npm scripts to help you with development:
+
+```bash
+# 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
+```
+
+### Code Style and Linting
+
+This project uses ESLint to enforce code quality and consistency. The configuration is in `eslint.config.js`. Key style guidelines include:
+
+- 2 space indentation
+- Double quotes for strings
+- Semicolons required
+- No trailing spaces
+- Organized imports
+
+When contributing to this project, please ensure your code follows these guidelines by running `npm run lint:fix` before submitting changes.
+
+## Usage with MCP Clients (e.g., Cursor)
+
+To integrate this server with an MCP client like Cursor, you need to configure the client to connect to this server. Add the following to Cursor's `settings.json` (accessible via `Cmd/Ctrl + Shift + P` -> "Configure Language Specific Settings..." -> "JSON") or a similar configuration file for MCP providers:
+
+```jsonc
+// In your MCP client's configuration (e.g., Cursor's settings.json)
+{
+  // ... other configurations
+  "mcpServers": {
+    // ... other providers
+    "zeplin-mcp": {
+      "command": "node",
+      "args": [
+        "/path/to/your/zeplin-mcp/dist/index.js" // IMPORTANT: Update this path
+      ],
+      "env": {
+        "ZEPLIN_ACCESS_TOKEN": "<YOUR_ZEPLIN_PERSONAL_ACCESS_TOKEN>" // IMPORTANT: Replace with your actual token
+      }
+    }
+    // ...
+  }
+  // ...
+}
+```
+
+**Important:**
+*   Replace `"/path/to/your/zeplin-mcp/dist/index.js"` with the **absolute path** to the compiled `index.js` file in your `zeplin-mcp` project directory.
+*   Replace `<YOUR_ZEPLIN_PERSONAL_ACCESS_TOKEN>` with your actual Zeplin PAT.
+
+## Crafting Effective Prompts
+
+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 increase the output quality. Here are some examples to guide you:
+
+### Example Prompt 1: Minor Changes/Additions
+
+When you need to implement a small update or addition to an existing screen or component based on a new Zeplin design version.
+
+```
+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.
+```
+
+**Why this is effective:**
+*   **Contextualizes the change:** Clearly states what's new.
+*   **Provides the Zeplin link:** Allows the MCP server to fetch the latest design data.
+*   **Gives file paths:** Helps the AI locate existing code to modify.
+*   **Specifies components involved:** Narrows down the scope of work.
+
+### Example Prompt 2: Complex Implementations (Component-First)
+
+For implementing larger screens or features, it's often best to build individual components first and then assemble them.
+
+```
+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.
+```
+
+**Why this is effective:**
+
+* **Breaks down complexity:** Tackles smaller, manageable pieces first.
+* **Iterative approach:** Allows for review and correction at each step.
+* **Builds on previous work:** The AI can use the components it just created.
+* **Clear Zeplin references:** Ensures each piece is based on the correct design.
+
+
+
+### Strategies to deal with context window limitations
+
+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:
+
+1.  **Limit Screen Variants (`includeVariants: false`):**
+    *   **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.
+    *   **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.
+    *   **Example Prompt Hint:** "Implement the login form from this screen: `https://zpl.io/abc123X`. I only need the specific version linked, not all its variants."
+        *The AI agent, when calling `get_screen`, should then ideally use `includeVariants: false`.*
+
+2.  **Focus on Specific Layers/Components (`targetLayerName` or Targeted Prompts):**
+    *   **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.
+    *   **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.
+    *   **When to use:** When your task involves a specific part of a larger screen, like a single button, an icon, or a text block.
+    *   **Example Prompt:** "Focus on the 'UserProfileHeader' component within this screen: `https://zpl.io/screenXYZ`. I need to implement its layout and text styles."
+        *If the AI uses `get_screen`, it could populate `targetLayerName: "UserProfileHeader"`.*
+
+3.  **Iterative, Component-First Implementation:**
+    *   **How it works:** As detailed in [Example Prompt 2: Complex Implementations (Component-First)](#example-prompt-2-complex-implementations-component-first), break down the implementation of a complex screen into smaller, component-sized tasks.
+    *   **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.
+    *   **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/clients/zeplinApi.js

@@ -0,0 +1,74 @@
+import { ZeplinApi, Configuration } from "@zeplin/sdk";
+import { pruneLayersForTargetLayer } from "../utils/api-utils.js";
+import { preProcess, preProcessDesignTokens } from "../utils/preprocessing.js";
+/**
+ * Initialize the Zeplin API client
+ */
+export const api = new ZeplinApi(new Configuration({ accessToken: process.env.ZEPLIN_ACCESS_TOKEN }));
+/**
+ * Fetches design tokens for a project
+ * @param projectId The ID of the project
+ * @returns The design tokens data
+ */
+export async function fetchProjectDesignTokens(projectId) {
+    const designTokens = await api.designTokens.getProjectDesignTokens(projectId, { includeLinkedStyleguides: true });
+    return {
+        designTokens: preProcessDesignTokens(designTokens.data),
+    };
+}
+/**
+ * Fetches design tokens for a styleguide
+ * @param styleguideId The ID of the styleguide
+ * @returns The design tokens data
+ */
+export async function fetchStyleguideDesignTokens(styleguideId) {
+    const designTokens = await api.designTokens.getStyleguideDesignTokens(styleguideId, { includeLinkedStyleguides: true });
+    return {
+        designTokens: preProcessDesignTokens(designTokens.data),
+    };
+}
+/**
+ * Processes screen versions and annotations to create screen variants
+ * @param projectId The project ID
+ * @param screenIds Array of screen IDs
+ * @param variantNames Array of variant names
+ * @param targetLayerName Optional layer name to extract
+ * @returns Array of processed screen variants
+ */
+export async function processScreenVersionsAndAnnotations(projectId, screenIds, variantNames, targetLayerName) {
+    const screenVersionResponses = await Promise.all(screenIds.map(async (screenId) => {
+        const response = await api.screens.getLatestScreenVersion(projectId, screenId);
+        const processedData = preProcess(response.data);
+        return {
+            ...response,
+            data: processedData
+        };
+    }));
+    const screenAnnotationsResponse = await Promise.all(screenIds.map((screenId) => api.screens.getScreenAnnotations(projectId, screenId)));
+    const screenAnnotations = screenAnnotationsResponse.map((response, index) => {
+        const annotations = response.data;
+        const screenVersion = screenVersionResponses[index];
+        return annotations.map((annotation) => ({
+            type: annotation.type.name,
+            text: annotation.content,
+            position: {
+                x: annotation.position.x * (screenVersion.data.width || 0),
+                y: annotation.position.y * (screenVersion.data.height || 0),
+            },
+        }));
+    });
+    return screenVersionResponses.map((response, index) => {
+        const screenVersion = response.data;
+        // If targetLayerName is provided, prune the layers.
+        // Otherwise, use all layers from the screenVersion.
+        const layersToInclude = targetLayerName
+            ? pruneLayersForTargetLayer(screenVersion.layers || [], targetLayerName)
+            : screenVersion.layers || [];
+        return {
+            name: variantNames[index],
+            annotations: screenAnnotations[index],
+            layers: layersToInclude,
+            assets: screenVersion.assets,
+        };
+    });
+}

package/dist/constants.js

@@ -0,0 +1,61 @@
+export const INSTRUCTIONS = `**Role:** You are an expert front-end developer tasked with generating code from a design specification provided as structured data.
+
+    **Goal:** Generate clean, maintainable, and accurate [Specify Target Framework/Language, e.g., React with Tailwind CSS / SwiftUI / HTML & CSS] code based on the provided **design specification (which could be a Zeplin Component or a Zeplin Screen)**.
+
+    **Inputs:**
+    1.  **Design Data (JSON):** This structured data represents either a Zeplin Component or a Zeplin Screen.
+        *   For **Screens**, it typically includes an overall screen name, variants (if any), screen-level annotations, and a list of layers for each variant.
+        *   For **Components**, it includes the component's name, its variants (each with potential \`props\` like \`variantProperties\` and \`layers\`), or a single component structure with its layers.
+        *   Use this JSON for specific details: text \`content\`, \`component_name\` for identifying sub-components/instances, explicit color/typography values (to be mapped to tokens), layer structure, and \`annotations\`.
+
+    **Core Instructions:**
+
+    1.  **Determine Input Type:**
+        *   First, analyze the top-level structure of the provided JSON. Determine if it represents a **Zeplin Component definition** (e.g., the JSON might have a top-level \`component\` object, or a \`name\` and \`variants\` array where variants have \`props\` or \`variantProperties\`) or a **Zeplin Screen definition** (e.g., the JSON describes a screen with its own \`name\`, \`variants\`, \`layers\`, and \`annotations\`).
+
+    2.  **If the Input is a Zeplin Component Definition:**
+        *   Your primary goal is to generate the code that **defines this component**.
+        *   The component definition should accept parameters/props based on any \`props\` or \`variantProperties\` found in the JSON for the component or its variants.
+        *   If multiple \`variants\` are detailed for the component, the generated code should allow the component to render these different states, typically controlled via its props.
+        *   The internal structure of the component will be derived from its \`layers\` (see "Processing Layers" below).
+
+    3.  **Processing Layers (applies when rendering a Screen OR defining the internal structure of a Component):**
+        *   When iterating through the \`layers\` array found in the JSON (whether for a screen or for a component you are defining):
+            *   **a. Component Instance Prioritization:**
+                *   If a layer in the JSON has a \`component_name\` field, this indicates an instance of another component. **Strictly prioritize** using an existing component from the (optional) provided codebase context that matches this \`component_name\`.
+                *   Extract necessary props for this component instance from its text content, styling, or nested layers.
+                *   **Do NOT** generate new code for the children/internal structure of this identified component instance; assume the referenced component encapsulates that.
+                *   If a matching component is not found in the codebase context, clearly note this (e.g., in comments) and generate a plausible placeholder or a basic structure based on its layer data.
+            *   **b. Layout & Positioning:**
+                *   Derive layout and structure from the **Layer Data JSON**.
+                *   Use flexible layout techniques ([e.g., Flexbox, Grid, StackViews, AutoLayout]) appropriate for the target framework.
+                *   **Avoid hardcoding pixel dimensions or absolute positions.** Use relative units, spacing tokens, or layout containers that adapt. Layer \`rect\` data in the JSON is a guide, not a rigid spec.
+            *   **c. Styling:**
+                *   **Design Tokens First:** When styling elements based on color (e.g., from a layer's fills like color: {r:38, g:43, b:46, a:1}) or typography (e.g., from textStyles like fontFamily: "Graphik", fontSize: 16, fontWeight: 500), your first priority is to find a matching design token.
+                *   Consult Input JSON \`designTokens\`: Look for a token within the designTokens section of the provided input JSON. Match based on the value of the token. For example, if a layer has color: {r:38, g:43, b:46, a:1}, search for a color token whose value is rgb(38, 43, 46). If a text layer uses fontFamily: "Graphik", fontSize: 13, fontWeight: 500, search for a text style token whose value includes these font properties.
+                *   Codebase Context (Fallback): If no direct match is found in the input JSON's designTokens, then attempt to map them to existing design tokens or variables from the provided codebase context.
+                *   Raw Values (Last Resort): If no matching token is found in either the input JSON's designTokens or the codebase context, use the specific value from the JSON layer data but add a comment indicating a potential token is missing. For example:
+                    // TODO: Use design token for color rgba(38, 43, 46, 1)
+                    // TODO: Use design token for font: Graphik, 16px, 500w, letterSpacing 0.16
+            *   **d. Content & Assets:**
+                *   Use exact text \`content\` provided in the JSON data for labels, headings, paragraphs, etc.
+                *   For images or icons identified in the JSON (e.g., via \`layer_name\` or \`component_name\` like "Omlet logo", "GitHub logo"), first search for them in the codebase and use them if they already exist.
+                *   If not found, use the \`download_asset\` tool to download the relevant asset. The URL of the asset is located at the \`assets\` section of the JSON data. Use \`layer_source_id\` and \`layer_name\` to match which layers are using the asset.
+                *   If the asset is not found in the codebase context and if the download fails as a last resort create a basic structure based on its layer data.
+
+    4.  **Annotations:**
+        *   If the JSON includes an \`annotations\` field (either at the screen level or potentially associated with layers if the pre-processing step adds them there), treat its contents as **critical overrides or specific instructions** that MUST be followed, potentially contradicting other layers or visual representation.
+
+    5.  **Code Conventions & Brevity:**
+        *   Follow existing naming conventions (variables, functions) if codebase context is provided. Otherwise, use clear, descriptive names.
+        *   Be concise. Omit default HTML/CSS/framework attributes or styles. Generate only the necessary code to represent the design elements. Do not include boilerplate unless explicitly part of the component structure.
+
+    6.  **Output Format:**
+        *   Generate code for [Specify Target: e.g., a single React functional component, a SwiftUI View struct, a block of HTML with associated CSS].
+        *   If the input JSON was identified as a Zeplin Component definition, the output should be the code that **defines that component**, making it usable and configurable based on its properties and variants.
+        *   If the input JSON was identified as a Zeplin Screen definition, the output should represent the **entire screen**, likely as a larger component or a composition of elements and other (potentially imported) components.
+        *   Ensure the code is well-formatted and syntactically correct.
+
+    **Constraint:** Only use information present in the provided Design Data JSON, and any explicitly provided codebase context. Do not invent features or functionality not represented in the inputs.
+
+    **Now, analyze the provided Design Data (JSON), and generate the code according to these instructions.**`;

package/dist/index.js

@@ -0,0 +1,253 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { api, fetchProjectDesignTokens, fetchStyleguideDesignTokens, processScreenVersionsAndAnnotations } from "./clients/zeplinApi.js";
+import { INSTRUCTIONS } from "./constants.js";
+import { assetRegistry } from "./utils/asset-registry.js";
+import { getAssetUrl, downloadAsset } from "./utils/asset-utils.js";
+import { createErrorResponse, createSuccessResponse } from "./utils/response-utils.js";
+import { resolveUrl, URL_PATTERNS } from "./utils/url-utils.js";
+/**
+ * Fetches and processes screen data from Zeplin
+ * @param url The resolved Zeplin screen URL
+ * @param includeVariants Whether to include variants in the response
+ * @param targetLayerName Optional name of layer to extract layer data for
+ * @returns Formatted response object with screen data or error message
+ */
+export async function getScreenData(url, includeVariants, targetLayerName) {
+    const match = url.match(URL_PATTERNS.SCREEN);
+    if (!match) {
+        return createErrorResponse("Screen link is not valid — here's the expected format: https://app.zeplin.io/project/{projectId}/screen/{screenId}");
+    }
+    const [_, projectId, screenId] = match;
+    try {
+        // Reset the asset registry to clear any previous assets
+        assetRegistry.reset();
+        const screenResponse = await api.screens.getScreen(projectId, screenId);
+        const screen = screenResponse.data;
+        let name;
+        let screenIds;
+        let variantNames;
+        if (screen.variant && includeVariants) {
+            const variantGroupId = screen.variant.group.id;
+            const variantGroupResponse = await api.screens.getScreenVariant(projectId, variantGroupId);
+            const variantGroup = variantGroupResponse.data;
+            name = variantGroup.name;
+            screenIds = variantGroup.variants
+                .map((variant) => variant.screenId)
+                .filter((id) => id !== undefined);
+            variantNames = variantGroup.variants
+                .map((variant) => variant.value)
+                .filter((name) => name !== undefined);
+        }
+        else {
+            name = screen.name || "Unnamed Screen";
+            screenIds = [screenId];
+            variantNames = [screen.name || "Unnamed Screen"];
+        }
+        const variants = await processScreenVersionsAndAnnotations(projectId, screenIds, variantNames, targetLayerName);
+        // Register assets for future lookups but don't include them in the response
+        variants.forEach(variant => {
+            if (variant.assets && variant.assets.length > 0) {
+                assetRegistry.registerAssets(variant.assets.filter(asset => asset.contents));
+            }
+        });
+        const designTokens = await fetchProjectDesignTokens(projectId);
+        const screenData = {
+            type: "Screen",
+            name,
+            variants: variants.map(variant => ({
+                name: variant.name,
+                annotations: variant.annotations,
+                layers: variant.layers
+                // Assets are intentionally omitted
+            })),
+            designTokens: designTokens.designTokens
+        };
+        return createSuccessResponse(screenData, INSTRUCTIONS);
+    }
+    catch (error) {
+        return createErrorResponse(`Failed to fetch screen data: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Fetches and processes component data from Zeplin
+ * @param url The resolved Zeplin component URL
+ * @returns Formatted response object with component data or error message
+ */
+export async function getComponentData(url) {
+    let match = url.match(URL_PATTERNS.COMPONENT);
+    let isProjectComponent = false;
+    if (!match) {
+        match = url.match(URL_PATTERNS.PROJECT_STYLEGUIDE_COMPONENT);
+        isProjectComponent = true;
+    }
+    if (!match) {
+        return createErrorResponse("Component link is not valid. Expected formats: https://app.zeplin.io/styleguide/{styleguideId}/component/{componentId} or https://app.zeplin.io/project/{projectId}/styleguide/component/{componentId}");
+    }
+    try {
+        assetRegistry.reset();
+        let componentResponse;
+        let styleguideId;
+        let projectId;
+        let componentId;
+        if (isProjectComponent) {
+            [, projectId, componentId] = match;
+            componentResponse = await api.components.getProjectComponent(projectId, componentId, { includeLatestVersion: true });
+        }
+        else {
+            [, styleguideId, componentId] = match;
+            componentResponse = await api.components.getStyleguideComponent(styleguideId, componentId, { includeLatestVersion: true });
+        }
+        const designTokens = isProjectComponent && projectId
+            ? await fetchProjectDesignTokens(projectId)
+            : styleguideId
+                ? await fetchStyleguideDesignTokens(styleguideId)
+                : undefined;
+        const component = componentResponse.data;
+        const sectionId = component.section?.id;
+        // Register assets for future lookups but don't include them in the response
+        if (component.latestVersion?.assets) {
+            assetRegistry.registerAssets(component.latestVersion.assets.filter(asset => asset.contents));
+        }
+        if (!sectionId || !styleguideId) {
+            const sanitizedComponent = JSON.parse(JSON.stringify(component));
+            if (sanitizedComponent.latestVersion && "assets" in sanitizedComponent.latestVersion) {
+                delete sanitizedComponent.latestVersion.assets;
+            }
+            const response = { component: sanitizedComponent };
+            return createSuccessResponse(response, INSTRUCTIONS);
+        }
+        const sectionsResponse = await api.components.getStyleguideComponentSections(styleguideId);
+        const sections = sectionsResponse.data;
+        const section = sections.find((s) => s.id === sectionId);
+        if (!section) {
+            const sanitizedComponent = JSON.parse(JSON.stringify(component));
+            if (sanitizedComponent.latestVersion && "assets" in sanitizedComponent.latestVersion) {
+                delete sanitizedComponent.latestVersion.assets;
+            }
+            const response = { component: sanitizedComponent };
+            return createSuccessResponse(response, INSTRUCTIONS);
+        }
+        const sectionComponentsResponse = await api.components.getStyleguideComponents(styleguideId, {
+            sectionId,
+            includeLatestVersion: true,
+        });
+        const sectionComponents = sectionComponentsResponse.data;
+        sectionComponents.forEach(componentVariant => {
+            if (componentVariant.latestVersion?.assets) {
+                assetRegistry.registerAssets(componentVariant.latestVersion.assets.filter(asset => asset.contents));
+            }
+        });
+        const componentData = {
+            name: section.name,
+            variants: sectionComponents.map((componentVariant) => {
+                return {
+                    name: componentVariant.name,
+                    props: componentVariant.variantProperties?.map((property) => ({
+                        name: property.name,
+                        value: property.value,
+                    })),
+                    layers: componentVariant.latestVersion?.layers,
+                    // Assets are intentionally omitted
+                };
+            }),
+            designTokens: designTokens?.designTokens,
+        };
+        return createSuccessResponse(componentData, INSTRUCTIONS);
+    }
+    catch (error) {
+        return createErrorResponse(`Failed to fetch component data: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+// Initialize the MCP server
+const server = new McpServer({
+    name: "Zeplin MCP Server",
+    version: "0.1.0",
+});
+// Register the get_component tool
+server.tool("get_component", "Fetches detailed design specifications for a specific Zeplin component, including its properties, variants, layers, and associated design tokens. Use this when you need to understand the structure and styling of a single, reusable UI element from Zeplin.", {
+    url: z.string().url(),
+}, async ({ url }) => {
+    try {
+        const resolvedUrl = await resolveUrl(url.trim());
+        return await getComponentData(resolvedUrl);
+    }
+    catch (error) {
+        return createErrorResponse(`Error resolving or processing URL: ${error instanceof Error ? error.message : String(error)}`);
+    }
+});
+// Register the get_screen tool
+server.tool("get_screen", "Fetches detailed design data for a specific screen from Zeplin. This includes screen variants, layer information (structure, position, styling), annotations, and project-level design tokens. Use this to understand screen layout, content, and interactions for development or review.", {
+    url: z.string().url(),
+    includeVariants: z.boolean().default(true)
+        .describe("Set to `true` (default) to retrieve all variants of the screen (e.g., different states or sizes). Set to `false` if only the specific screen version linked in the URL is needed, or to conserve tokens if variants are not relevant to the user's query. Fetching all variants provides a complete picture but uses more tokens."),
+    targetLayerName: z.string().optional()
+        .describe("Optional. If the user's query refers to a specific named layer or element on the screen (e.g., 'the submit button', 'user profile image'), provide that layer's exact name here. This will focus the returned data on that specific layer and its children, making the response more concise and relevant. If omitted or the layer name is not found, data for all layers on the screen will be returned."),
+}, async ({ url, includeVariants, targetLayerName }) => {
+    try {
+        const resolvedUrl = await resolveUrl(url.trim());
+        return await getScreenData(resolvedUrl, includeVariants, targetLayerName);
+    }
+    catch (error) {
+        return createErrorResponse(`Error resolving or processing URL: ${error instanceof Error ? error.message : String(error)}`);
+    }
+});
+// Register the download_layer_asset tool
+server.tool("download_layer_asset", "Downloads a specific visual asset (e.g., SVG icon, PNG image) for a given layer from Zeplin and saves it to a local path. Use this tool when an asset referenced in the design (obtained from `get_screen` or `get_component`) is missing from the codebase and needs to be fetched directly from Zeplin.", {
+    layerSourceId: z.string()
+        .describe("The unique source ID of the layer for which the asset should be downloaded. This ID is obtained from the `layers` array in the response of `get_screen` or `get_component` calls, from a `sourceId` or similar field associated with a specific layer that has exportable assets"),
+    localPath: z.string()
+        .describe("The absolute path to the directory where images/assets are stored in the project. If the directory does not exist, it will be created. The format of this path should respect the directory format of the operating system you are running on. Don't use any special character escaping in the path name either."),
+    assetType: z.enum(["svg", "png", "pdf", "jpg"])
+        .describe("The desired format of the asset to download. Must be one of 'svg', 'png', 'jpg', or 'pdf'. Choose the format most suitable for the project's needs or as indicated by design specifications. If unsure, 'svg' is often preferred for vector graphics and 'png' for bitmaps."),
+}, async ({ layerSourceId, localPath, assetType }) => {
+    const assetUrl = getAssetUrl(layerSourceId, assetType);
+    if (!assetUrl) {
+        return createErrorResponse(`No asset found with layer source ID: ${layerSourceId} and format ${assetType}`);
+    }
+    return await downloadAsset(assetUrl, localPath);
+});
+server.tool("get_design_tokens", "Download design tokens for a project or styleguide", {
+    resourceId: z.string()
+        .describe("The ID of the project or styleguide for which the design tokens should be downloaded."),
+}, async ({ resourceId }) => {
+    let projectDesignTokens = null;
+    let styleguideDesignTokens = null;
+    let projectError = null;
+    let styleguideError = null;
+    try {
+        projectDesignTokens = await fetchProjectDesignTokens(resourceId);
+    }
+    catch (error) {
+        projectError = error;
+    }
+    try {
+        styleguideDesignTokens = await fetchStyleguideDesignTokens(resourceId);
+    }
+    catch (error) {
+        styleguideError = error;
+    }
+    // If both failed, return an error
+    if (!projectDesignTokens && !styleguideDesignTokens) {
+        const errorMessage = `No design tokens found for project or styleguide with ID: ${resourceId}`;
+        if (projectError && styleguideError) {
+            return createErrorResponse(`${errorMessage}. Project error: ${projectError instanceof Error ? projectError.message : String(projectError)}. Styleguide error: ${styleguideError instanceof Error ? styleguideError.message : String(styleguideError)}`);
+        }
+        return createErrorResponse(errorMessage);
+    }
+    return createSuccessResponse({
+        projectDesignTokens,
+        styleguideDesignTokens,
+    }, INSTRUCTIONS);
+});
+// Start the server
+try {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+catch (error) {
+    console.error(`Failed to start MCP server: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/api-utils.js

@@ -0,0 +1,50 @@
+/**
+ * Recursively searches for a component with the given name in the layer tree
+ * and returns the layer, its parent, and path to the component
+ * @param layers Array of layers to search through
+ * @param targetLayerName Name of the component to find
+ * @param parentLayer Optional parent layer reference
+ * @param path Optional path to the current position in the tree
+ * @returns Object containing found status, layer, parent layer, and path
+ */
+export function findTargetLayer(layers, targetLayerName, parentLayer = null, path = []) {
+    if (!layers || !Array.isArray(layers)) {
+        return { found: false, layer: null, parentLayer: null, path: [] };
+    }
+    for (const layer of layers) {
+        if (layer.componentName === targetLayerName || layer.name === targetLayerName) {
+            return { found: true, layer, parentLayer, path: [...path, layer] };
+        }
+        if (layer.layers && Array.isArray(layer.layers)) {
+            const result = findTargetLayer(layer.layers, targetLayerName, layer, [...path, layer]);
+            if (result.found) {
+                return result;
+            }
+        }
+    }
+    return { found: false, layer: null, parentLayer: null, path: [] };
+}
+/**
+ * Prunes layers data to only include the target component, its immediate parent, and all of its children.
+ * @param layers The full layers array from a screen version.
+ * @param targetLayerName The name of the layer/component to find and keep.
+ * @returns Pruned layer array containing only relevant layers
+ */
+export function pruneLayersForTargetLayer(layers, targetLayerName) {
+    if (!targetLayerName) {
+        return layers;
+    }
+    if (!Array.isArray(layers)) {
+        return [];
+    }
+    const { found, layer: targetLayer, parentLayer } = findTargetLayer(layers, targetLayerName);
+    if (!found || !targetLayer) {
+        return [];
+    }
+    if (parentLayer) {
+        return [parentLayer];
+    }
+    else {
+        return [targetLayer];
+    }
+}

package/dist/utils/asset-registry.js

@@ -0,0 +1,79 @@
+/**
+ * Registry for assets that can be looked up by layerSourceId
+ */
+class AssetRegistry {
+    assetRecords = new Map();
+    /**
+     * Resets the asset registry
+     */
+    reset() {
+        this.assetRecords.clear();
+    }
+    /**
+     * Registers an asset in the registry
+     * @param asset The asset to register
+     */
+    registerAsset(asset) {
+        if (!asset.layerSourceId || !asset.contents) {
+            return;
+        }
+        const record = {
+            displayName: asset.displayName,
+            layerName: asset.layerName,
+            contents: asset.contents.map(content => ({
+                format: content.format,
+                url: content.url
+            }))
+        };
+        this.assetRecords.set(asset.layerSourceId, record);
+    }
+    /**
+     * Registers multiple assets in the registry
+     * @param assets The assets to register
+     */
+    registerAssets(assets) {
+        assets.forEach(asset => this.registerAsset(asset));
+    }
+    /**
+     * Gets an asset record by its layer source ID
+     * @param layerSourceId The layer source ID
+     * @returns The asset record or undefined if not found
+     */
+    getAssetRecord(layerSourceId) {
+        return this.assetRecords.get(layerSourceId);
+    }
+    /**
+     * Gets the URL for a specific format of an asset
+     * @param layerSourceId The layer source ID
+     * @param format The desired format
+     * @returns The URL or undefined if not found
+     */
+    getAssetUrl(layerSourceId, format) {
+        const record = this.assetRecords.get(layerSourceId);
+        if (!record)
+            return undefined;
+        const content = record.contents.find(c => c.format === format);
+        return content?.url;
+    }
+    /**
+     * Extracts asset information from component, screen, or variant data
+     * @param data The data containing assets
+     */
+    extractAssetsFromData(data) {
+        if (!data)
+            return;
+        // Extract from variants
+        if (Array.isArray(data.variants)) {
+            data.variants.forEach((variant) => {
+                if (variant.assets && Array.isArray(variant.assets)) {
+                    this.registerAssets(variant.assets.filter((asset) => asset.contents));
+                }
+            });
+        }
+        // Extract from component
+        if (data.component?.latestVersion?.assets) {
+            this.registerAssets(data.component.latestVersion.assets.filter((asset) => asset.contents));
+        }
+    }
+}
+export const assetRegistry = new AssetRegistry();

package/dist/utils/asset-utils.js

@@ -0,0 +1,78 @@
+import * as fs from "fs/promises";
+import fetch from "node-fetch";
+import * as path from "path";
+import { assetRegistry } from "./asset-registry.js";
+import { createErrorResponse, createResponse } from "./response-utils.js";
+/**
+ * Finds an asset by its source ID from the asset registry
+ * @param sourceId The source ID to search for
+ * @returns Object containing the asset URL and information or undefined
+ */
+export function findAssetById(sourceId) {
+    const record = assetRegistry.getAssetRecord(sourceId);
+    if (!record || record.contents.length === 0)
+        return undefined;
+    return {
+        url: record.contents[0].url,
+        format: record.contents[0].format,
+        displayName: record.displayName
+    };
+}
+/**
+ * Gets a downloadable asset URL for the specified format
+ * @param sourceId The source ID of the asset
+ * @param format The desired file format
+ * @returns The URL or undefined if not available
+ */
+export function getAssetUrl(sourceId, format) {
+    return assetRegistry.getAssetUrl(sourceId, format);
+}
+/**
+ * Removes assets from response data to reduce payload size
+ * @param data The data to sanitize
+ * @returns The data with assets removed
+ */
+export function sanitizeResponse(data) {
+    if (!data)
+        return data;
+    assetRegistry.extractAssetsFromData(data);
+    const result = JSON.parse(JSON.stringify(data));
+    if (Array.isArray(result.variants)) {
+        result.variants.forEach((variant) => {
+            delete variant.assets;
+        });
+    }
+    if (result.component?.latestVersion) {
+        delete result.component.latestVersion.assets;
+    }
+    return result;
+}
+/**
+ * Downloads an asset from a URL and saves it to the specified local directory
+ * @param assetUrl The URL of the asset to download
+ * @param localDir The local directory path to save the asset
+ * @returns Response with download status or error message
+ */
+export async function downloadAsset(assetUrl, localDir) {
+    try {
+        const url = new URL(assetUrl);
+        const urlPath = url.pathname;
+        const fileExtension = path.extname(urlPath) || ".png";
+        const assetId = path.basename(urlPath, fileExtension);
+        await fs.mkdir(localDir, { recursive: true });
+        const fileName = assetId + fileExtension;
+        const filePath = path.join(localDir, fileName);
+        const response = await fetch(assetUrl);
+        if (!response.ok) {
+            return createErrorResponse(`Failed to download asset: Server responded with ${response.status}`);
+        }
+        const buffer = await response.arrayBuffer();
+        await fs.writeFile(filePath, Buffer.from(buffer));
+        return createResponse({
+            message: `Asset successfully downloaded to ${filePath}`
+        });
+    }
+    catch (error) {
+        return createErrorResponse(`Failed to download asset: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}

package/dist/utils/index.js

@@ -0,0 +1,13 @@
+/**
+ * Central export file for all utilities
+ */
+// Asset utilities
+export * from "./asset-utils.js";
+// URL utilities
+export * from "./url-utils.js";
+// API utilities
+export * from "./api-utils.js";
+// Preprocessing utilities
+export * from "./preprocessing.js";
+// Response utilities
+export * from "./response-utils.js";

package/dist/utils/preprocessing.js

@@ -0,0 +1,101 @@
+/**
+ * Preprocess a screen object to remove unnecessary information
+ * @param screen The screen object to preprocess
+ * @returns The processed screen object
+ */
+export function preProcessScreen(screen) {
+    return preProcess(screen);
+}
+/**
+ * Preprocess a design tokens object to remove metadata
+ * @param designTokens The design tokens to preprocess
+ * @returns The processed design tokens
+ */
+export function preProcessDesignTokens(designTokens) {
+    const processedTokens = preProcess(designTokens);
+    return removeMetadata(processedTokens);
+}
+/**
+ * Generic preprocessing function that removes unnecessary properties from objects
+ * @param data The data to preprocess
+ * @returns Processed data with unnecessary properties removed
+ */
+export function preProcess(data) {
+    if (Array.isArray(data)) {
+        return data
+            .map(item => preProcess(item))
+            .filter(item => {
+            if (Array.isArray(item) && item.length === 0)
+                return false;
+            return true;
+        });
+    }
+    else if (data !== null && typeof data === "object") {
+        const result = {};
+        // Skip unnecessary properties
+        const propsToSkip = new Set(["created", "creator", "thumbnails", "id"]);
+        const defaultValues = new Map([
+            ["opacity", 1],
+            ["blend_mode", "normal"],
+            ["rotation", 0]
+        ]);
+        for (const [key, value] of Object.entries(data)) {
+            if (propsToSkip.has(key))
+                continue;
+            if (defaultValues.has(key) && defaultValues.get(key) === value)
+                continue;
+            let processedValue;
+            if (key === "contents" && Array.isArray(value)) {
+                const itemsToKeep = value.filter(originalContentItem => {
+                    if (originalContentItem && typeof originalContentItem === "object" && originalContentItem !== null && "density" in originalContentItem) {
+                        return originalContentItem.density === 1;
+                    }
+                    if (Array.isArray(originalContentItem) && originalContentItem.length === 0) {
+                        return false;
+                    }
+                    return true;
+                });
+                processedValue = itemsToKeep.map(keptItem => preProcess(keptItem))
+                    .filter(processedItem => {
+                    if (Array.isArray(processedItem) && processedItem.length === 0) {
+                        return false;
+                    }
+                    return true;
+                });
+            }
+            else {
+                processedValue = preProcess(value);
+            }
+            if (Array.isArray(processedValue) && processedValue.length === 0) {
+                continue;
+            }
+            result[key] = processedValue;
+        }
+        return result;
+    }
+    else {
+        return data;
+    }
+}
+/**
+ * Removes metadata from design tokens
+ * @param obj Object containing design tokens
+ * @returns Object with metadata removed
+ */
+function removeMetadata(obj) {
+    if (Array.isArray(obj)) {
+        return obj.map(removeMetadata);
+    }
+    else if (obj !== null && typeof obj === "object") {
+        const result = {};
+        for (const [key, value] of Object.entries(obj)) {
+            if (key === "metadata")
+                continue;
+            result[key] = removeMetadata(value);
+        }
+        return result;
+    }
+    else {
+        return obj;
+    }
+}

package/dist/utils/response-utils.js

@@ -0,0 +1,59 @@
+/**
+ * Creates an error response with consistent formatting
+ * @param message Error message to display
+ * @returns Formatted error response
+ */
+export function createErrorResponse(message) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: message,
+            },
+        ],
+        isError: true,
+    };
+}
+/**
+ * Creates a success response with consistent formatting
+ * @param data The data to include in the response
+ * @param instructionsTemplate The template for instructions to include
+ * @returns Formatted success response
+ */
+export function createSuccessResponse(data, instructionsTemplate) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: `${instructionsTemplate}
+
+              ${typeof data === "string" ? data : `${data.type || ""} data in JSON format:
+              ${JSON.stringify(data, null, 2)}`}`,
+            },
+        ],
+    };
+}
+/**
+ * Creates a generic response based on provided options
+ * @param options Response options including message, error status, and data
+ * @returns Formatted API response
+ */
+export function createResponse(options) {
+    const content = [];
+    if (options.message) {
+        content.push({
+            type: "text",
+            text: options.message
+        });
+    }
+    if (options.data && typeof options.data !== "string" && !options.isError) {
+        content.push({
+            type: "text",
+            text: JSON.stringify(options.data, null, 2)
+        });
+    }
+    return {
+        content,
+        isError: options.isError
+    };
+}

package/dist/utils/url-utils.js

@@ -0,0 +1,34 @@
+/**
+ * URL patterns for different Zeplin resource types
+ */
+export const URL_PATTERNS = {
+    COMPONENT: /^https:\/\/app\.zeplin\.io\/styleguide\/([^/]+)\/component\/([^/]+)/,
+    PROJECT_STYLEGUIDE_COMPONENT: /^https:\/\/app\.zeplin\.io\/project\/([^/]+)\/styleguide\/component\/([^/]+)/,
+    SCREEN: /^https:\/\/app\.zeplin\.io\/project\/([^/]+)\/screen\/([^/]+)/
+};
+/**
+ * Resolves a Zeplin shortlink to its full URL
+ * @param url The URL or shortlink to resolve
+ * @returns The resolved URL
+ */
+export async function resolveUrl(url) {
+    if (!url.startsWith("https://zpl.io/")) {
+        return url;
+    }
+    try {
+        const response = await fetch(url, {
+            method: "GET",
+            headers: {
+                "Accept": "application/json"
+            },
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to resolve URL: ${response.status} ${response.statusText}`);
+        }
+        const data = await response.json();
+        return data.url;
+    }
+    catch (error) {
+        throw new Error(`Failed to resolve URL: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@zeplin/mcp-server",
+  "version": "0.2.0",
+  "description": "An MCP server for Zeplin for AI assisted UI development.",
+  "author": "Zeplin",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zeplin/mcp-server.git"
+  },
+  "homepage": "https://github.com/zeplin/mcp-server#readme",
+  "bugs": {
+    "url": "https://github.com/zeplin/mcp-server/issues"
+  },
+  "keywords": [
+    "zeplin",
+    "design",
+    "mcp",
+    "model context protocol",
+    "ai"
+  ],
+  "bin": {
+    "zeplin-mcp-server": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "scripts": {
+    "dev": "tsc -w",
+    "build": "tsc",
+    "lint": "eslint --ext .ts src",
+    "lint:fix": "eslint --ext .ts --fix src",
+    "inspect": "source .env && npx @modelcontextprotocol/inspector -e ZEPLIN_ACCESS_TOKEN=$ZEPLIN_ACCESS_TOKEN node dist/index.js",
+    "prepublishOnly": "npm run lint && npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.10.2",
+    "@zeplin/sdk": "^1.25.0",
+    "node-fetch": "^3.3.2",
+    "zod": "^3.24.3"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.27.0",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.14.1",
+    "@typescript-eslint/eslint-plugin": "^8.32.1",
+    "@typescript-eslint/parser": "^8.32.1",
+    "eslint": "^9.27.0",
+    "eslint-plugin-import": "^2.31.0",
+    "globals": "^16.1.0",
+    "typescript": "^5.8.3"
+  }
+}