fxgraph-mcp-server

生成 AI エージェントが実行中の JavaFX アプリケーションをリアルタイムに分析・操作するための MCP サーバーと Agent Skills を提供するプロジェクトです。

Java Attach API でターゲット JVM にインスペクタエージェントを動的注入し、シーングラフの探索・プロパティ変更・UI 操作・スクリーンショット取得などを AI から直接実行できます。

機能概要

シーングラフ探索 — 実行中の JavaFX アプリのウィンドウ・ノードツリーを JSON で取得
ノード検索 — タイプ・CSS ID・テキスト・スタイルクラスからノードを検索
プロパティ読み取り・変更 — テキスト・スタイル・表示状態などのプロパティを動的に操作
UI インタラクション — クリック・フォーカス・キー入力を JavaFX イベントシステム経由で送信
ノードハイライト — 対象ノードを視覚的なオーバーレイでハイライト表示
スクリーンショット — ノード単体またはシーン全体を PNG 保存

アーキテクチャ

MCP Client (AI / OpenCode)
  └─[STDIO]─► McpServerApplication (Spring Boot)
                └─► FxgraphService (@Tool × 13 メソッド)
                      └─► JavaFxAgent (Attach API + TCP socket)
                            └─[TCP NDJSON]─► FxGraphInspectorAgent (注入済みエージェント)
                                               └─► SceneGraphInspector
                                                     └─► JavaFX Scene Graph

Agent Skills（CLI 経由）:
AI → bash → scripts/fxgraph → fxgraph-cli.jar
              └─► CliCommandDispatcher
                    └─► JavaFxAgent

通信プロトコルは 改行区切り JSON（NDJSON）over TCP。MCP サーバーは STDIO トランスポート で動作します。

サブプロジェクト構成

モジュール	役割
`core`	共有モデル・プロトコル・エージェント通信ロジック（Spring 非依存）
`agent`	対象 JVM に注入される Java Agent（Spring 非依存）
`cli`	軽量 CLI ツール（Agent Skills から直接利用）
`mcp-server`	Spring Boot MCP サーバー（STDIO モード）
`javafx-test-app`	動作確認用サンプル JavaFX アプリ
`skills/fxgraph`	AI Agent Skill 定義・スクリプト

必要要件

Java 21+
Gradle（プロジェクトに gradlew 同梱）
対象の JavaFX アプリケーション（Java 11+ で動作）

セットアップ

ビルド

# プロジェクト全体をビルド
./gradlew build

# 各モジュールの Shadow JAR を生成
./gradlew :mcp-server:shadowJar   # → mcp-server/build/libs/fxgraph-mcp-server.jar
./gradlew :cli:shadowJar          # → cli/build/libs/fxgraph-cli.jar
./gradlew :agent:shadowJar        # → agent/build/libs/fxgraph-agent.jar

MCP サーバーとして使用する（OpenCodeの場合）

fxgraph-mcp-server.jar を生成し、OpenCode の設定ファイルに追記します。

./gradlew :mcp-server:shadowJar

~/.config/opencode/config.json の設定例:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "fxgraph": {
      "type": "local",
      "command": ["java", "-jar", "/path/to/fxgraph-mcp-server.jar"],
      "enabled": true
    }
  }
}

使用するには、プロンプトで use the fxgraph tool と指定します。

fxgraph-agent.jar は fxgraph-mcp-server.jar と同じディレクトリに自動でコピーされます。

Agent Skills として使用する（CLI）

CLI と Agent JAR を skills/fxgraph/scripts/ へデプロイします。

./gradlew :cli:installSkillJars

デプロイ後の構成:

skills/fxgraph/scripts/
├── fxgraph             # 実行ラッパースクリプト
├── fxgraph-cli.jar     # CLI ツール
└── fxgraph-agent.jar   # 対象 JVM に注入されるエージェント

AI エージェントに skills/fxgraph/SKILL.md を読み込ませることで、CLI 経由でも同等の操作が可能になります。

JAR ファイルはバージョン管理対象外（.gitignore）です。ソース変更後は installSkillJars を再実行してください。

MCP ツール一覧

ツール	説明
`discoverApplications`	実行中の JavaFX アプリケーションを一覧取得
`connectApplication`	PID 指定でアプリケーションに接続し `sessionId` を取得
`disconnectApplication`	接続を切断してリソースを解放
`getStages`	ウィンドウ（Stage）の一覧・サイズ・位置を取得
`getScenegraph`	シーングラフのツリー構造を取得（深さ・プロパティ・バウンズ指定可）
`getNodeDetails`	特定ノードの詳細プロパティを取得
`findNodes`	タイプ・CSS ID・テキスト・スタイルクラスからノードを検索
`setProperty`	ノードのプロパティ値を変更（text・style・visible 等）
`selectNode`	ノードを視覚的にハイライト（赤枠オーバーレイ）。`nodeId=0` で解除
`clickNode`	ノードにクリックイベントを送信
`requestFocus`	ノードにキーボードフォーカスを要求
`typeKey`	キー入力イベントを送信（`ENTER`・`TAB` 等のキーコード対応）
`takeScreenshot`	ノードまたはシーン全体のスクリーンショットを PNG 保存

詳細な入出力スキーマは docs/tools-reference.md を参照してください。

使用例（MCP ツール呼び出しフロー）

1. discoverApplications()
   → [{ "pid": 12345, "mainClass": "com.example.MyApp", "javaFX": true }]

2. connectApplication(pid: 12345)
   → { "sessionId": "550e8400-...", "agentPort": 54321 }

3. getStages(sessionId: "550e8400-...")
   → [{ "stageId": "...", "title": "Main Window", "rootNodeId": 987654321 }]

4. getScenegraph(sessionId: "...", depth: 3, includeProperties: true, propertyFilter: ["text"])
   → { "rootNodes": [{ "nodeId": 987654321, "type": "VBox", "children": [...] }] }

5. setProperty(sessionId: "...", nodeId: 123456, propertyName: "text", value: "Hello")
   → { "oldValue": "Click Me", "newValue": "Hello" }

6. takeScreenshot(sessionId: "...", savePath: "/tmp/result.png")
   → { "savedPath": "/tmp/result.png", "width": 800, "height": 600 }

7. disconnectApplication(sessionId: "...")
   → { "success": true }

CLI コマンド一覧

Agent Skills から bash ツール経由で実行します。

CLI="/path/to/skills/fxgraph/scripts/fxgraph"

# 実行中の JavaFX プロセスを検出
$CLI discover

# ウィンドウ一覧を取得
$CLI <PID> stages

# シーングラフを取得（深さ 3、テキストプロパティ付き）
$CLI <PID> scenegraph --depth 3 --props --filter text

# ノードを検索（タイプ・ID・テキスト・スタイルクラスから）
$CLI <PID> find-nodes --type Button
$CLI <PID> find-nodes --id submitBtn
$CLI <PID> find-nodes --text "Submit"
$CLI <PID> find-nodes --styleClass primary-action --stageId <STAGE_ID>

# ノードの詳細プロパティを取得（--filter 必須）
$CLI <PID> node-details <NODE_ID> --filter text,visible,disable

# プロパティを変更
$CLI <PID> set-property <NODE_ID> text "Hello"
$CLI <PID> set-property <NODE_ID> visible false --type boolean

# ノードをハイライト
$CLI <PID> select-node <NODE_ID>

# クリック・フォーカス・キー入力
$CLI <PID> click-node <NODE_ID>
$CLI <PID> focus <NODE_ID>
$CLI <PID> type-key ENTER

# スクリーンショット
$CLI <PID> screenshot ./result.png
$CLI <PID> screenshot ./node.png --nodeId <NODE_ID>

すべてのコマンドは JSON を出力します。--json フラグは存在しません（渡すとエラーになります）。 --props フラグは scenegraph コマンド専用です。node-details では --filter を使用してください。

CLI の完全なオプション仕様は skills/fxgraph/references/ を参照してください。

テスト実行

# 全テストを実行
./gradlew test

# モジュール別テスト
./gradlew :core:test
./gradlew :agent:test        # Monocle (headless) で JavaFX テストを実行
./gradlew :cli:test
./gradlew :mcp-server:test   # 統合テスト（事前に shadowJar が必要）

# 統合テストの事前準備
./gradlew :mcp-server:shadowJar && ./gradlew :mcp-server:test

agent モジュールのテストは Monocle ヘッドレスモードで実行されるため、CI 環境でも追加設定不要です。

動作確認用サンプルアプリ

AtlantaFX (NordDark テーマ) を使った Todo リストアプリをサンプルとして同梱しています。

./gradlew :javafx-test-app:run

技術スタック

ライブラリ	バージョン	用途
Java	21	言語・ランタイム
Spring Boot	4.0.2	MCP サーバー基盤
Spring AI MCP	1.1.2	MCP プロトコル実装
Jackson	2.18.3	JSON シリアライズ
JavaFX	21	対象プラットフォーム
JUnit	5.10.0	テストフレームワーク
Mockito	5.11.0	テストモック
AtlantaFX	2.0.1	テスト用サンプルアプリ

注意事項

STDIO トランスポートのみ対応 — 複数の AI エージェントからの同時接続はできません。
ノード ID はセッション内でのみ安定 — System.identityHashCode(node) を使用しているため、JVM 再起動後は変化します。
Java Attach API — 一部の JVM 設定では AttachNotSupportedException が発生する場合があります。その際は起動オプションに -Djdk.attach.allowAttachSelf=true の追加をお試しください。
MCP サーバーログ — STDIO を汚染しないよう、ログはすべてローリングファイル (fxgraph.log) へ出力されます。
UI 操作の実現性 — クリック・キー入力エミュレーションは OS のセキュリティ制限により低レベルな入力注入が不可能なため、JavaFX イベントシステム経由での模倣を行っています。このため、対象アプリケーションの実装次第では動作しない場合があります（例：ネイティブイベントに依存するコントロール、カスタム描画ノードなど）。

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

fxgraph-mcp-server

機能概要

アーキテクチャ

サブプロジェクト構成

必要要件

セットアップ

ビルド

MCP サーバーとして使用する（OpenCodeの場合）

Agent Skills として使用する（CLI）

MCP ツール一覧

使用例（MCP ツール呼び出しフロー）

CLI コマンド一覧

テスト実行

動作確認用サンプルアプリ

技術スタック

注意事項

関連

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 24 Commits
.github/workflows		.github/workflows
.opencode/commands		.opencode/commands
agent		agent
cli		cli
core		core
docs		docs
gradle		gradle
javafx-test-app		javafx-test-app
mcp-server		mcp-server
skills		skills
.gitignore		.gitignore
AGENTS.md		AGENTS.md
README.md		README.md
build.gradle		build.gradle
gradlew		gradlew
gradlew.bat		gradlew.bat
settings.gradle		settings.gradle

Folders and files

Latest commit

History

Repository files navigation

fxgraph-mcp-server

機能概要

アーキテクチャ

サブプロジェクト構成

必要要件

セットアップ

ビルド

MCP サーバーとして使用する（OpenCodeの場合）

Agent Skills として使用する（CLI）

MCP ツール一覧

使用例（MCP ツール呼び出しフロー）

CLI コマンド一覧

テスト実行

動作確認用サンプルアプリ

技術スタック

注意事項

関連

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages