Scenic MCP - Input Control for Scenic Applications

Scenic MCP

Scenic GUI アプリケーション向け Model Context Protocol（MCP）サーバー

バージョン：1.0.0

キーボード入力、マウス操作、視覚的なフィードバックを通じて、AI アシスタントが Scenic GUI アプリケーションを操作できるようにします。自動テスト、AI 主導の開発ワークフロー、アクセシビリティツールに最適です。

機能

• 🎹 キーボード入力 - 修飾キー（Ctrl、Shift、Alt、Cmd）に対応し、テキストや特殊キーを送信します
• 🖱️ マウス操作 - カーソルを移動し、指定した座標をクリックします
• 🎯 セマンティック操作 - 生の座標だけでなく、セマンティックマークアップを使って特定のコンポーネントをクリックします
• 📸 視覚的なフィードバック - ビューポートの構造を調べ、スクリーンショットを撮影します
• 🤖 MCP 連携 - Claude Desktop、Claude Code、その他の MCP クライアントで動作します

クイックスタート

1. Scenic アプリの mix.exs に追加する

現在はまだ Hex に公開されていないため、リポジトリをクローンし、ローカル依存関係として追加する必要があります。

defp deps do
  [
    {:scenic_mcp, "../scenic_mcp"}
  ]
end

2. ビューポートとドライバーを設定する

Scenic MCP には、名前付きのビューポートプロセスとドライバープロセスが必要です。スーパービジョンツリーを更新してください。

# In your application.ex
def start(_type, _args) do
  children = [
    {Scenic, scenic_viewport_config()}
  ]

  Supervisor.start_link(children, strategy: :one_for_one)
end

defp scenic_viewport_config do
  [
    name: :main_viewport,  # Required!
    size: {800, 600},
    default_scene: MyApp.RootScene,
    drivers: [
      [
        name: :scenic_driver,  # Required!
        module: Scenic.Driver.Local,
        window: [title: "My App"],
        on_close: :stop_system
      ]
    ]
  ]
end

ここでの name は、ViewPort プロセスと Driver プロセスの登録名となるアトムを定義します。ViewPort とやり取りするために、該当するプロセスの pid を見つける必要があります。そのため、この特定の名前 main_viewport を検索する方法を採用しました。ScenicMCP を動作させるには、上記のように設定してください。

ビューポート名：:main_viewport ドライバー名：:scenic_driver

任意：カスタムプロセス名

異なるプロセス名が必要な場合は、次のように設定してください。

# config/config.exs
config :scenic_mcp,
  viewport_name: :my_custom_viewport,
  driver_name: :my_custom_driver,
  port: 9999

3. TypeScript の依存関係をインストールする

cd scenic_mcp
npm install
npm run build

4. Claude Code または Claude Desktop を設定する

Claude Code CLI を使用する（推奨）

claude mcp add scenic-mcp /path/to/scenic_mcp/dist/index.js
claude mcp list  # Verify installation

手動で設定する

~/.claude.json を編集します。

{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "scenic-mcp": {
          "type": "stdio",
          "command": "/path/to/scenic_mcp/dist/index.js",
          "args": [],
          "env": {}
        }
      }
    }
  }
}

任意：Tidewave MCP の設定

Tidewave は、Elixir/Phoenix アプリ向けに実行時のイントロスペクション（ログ、SQL クエリ、コード評価、ドキュメント）を提供します。プロジェクトに Tidewave が含まれている場合（Flamelex/Quillex には含まれています）、Scenic MCP と併せて追加できます。

Claude Code CLI を使用する場合：

TIDEWAVE_PORT=4000  # Change to your app's port
claude mcp add --transport http tidewave http://localhost:$TIDEWAVE_PORT/tidewave/mcp

手動で設定する場合：

同じプロジェクト設定の ~/.claude.json に、次の内容を追加します。

{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "scenic-mcp": {
          "type": "stdio",
          "command": "/path/to/scenic_mcp/dist/index.js",
          "args": [],
          "env": {}
        },
        "tidewave": {
          "type": "http",
          "url": "http://localhost:$TIDEWAVE_PORT/tidewave/mcp"
        }
      }
    }
  }
}

$TIDEWAVE_PORT をアプリケーションの HTTP ポートに置き換えてください（例：Phoenix のデフォルトでは 4000）。

5. Scenic アプリを起動する

cd your_scenic_app
iex -S mix

次のように表示されます。

✅ ScenicMCP successfully started on port 9999

使い方

利用可能なツール

接続とステータス

• connect_scenic - 起動中の Scenic アプリへの接続を確立します
• get_scenic_status - 接続ステータスとサーバー情報を確認します

ユーザー入力

• send_keys - キーボード入力（テキスト、特殊キー、修飾キー）を送信します
• send_mouse_move - カーソルを座標に移動します
• send_mouse_click - 座標をクリックします（左／右／中央ボタン）

視覚的なフィードバック

• inspect_viewport - ビューポート構造のテキストによる説明を取得します
• take_screenshot - PNG スクリーンショットを撮影します（パスまたは base64）

例

テキスト入力

send_keys({ text: "Hello, World!" })

特殊キー

send_keys({ key: "enter" })
send_keys({ key: "escape" })
send_keys({ key: "tab" })

キーボードショートカット

send_keys({ key: "s", modifiers: ["ctrl"] })      // Ctrl+S (Save)
send_keys({ key: "c", modifiers: ["cmd"] })       // Cmd+C (Copy on Mac)
send_keys({ key: "z", modifiers: ["ctrl", "shift"] })  // Ctrl+Shift+Z (Redo)

マウス操作

send_mouse_move({ x: 100, y: 200 })
send_mouse_click({ x: 150, y: 250, button: "left" })
send_mouse_click({ x: 300, y: 100, button: "right" })  // Right-click

視覚的な確認

inspect_viewport()  // Get component structure

take_screenshot({ format: "path" })  // Save to /tmp
take_screenshot({
  filename: "app_state.png",
  format: "base64"  // Get base64 data
})

アーキテクチャ

AI Agent (Claude Desktop/Code)
    ↓ stdio
TypeScript MCP Server (this package)
    ↓ TCP (port 9999)
Elixir GenServer (ScenicMcp.Server)
    ↓ function calls
Scenic Driver Process
    ↓ input events
Your Scenic Application

動作の仕組み

1. TypeScript MCP サーバー が stdio を介して MCP プロトコルを処理します
2. TCP ブリッジ が Elixir への永続的な接続を維持します
3. Elixir GenServer が TCP 経由で JSON コマンドを受信します
4. ツールハンドラー が Scenic のビューポートおよびドライバーと連携します
5. ドライバー が入力イベントをアプリケーションに送信します

設定

利用可能なオプション

# config/config.exs
config :scenic_mcp,
  # TCP port for MCP server (default: 9999)
  port: 9999,

  # Viewport process name (default: :main_viewport)
  viewport_name: :main_viewport,

  # Driver process name (default: :scenic_driver)
  driver_name: :scenic_driver,

  # Application name for logging (default: "Unknown")
  app_name: "MyApp"

複数の Scenic アプリ

複数の Scenic アプリを実行する場合は、それぞれ異なるポートを設定してください。

# In flamelex/config/config.exs
config :scenic_mcp, port: 9999, app_name: "Flamelex"

# In quillex/config/config.exs
config :scenic_mcp, port: 9997, app_name: "Quillex"

# In your_test/config/test.exs
config :scenic_mcp, port: 9996, app_name: "Test"

特定のポートに接続します。

connect_scenic({ port: 9997 })  // Connect to Quillex

開発

TypeScript をビルドする

npm run build       # One-time build
npm run dev         # Watch mode for development

配布用にバンドルする

npm run bundle      # Copies dist/* to priv/mcp_server/

テストを実行する

# Elixir tests
mix test

# Test specific file
mix test test/scenic_mcp/server_test.exs

プロジェクト構成

scenic_mcp/
├── lib/
│   ├── scenic_mcp.ex           # Module documentation
│   └── scenic_mcp/
│       ├── application.ex      # OTP application
│       ├── config.ex           # Configuration management
│       ├── server.ex           # TCP server (GenServer)
│       └── tools.ex            # Tool handlers
├── src/
│   ├── index.ts                # MCP server entry point
│   ├── connection.ts           # TCP connection management
│   └── tools.ts                # Tool definitions
├── test/
│   └── scenic_mcp/
│       └── server_test.exs     # Integration tests
└── dist/                       # Compiled TypeScript

トラブルシューティング

MCP サーバーに接続できない

エラー： MCP サーバーへの接続に失敗する、または Claude Code／Desktop でツールを利用できない

解決方法： コンパイル済みの dist/index.js ファイルには実行権限が必要です。ソースファイルに実行権限があっても、TypeScript のコンパイルではその権限が保持されません。

修正方法：

chmod +x /path/to/scenic_mcp/dist/index.js

自動修正： ビルドスクリプトがファイルに自動的に実行権限を付与するようになりました。この修正が追加される前にビルドした場合は、次のいずれかを実行してください。

1. npm run build を再度実行します（推奨）
2. chmod +x dist/index.js を手動で実行します

修正後、変更を反映するには Claude Code を再起動するか、新しい会話を開始してください。

ポートがすでに使用されています

エラー： Port 9999 is already in use!

解決方法： config.exs で別のポートを設定します。

config :scenic_mcp, port: 9998

ビューポートが見つかりません

エラー： Unable to find Scenic viewport process ':main_viewport'

解決方法：

1. Scenic の設定でビューポートに name: :main_viewport が指定されていることを確認します
2. または、想定する名前を config :scenic_mcp, viewport_name: :your_name で設定します
3. Scenic アプリが実行中であることを確認します：Process.whereis(:main_viewport)

ドライバーが見つかりません

エラー： Unable to find Scenic driver process ':scenic_driver'

解決方法：

1. ドライバーの設定でドライバーに name: :scenic_driver が指定されていることを確認します
2. または、想定する名前を config :scenic_mcp, driver_name: :your_name で設定します
3. ドライバーが起動していることを確認します：Process.whereis(:scenic_driver)

接続がタイムアウトする

エラー： Command timeout after 5000ms

解決方法：

1. Scenic アプリが実行中か確認します
2. ポートが正しいことを確認します：connect_scenic({ port: YOUR_PORT })
3. ファイアウォールの設定を確認します（localhost:9999 への接続を許可する必要があります）

テストが失敗する

接続エラーでテストが失敗する場合：

1. テスト用ポート（9996-9998）を使用しているほかのアプリがないことを確認します
2. 詳細な出力を表示するには、mix test --trace でテストを実行します
3. scenic_driver_local 依存関係が正しくコンパイルされていることを確認します

セキュリティに関する考慮事項

⚠️ 重要なセキュリティ上の注意：

• Scenic MCP は localhost のみにバインドされるため、外部ネットワークからはアクセスできません
• 認証はありません。ローカルアクセスが可能な人は誰でもアプリを操作できます
• 開発環境およびテスト環境のみを対象としています
• TCP ポート（9999）を信頼できないネットワークに公開しないでください
• 追加のセキュリティ対策なしで本番環境に使用しないでください

詳しいセキュリティガイドラインについては、SECURITY.md を参照してください。

統合ガイド

既存のアプリケーションへの Scenic MCP の追加、一般的なパターンとベストプラクティス、テスト戦略、実装例など、手順ごとの統合方法については docs/INTEGRATION.md を参照してください。

API リファレンス

エラー処理

すべてのツール関数は、一貫したエラー構造を返します。

{
  "error": "Descriptive error message with context and potential solutions"
}

成功時のレスポンスには status フィールドが含まれます。

{
  "status": "ok",
  "message": "Operation completed successfully",
  ...additional data...
}

貢献

貢献を歓迎します。以下の手順に従ってください。

1. リポジトリをフォークします
2. 機能ブランチを作成します
3. 新しい機能のテストを追加します
4. mix test が成功することを確認します
5. プルリクエストを送信します

要件

• Elixir ~> 1.14
• Erlang/OTP 24+
• Node.js >= 18.0
• Scenic ~> 0.11
• Claude Desktop または Claude Code（MCP クライアント用）

ライセンス

MIT License。詳しくは LICENSE を参照してください。

関連プロジェクト

• Scenic - Elixir 用の 2D UI フレームワーク
• MCP - Model Context Protocol の仕様
• Tidewave - Elixir/Phoenix 用 MCP ツール

変更履歴

バージョン履歴については CHANGELOG.md を参照してください。

サポート

• バグを報告する：GitHub Issues
• ドキュメント：この README と docs/
• 例：examples/ ディレクトリを参照してください

---

Elixir と Scenic のコミュニティに ❤️ を込めて