Touchpoint

Touchpoint

あらゆるデスクトップで、AI エージェントに目と手を与えます。

pip install touchpoint-py

AI エージェントが Chrome でデータを調査し、書式設定済みの Excel テーブルを作成します — タスク全体を約 12 分で完了

Touchpoint は、ネイティブのアクセシビリティ API を通じてデスクトップ UI を読み取り、操作するためのクロスプラットフォーム Python ライブラリです。インポートは 1 つ、API も 1 つで、Linux、macOS、Windows で動作し、CDP（Chrome DevTools Protocol）経由で Chromium アプリと Electron アプリを標準でサポートします。

ピクセルをスクレイピングしたり、ビジョンモデルを実行したりする代わりに、Touchpoint は実際のアクセシビリティツリーを読み取ります。画面上のあらゆる要素の構造化された名前、ロール、状態、位置を取得します。高速で信頼性が高く、ビジョンモデルは不要です。MCP サーバーが付属しているため、Claude、Cursor などの LLM エージェントや、あらゆるローカルモデルが、すぐに任意のデスクトップアプリを操作できます。

import touchpoint as tp

elements = tp.find("Send", role=tp.Role.BUTTON, app="Slack")
tp.click(elements[0])

Touchpoint を選ぶ理由

目次

• 目次
• インストール
  • プラットフォーム要件
• クイックスタート
  • 要素 ID
  • 出力形式
• MCP サーバー
  • ツール
  • クライアントの設定
  • 環境変数
• ブラウザーと Electron アプリ（CDP）
  • セットアップ
• API リファレンス
  • 検出
  • 検索と待機
  • アクション
  • 入力
  • スクリーンショットと設定
• アーキテクチャ
• 設定
• 開発
• ステータス
  • 既知の制限事項
• ライセンス

インストール

Python 3.10 以降が必要です。

pip install touchpoint-py

すべてが含まれています。プラットフォームのネイティブバックエンド、ブラウザーおよび Electron アプリ向けの CDP サポート、MCP サーバー、スクリーンショット機能を利用できます。プラットフォーム固有の依存関係は、pip の環境マーカーによって自動的にインストールされます。

プラットフォーム要件

クイックスタート

import touchpoint as tp

# Discover
apps = tp.apps()                            # ["Firefox", "Slack", "Terminal", ...]
windows = tp.windows()                      # Window objects with title, position, size
all_els = tp.elements(app="Firefox", named_only=True)  # only elements with text labels

# Find
results = tp.find("Search", role=tp.Role.TEXT_FIELD, app="Firefox")

# Act
tp.set_value(results[0], "touchpoint python", replace=True)
tp.press_key("enter")
tp.hotkey("ctrl", "s")                      # keyboard shortcuts

# Wait for UI changes
tp.wait_for("results", app="Firefox", timeout=10)

# Screenshot
img = tp.screenshot()                       # full desktop → PIL.Image
img = tp.screenshot(app="Firefox")           # cropped to app window

要素 ID

各要素には、atspi:1234:1:2.0 や cdp:9222:TID:4 のような一意の ID があります。アクション関数には Element オブジェクトまたは ID 文字列を直接渡せます。ステップをまたいで参照を保存する場合に便利です。

results = tp.find("Send", max_results=1)
element_id = results[0].id                  # "atspi:1234:1:5.2"

# later...
tp.click(element_id)                        # works with just the string

出力形式

結果の返却方法を設定します。

tp.elements(app="Slack", format="flat")     # one compact line per element (best for LLMs)
tp.elements(app="Slack", format="tree")     # indented parent/child hierarchy
tp.elements(app="Slack", format="json")     # full JSON with all fields

MCP サーバー

Touchpoint には、MCP 互換クライアントで利用できる MCP（Model Context Protocol） サーバーが付属しています。これを使うと、Claude、Cursor、ローカルモデルなどの LLM エージェントや、MCP に対応するあらゆるツールからデスクトップを操作できます。

2 つのモード — ビジョンあり／ビジョンなし

モードを切り替えるには、TOUCHPOINT_MODE=no-vision を設定します（デフォルトは vision です）。

• ビジョンモード — エージェントは screenshot() で画面を確認し、要素 ID または座標を使って操作します。優れた視覚機能を備えた最先端モデルに最適です。
• ビジョンなしモード — エージェントは snapshot() でアクティブウィンドウのコンパクトな構造化テキストツリーを取得し、その後、要素 ID を直接使って操作します。ビジョン機能のないローカルモデルを含む、あらゆるモデルで動作します。ほとんどのアクションツールは、自動検証フラグ（(new window: ...)、(focus moved)、(no change detected)）を追加するため、エージェントはスクリーンショットを撮らずに状態の変化を検出できます。

ツール

MCP サーバーには、各モードでの正しいワークフローをエージェントに教える組み込みの指示が含まれています。状況把握 → 操作 → 検証のループ、read_text と find の使い分け、エラーからの復旧方法などが説明されています。

         ┌──────────┐
    ┌───▶│  ORIENT  │  screenshot · apps · windows
    │    └────┬─────┘
    │         ▼
    │    ┌──────────┐
    │    │  LOCATE  │  find · snapshot · get_element
    │    └────┬─────┘
    │         ▼
    │    ┌──────────┐
    │    │   ACT    │  click · set_value · type_text · press_key
    │    └────┬─────┘
    │         ▼
    │    ┌──────────┐
    │    │  VERIFY  │───▶ Done ✅
    │    └────┬─────┘
    │         │ not yet
    └─────────┘

クライアントの設定

{
  "mcpServers": {
    "touchpoint": {
      "command": "touchpoint-mcp"
    }
  }
}

{
  "servers": {
    "touchpoint": {
      "command": "touchpoint-mcp"
    }
  }
}

{
  "mcpServers": {
    "touchpoint": {
      "command": "touchpoint-mcp"
    }
  }
}

{
  "mcpServers": {
    "touchpoint": {
      "command": "touchpoint-mcp"
    }
  }
}

claude mcp add touchpoint -- touchpoint-mcp

{
  "mcpServers": {
    "touchpoint": {
      "command": "touchpoint-mcp"
    }
  }
}

ブラウザーと Electron アプリ（CDP）

ネイティブのアクセシビリティ API が Electron および Chromium アプリ（Slack、Discord、VS Code など）に対して返すデータは限られています。Touchpoint の CDP バックエンドは Chrome DevTools Protocol 経由で接続し、ウェブコンテンツ全体を取得します。

自動検出はデフォルトで有効です。Touchpoint は、デバッグポートを指定して起動された実行中のブラウザーと Electron アプリを自動的に検出します。アプリをフラグ付きで起動する以外に、手動設定は不要です。

セットアップ

1. デバッグポートを指定してアプリを起動します：

# Linux
google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/tp-chrome

# macOS
open -na "Google Chrome" --args --remote-debugging-port=9222 --user-data-dir=/tmp/tp-chrome

# Windows
start chrome --remote-debugging-port=9222 --user-data-dir=%TEMP%\tp-chrome

2. Touchpoint を設定します：

import touchpoint as tp

tp.configure(cdp_discover=True)             # auto-discover from running processes
# or
tp.configure(cdp_ports={"Google Chrome": 9222})  # explicit mapping

3. source パラメーターで取得する内容を制御します：

tp.elements(app="Google Chrome", source="full")     # native chrome + web content (default)
tp.elements(app="Google Chrome", source="cdp_ax")   # web content only (CDP accessibility tree)
tp.elements(app="Google Chrome", source="native")   # native UI only (toolbar, tabs, menus)
tp.elements(app="Google Chrome", source="dom")      # DOM walker (catches what AX misses)

CDP の結果はネイティブバックエンドの結果と統合されます。elements() を 1 回呼び出すだけで、AT-SPI2/UIA/AX からツールバーとウィンドウコントロールを取得し、CDP からウェブページ全体のコンテンツを取得できます。

互換性のため、source="ax" は引き続き source="cdp_ax" の別名として受け付けられます。macOS のネイティブ AX バックエンドと混同されないよう、新しいコードでは cdp_ax を使用してください。

API リファレンス

検出

検索と待機

アクション

入力

スクリーンショットと設定

すべてのアクション関数は、Element オブジェクトまたは文字列IDを受け取ります。elements()、find()、get_element() は、オブジェクトの代わりに書式設定済み文字列を返す format="flat"、format="json"、または format="tree"（要素のみ）に対応しています。ウィンドウ管理は、Linux AT-SPI2、Windows UIA、macOS AXの各バックエンドで実装されています。

アーキテクチャ

┌───────────────────────────────────────────────────────┐
│               import touchpoint as tp                 │
│  tp.find() · tp.click() · tp.screenshot() · ...       │
│                    (Public API)                       │
├─────────────────────────┬─────────────────────────────┤
│     Backend (ABC)       │    InputProvider (ABC)      │
├─────────────────────────┼─────────────────────────────┤
│  AT-SPI2     (Linux)    │  Xdotool       (X11)        │
│  UIA         (Windows)  │  SendInput     (Win32)      │
│  AX          (macOS)    │  CGEvent       (macOS)      │
│  CDP         (browsers) │                             │
├─────────────────────────┴─────────────────────────────┤
│  Utilities: formatter · matcher · screenshot · scale  │
└───────────────────────────────────────────────────────┘

2層設計：

• Backend はアクセシビリティツリーを読み取り、構造化されたアクション（クリック、set_value、フォーカス）を実行します。要素を認識し、信頼性の高い動作を実現します。
• InputProvider は生のキーボード入力とマウス入力をシミュレートします。座標ベースで、要素を認識しません。ネイティブのアクセシビリティアクションを利用できない場合に、自動フォールバックとして使用されます。

CDPはプラットフォームのバックエンドと並行して動作します。結果は統合されます。AT-SPI2/UIA/AXからネイティブのウィンドウ枠（ツールバー、タブ、メニュー）を取得し、CDPからウェブコンテンツ全体を取得して、1つのAPIにまとめます。

内部構造の詳細については、ARCHITECTURE.mdを参照してください。

設定

tp.configure(
    fuzzy_threshold=0.6,          # minimum match score for find() (0.0–1.0)
    fallback_input=True,          # use InputProvider when native actions fail
    type_chunk_size=40,           # split long text into chunks for typing (0 = disable)
    max_elements=5000,            # max elements per query
    max_depth=20,                 # default tree depth limit
    scale_factor=None,            # display scale override (None = auto-detect)
    cdp_ports={"Chrome": 9222},   # explicit CDP port mapping
    cdp_discover=True,            # auto-discover CDP ports from running processes
    cdp_refresh_interval=5.0,     # seconds between CDP target scans
    ax_messaging_timeout=1.0,     # max seconds to wait for a macOS AX app reply
)

tp.diagnostics() は、JSON形式で扱いやすいヘルスレポートを返します。 有効なバックエンド、入力プロバイダー、CDPターゲット、オプションのプラットフォームツール、設定済みのタイムアウト、およびAXメッセージングのタイムアウト後に最近スキップされたmacOSアプリが含まれます。

開発

git clone https://github.com/Touchpoint-Labs/touchpoint.git
cd touchpoint
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest

ステータス

アルファ版 — 3つすべてのプラットフォームで完全に機能し、テスト済みです。ユーザーからのフィードバックに基づき、1.0より前にAPIが変更される場合があります。

既知の制限事項

• Waylandでの入力 — Linux InputProviderはxdotoolを使用しますが、これはX11を必要とします。純粋なWayland環境（XWaylandなし）では、キーボードやマウスのシミュレーションは利用できません。アクセシビリティツリーとネイティブアクションは引き続き機能します。

• 同期CDP — CDP呼び出しはWebSocketの応答を待つ間、処理をブロックします。デッドロックを防ぐため、JavaScriptダイアログ（alert、confirm、prompt）は自動的に閉じられます。非同期への書き換えを予定しています。

• ブラウザーのナビゲーションAPIがない — TouchpointにはURLナビゲーション機能が組み込まれていません。エージェントはUI要素を直接操作して移動できます。アドレスバーを見つけ、URLを入力して、Enterキーを押します。

• CDPのウィンドウはOSウィンドウではなくページターゲットです — ただし、ウィンドウ管理は引き続き機能します。tp.activate_window()はCDP経由でターゲットを前面に表示し、表示されたcdp:ウィンドウに対するminimize／fullscreen／close／move／resizeは、基盤となるネイティブOSウィンドウ（所有PIDから特定）に転送され、プラットフォームバックエンドによって処理されます。そのターゲットに対応するネイティブOSウィンドウが見つからない場合（例：ウィンドウが閉じられている場合）に限り、ActionFailedErrorが発生します。

• バックエンド間のロール／状態の同等性には、まだ差があります — macOS AXとWindows UIAはどちらも0.3.0で大幅に改善されましたが、Windowsは依然としてより多くのヒューリスティックに依存しており、他のバックエンドよりも未マッピングのロングテールロールが多くあります。

ロードマップ

高優先度

• 非同期CDPアーキテクチャ — ノンブロッキングWebSocket、適切なダイアログキューイング、複数タブへの並行クエリ

中優先度

• バックエンド間のロール／状態の同等性 — 残るロールマッピングの不足を解消します。特にWindowsのUIAのロングテールロールが対象です。
• Wayland入力バックエンド — X11を利用できない場合のlibei／xdg-desktop-portal RemoteDesktop

低優先度

• ツールチップと通知の表示
• 要素のキャッシュ

ライセンス

MIT