pyjab-mcp

pyjab-mcp

AI エージェントから pyjab を通じてJava デスクトップアプリケーション（Swing および AWT）を操作できる MCP サーバーです。pyjab は Java Access Bridge を介して JVM 自体のアクセシビリティツリーを読み取ります。JavaFX はサポートされていません。JavaFX は Java Access Bridge ではなく UI Automation を通じてアクセシビリティ情報を公開するため、JAB の観点では JavaFX ウィンドウは Java ウィンドウではありません （pyjab#227）。

mcp-name: io.github.gaozhao1989/pyjab-mcp

対象アプリケーションを変更、再起動したり、コードを注入したりすることはありません。 これが重要な制約です。起動パラメーター、クラスパス、依存 JAR はすべてそのまま維持されるため、変更できない本番環境の Java クライアントにも使用できます。

代替手段は、対象 JVM の内部にエージェントを配置することです。 エージェントは、すでに実行中の JVM にアタッチするか、アプリケーションの起動時にコマンドラインで -javaagent を指定します。どちらの場合も、ツールのコードは他者のプロセス、つまり自ら起動しておらず、制御もしていない JVM の内部に置かれます。このサーバーはどちらも行いません。アプリケーション内に何も読み込まず、Java Access Bridge を通じて外部からアクセシビリティツリーを読み取るため、自ら起動していないプロセスにもアタッチできます。

このうち、すでに実行中の JVM にエージェントを動的にアタッチする方法については、JDK の方針が示されていますが、適用時期は未定です。 JEP 451 は準備段階として JDK 21 で導入され、すでに実行中の JVM へのエージェントの読み込み時に警告が出るようになりました。この JEP はその目的を、*「エージェントの動的読み込みをデフォルトで禁止する将来のリリースに向けてユーザーに備えてもらうこと」*としていますが、そのリリースはまだ特定されていません。また、JEP 自体の非目標では、起動時に -javaagent で指定するエージェントや、エージェントの読み込み以外を目的とする Attach API の使用は、この方針の対象外とされています。

ステータス

PyPI でリリース済み — 16 個のツール：java_diagnostics、java_list_windows、java_attach_window、java_snapshot、java_find、java_get_element、java_get_text、java_get_table、java_click、java_set_text、java_select、java_fill_form、java_send_keys、java_focus_window、java_wait_for、java_screenshot。pyjab>=1.11.0 が必要です。1.9.0 ではスナップショットの作成に使用するツリー走査が追加され、1.10.0 では公開ウィンドウ一覧と JABDriver.detach() が追加されました。これはプロセスを終了せずにドライバーのバインドを解除します。このサーバーにはセッションを解除するツールがないため、バインドはプロセスの存続期間中続きます。1.11.0 では JABDriver.send_keys が追加され、java_send_keys が実際のキーコンビネーションを送信できるようになりました。また、JABDriver.focus() も追加され、java_focus_window でウィンドウを前面に表示できるようになりました。

java_send_keys は、キーボードフォーカスがあるウィンドウにキーコンビネーションを送信します。また、アタッチしてもウィンドウにフォーカスは与えられません （pyjab#180）。 java_focus_window はこの不足を補います。ウィンドウを前面に表示し、フォーカスを要求したこととフォーカスを得たことは異なるため、実際にウィンドウが前面に表示されたかどうかを推測せずに報告します。API の存在を決めつけずに確認するため、指定バージョンより古い環境では AttributeError で失敗するのではなく、どのリリースで利用できるかが示されます。

名前が同じ要素が 2 つある場合があります。 そのため、ハンドルには要素の名前だけでなく、位置も含まれます。名前で検索するとすべての一致が返され、それぞれに個別のハンドルが割り当てられます。また、エンドツーエンドテストでは、一方をクリックしたときに他方ではなく、その要素だけが操作されることを確認します。

確認が完了するまで、何も操作されません。 各操作では要素を再検索し、ロール、名前、兄弟要素内の位置、境界をスナップショットの記録内容と比較してから、確認した要素に対して操作します。何かが異なる場合は何もせず、その差異を報告します。 java_get_table は、この基盤が真価を発揮する部分です。プラットフォームブリッジではまったく取得できない情報を、そのブリッジ経由ではなく、JVM 自身の AccessibleTable インターフェースを通じて JTable から読み取ります。行数と列数を取得し、その後、行をページ単位でセルのテキストを読み取ります。

実際の動作は windows-gui.yml によってホストされた Windows ランナー上で検証されます。エンドツーエンドテストでは、実際の Swing アプリケーションに接続してスナップショットを取得し、実際の要素に対してハンドルを解決し、ブリッジがアイドル状態になった後に開かれたウィンドウも引き続き認識されることを確認します。最後のテストがこのレイヤーが存在する理由です。間違ったスレッド上のメッセージポンプでも、このリポジトリのほかのテストはすべて通過します。このテストでまだカバーできないのは、皆さんのアプリケーションです。実行時には pyjab のテストアプリを操作しますが、本当に重要なのは皆さんが使うアプリケーションです。

上記のツール一覧で指定されているものと同じ pyjab>=1.11.0 が必要で、そこで挙げられているリリースが対象です。ここで改めて説明する価値がある追加点は JABDriver.focus() です。java_focus_window はこれを使ってウィンドウを前面に表示し、前面に表示できたかどうかも報告します。この戻り値こそが、このツールが存在する理由です。キーの組み合わせを送信する前に呼び出し元が知る必要があるのは、フォーカスを要求したという事実ではなく、キーボードフォーカスが実際にどこにあるかです。

java_snapshot のハンドルは参照ではなく位置です。後続の呼び出しでは要素を再検索し、何らかの処理を行う前にロール、名前、位置、境界を確認します。そのため、ウィンドウが移動していた場合は、誤ったコントロールに操作を実行するのではなく、メッセージが返されます。

すでに結論が出ていたのは、この方針全体の根拠となった疑問です。 汎用の Windows オートメーションが使うものと同じ UIAutomationCore を通じて、実際の Java ウィンドウで測定した結果は次のとおりです。

	要素数	名前付き	深さ
汎用 UI Automation、Java ウィンドウ	6	5	3
pyjab、同じウィンドウ	601	513	12
対照：UI Automation、デスクトップ全体	147	99	完了

対照があることで、要素数が 6 という結果に意味が生まれます。同じ測定をデスクトップ全体に対して行うと完了するため、測定自体は機能しており、Java ウィンドウが難しい対象だと分かります。

まず読むファイル

ファイル	内容
docs/ARCHITECTURE.md	サーバーの構成、設計上の制約、それぞれのガードが適用する内容
docs/CLIENTS.md	Claude Desktop、Claude Code、Cursor、VS Code への接続方法
docs/RELEASING.md	リリースの手順と、リリース前に必要なもの
CHANGELOG.md	変更点とその理由

メンテナー向けの作業メモは、意図的にこのリポジトリには含めていません。ユーザーやコントリビューターに必要な情報はすべて上記にあり、文章以外のルールは tools/ のガードで適用されます。これらのガードはプッシュのたびに CI で実行されます。

要件

• Windows
• Python 3.10 以降
• Java Access Bridge を有効にした JDK — "%JAVA_HOME%\bin\jabswitch" -enable を実行してから、操作対象の Java アプリケーションを再起動してください
• 依存関係一式を導入する pyjab

インストール

pip install pyjab-mcp

サーバー自体を開発する場合は pip install -e ".[dev]" を実行してください。詳しくは開発方法をご覧ください。

またはバンドルをインストールする：1 ファイルでビルド不要

v0.1.0～v0.1.2 はバンドル登場前のリリースで、アセットは含まれていません。それ以降のリリースにはすべてバンドルが含まれています。バンドルは pyjab-mcp-<version>.mcpb というファイルで、ビルド済みの wheel とその依存関係一式を、サポート対象の CPython マイナーバージョンごとに 1 つのツリーへまとめ、エントリースクリプトと一緒に 1 つのファイルに収めたものです。各ツリーにはパッケージ自体も含まれているため、このファイルには、ツリーの隣に wheel が 1 つ置かれるのではなく、マイナーバージョンごとに pyjab_mcp が 1 つずつ含まれます。リリースページからダウンロードし、クライアントに渡してください。Claude Desktop では .mcpb を開いてインストールできます。詳細はdocs/CLIENTS.mdを参照してください。

バンドルによって上記の要件が変わることはありません。ただし、そのうち 1 つは、実際に同梱されているインタープリターに限定されます。 Python インタープリターも JDK もバンドルされません。このサーバーは Java Access Bridge を操作するため、マシンには引き続き 64 ビット版 Windows、64 ビット版 CPython 3.10～3.13、Java Access Bridge が有効な JDK が必要です。また、接続する前に、操作対象の Java アプリケーションを起動しておく必要があります。このバージョン範囲は上限のない pip install よりも狭く、これは些細な違いではありません。pydantic-core、cffi、rpds-py、cryptography、pywin32 はそれぞれ 1 つのマイナーバージョン向けにタグ付けされたコンパイル済み wheel を提供しているため、バンドルは数十メガバイトになります。ほかのインタープリターで起動すると、ネイティブモジュールからの ImportError ではなく、検出したインタープリターとファイルに含まれるインタープリターを明記したメッセージを表示して停止します。

インタープリターは PATH 上の python である必要があります。 マニフェストでは user_config によるフォールバックを宣言していないため、クライアントはそこで解決される python を実行します。CPython がインストールされていても PATH 上にないマシンでは、クライアントにツールが表示されません。また、原因を示す情報もありません。インタープリター自体が起動しないため、バンドルによる拒否メッセージも実行できないからです。where.exe python を実行すると使用されるインタープリターが表示されます。何も表示されない場合は、インストール先のディレクトリを PATH に追加してください。

MCPB は権限を制限しません。 マニフェストレベルのサンドボックスはありません。バンドルされたサーバーは、手動で起動した場合とまったく同じように、インストールしたユーザーの完全な権限で実行されます。このファイルを含め、誰かから受け取った .mcpb をインストールする前に、ソースコードを確認してください。

使い方

パッケージがインストールするコンソールスクリプト：

{
  "mcpServers": {
    "pyjab-mcp": { "command": "python", "args": ["-m", "pyjab_mcp"] }
  }
}

Claude Desktop は %APPDATA%\Claude\claude_desktop_config.json を読み込み、次の設定を使用します（バックスラッシュを 2 つ重ねてください。JSON ではその必要があります）。

{
  "mcpServers": {
    "pyjab-mcp": { "command": "C:\\Users\\you\\.venv\\Scripts\\pyjab-mcp.exe", "args": [] }
  }
}

Claude Code では、同じエントリが自動的に書き込まれます：claude mcp add pyjab-mcp -- pyjab-mcp。

**docs/CLIENTS.md**には Cursor と VS Code の設定、それぞれが読み込む設定ファイル、多くの環境で設定に失敗する Windows のパスの問題、ツールがエラーを返した場合の対処方法も記載されています。

まず java_diagnostics を実行してください。環境のどの部分が不足しているのかを報告します。たとえば Java Access Bridge が有効になっていない、ブリッジ DLL がない、32 ビット版インタープリターが使われている（その場合は 32 ビット版ブリッジ DLL を探します）といった状態です。ロケーターエラーでツール呼び出しが失敗するのを防げます。

できることと、できないこと

Java Access Bridge は、アプリケーションが自らについて宣言している情報、つまりロール、名前、値、状態、コントロールがサポートするアクションのツリーを公開します。このサーバーが操作するのはその情報であり、アクセスできる範囲もそれによって決まります。

対応しているのは、アクセシビリティ情報を公開する Java アプリケーション、すなわちデスクトップアプリケーションとして実行されている Swing および AWT アプリケーションとアプレットです。JavaFX はサポートされていません。アクセシビリティ情報を Java Access Bridge ではなく UI Automation 経由で公開するためです。ボタン、メニュー、テーブル、ツリー、リスト、テキストフィールドとその値はすべて読み取りと操作が可能です。また、java_get_table はピクセルではなく、テーブル自体のインターフェースを通じてセルを読み取ります。

アクセスできないものは、読み取る情報が存在しないものです。

サポート対象外	理由
Canvas に描画されたインターフェース — 独自のウィジェットを描画する JPanel	アクセシビリティ対応の子要素がないため、見つけることも、クリックすることも、読み取ることもできません。java_screenshot で画像を見ることはできますが、画像を操作することはできません。このようなパネルを操作する必要がある場合、アプリケーション側でコントロールを公開する必要があります。これは予想ではなく、実測に基づいています。 pyjab は Canvas に描画されたパネル（pyjab#73）を調査し、アクセシビリティ対応の子要素がないことを確認しました。このリポジトリには現在、パネルを描画し、子コンポーネントを含まないフィクスチャアプリケーション（tests/e2e/fixtures/BoundaryApp.java）を使った回帰テストがあります。このテストでは、パネルが children_count = 0 のリーフであること、および同じ要素のスクリーンショットから実際の PNG バイト列が返されることを併せて検証します。つまり、ピクセルはあっても構造はないという点が、まさに重要なのです。このテストは windows-gui ジョブで実行されます。pyjab でも同じ課題が pyjab#169 で追跡され、こうした動作 4 件の回帰テストを追加したうえで、2026-10-10 に完了としてクローズされました。
ブラウザー内の Java（埋め込み JVM、Java Web Start の子孫）	ウィンドウを所有しているのはブラウザーであり、JAB を通じてアプレットの Java アクセシビリティツリーを公開しません。
プラグインホスト内のアプレット	同じ理由で、JAB ツリーがデスクトップに届きません。
Java 以外の Windows アプリケーション	このサーバーは UIA に対応していません。UIA ベースの MCP サーバーが適切なツールです。
ピクセルベースのもの全般 — スクリーンショットを読んでレイアウトを推測すること、座標をクリックすること	明確に対象外です。ピクセルからの推測を置き換えることが、このプロジェクトの目的です。

次の点もご確認ください。

• アプリケーションは起動前に JAB を有効にしておく必要があります。 起動後に JAB を有効にしても、実行中のプロセスにツリーは追加されません。アプリケーションを再起動してください。
• このサーバーはアタッチのみを行います。 アプリケーションを起動することも終了することもありません。JABDriver.detach() はバインドを解除し、プロセスは実行中のままにします。
• 画像は構造ではありません。 java_screenshot は画面を見るためのものです。操作したいものはすべてツリー内で見つける必要があります。ハンドルと名前が存在するのはそこだからです。

意図的に対象外としていること

上記の一覧は、基盤 が対応できないことです。ここでは別の種類、つまりこのサーバーで実現可能でもあえて対応していないことを挙げています。ホスト型の代替サービスと比較して評価する人が、何を手放すことになるのか、また、それぞれを追加するには何を変更する必要があるのかを把握できるようにするためです。

ないもの	理由と追加に必要なこと
リモートトランスポート（ストリーミング可能な HTTP、SSE）	MCP との通信は stdio のみです。クライアントがローカルでサーバーを起動し、同じデスクトップ上のアプリケーションに接続します。リモートトランスポートを実現するには、接続先となる Windows ホスト、認証の仕組み、そして 2 つ目のクライアントが、1 つ目のクライアントが操作中のアプリケーションに何をできるのかを決める必要があります。
同時に複数のセッションを利用すること	セッションは軽量かつ独立している（ウィンドウごとに java_attach_window を使用する）ため、現在でも複数のウィンドウを利用できます。足りないのはマルチテナントの調停、つまりアプリケーションの所有者を誰とするか、2 つのエージェントが同時に操作した場合にどうするかです。これは機能ではなくポリシーの問題です。
監査ログ	ここでは、実行した内容を記録するジャーナルは作成されません。監査証跡となるのは MCP クライアントが保持するトランスクリプトであり、その完全性はクライアント側の責任です。サーバー側のログを実装するには、追記専用ファイルに加えて、何を絶対に記録してはならないか（ウィンドウタイトルやセルの値はユーザーデータです）を決める必要があります。
バッチ実行	バッチツールは java_fill_form のみで、意図的に実行範囲を制限しています。「これらのツール呼び出しを順番に実行する」という汎用機能を作るなら、セキュリティモデルを備えたスクリプト言語が必要になりますが、クライアントにはすでにそれがあります。
CI との統合	このリポジトリのエンドツーエンド層が、このリポジトリに対する答えです。他の人のアプリケーションをその人のパイプラインから操作するには、デスクトップセッションを備えた、ヘッドレスに近い Windows ランナーが必要です（これは存在し、windows-gui ジョブで使用しています）。さらに、そのランナーに対象のアプリケーションをインストールし、JAB を有効にする必要があります。

それぞれは未完成の機能ではなく、意図的に設けた境界です。トランスポートやマルチテナントなど、アーキテクチャに関わるものを追加すると、ServerState の隣に機能を置くのではなく、その構造自体を変更することになります。

サポート

• 無料サポート — バグ、質問、機能リクエストは GitHub の issue にお寄せください。 pyjab-mcp --version と java_diagnostics ツールの出力を含めてください。この 2 つがあれば、環境に関する質問の多くに、聞かれる前に回答できます。
• 商用・エンタープライズサポート — 制限されたネットワーク内への導入、特定のアプリケーションへの適応、または SLA については、[email protected]（このパッケージのメタデータに記載されているアドレス）までご連絡ください。オープンソースパッケージは完全版で、利用制限もありません。ライセンスキーや割り当て上限はなく、利用できないよう制限された機能もありません。

検証方法

プッシュのたびに実行されるテストスイートでは、アプリケーションを操作できません。Windows、JDK、デスクトップセッション、起動中の Swing アプリケーションが必要だからです。その層は tests/e2e/ にあり、PYJAB_MCP_E2E=1 が設定されている場合を除いてスキップされます。windows-gui.yml は、ホスト型の windows-latest ランナー上で、手動または毎週のスケジュールでこのテストを実行します。このテストでは、ブリッジがアイドル状態になった後に 2 つ目の JVM を起動します。誤ったスレッド上のメッセージポンプは、他のすべてのテストに合格して、このケースだけで失敗するためです。

gh workflow run windows-gui.yml -f java=17     # the end-to-end run and the JDK matrix
gh run watch

これはステータスチェックではありません。誰かが実行を依頼するか、週次の実行日が来ない限り実行されないため、通常の CI が成功していても、稼働中のウィンドウについては何も示しません。

リリース

タグに基づいてリリースします。src/pyjab_mcp/__init__.py のバージョンを更新し、変更履歴の Unreleased セクションを新しいバージョンの下に移動して、server.json を設定した後、python tools/check_release_version.py vX.Y.Z を実行してタグを付けます。 docs/RELEASING.md に手順全体、一度だけ行う 2 つのセットアップ（PyPI のペンディングパブリッシャーとレジストリの名前空間）、および 4 つのリリースジョブの内容が記載されています。

取り組み中

python -m pytest tests/                    # the portable suite, any platform
python tools/check_pyjab_api_surface.py    # every pyjab call is public, released, recorded
python tools/check_documented_surface.py   # docs/ARCHITECTURE.md's tool table and the code agree
python tools/check_local_only_files.py     # maintainer notes stay unpublished
python tools/check_pyjab_readiness.py      # which pyjab APIs the pin expects, and whether it resolves them
python tools/check_pyjab_changelog.py      # every marked pyjab change has an answer here
python tools/check_published_references.py # shipped files do not cite unpublished ones
python tools/check_changelog_immutable.py  # a released changelog section is frozen
python tools/check_release_version.py vX.Y.Z  # the four places a version lives agree
python -m pytest tests/contract/           # the pyjab shapes this project depends on
python -m build && python tools/check_dist_contents.py --dist dist

残りの 2 つ、check_release_l3.py と check_release_unpublished.py は、読み取るタグまたは実行があって初めて意味を持つため、手動ではなくリリースパイプライン内で実行されます。

ガードは、プロジェクトのルールを機械的に適用するものです。pyjab が独自のルールに使っているものと同じ形式で、許可されている内容を登録し、双方向にチェックします。そのため、呼び出し箇所を追加しても、許容される理由が記述されるまでは失敗します。docs/ARCHITECTURE.md に、各ガードとその適用内容を記載しています。