kiyas

AI によるデザイン再現度の検証 — MCP サーバーと CLI
「comparison」—「キーアス」と発音します

---

開発者を第一に考えた MCP サーバー（CLI としても実行可能）です。Figma のデザインとレンダリングされた UI コンポーネントを比較し、AI によるセマンティックな差分を提示します。Claude Code、Cursor、Codex CLI など、MCP 対応のあらゆるクライアントと連携できます。

ピクセル差分ツールとは異なり、kiyas はビジョン AI を使って、_何が_異なり、_なぜ_重要なのかを理解します。次のような、実際に役立つ人が読みやすいフィードバックを出力します。

• 「実装では border-radius が 8px ですが、デザインでは 12px です」
• 「タイトルとサブタイトルの間隔が、デザインより 16px 狭くなっています」

コンポーネント名を説明するだけで構いません。kiyas がコードベースから該当箇所を探し、スクリーンショットを撮影して、Figma のデザインと比較します。

ターミナルよりアプリを使いたいですか？デスクトップアプリもあります。

---

デスクトップアプリ

クリック操作で同じ比較を実行できる macOS ネイティブアプリです。デザイナーや、ターミナルを使わずに済ませたい方に向けて作られています。プロジェクトを選び、Figma のリンクを貼り付ける（またはスクリーンショットをドロップする）だけで、コンポーネントを説明すれば、アプリ内で完全なレポートを確認できます。同じエンジンとサブスクリプションベースの認証を使用しており、AI の呼び出しはマシン上の Claude Code または Codex CLI を経由するため、API キーは不要です。

⬇ 最新リリースをダウンロード（Apple Silicon）

1. .dmg をダウンロードし、Kiyas を Applications にドラッグします。
2. プレビュー版はまだ公証されていません。初回起動時は、右クリックして「開く」を選択するか、xattr -dr com.apple.quarantine /Applications/Kiyas.app を実行してください。
3. 任意のターミナルで一度 Claude Code または Codex にサインインすると、アプリがその認証情報を引き継ぎます。

主な機能：開発サーバー検出機能付きのプロジェクトサイドバー、比較前のキャプチャプレビューと切り抜き、組み込みターミナル、完全なダークモード、macOS 26 の Liquid Glass アイコン。

ソースからビルドする場合：

git clone https://github.com/saiffmirza/kiyas && cd kiyas
npm install
npm run desktop        # dev mode
# or package a .app/.dmg:
cd apps/desktop && npx electron-builder --mac

---

動作の仕組み

                          ┌─────────────────────┐
                          │  kiyas               │
                          │  (MCP server / CLI)  │
                          │                      │
                          │  figma / design img  │
                          │  + target/component  │
                          └──────────┬───────────┘
                                     │
                      ┌──────────────┼──────────────┐
                      ▼              ▼               ▼
              ┌──────────────┐ ┌───────────┐ ┌─────────────┐
              │ 1. Auth      │ │ 2. Design │ │ 3. Resolve  │
              │              │ │  Capture  │ │  Component  │
              │ Verify       │ │           │ │             │
              │ Claude Code  │ │ Figma API │ │ AI agent    │
              │ or Codex CLI │ │ PNG export│ │ searches    │
              │ is installed │ │ — or your │ │ codebase,   │
              │ & signed in  │ │ own image │ │ finds URL + │
              │              │ │ (--design)│ │ CSS selector│
              └──────┬───────┘ └─────┬─────┘ └──────┬──────┘
                     │               │               │
                     │               ▼               ▼
                     │        ┌────────────┐  ┌────────────┐
                     │        │  Figma     │  │ Playwright │
                     │        │  design    │  │ screenshot │
                     │        │  (PNG)     │  │ (PNG)      │
                     │        └─────┬──────┘  └─────┬──────┘
                     │              │               │
                     │              └───────┬───────┘
                     │                      ▼
                     │          ┌──────────────────────┐
                     └─────────►│ 4. Vision AI Compare │
                                │                      │
                                │ Both images sent to  │
                                │ Claude Code CLI with │
                                │ a structured prompt   │
                                │                      │
                                │ Returns JSON array   │
                                │ of discrepancies     │
                                └──────────┬───────────┘
                                           │
                                           ▼
                                ┌──────────────────────┐
                                │ 5. HTML Report       │
                                │                      │
                                │ Side-by-side images  │
                                │ Severity badges      │
                                │ Interactive filters  │
                                │ HIGH / MEDIUM / LOW  │
                                │                      │
                                │ file:// link in      │
                                │ terminal output      │
                                └──────────────────────┘

手順：

1. 認証 — kiyas は AI の呼び出しを Claude Code または Codex CLI に委任します。既存のサブスクリプションですべて処理されるため、API キーは不要です。
2. デザイン画像の取得 — Figma の URL を解析し、Figma REST API を呼び出してフレームを PNG として書き出します（スクリーンショットと同じスケール。--scale を参照）。さらに、ノードのメタデータ（色、フォント、間隔）を取得します。または、Figma をまったく使わず、--design <path-or-url> に独自のデザイン画像を渡すこともできます。この場合、Figma トークンは不要です。
3. コンポーネントの特定 — AI エージェントがコードベース（ファイルツリー、ルート、コンポーネント）をスキャンし、自然言語による説明を、開発サーバー上の URL と CSS セレクターに対応付けます。
4. 実装のスクリーンショット撮影 — Playwright がヘッドレス Chromium を起動し、特定した URL に移動してコンポーネントをキャプチャします。
5. AI による比較 — 2 つの PNG を、構造化されたプロンプトとともに Claude Code CLI に渡します。AI は具体的な CSS プロパティと値を示しながら、すべての相違点を特定します。
6. レポート — 結果は、画像の並列比較、重大度バッジ、インタラクティブなフィルターを備えた HTML レポートとして整形されます。簡単にアクセスできるよう、ファイルへのリンクがターミナルに表示されます。

---

MCP サーバーとして使用

kiyas は、比較エンジンを stdio 経由の MCP サーバーとして公開します。Zod で型付けされた入力スキーマを持つツールが 3 つあります。

ツール	説明	必須の入力
compare	デザインと実装を新たに比較し、reportId と概要を返します	(figma または designImage) + (target または component)
get_diff_report	保存済みレポートの HTML または JSON コンテンツを取得します	reportId
list_issues	保存済みレポートの差異を一覧表示します。重大度による絞り込みも可能です	reportId

レポートはプロジェクトディレクトリ内の .kiyas/reports/<reportId>/ に保存されるため、同じ reportId は呼び出し間や CLI／MCP の利用間でも有効です。

インストール

npm install -g kiyas-cli
npx playwright install chromium

接続する

Claude Code

claude mcp add kiyas -- npx -y kiyas-cli@latest mcp

# with a Figma token (only needed for Figma-URL comparisons):
claude mcp add kiyas -e FIGMA_ACCESS_TOKEN=figd_xxx -- npx -y kiyas-cli@latest mcp

kiyas は公式の MCP Registry にも io.github.saiffmirza/kiyas として登録されているため、レジストリに対応したクライアントは MCP カタログから直接インストールできます。

Cursor — ~/.cursor/mcp.json を編集します。

{
  "mcpServers": {
    "kiyas": {
      "command": "npx",
      "args": ["kiyas-cli@latest", "mcp"]
    }
  }
}

Codex CLI — ~/.codex/config.toml を編集します。

[mcp_servers.kiyas]
command = "npx"
args    = ["kiyas-cli@latest", "mcp"]

最新の状態を保つ

上記の設定では kiyas-cli@latest を使用しているため、npx は起動のたびに新しいリリースを取得します。その代わり、起動ごとにレジストリを確認する必要があり、オフラインでは起動に失敗する場合があります。バージョンを固定する（[email protected]）か、グローバルインストールを使用しても問題ありません。kiyas は起動時に一度だけ npm を確認し（ブロックしません）、新しいバージョンがある場合は stderr に通知を出力します。

MCP ユーザー向けの Figma アクセス

compare ツールで Figma アクセスが必要なのは、figma URL を渡す場合のみです。アクセス方法は 3 つあります。

1. サーバー設定でトークンを渡す（推奨）：

claude mcp add kiyas -e FIGMA_ACCESS_TOKEN=<your-token> -- npx -y kiyas-cli@latest mcp

または、.mcp.json／mcp.json／config.toml に env ブロックを追加します。

{
  "mcpServers": {
    "kiyas": {
      "command": "npx",
      "args": ["kiyas-cli@latest", "mcp"],
      "env": { "FIGMA_ACCESS_TOKEN": "your-token" }
    }
  }
}

2. プロジェクトルートまたはホームディレクトリに .kiyasrc ファイルを置く：{ "figmaAccessToken": "..." }

3. トークンを使わず、Figma MCP サーバーと連携する。 エージェントがすでに Figma 独自の MCP サーバーに接続されている場合、エージェント自身でフレームを画像としてエクスポートし、figma URL の代わりにファイルパス（または画像 URL）を designImage として渡せます。このモードでは、kiyas が Figma API にアクセスすることはありません。

Figma ファイルからノード 1:234 を PNG としてエクスポートし、kiyas を使ってログインページのプライマリボタンと比較してください。

figma URL を使用しているのにトークンが設定されていない場合、ツールは待機し続けず、これらの手順を表示してすぐに失敗します。

接続したら、次のようにエージェントに依頼できます。

<url> の Figma フレームをログインページのプライマリボタンと比較し、重大度の高い問題だけを一覧表示してください。

エージェントは compare を呼び出して reportId を生成し、その ID を使って severity: "high" を指定し list_issues を呼び出します。

---

クイックスタート（CLI）

前提条件

• Node.js 20 以降
• Claude Code がインストールされ、サインイン済みであること（Pro、Max、または Team のサブスクリプション）、または OpenAI の場合は Codex
• Figma の個人用アクセストークン（こちらで生成）— --figma を使用する場合のみ必要です。ローカルのスクリーンショットを --design で比較する場合、トークンは不要です。

インストール

npm install -g kiyas-cli
npx playwright install chromium

セットアップ

kiyas setup

次の項目を設定します。

1. Figma トークン — 読み取り専用の個人用アクセストークンを作成し、.env に保存します
2. AI プロバイダー — Claude Code または Codex を確認し、デフォルトを設定します

実行

# Describe the component by name — kiyas finds it automatically
kiyas --figma "https://www.figma.com/design/abc123/Design?node-id=1:234" \
  --component "eventHeader on the redemption screen"

# Or provide a direct URL if you already know it
kiyas --figma "https://www.figma.com/design/abc123/Design?node-id=1:234" \
  --target "http://localhost:3000/redemption" \
  --selector ".event-header"

# Save the report to a specific path
kiyas --figma "https://www.figma.com/design/abc123/Design?node-id=1:234" \
  --component "primary button" \
  --output report.html

# Output as JSON (for CI pipelines)
kiyas --figma "https://www.figma.com/design/abc123/Design?node-id=1:234" \
  --component "primary button" \
  --format json

# Compare against a design screenshot instead of Figma (no Figma token needed)
kiyas --design ./design.png \
  --component "primary button" \
  --output report.html

# Use OpenAI instead of Claude
kiyas --figma "https://www.figma.com/design/abc123/Design?node-id=1:234" \
  --component "nav bar" \
  --model openai

---

CLI リファレンス

フラグ	説明	必須
--figma <url>	Figma フレーム／コンポーネントの URL	はい**
--design <path>	Figma の代わりに使用するデザイン画像（ローカルパスまたは URL）	はい**
--component <description>	検索するコンポーネントの自然言語による説明	はい*
--target <url>	レンダリング済みコンポーネントの直接 URL（AI による検索をスキップ）	はい*
--dev-server <url>	開発サーバーのベース URL（デフォルト：3000/5173/8080/4200 を自動検出）	いいえ
--model <provider>	AI プロバイダー：claude（デフォルト）または openai	いいえ
--output <path>	レポートの保存先（デフォルト：kiyas-report-<timestamp>.html）	いいえ
--format <type>	出力形式：html（デフォルト）または json	いいえ
--viewport <size>	スクリーンショットのビューポートサイズ（デフォルト：1280x720）	いいえ
--scale <n>	Figma のエクスポートとスクリーンショットの両方に適用するレンダリング倍率。デフォルトは自動調整：コンポーネントサイズのキャプチャ（セレクター、またはビューポートが 1000px 以下）では 2、大きな全ページキャプチャでは 1	いいえ
--no-full-page	スクロール可能なページ全体ではなく、ビューポートのみをキャプチャします	いいえ
--selector <css>	特定の要素をスクリーンショットするための CSS セレクター	いいえ
--wait <ms>	スクリーンショット撮影前の待機時間（ミリ秒、アニメーション／読み込み用）	いいえ
--auth-state <path>	認証済みスクリーンショット用の Playwright storageState JSON	いいえ
--config <path>	一括比較用の JSON 設定ファイルのパス	いいえ
--threshold <level>	重大度フィルター：all、medium、high（デフォルト：all）	いいえ

*--component または --target のいずれかを指定してください。--component を使用すると、kiyas は AI を使ってコードベース内のコンポーネントを検索し、URL を特定します。

**--figma または --design のいずれかを指定してください。--design を指定すると、Figma のエクスポートは完全にスキップされ、Figma トークンも不要です。

---

認証済みスクリーンショット

実際のデザインの多くは、ログインが必要な場所にあります。kiyas は Playwright の storageState JSON ファイル（Cookie と localStorage）を受け付け、スクリーンショットのセッションで再利用します。Playwright のテストで使用するものと同じ形式なので、テストで既に生成されている認証状態ファイルをそのまま使用できます。

# 1. Record a session — log in, then close the browser. Playwright writes auth.json.
npx playwright codegen --save-storage=auth.json https://app.example.com

# 2. Use it for kiyas screenshots
kiyas \
  --figma "https://www.figma.com/design/.../?node-id=1:234" \
  --target "https://app.example.com/dashboard" \
  --auth-state ./auth.json

MCP の compare ツールにも同じオプションがあり、authState として公開されています。パスを渡すと、エージェントは追加の設定なしで認証済みビューのスクリーンショットを撮影します。

---

認証

kiyas は既存の AI サブスクリプションを利用するため、別途 API キーを用意する必要はありません。すべての AI 呼び出しを Claude Code または Codex の CLI に委譲し、それぞれの CLI が独自に認証を処理します。

Claude（デフォルト）： Claude Code をインストールし、Pro、Max、または Team のサブスクリプションでサインインする必要があります。kiyas は AI の呼び出しに claude CLI を起動するため、使用量は既存のサブスクリプションの利用枠に加算されます。

# Install Claude Code if you haven't already
npm install -g @anthropic-ai/claude-code

# Sign in
claude auth login

OpenAI（代替）： Codex をインストールし、サインインする必要があります。選択するには --model openai を使用します。

codex auth login

CLI が見つからない場合、kiyas はインストールとサインインを促します。

Claude Code is not installed or not signed in.

kiyas uses your existing Claude Code subscription — no API keys needed.

To fix this, either:

  1. Install and sign into Claude Code:
     npm install -g @anthropic-ai/claude-code
     claude auth login

  2. Or switch kiyas to use OpenAI instead:
     kiyas set model openai
     (requires signing into Codex: codex auth login)

Figma： File content → Read only スコープを持つ個人用アクセストークンが必要です。kiyas setup を実行して設定するか、.env に FIGMA_ACCESS_TOKEN を手動で設定してください。

---

精度と再現性

kiyasはビジョンAIを取り巻くハーネスであり、ハーネスは結果が一貫していて初めて役に立ちます。kiyasが制御する内容は次のとおりです。

• モデルの固定 — 比較モデルと解決モデルを固定し（claude --model / codex -m）、CLIのデフォルト設定によって変動しないようにします。kiyas set claudeModel <id> / kiyas set codexModel <id> で設定できます。
• AIコンテキストの分離 — 比較は空の作業ディレクトリで実行されるため、プロジェクトの CLAUDE.md / AGENTS.md、フック、MCP サーバーが出力に影響することはありません。
• キャプチャ環境の固定 — アニメーションとトランジションを無効にし、フォントの読み込みを待機し、タイムゾーンをUTCに、ロケールを固定し、ページ全体のスクリーンショットを撮影します。また、Figmaのエクスポート倍率は常にスクリーンショットのデバイススケールファクターに一致します。コンポーネントサイズのキャプチャはデフォルトで2倍です。評価セットで測定したところ、これにより微細な変更の再現率が75%から90%に向上しました。
• 出力の検証 — モデルの応答はスキーマに照らして検証されます（形式が不正な指摘は警告とともに破棄されます。無効な応答が過半数を占める場合は、誤ったレポートを気づかれないまま生成するのではなく、実行を失敗させます）。
• 実行マニフェスト — 各レポートのJSONには、ビューポート、倍率、しきい値、固定されたモデル、CLIのバージョン、プロンプトのバージョンハッシュ、および --component の説明がどのように解決されたかが記録されるため、2つのレポートを有意義に比較できます。
• 複数回実行での投票 — --runs 3 を指定すると、比較を3回並行して実行し、過半数の投票で選ばれた指摘のみを信頼度スコア付きで残します。コストはN倍になりますが、一貫性が高まります。デフォルトでは無効です。
• 感覚ではなく測定 — npm run eval（リポジトリ専用で、配布物には含まれません）は、既知のCSS変更を注入したフィクスチャページと変更のないペアからなるゴールデン評価セットを実行します。再現率、適合率、重大度の一致、誤検知率の下限、実行間の安定性を決定論的にスコア化します。プロンプトやパイプラインの変更は、この評価セットに照らして検証されます。

---

設定ファイル

比較を繰り返し実行するチームは、kiyas.config.json を作成してください。

{
  "figmaAccessToken": "env:FIGMA_ACCESS_TOKEN",
  "model": "claude",
  "viewport": "1280x720",
  "comparisons": [
    {
      "name": "Primary Button",
      "figma": "https://www.figma.com/design/abc123/Design?node-id=1:234",
      "target": "primary button on the login page"
    },
    {
      "name": "Event Card",
      "figma": "https://www.figma.com/design/abc123/Design?node-id=5:678",
      "target": "http://localhost:6006/iframe.html?id=card--event",
      "selector": ".event-card"
    }
  ]
}

target フィールドには、コンポーネントの説明（AIによって解決）と直接指定するURLのどちらも使用できます。各比較では、デザインのソースとして figma（URL）または design（ローカルの画像パス）のいずれかを指定します。次のように実行します。

kiyas --config ./kiyas.config.json

---

プロジェクト構成

kiyas/  (npm workspaces monorepo)
├── packages/
│   ├── core/                       # @kiyas/core — the engine (private, bundled into the CLI)
│   │   └── src/
│   │       ├── index.ts            # Public API barrel (runComparison, resolveComponent, …)
│   │       ├── config.ts           # Config file loading + Figma token resolution
│   │       ├── settings.ts         # Persisted user settings
│   │       ├── auth/
│   │       │   ├── index.ts        # Auth resolver (picks best available auth)
│   │       │   ├── claude-oauth.ts # Verify Claude Code CLI is available
│   │       │   └── openai-auth.ts  # Verify Codex CLI is available
│   │       ├── resolve/
│   │       │   └── component.ts    # AI agent: finds component in codebase → URL + selector
│   │       ├── capture/
│   │       │   ├── figma.ts        # Figma REST API: export frame as PNG + metadata
│   │       │   └── playwright.ts   # Playwright: headless screenshot of rendered component
│   │       ├── compare/
│   │       │   ├── index.ts        # Orchestrator: sends images to vision AI
│   │       │   ├── pipeline.ts     # Pure runComparison() + report persistence (shared by CLI + MCP)
│   │       │   ├── claude.ts       # Claude comparison via Claude Code CLI
│   │       │   ├── openai.ts       # OpenAI comparison via Codex CLI
│   │       │   └── prompt.ts       # The comparison prompt (shared across providers)
│   │       ├── report/
│   │       │   └── html.ts         # Generate self-contained HTML report with embedded images
│   │       └── utils/
│   │           ├── parse-figma-url.ts  # Extract file key + node ID from Figma URL
│   │           └── logger.ts       # Minimal logging utility
│   └── cli/                        # kiyas-cli — the published npm package
│       ├── src/
│       │   ├── index.ts            # CLI entry point (argument parsing, orchestration)
│       │   ├── setup.ts            # Interactive first-time setup
│       │   └── mcp/
│       │       ├── server.ts       # MCP server bootstrap (stdio transport)
│       │       └── tools.ts        # Zod schemas + handlers (compare, get_diff_report, list_issues)
│       ├── package.json
│       └── tsup.config.ts
├── apps/
│   └── desktop/                    # @kiyas/desktop — Electron app (macOS)
│       ├── src/
│       │   ├── main/               # Main process: IPC, capture flow, pty terminal
│       │   ├── preload/            # Typed context bridge (window.kiyas)
│       │   └── renderer/           # React UI (cream/navy/gold theme, dark mode)
│       ├── build/kiyas.icon        # Icon Composer bundle (Liquid Glass icon source)
│       ├── scripts/gen-icon.mjs    # Renders all icon variants from the Farisi kāf
│       └── electron-builder.yml
├── eval/                           # Golden eval set + scoring harness
├── .env.example
├── .kiyasrc.example
├── package.json                    # Workspace root
└── tsconfig.json

---

技術スタック

レイヤー	ツール
ランタイム	Node.js（TypeScript）
MCP	@modelcontextprotocol/sdk、Zod（stdioトランスポート）
スクリーンショット撮影	Playwright（ヘッドレスChromium）
Figmaエクスポート	Figma REST API
AI比較	Claude Code CLIまたはCodex CLI（ビジョン）
コンポーネント解決	Claude Code CLI / Codex CLI（エージェント）
出力	HTML（デフォルト）、JSON
デスクトップアプリ	Electron、electron-vite、React、node-pty + xterm
ビルド	tsup、electron-builder
パッケージマネージャー	npm

---

ライセンス

MIT