Zeplin MCP Server for AI-Assisted UI Implementation

Zeplin MCP サーバー：AI 支援による UI 開発

Cursor、Windsurf、VS Code（Copilot を使用）などの AI エージェントを Zeplin に接続します。MCP サーバーを使うことで、AI エージェントは次の情報を利用できます。

• コンポーネントと画面の仕様： コンポーネントと画面全体の詳細な仕様およびアセットを利用でき、デザインに忠実な UI コードの生成に役立ちます。
• ドキュメント： 画面に追加された注釈を通じて、動作の仕方や実装のヒントなど、補足情報を提供します。これにより、エージェントは静的なビジュアルにとどまらず、実際のインタラクションを構築できます。
• デザイントークン： プロジェクト全体で使用されている色、タイポグラフィ、間隔、その他のデザイン変数を利用できるため、エージェントは既存のトークンを可能な限り再利用できます。

目次

• 前提条件
• インストール
• 設定
• 開発
• 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 つを使用
• 文字列には二重引用符を使用
• セミコロンを必須とする
• 行末にスペースを残さない
• import を整理する

このプロジェクトに貢献する際は、変更を提出する前に 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。すべてのバリエーションではなく、リンク先の特定のバージョンだけが必要です。」 AI エージェントが get_screen を呼び出す際には、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 サーバーへの各リクエストで、より小さく焦点を絞ったデータセットを取得できます。コンテキストの制限内に収めやすくなるうえ、モデルが一度に一つの要素に集中できるようになります。