Skip to main content
Glama
README.md
<p align="center">
  <img src="media/readme-hero-v2.png" alt="AgentDeskLink — Browser + Desktop, over MCP" width="1200">
</p>

**日本語** | [English](README_en.md)

# AI に、ブラウザとデスクトップの操作を。

**ブラウザも、デスクトップも。使い慣れた AI エージェントから。**

AgentDeskLink は、AI エージェントとローカルのブラウザ・デスクトップをつなぐ MCP サーバーです。画面の要素を読み取り、許可されたクリックや文字入力を実行。必要な場面では画像も確認しながら操作できます。

[はじめる](release-docs/INSTALL.md) · [できること](#できること) · [対応環境](#対応環境) · [リリースガイド](release-docs/README.md) · [MIT License](LICENSE)

> **0.1.12 / ベータ版**\
> 利用範囲を限定して提供しています。導入前に[対応環境と既知の制限](release-docs/KNOWN_ISSUES.md)を確認してください。

このバージョンでは、信頼済みワークスペースの初期設定を全操作に変更し、用途別の権限選択と保存状態の案内を改善しました。長い選択肢の検索、観測応答のバイト上限、表や定義リスト内の個人情報マスク、デスクトップの対象取得も改善しています。[変更点](release-docs/RELEASE_NOTES_ja.md)と[操作設定・承認のガイド](release-docs/OPERATIONS.md)を確認してください。

## できること

| 機能 | 使いどころ |
| --- | --- |
| **画面を要素と差分で読む** | ボタンや入力欄の役割・値を取得し、操作後に変わった部分を読み返す |
| **必要なところを画像で見る** | ブラウザや対象ウィンドウを撮影し、Canvas や図表を含む描画を確認する |
| **ブラウザもアプリも操作する** | 許可した文字入力・クリック・選択・スクロールを、同じ MCP 接続から実行する |
| **複数ウィンドウを個別に扱う** | 同じアプリのウィンドウを区別し、観測した対象へ操作を行う |

ブラウザのドラッグやタッチスワイプ、時刻付きの連続フレーム取得にも対応します。デスクトップの物理入力は `interactive_desktop` モードで利用します。

## VS Code ではじめる

1. 共通パッケージ `agentdesklink-0.1.12.vsix` を取得し、「拡張機能: VSIXからのインストール」で導入します。
2. フォルダーを開き、ワークスペースを信頼します。
3. アクティビティバーの **AgentDeskLink** を開きます。
4. **設定を開く**から「現在の権限」を確認します。新規設定では全操作・全 URL・全アプリが有効です。旧設定がある場合は以前の権限を引き継ぎます。必要なら読み取り専用・通常操作・個別承認へ切り替え、対象を限定します。
5. MCP は信頼済みワークスペースで既定オンです。以前オフにした場合は **このワークスペースで MCP を有効にする**をオンにし、MCP 管理画面でサーバーを起動します。

**Node.js の別途インストールや helper のビルドは不要です。** 同じ VSIX に各 OS 用のランタイムを同梱し、起動時に自動で選びます。Chrome は専用プロファイルで利用し、見つからない場合は初回に専用 Chromium を自動取得します。

AgentDeskLink 自体に外部 AI の API キーは不要です。AI の接続・認証は利用する MCP ホスト側で行います。

[インストール手順を見る →](release-docs/INSTALL.md)

### 他のAIクライアントにも一括接続

設定パネルの **AIクライアント → すべて有効** で、インストール済みの Claude Code、Claude Desktop、Codex、Cursor、Windsurf、Devin、Gemini CLI、Cline、Roo Code を自動検出して MCP を登録します。VS Code の MCP も同時に有効になります。**すべて無効** で登録を解除し、接続中の外部クライアントも停止します。

一括有効にしたワークスペースの操作権限を共有します。他のMCP設定は保持し、同名の手動登録があれば個別に表示します。各クライアントで再接続・新しい会話・再起動が必要な場合があります。

## 対応環境

| 環境 | 利用できる範囲 |
| --- | --- |
| **macOS 14 以上 / Apple silicon** | ブラウザ・デスクトップ。OS のアクセシビリティ権限、画像取得には画面収録権限が必要 |
| **Windows 11 x64** | ブラウザ・デスクトップ。デスクトップ操作は対象アプリと同じ対話セッションで実行 |
| **Linux x64(Ubuntu 24.04)** | ブラウザ・デスクトップ(AT-SPI2 による意味的操作)。ブラウザには Chrome または Chromium の実行に必要な共有ライブラリと OS sandbox、デスクトップには python3-gi・gir1.2-atspi-2.0・at-spi2-core が必要 |

macOS と Windows では、CLI のポリシーで明示的に許可したアプリの状態確認・起動・通常終了も利用できます。Windows で起動するアプリは専用の Win32 デスクトップに配置します。

Linux のデスクトップ操作はアクセシビリティ API(AT-SPI2)による観測と click / fill / check / select / scroll だけです。物理入力・ウィンドウ画像・アプリの起動/終了は未対応で、`adl_capabilities` の `platform_unsupported` に明示します。全アプリ許可をオフにして対象を限定する場合は、アプリ ID に AT-SPI のアプリケーション名、パスに実行ファイルの絶対パス(`readlink /proc/<pid>/exe` の値)を指定します。準備方法と制限は[インストールガイド](release-docs/INSTALL.md#os-ごとの準備)を参照してください。

OS・アプリ・表示構成によって利用できる操作は異なります。詳しくは[対応環境と既知の制限](release-docs/KNOWN_ISSUES.md)を参照してください。

## 操作する範囲を、自分で決める

- **初期状態ですぐ操作できます。** 信頼済みワークスペースでは MCP、全操作、すべての http(s) URL・アプリ、物理入力、ネイティブ画像、localhost・プライベート網を有効にします。既存の明示的な拒否設定は保持します。OS のアクセシビリティ・画面収録権限は引き続き必要です。
- **設定ファイルの指定は不要。** VS Code 拡張は同梱設定で動作します。CLI を直接起動する場合は、ポリシー JSON で対象と操作を設定します。
- **普段のブラウザと分けて使う。** 人間のプロファイルやログイン状態を共有しません。
- **物理入力は専用モード。** `interactive_desktop` は実際のマウス・キーボードを使うため、人間の操作と並行して利用しないでください。

初期状態は **全操作** です。必要に応じて **読み取り専用 / 下書き(通常操作) / 承認付き保存(個別承認)** へ切り替えられます。以下は制限する段階を選んだ場合の動作です。通常操作では通常の入力・クリックと JavaScript 内で処理するフォームを利用できます。実際の GET/POST フォーム送信には個別承認が必要で、個別承認モードでも送信が起きるときだけ確認します(GET の検索フォームは例外で、承認なしで送信できます)。通常操作では、ページが保存のために送る書き込み通信(fetch / XHR の POST・PUT・PATCH・DELETE)を遮断するため、多くの Web アプリはデータを保存できません。個別承認では、操作中にページが送るその通信を送信前に保留し、メソッド・URL・本文(秘密は伏せます)を確認して、承認した内容だけを 1 回送信します。重要操作は、ボタンの動詞(削除・送信・支払・購読解除・ログアウトなど)と実際のフォーム送信で判定し、同一 origin へ移動するだけのリンクやダイアログの「キャンセル」は通常操作です。判定は `consequentialAllowLabels` / `consequentialDenyLabels` で調整できます。個別承認は対象・入力値・フォーム内容に結び付きます。main document では、無関係な時計の更新だけでは失効せず、対象・フォーム・文書の変更、期限切れ、緊急停止で失効します。open Shadow DOM と同一 origin の iframe にも対応します。許可したデスクトップアプリのネイティブ操作にも同じ段階が適用されます(macOS / Windows / Linux)。通常操作では機密・重要でないコントロールだけを操作し、個別承認では削除・送信などの重要なコントロールを対象・名前・観測リビジョンに結び付けて一度ずつ承認します。パスワードなどの機密コントロールは承認でも操作しません。閉じた Shadow DOM、別プロセス iframe の個別承認は未対応です。「全操作許可」は初期状態でオンです。制限する段階を選ぶと全操作と物理入力をオフにします。承認付き保存では全アプリ許可もオフにし、承認ホストをAIが操作できないよう対象を限定します。

初期状態では許可元の登録は不要です。「すべてのURL」をオフにすると許可元を限定できます。`browserOrigins` は移動先、`browserResourceOrigins` は CDN などの GET/HEAD 読み込み専用です。localhost も既定で利用できます。URL 範囲を限定した場合は正確な origin の許可と `allowLoopback` が必要です。メール・電話番号などは既定でマスクし、必要な場合にだけ `allowPersonalData` で表示を許可できます。パスワード・トークン・明示保護領域はこの設定でも保護します。

`adl_observe` の `text: {element_id, offset, length}` で長文の続きを取得できます。位置はマスク済みのテキストを基準にします。`adl_act` の `include_diff: true` は操作直後の差分を返し、ページ遷移後は全量(`reset: true`)に切り替えます。操作応答の `network_blocked` は操作自体の通信が遮断されたことを示し、無関係なサブリソースの遮断は `subresources_blocked` で示します。`write_blocked: true` は、ページが送った書き込みが遮断され、画面の表示が保存されていないことを示します。`ok: true` だけでサイト上の処理完了や保存とは判断できません。操作の後は、その操作が始めた通信が終わりページの変化が止まるまで(最長 400 ミリ秒)待ってから差分を作ります。警告は 1 回だけ返し、操作の応答にはその操作が起こした遮断だけを含めます。標準モードでは、fetch の POST などの書き込みは検索用途でも許可しません。

画像やテキスト内の未知の秘密情報を完全に検出する保証はありません。設定パネルやコマンドパレットの「緊急停止」で拡張が管理する操作を停止し、「操作を再開」で再開できます。すでにアプリへ渡った処理は取り消せません。

パネルで可視ブラウザ、アイドル期限、認証なしの HTTP(S) プロキシを設定できます。可視ブラウザのログイン引き継ぎには `adl_handoff` を使います。個別承認モードでは、同じ origin のサイト処理・フォーム通信を最大 120 秒許す専用の承認を受け、自動操作を停止します。この間は人間のクリック前にもサイトが送信・変更・削除を行えます。手動操作後に再開して観測し直してください。再開や期限終了でも送信済みの処理は取り消せません。

同梱 Node は `--use-system-ca` で起動します。プロキシ利用時も接続先の DNS/IP 検査を維持するため、プロキシ側でしか名前解決できないホストは利用できません。初回の DOM API 検証に通らない文書は、分離した読み取り専用の互換経路で取得します。既に観測した同じ文書の後発改変は `untrusted_dom_api` で停止します。詳しくは[対応環境と既知の制限](release-docs/KNOWN_ISSUES.md)を確認してください。

`adl_observe` は既定値(`enabled: true` や空の値など)を省いた JSON を返し、`format: "lines"` で行形式も返せます。既定の JSON・差分・scope・cursor も利用できます。`scope` はページ内検索で、`text:"v1.0: fixed"` のような引用、`role:` / `name:` / `id:` の指定ができます(詳しくは [操作設定](release-docs/OPERATIONS.md))。リンクは `href` を、代替テキスト付きの画像・canvas は `img` として返し、隠し本文は除外し、除外があった要素に `hidden_text: true` を付けます。既定の観測は本文へ進む `landmarks` を返し、DOM は最大 64 階層まで取得します。`adl_act` の座標クリックは、最新の保持画像から `point: {frame_id,x,y}` を指定します。画像取得元の CSS ピクセルを使い、位置や対象が変わった場合は再取得が必要です。

ブラウザの `data-adl-sensitive`、`data-adl-classification="SECRET"` / `"UNKNOWN"` は子孫にも適用されます。子の `PUBLIC` 指定や `allowAllOperations` でも解除できません。観測では保護対象の内容をマスクし、領域内の操作を拒否します。画像と保持フレームのcropにもマスクを適用します。これらの明示マーカーは自動検出を補うものです。

select は `options_total` と `options_truncation` で総数と省略理由を返します。`response_budget` は予算を増やすと回復し、`source_limit` は初回100件の取得上限です。`adl_observe` の `options: {element_id, query, offset, limit}` で候補を検索・ページ取得できます。`byte_budget` は UTF-8 JSON の厳密なバイト上限です。互換の `token_budget` はその4分の1の推定値で、実トークン上限ではありません。両方を同時には指定できません。

## ソースから試す

このリポジトリを clone し、そのフォルダーで以下を実行します。Node.js 24 以上が必要です。VSIX や文書 ZIP にはデモのソースを同梱していません。

```sh
npm ci
npx playwright install chromium
npm run build
```

別のターミナルでローカルデモを起動します。

```sh
node examples/demo-server.mjs
```

MCP ホストから、デモ用ポリシーを指定してサーバーを起動します。パスは実際の絶対パスへ置き換えてください。ホストによって設定ファイルの形式は異なります。

```json
{
  "mcpServers": {
    "agentdesklink": {
      "command": "node",
      "args": [
        "/absolute/path/AgentDeskLink/dist/src/server.js",
        "--config",
        "/absolute/path/AgentDeskLink/config/demo.json"
      ]
    }
  }
}
```

サーバーは stdio 接続です。デスクトップをソースから利用する場合は OS 用 helper のビルドと設定も必要です。Linux の helper は Python スクリプト(`native/linux-atspi/adl-linux-atspi-helper.py`)なのでビルドは不要で、`python3-gi`・`gir1.2-atspi-2.0`・`at-spi2-core` を OS に導入します。

CLI の相対 `auditPath` はポリシー JSON のあるディレクトリから解決します。書き込めない場合は、接続前に標準エラーへ原因コードを出して停止します。

設定と利用範囲は[操作設定と承認](release-docs/OPERATIONS.md)を参照してください。

### 設定例

| 試したいこと | 設定ファイル |
| --- | --- |
| ローカルのブラウザデモ | [demo.json](config/demo.json) |
| ブラウザの画像取得 | [visual.example.json](config/visual.example.json) |
| macOS 計算機の操作 | [macos-calculator.example.json](config/macos-calculator.example.json) |
| Windows 文字コード表の操作 | [windows-character-map.example.json](config/windows-character-map.example.json) |
| Linux アプリ(AT-SPI2)の標準モード操作 | [linux-atspi.example.json](config/linux-atspi.example.json) |

## ガイド

- [インストールとはじめ方](release-docs/INSTALL.md)
- [このバージョンの変更点](release-docs/RELEASE_NOTES_ja.md)
- [対応環境と既知の制限](release-docs/KNOWN_ISSUES.md)
- [更新の設定](release-docs/UPDATES.md)

## ライセンス

[MIT License](LICENSE)。同梱する第三者ソフトウェアには、それぞれのライセンスが適用されます。

TDQS

B3.4/5.0

Scored across 16 tools

Disambiguation4/5

Most tools target distinct stages: discovery, target/app lifecycle, semantic observation, pixel capture, physical input, batch execution, task control, and session close. A few adjacent pairs exist—capture vs record, act vs execute, app vs applications—but their descriptions clarify mode, safety boundary, and scope.

Naming Consistency4/5

All tool names share the adl_ prefix and snake_case style, with no mixed casing conventions. The pattern is not strictly verb_noun throughout, since several are noun-only discovery/lifecycle tools such as adl_capabilities, adl_targets, adl_applications, adl_app, and adl_task.

Tool Count4/5

Sixteen tools is slightly above the ideal compact range, but each maps to a distinct capability or safety lifecycle stage. The count is reasonable for a safety-sensitive desktop/browser automation server, though capture vs record and act vs execute add some surface area.

Completeness5/5

The surface covers discovery, target/app lifecycle, open/observe, semantic and physical input, batch execution, waiting, task management, and session close. Missing capabilities like arbitrary JS, clipboard access, or unrestricted OS input appear to be intentional safety exclusions rather than gaps.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues