can-see

can-see

仮想ターミナルと PNG スクリーンショットを通じて、AI エージェントがターミナル／CLI アプリケーションを見て、操作できる MCP サーバーです。

Claude Code および MCP 互換のあらゆるエージェント向けに構築されています。

その理由

説明するより、見せるほうが簡単なこともあります。TUI アプリや対話型 CLI ウィザード、あるいは視覚的なターミナル出力を伴うものをデバッグする際、can-see を使えば、色、レイアウト、カーソル位置など、実際に見えている状態をエージェントがそのまま確認できます。

仕組み

1. 起動：仮想ターミナルで CLI アプリを起動します（node-pty + @xterm/headless）
2. スクリーンショット：ターミナルを PNG 画像として撮影します（node-canvas でレンダリング）
3. キー／テキストを送信：アプリを操作します
4. 再度スクリーンショットを撮影：結果を確認します
5. セッションを終了：操作が終わったらセッションを終了します

インストール

npm install -g can-see

前提条件

can-see は node-canvas（Cairo）と node-pty に依存しており、ネイティブコンパイルが必要です。ほとんどのシステムでは、以下が必要です。

• Windows： Visual Studio Build Tools（C++ ワークロード） — npm install --global windows-build-tools を実行するか、Visual Studio Installer からインストールします
• macOS： Xcode Command Line Tools — xcode-select --install
• Linux： sudo apt install build-essential libcairo2-dev libjpeg-dev libpango1.0-dev libgif-dev librsvg2-dev

設定

Claude Code

プロジェクトの .mcp.json に追加します。

{
  "mcpServers": {
    "can-see": {
      "command": "npx",
      "args": ["-y", "can-see"]
    }
  }
}

グローバルにインストールしている場合は、次のようにします。

{
  "mcpServers": {
    "can-see": {
      "command": "can-see"
    }
  }
}

その他の MCP クライアント

can-see は stdio トランスポートを使用します。MCP クライアントから can-see バイナリまたは npx -y can-see を指定してください。

ツール

ツール	説明
launch	仮想端末で CLI アプリを起動します。sessionId を返します。環境変数を設定するための任意の env を受け付けます。
screenshot	端末を PNG 画像としてキャプチャします。
screenshot_region	端末の特定の矩形領域をキャプチャします。
screenshot_text_region	ビューポート内のテキストを検索し、その周辺領域を PNG としてキャプチャします。
capture_baseline	後で差分比較できるよう、端末の状態をスナップショットします。
diff_screenshot	現在の状態をベースラインと比較し、変更箇所を強調表示します。
get_cell_info	指定したセルの文字、色、属性を取得します。出力を減らす compact モードに対応しています。
read_text	端末バッファーをプレーンテキストとして読み取ります。
read_scrollback	表示中のビューポートより上にスクロールしたテキストを読み取ります。
wait_for_text	端末バッファーに特定のテキストが表示されるまで待機します。
wait_for_idle	指定した時間、端末出力が安定するまで待機します。タイマーやスピナーがあるアプリ向けのコンテンツ比較モード用の stableMs、無視する行を指定する excludeRows、動的な行を除外するための excludePattern（正規表現）に対応しています。
wait_for_color	指定した位置に特定の色が表示されるまで待機します。
wait_for_exit	プロセスが終了するまで待機し、終了コードとシグナルを返します。
start_recording	アニメーション GIF 用のフレームのキャプチャを開始します。
stop_recording	録画を停止し、メタデータ（frameCount、durationMs）とともにアニメーション GIF を返します。GIF がインラインサイズの上限を超える場合、フレームを自動的にトリミングするか、ファイルに保存します。
send_keys	キー入力を送信します（例：Enter、Ctrl+C、['Down', 'Down', 'Enter']）。
send_text	アプリにテキスト文字列を入力します。
get_process_status	プロセスの状態を取得し、「アプリがアイドル状態」と「アプリが終了した」を区別します。PID、実行状態、終了コードを返します。
list_sessions	アクティブな端末セッションをすべて一覧表示します。
close	アプリを終了し、後処理を行います。完了したら必ず閉じてください。
close_all	アクティブなセッションをすべて一度に終了します。テスト実行の合間のクリーンアップに便利です。

対応キー

Enter、Tab、Escape、Backspace、Space、Up、Down、Left、Right、Home、End、Delete、PageUp、PageDown、Ctrl+A から Ctrl+Z。

環境変数

変数	デフォルト	説明
DEFAULT_COLS	120	端末の幅（列数）
DEFAULT_ROWS	30	端末の高さ（行数）
IDLE_TIMEOUT_MS	300000	アイドル状態のセッションをこのミリ秒数（5 分）後に自動終了します

使用例

MCP に接続されたエージェントから：

Agent: I'll launch your app to see what's happening.
→ launch("node", ["app.js"])  → sessionId: "abc-123"

Agent: Let me wait for the app to start.
→ wait_for_text("abc-123", "Ready")  → Found "Ready" after 1200ms

Agent: Let me read the current output.
→ read_text("abc-123")  → "Welcome to MyApp\nReady\n> "

Agent: I can see the prompt. Let me select option 2.
→ send_keys("abc-123", ["Down", "Enter"])

Agent: Waiting for the screen to settle.
→ wait_for_idle("abc-123")  → Terminal idle for 520ms

Agent: Let me check the result.
→ screenshot("abc-123")  → [PNG image showing result]

Agent: Done, closing the session.
→ close("abc-123")

変更履歴

0.5.0

新しいツール：

• wait_for_exit — プロセスの終了を待機し、終了コードとシグナルを取得します
• close_all — アクティブなセッションをすべて一度に終了します
• get_process_status — 「アプリがアイドル状態」と「アプリが終了した」を区別します
• screenshot_text_region — ビューポート内のテキストを検索し、周辺領域を PNG としてキャプチャします

機能強化：

• launch がカスタム環境変数を指定する env パラメーターを受け付けるようになりました
• wait_for_idle が stableMs モードで動的な行を除外する excludePattern（正規表現）に対応しました
• stop_recording が GIF とともに frameCount および durationMs メタデータを返すようになりました
• get_cell_info が出力を減らす compact オプションに対応しました（{char, fg, bold} のみ）

バグ修正：

• プロセスが同時に終了した際、最終バッファーに存在するテキストや色を見逃す wait_for_text と wait_for_color の競合状態を修正しました
• wait_for_idle に stableMs と idleMs の両方が渡された場合の相互排他性検証を追加しました

ライセンス

MIT