/setup-pencil

description: "Lesson command"
duration: "約15分"
prerequisites: ["ブラウザが使える", "Claude Code または Cursor が導入済み"]
level: "beginner"
tags: ["setup", "pencil", "mcp", "design"]
nonInteractiveMode: incompatible

Pencil MCP セットアップ

Step 0: セットアップ進捗の確認

**AIが自動実行する内容:** 1. `uv run python tools/setup_progress.py show --current setup-pencil` を実行して進捗を表示 2. 既存の設定を自動検出:

• Claude Code の場合: `~/.claude/mcp_settings.json` に `pencil` サーバーが定義されているか確認
• Cursor の場合: `.cursor/mcp.json` に `pencil` サーバーが定義されているか確認
• 設定済みの場合、Step 4（接続テスト）のみ実行して完了にできる

このセッションでやること

| 項目 | 内容 | |------|------| | ゴール | Pencil デスクトップアプリをインストールし、MCP サーバー経由で Claude Code/Cursor からデザインファイル（.pen）を操作できるようにする | | 所要時間 | 約15分 | | 前提条件 | ブラウザが使えること、Claude Code または Cursor が導入済みであること | | 操作レベル | アプリインストール + MCP設定（AIが自動支援） |

**このセッションの流れ:** 1. Pencil デスクトップアプリをダウンロード・インストール 2. Pencil アプリを起動して初期設定 3. MCP設定ファイルに Pencil サーバーを追加 4. MCP接続テスト

> **ヒント**: AIの応答が途中で止まった場合は「続きを表示して」「止まってるよ」と入力すると再開します。

---

準備チェック

**AskQuestionの設定:**

{
  "title": "セッション開始前の確認",
  "questions": [{
    "id": "readiness",
    "prompt": "準備はできていますか？",
    "options": [
      {"id": "ready", "label": "準備OK！始めましょう"},
      {"id": "check_prereq", "label": "前提条件を確認したい"},
      {"id": "already_installed", "label": "Pencilは既にインストール済み"},
      {"id": "different_lesson", "label": "別のレッスンに移動したい"}
    ]
  }]
}

(ready → Step 1へ) (check_prereq → 「Claude Code または Cursor が導入済みであれば準備OKです」と案内) (already_installed → Step 3（MCP設定）へスキップ) (different_lesson → モジュール一覧を表示)

---

Step 1: Pencil デスクトップアプリのダウンロード

**AIが実行すること:** 1. OSを自動判定する（Mac / Windows / Linux） 2. ブラウザで Pencil ダウンロードページを開く:

# Mac:
open https://pencil.evolves.dev/download
# Windows:
start https://pencil.evolves.dev/download
# Linux:
xdg-open https://pencil.evolves.dev/download

**ブラウザが開いたら、以下のAskQuestionを表示:**

{
  "title": "Step 1: Pencil アプリのダウンロード",
  "questions": [{
    "id": "download_status",
    "prompt": "ブラウザで Pencil のダウンロードページが開きましたか？\n\n手順:\n1. お使いのOS（Mac / Windows）に合ったインストーラーをダウンロード\n2. ダウンロードしたファイルを実行してインストール\n   - Mac: .dmg を開いてアプリケーションフォルダにドラッグ\n   - Windows: .exe を実行してウィザードに従う\n\nインストールできましたか？",
    "options": [
      {"id": "installed", "label": "インストールしました！"},
      {"id": "browser_not_open", "label": "ブラウザが開かない"},
      {"id": "download_issue", "label": "ダウンロードできない"},
      {"id": "mac_security", "label": "Macのセキュリティ警告が出る"}
    ]
  }]
}

(installed → Step 2へ) (browser_not_open → 「ブラウザで直接このURLを開いてください: https://pencil.evolves.dev/download」と案内) (download_issue → 「インターネット接続を確認してください。ダウンロードが遅い場合は少しお待ちください」と案内) (mac_security → 「システム設定 → プライバシーとセキュリティ → 「このまま開く」をクリックしてください。または、Finderでアプリを右クリック→「開く」を選択してください」と案内)

---

Step 2: Pencil アプリの起動と初期設定

**ユーザーに案内するメッセージ:**

Pencil アプリを起動してください:

┌─────────────────────────────────────────────────────────────┐
│ 1. アプリケーションから「Pencil」を起動                      │
│ 2. 初回起動時にアカウント作成またはログインが必要な場合は    │
│    画面の指示に従ってください                                │
│ 3. エディター画面が表示されたらOKです                        │
│                                                             │
│ ※ Pencil は .pen 形式のデザインファイルを作成・編集する     │
│   デスクトップアプリです                                    │
└─────────────────────────────────────────────────────────────┘

**AskQuestionの設定:**

{
  "title": "Step 2: Pencil アプリの起動",
  "questions": [{
    "id": "app_status",
    "prompt": "Pencil アプリを起動できましたか？",
    "options": [
      {"id": "running", "label": "Pencilが起動しています！"},
      {"id": "cant_find", "label": "アプリが見つからない"},
      {"id": "crash", "label": "起動するとクラッシュする"},
      {"id": "login_issue", "label": "ログイン/アカウント作成で困っている"}
    ]
  }]
}

(running → Step 3へ) (cant_find → Mac: 「アプリケーション」フォルダ / Windows: スタートメニューを確認。インストールが完了していなければ Step 1 に戻る) (crash → 「OSが最新か確認してください。問題が続く場合は、一度アンインストールして再インストールしてください」と案内) (login_issue → 「Pencil の公式サイト（https://pencil.evolves.dev）でアカウントを作成できます。メールアドレスで登録できます」と案内)

---

Step 3: MCP設定ファイルに Pencil サーバーを追加

**AIが自動で実行すること:**

1. 使用ツールを判定する（Claude Code or Cursor） 2. Pencil MCP サーバーの設定方法を案内する

**Pencil MCP の接続方式:**

Pencil MCP は Pencil デスクトップアプリに内蔵されています。アプリが起動していれば、MCP サーバーとして自動的に利用可能になります。

**Claude Code の場合:** `~/.claude/mcp_settings.json` に以下を追加:

{
  "mcpServers": {
    "pencil": {
      "url": "http://localhost:13742/sse"
    }
  }
}

**Cursor の場合:** `~/.cursor/mcp.json` に以下を追加:

{
  "mcpServers": {
    "pencil": {
      "url": "http://localhost:13742/sse"
    }
  }
}

> **注意**: 既存の MCP 設定ファイルがある場合は、`mcpServers` 内に `pencil` エントリを追記してください。他のサーバー設定は削除しないでください。

**AskQuestionの設定:**

{
  "title": "Step 3: MCP設定",
  "questions": [{
    "id": "config_status",
    "prompt": "MCP設定ファイルに Pencil サーバーの設定を追加しましたか？",
    "options": [
      {"id": "done", "label": "設定を追加しました！"},
      {"id": "auto_setup", "label": "AIに自動で設定してほしい"},
      {"id": "existing_config", "label": "既に設定ファイルがあるので追記方法を知りたい"},
      {"id": "help", "label": "設定方法がわからない"}
    ]
  }]
}

(done → Step 4へ) (auto_setup → AIが自動で設定ファイルを作成/更新する。既存のサーバー設定は保持する) (existing_config → 既存ファイルの内容を読み取り、`mcpServers` に `pencil` エントリを追記する方法を案内) (help → ツール別の詳細手順を案内)

---

Step 4: MCP接続テスト

**AIが実行すること:**

1. Claude Code / Cursor の再起動を案内:

MCP設定を反映するには、ツールの再起動が必要です。

Claude Code の場合:
  → 一度 exit で終了し、再度 claude を起動してください

Cursor の場合:
  → Cmd+Shift+P (Mac) / Ctrl+Shift+P (Windows) で
    コマンドパレットを開き「Reload Window」を実行してください

**AskQuestionの設定:**

{
  "title": "Step 4: MCP接続テスト",
  "questions": [{
    "id": "restart_status",
    "prompt": "ツールを再起動しましたか？（Pencil アプリも起動中であることを確認してください）",
    "options": [
      {"id": "restarted", "label": "再起動しました！テストしてください"},
      {"id": "how_restart", "label": "再起動の方法がわからない"},
      {"id": "skip_test", "label": "テストをスキップする"}
    ]
  }]
}

(restarted → MCP接続テスト実行)

2. MCP接続テスト:

• `get_editor_state()` を実行してPencilの状態を取得
• 接続成功: 「Pencil MCP に正常に接続できました」と表示
• 接続失敗: トラブルシューティングへ

**テスト成功時:**

Pencil MCP の設定が完了しました！

テスト結果: Pencil MCP サーバーに正常に接続できました。
これで Claude Code/Cursor