joLink

joLink Runtime

English | 简体中文

AI コーディングエージェント向けの軽量なヘッドレス Java IDE です。

自律的な Java 開発のフィードバックループを完成させます。

設計原則： LLM の不確実性を減らすために、すべてが存在します。

joLink はエディター UI を提供しません。その代わりに、MCP を通じてインクリメンタルコンパイル、 テスト、アプリケーションの起動、ブレークポイントデバッグを、すでに利用しているコーディング エージェントに公開します。これにより、エージェントはコードを実行し、実際の状態を調べ、自らの 変更を検証できます。

コンパイル状態の保持と HotSwap により、全体の再ビルドや JVM の再起動を繰り返す回数を減らします。 テスト、ログ、エンドポイントの応答だけでは十分でない場合、エージェントはブレークポイントを使い、 例外イベント、スタックフレーム、変数を調べることができます。

無料でローカルに利用できます。joLink アカウント、モデル API キー、推論プロバイダー、個別の エージェントアプリケーションは必要ありません。

インストール

1. コーディングエージェントで新しいチャットを開きます。
2. 以下のコードブロックのコピーボタンをクリックし、プロンプト全体をチャットに貼り付けて送信します。

Follow this guide:
https://github.com/L1ch404/jolink-runtime/blob/main/INSTALL.md
Install joLink MCP and its English Skill for my current agent.
Enable the global Java change-verification rule for this agent across projects.
Use user-level installation by default and preserve existing configuration.
Check the saved configuration, Skill and rule. If a client UI action or reload is needed,
stop and tell me what to do; leave connection and rule-loading verification to a chat after reloading.

警告

上記のプロンプトに従うと、現在のエージェントに Java のグローバル検証ルールが追加され、すべてのプロジェクトに適用されます。 これにより、エージェントは追加のテストや実行時チェックを行うため、トークン使用量とタスク完了までの時間が増える場合があります。 このグローバルルールを適用したくない場合は、プロンプトを送信する前に有効化する行を削除してください。

3. エージェントから再読み込みが必要だと報告された場合は、指示に従って MCP を再接続するか、クライアントを再起動し、 新しいチャットを開きます。設定が完了していても、まだ読み込まれていないことはインストール失敗を意味しません。 読み込み済みのチャットでは、次のように送信できます。

Verify the existing joLink MCP and jolink-java Skill in this client without reinstalling them.
Call the joLink status tool exposed by this client once, and check its Skill list or loading facility.
If I enabled it, also check whether the global Java change-verification rule is loaded through the client's native instructions view.
If anything is unavailable or its loading cannot be confirmed, report it and stop; do not write a standalone verification script.
Do not start applications or run tests.

このガイドでは、Codex、 Claude Code、Cursor、VS Code/Copilot、CodeBuddy、Gemini CLI、OpenCode、Cline、 Roo Code、Windsurf、Kiro 向けに、公式のクライアント別設定場所と例を紹介します。すべて uvx jolink-runtime@latest で MCP を起動し、同じ English Skill を使用します。プラグインバンドルや統合インストーラーは 必要ありません。作業を行うのは MCP で、ワークフローを説明するのは Skill です。オプションの グローバル検証ルールを有効にすると、すべてのプロジェクトの 実装タスクに、妥当な範囲の Java 検証が適用されます。上記のプロンプトでは明示的にこのルールを 有効にしています。MCP と Skill だけを使いたい場合は、この行を削除してください。 このガイドでは、uv のセットアップ、設定の保持、再接続、検証についても説明します。

中国語の手順については、中国語版インストールガイドを参照してください。

joLink を選ぶ理由

コーディングエージェントはコードの読み取りや変更を得意としますが、静的な仮定のループから 抜け出せなくなることがあります。

analyze
-> patch
-> assume the patch works
-> patch again

joLink は不足している実行時のフィードバックループを追加します。

analyze
-> change
-> run
-> observe
-> update the hypothesis
-> change again if necessary

次のような場合に役立ちます。

• Java アプリケーションがまだ実行されていない；
• コード変更を実際の動作に照らして検証する必要がある；
• パッチを繰り返し適用しても問題が解決していない；
• エンドポイントの結果がソースコードの解釈と一致しない；
• 実行された経路を説明するには、ログやテストだけでは不十分である；
• ビジネス上の命名に一貫性がなく、静的検索では関連コードを見つけられない；
• ブレークポイント、スタック、変数など、より詳細な実行時の証拠が必要である。

すべての問題でデバッガーを使うことが目的ではありません。

まず、役立つ最も低コストの証拠から確認します。

application status
-> logs and actual outputs
-> exception events
-> executed path
-> breakpoints, stack frames, and variables

必要な場合にのみ、さらに詳しくデバッグします。

できること

joLink は、次の4つの目的に特化した MCP ツールを提供します。

• java_application — プロジェクトの起動、コンパイルを考慮した再起動（デフォルトでは HotSwap）、停止、アタッチ。
• java_fast_test — アプリケーションを起動せずに、選択した Java テストを実行し、結果の詳細を確認して実行をキャンセル。
• java_status — Java プロセスの検出、簡潔なステータスの表示、必要に応じた詳細情報とログの取得。
• java_debugger — ブレークポイント、例外イベント、スタック、変数、再開。

管理対象プロジェクトを編集した後は、java_application(action=restart) を呼び出してください。 既存の JDT ワークスペースで変更をインクリメンタルにコンパイルし、HotSwap を優先します。互換性のない変更がある場合は、同じコンパイル済み出力を使って JVM を再起動します。 hotswap=false を設定すると、プロセス／アプリケーションを強制的に再初期化します。結果の apply_method で、HotSwap と実際の再起動を区別できます。再起動ワークフローを参照してください。

Fast Test は、小規模な設定キャッシュが存在しない場合、または変更されている場合にのみ、Maven または Gradle Probe を使用します。エクスポートされたテスト Build World と JDT ワークスペースは、MCP プロセスをまたいで保持されます。JDT はメインクラスとテストクラスを最新の状態に保ち、明示的に指定された JUnit 4/5 または TestNG のテストを分離された JVM で実行します。

java_fast_test(action=run,
  project_path=/path/to/project,
  source_files=[src/main/java/example/Service.java],
  tests=[example.ServiceTest#works], timeout=60)
-> if unfinished, choose a suitable waiting interval, then call java_status(action=status)
-> read diagnostics/failures with java_fast_test(action=result, test_run_id=...)
-> cancel with java_fast_test(action=cancel, test_run_id=...)

java_status(status).fast_test は簡潔なままです。run が返る前にコンパイルに失敗した場合、返信にはコンパイラの診断情報が直接含まれます。タイムアウト後に発生したエラーと失敗したテストの詳細は result から確認できます。テストを再実行せず、概要の next_action に従うか、test_run_id を使用してください。 コンパイラのファイル一覧全体は省略されます。現在の MCP セッションでは、実行中および直近に完了したテストの試行のみが保持されます。利用できない ID を指定すると、TEST_RUN_NOT_FOUND が返されます。

passed=false は、選択したテストが実行され、失敗が見つかったことを意味します。ツールのインフラストラクチャエラーではありません。Fast Test は、実行中のアプリケーションを必要とせず、変更もしません。現在の JDT は、Java 8 から 26 までのソース／ターゲットレベルをサポートしています。製品の回帰テストでは、メインとテストで異なるレベルを設定した場合も含め、8、11、17、21 を対象としています。 ターゲットライブラリとアプリケーション／テストの JDK は、引き続きプロジェクトの設定に従います。 サポートされるビルド構成には、Maven の jar プロジェクト、標準的な Reactor 内で明示的に1つ選択した jar モジュール、複数の Project 間の依存関係を含む Gradle の Java ビルド（7.4.2、8.10、8.14 でテスト済み）が含まれます。 Maven と Gradle のマルチモジュールの起動および Fast Test では、選択したモジュールの上流依存関係が、1つの Worker 内の個別の JDT プロジェクトに解決されます。 変更されていないモジュールは出力を再利用します。JavaBuilder は、変更された API と定数を、影響を受ける下流のソースに反映します。ローカルのモジュール依存関係には、インストール済み JAR ではなく、現在のワークスペースの出力が使用されます。Maven は test-jar 依存関係にも対応しています。Gradle のマルチモジュールのフローと検証結果を参照してください。

デモ

予期しない API レスポンスから、実行時の調査へ。

ソースコードを読むことで、エージェントは何が起こり得るかを把握できます。アプリケーションを実行して状態を調べることで、実際に何が起きているかを確認できます。

以下のスクリーンショットは、デバッグの例を示しています。エージェントが Java アプリケーションを起動し、エンドポイントを確認して予期しない結果に気づき、joLink を使って実行経路を調査します。

これは構成されたデモシナリオであり、実際の業務上のインシデントの記録ではありません。 プライバシー保護のため、スクリーンショット内の一部の機密情報はマスキングされています。

1. アプリケーションを起動し、実際のレスポンスを確認する

エージェントは java_application を使ってアプリケーションを起動し、java_status で状態を確認してから、サンプルのリスクスコアリングエンドポイントに HTTP リクエストを送信します。

score=80 の場合、想定されるカテゴリは High Risk ですが、エージェントには Medium Risk と報告されます。さらに調査する前に、追加の境界値を確認します。

2. ブレークポイントを設定し、実行時変数を調べる

エージェントは java_debugger を使って Medium Risk 分岐にブレークポイントを設定し、 別のリクエストを実行して、ブレークポイントに到達した後の変数を調べます。

会話には、実行が Medium Risk 分岐にある間、score=80 と表示されています。これにより、エージェントはソースコード上の想定だけに頼らず、実行時の証拠に基づいて境界条件に関する仮説を調査できます。

この例では、アプリケーションの起動と実行時の調査を紹介します。 これは Fast Test のパフォーマンスベンチマークではありません。スクリーンショットは調査段階を示しており、その後の修正と再検証は含まれていません。

プライベート診断

joLink は stdout を MCP JSON-RPC 専用に保ちます。Python のライフサイクルログと トレースバックも、上限付きのプライベートなローテーションファイルに書き込まれます。

Windows: %LOCALAPPDATA%\jolink-runtime\logs\mcp.log
macOS/Linux: $XDG_CACHE_HOME/jolink-runtime/logs/mcp.log
               or ~/.cache/jolink-runtime/logs/mcp.log

status は、details=true を指定しても mcp.log のパスやログ設定を返しません。 joLink 自体の診断を行う場合は、上記のパスにあるローカルファイルを読み取ってください。診断ファイルの エラーによって MCP サーバーの起動が妨げられることはありません。このファイルは 4 MiB に制限され、ローテーションされたバックアップが 3 つ保存されます。stdout は変更されません。

java_status(action=status) は、準備状態、プロセス／デバッグ状態、 アクティブな操作、最近の再起動／テストの概要を簡潔に表示します。現在の起動エラー、 完全な last_reload、コンパイラー／キャッシュ設定、所要時間を確認するには、 java_status(action=status, details=true) を読み取ってください。 完了した launch/restart 呼び出しは、それぞれ詳細な結果をすでに返します。この フラグは、同期応答のタイムアウト後も操作が継続した場合に役立ちます。 どちらの呼び出しもビルドログを読み取ったり、埋め込んだりしません。現在の起動のビルドログには java_status(action=logs, source=build) を使用してください。アプリケーションの出力を読み取るには source を省略します。どちらも tail を受け付けます。再起動の概要には、詳細を示す next_action が含まれます。

launch/restart の応答には previous_startup_ms が含まれます。これは、同じ起動について 前回正常に完了した JVM 起動時間をローカルに保存した値で、新しい操作の前に取得されます。 Probe／JDT のコンパイル時間は含まれません。ready_port が指定されている場合は、 TCP の準備完了が観測されるまでの起動時間を測定します。指定されていない場合は、JVM／ JDWP の起動時間のみを測定します。HotSwap や起動の失敗によって、この記録が置き換えられることはありません。 起動が成功すると、joLink キャッシュ内の startup-timings/ ディレクトリにある小さな JSON ファイルに一度だけ書き込まれます。停止、新しい会話、MCP の再起動によって、この記録が破棄されることはありません。 次回の起動時にそのファイルが読み取られます。有効期限、ビルド入力の検証、ステータスの繰り返し書き込みはありません。 記録がない起動では null が返されます。これは待機時間の参考値として扱い、予測値や準備状態の確認として扱わないでください。

MCP サーバーの環境変数に JOLINK_LOG_LEVEL を設定し、サーバーを再起動してください。 WARNING（デフォルト）では警告とエラーのみを保持します。INFO では JDT キャッシュ／ソース／ビルド／保存の概要と、ネイティブ FULL フォールバックの理由を記録します。 DEBUG では詳細な Worker 出力も保持します。ERROR ではエラーのみを保持します。 OFF では joLink の診断ログを無効にします。アプリケーションログとツールの結果には 影響しません。Worker は、増分伝播の上限を 10 ラウンドに固定しています。 JDT ビルド診断を参照してください。

公開アクションは次のとおりです。

launch
stop
restart
attach
detach
breakpoint
exception
wait_event
threads
stack
variables
resume
cleanup_debug_state
processes / status / logs

これらのアクションでは、次のことができます。

• Java アプリケーションを、管理対象の JVM プロセスとして起動する。
• project_path と main_class を指定して Maven／Gradle プロジェクトを起動する。または IntelliJ IDEA の Application／Spring Boot 構成を任意でインポートし、Maven／Gradle のコンパイルを実行せずに Build World をエクスポートし、JVM 起動前に JDT でコンパイルして、実行可能 JAR をパッケージ化せずに起動する。
• コード変更後にアプリケーションを停止または再起動する。
• 検出された編集を永続的なプライベート JDT セッションでコンパイルし、互換性のあるロード済みクラス定義を HotSwap で適用する。
• アプリケーションのステータスとログを確認する。
• すでに実行中のローカル JVM に接続する。
• セマンティックブレークポイントと例外ウォッチを設定する。
• 実行時イベントを待機する。
• スレッド、スタックフレーム、変数を確認する。
• 中断中の実行を再開する。
• デバッグ状態を安全にクリーンアップする。

現在のステータス

現在のパッケージバージョン：

0.1.0a9

ステータス：

Alpha / controlled dogfood

最初のアダプターは、JDWP を介してローカルの Java アプリケーションを対象とします。

現在の MCP 実装には、次の機能が含まれています。

• stdio トランスポート；
• stdout は MCP プロトコルメッセージ専用；
• JSON TextContent と、それに対応する structuredContent；
• Runtime の ok=false を MCP の isError=true にマッピング；
• キャンセル可能な wait_event；
• arm と await による、オプションの 2 フェーズ待機；
• JDWP の準備完了後にのみ起動する、オプションのループバック HTTP トリガー。1 回の呼び出しで完結する blocking ショートカット、または明示的な arm／await を使用できます；
• 待機スコープの JDWP リクエスト；
• 所有権を考慮したシャットダウン；
• 自動クリーンアップと再開パス；
• 短いポーリングタイムアウトをまたいで維持される、永続的な JDWP パケットのフレーミング。

現在の 2 フェーズ実装は、管理されたドッグフーディングを目的としています。 既知のキャンセル、クリーンアップによるプリエンプション、ハンドルの公開、レスポンス配信に関する制限は、次のドキュメントで追跡しています。

docs/stage-2.1.2-lifecycle-backlog.md

このアルファリリースを、無人の本番 JVM デバッグに使用しないでください。

要件

• JDK 8 以降
• uv

uv が Python 環境を自動的に管理します。通常、別途 Python をインストールする必要はありません。

次のコマンドで要件を確認してください。

java -version
uv --version

クイックスタート

MCP サーバーが接続されたら、以下のツールが利用可能であることを確認します。

java_application
java_fast_test
java_status
java_debugger

ローカルの Java プロジェクトを開き、コーディングエージェントに次のように依頼します。

Use joLink to start this Java application, inspect its status and logs,
and verify the latest code changes against real runtime behavior.

複数回修正を試みても解決していない問題の場合は、次のように依頼します。

Do not apply another speculative patch yet.

Use joLink to run the current Java application and collect actual runtime
evidence. Start with status, logs, tests, and actual outputs. Re-evaluate the
root-cause hypothesis before changing the code again.

さらに詳しく調査する場合は、次のように依頼します。

Use joLink to reproduce this issue.

Start with actual outputs and logs. If that evidence is insufficient, use a
breakpoint or exception watch, inspect the relevant stack frames and variables,
then resume or clean up the suspended JVM.

joLink は Java アプリケーションを起動して監視します。コーディングエージェントは、通常使用している HTTP、ターミナル、ブラウザー、テスト用のツールを使ってシナリオを実行できます。

project_path を指定して起動したアプリケーションでメソッド本体を編集する場合、エージェントは Maven のフルビルドや再起動を回避できます。

java_status(action=status; confirm runtime_active and compile_ready=true)
-> java_application(action=restart)
-> if still running, java_status(action=status; observe last_reload)
-> trigger a fresh request
-> verify the new runtime behavior

restart はソースの変更を自動検出してインクリメンタルにコンパイルし、デフォルトで HotSwap を使用します。削除またはアンロードされたクラス、生成リソースの変更、あるいは JVM による明示的な拒否がある場合は、すでにコンパイル済みの出力を使って実際に再起動します。hotswap=false を指定すると、プロセスが再初期化されます。保留中のコード変更がない場合は、コンパイルせずに再起動します。コンパイルエラーが発生しても、以前のプロセスは実行されたままです。HotSwap の応答が失われた場合は、明示的な拒否と誤認せず、結果不明として扱われます。呼び出しは timeout まで（最大30秒）待機します。完了しなかった場合は、既存の reload_id とともに restart_started を返し、active_operation と last_reload から状態を確認できます。apply_method では、HotSwap とプロセスの再起動を区別します。完了したビルドでは、JDT の状態とソースインデックスがローカルの永続ワークスペースに即座に保存されます。クラス出力のコピーは追加で作成されません。HotSwap では初期化が再実行されず、Spring メタデータも更新されません。新しいリクエストで確認してください。再定義されたクラスのブレークポイントは古くなるため、設定し直す必要があります。

ロックされた JDT Worker は、初回使用時にコンテンツアドレス方式のユーザーキャッシュへインストールされます。以前の joLink キャッシュに有効な Eclipse バンドルがあれば再利用され、不足分のバンドルはダウンロードして検証されます。製品の Worker と Equinox 設定は Python パッケージに含まれています。ビルド設定が変更された場合、またはセッションが利用できなくなった場合は、既存のプロジェクト起動パスを通じて更新されます。起動時またはフレームワークの状態を再作成する必要がある場合は、restart(hotswap=false) を使用してください。

この製品は Eclipse 4.40／JDT 3.46 と、それに対応する APT バンドルを使用しています。Worker は Java 17 のバイトコードを対象とし、デフォルトでは非公開の固定バージョンの Temurin 21 ランタイムを使用します。このランタイムはユーザーキャッシュに一度だけインストールされます。Maven／Gradle とアプリケーション／テスト JVM は、それぞれのプロジェクト JDK を引き続き使用します。代わりに、JOLINK_WORKER_JAVA_HOME で企業から提供された64ビットの JDK 17以降を指定できます。Lombok 1.18.20 の古いバージョンとの互換性問題は記録されたままです。プロジェクトの依存関係を置き換えて、問題を暗黙に修正することはありません。オフライン環境でのセットアップと実際の互換性の検証結果については、JDT 3.46 and private Worker JDK を参照してください。

JDK／Eclipse の初回ダウンロードでは、デフォルトで固定された公式 URL を使用します。JOLINK_DOWNLOAD_MIRROR=cn を設定すると、まず TUNA、次に joLink ミラーの https://7355608.net/jolink/assets、接続または転送に失敗した場合は上流の配布元を試します。カスタムミラーのベース URL を指定した場合は、そのミラーを試した後に上流の配布元を試します。official（または空の値）を指定した場合は、上流の配布元のみを使用します。IP アドレスや位置情報による検出は行われません。既存の SHA256 検証とインストール済みキャッシュには影響しません。ローカルでの検証中、TUNA へのアクセスはブロックされていました。cn を選択しても、TUNA が利用可能になるとは限りません。ランタイムミラーの設定を参照してください。

インポートされた IDEA の Make／Build フラグによって、Maven または Gradle のコンパイルが実行されることはありません。初回起動時に Probe がコンパイラーとランタイムの情報をエクスポートし、JDT が FULL コンパイルを実行します。次回以降の起動では、永続化された Probe モデルを再利用し、保存済みのソースサイズと更新日時を使って編集を検出します。追跡対象の Maven／Gradle 設定に変更があると、モデルが更新されます。追跡されていない外部スクリプトと非表示の入力については、互換性に関するフォローアップに記録されています。キャッシュの削除は、通常の起動やインストール手順ではありません。

現在の単一モジュールの起動方法とキャッシュの動作については、JDT を優先する起動方法を参照してください。

一般的なワークフロー

通常の検証フローは次のとおりです。

read the code
-> change the code
-> java_application(launch or restart, ready_port=<application port>)
-> if startup_state=starting, call java_status(status) until ready
-> if startup_state=failed, inspect java_status(logs)
-> trigger a test or endpoint
-> inspect the actual result
-> update the diagnosis

より詳しいデバッグフローは次のとおりです。

run or attach
-> for an owned HTTP application, confirm startup_state=ready
-> configure a breakpoint or exception watch
-> for a managed local HTTP request:
   wait_event(wait_mode=blocking, http_trigger=...)
-> otherwise:
   wait_event(wait_mode=arm)
   -> trigger the scenario after status=armed
   -> wait_event(wait_mode=await, wait_handle=...)
-> inspect stack frames and variables
-> resume or cleanup_debug_state

ローカルの HTTP エンドポイントでは、blocking を使うと既存の arm -> trigger -> await ライフサイクルを 1 回の呼び出しにまとめられます。

{
  "action": "wait_event",
  "wait_mode": "blocking",
  "timeout": 30,
  "http_trigger": {
    "method": "POST",
    "url": "http://127.0.0.1:8080/example",
    "json_body": {"id": 1},
    "timeout_seconds": 30
  }
}

アーム後、観測を始めるまでの間に外部アクションが必要な場合は、 明示的に arm を呼び出してから await を使用してください。終端結果を受け取ると、 その wait_handle は消費されます。このハンドルは Runtime イベントを観測するものであり、 HTTP レスポンス用のハンドルではありません。

joLink が起動した HTTP アプリケーションでは、プロセス／デバッガーの 起動と、アプリケーションの TCP レディネスを区別してください。

{
  "action": "launch",
  "jar_path": "target/app.jar",
  "jdwp_port": 5005,
  "ready_port": 8080,
  "timeout": 30
}

java_application(launch/restart) と java_fast_test では、timeout は同期的な結果待機の時間を制限します。 これにはランタイムの準備とコンパイルも含まれます。デフォルトは 30 秒です。より大きな値も 指定できますが、待機時間は 30 秒に限られます。0 を指定すると、タスクの送信後に戻ります。 この応答期限を過ぎても、元のタスクは続行されます。Test Runner の実行には、 別途内部の 300 秒の制限があります。timeout ではこの制限を設定できなくなりました。 実行中の場合は、段階に応じた待機時間を選び（たとえば sleep や PowerShell の Start-Sleep を使用して）、 その後 java_status を呼び出してください。短い間隔で繰り返しポーリングしたり、タスクを再送信したりしないでください。 以前のレディネス待機引数は削除されており、別名として残されてはいません。 直接の JAR／クラスパス起動では、タスクの状態を返す前に、従来どおりプロセスの作成と JDWP ハンドシェイクを行います。 timeout=0 は追加のレディネス待機を省略しますが、最初のハンドシェイクを非同期にはしません。 プロセスは稼働しているものの、アプリケーションポートが接続を受け付けていない場合、 結果は startup_state=starting のまま成功となります。プロセスは稼働し続け、 next_action=status になります。それ以降の各 status 呼び出しでは、保存されたポートを再度プローブします。 startup_state=ready が意味するのは、設定されたループバック TCP ポートが接続を受け付けたことだけです。 すべての依存関係、キャッシュ、ビジネスエンドポイントが正常であることを示すものではありません。

ready_port が省略されている場合、joLink はアプリケーションのレディネスを断言せず、 startup_state=unverified を報告します。アタッチ済みの JVM と、それ以外の未検証の JVM では HTTP トリガーを 引き続き使用できますが、結果には警告が含まれます。設定済みのレディネスがまだ starting の場合、 joLink は HTTP トリガーを拒否し、リクエストを送信しません。

ランタイムの安全性

joLink 0.1.0a9 は、ローカルの信頼できる開発環境向けに設計されています。

現在の安全上の境界：

• MCP トランスポートは stdio です。
• JDWP へのアクセスはローカル JVM に限定されています。
• 1 つの joLink サーバーが一度に制御する Java ターゲットは 1 つです。
• joLink が起動した JVM は、所有対象プロセスとして扱われます。
• 所有対象の JVM は joLink によって停止される場合があります。
• 外部から起動された JVM はアタッチ、一時停止解除、デタッチされます。
• アタッチされた JVM が意図的に終了されることはありません。
• 生の JDWP リクエストは、待機側が所有している間だけアームされます。論理的なブレークポイントと例外の定義は、削除またはクリーンアップされるまで保持されます。
• 組み込みの HTTP トリガーが受け付けるのは http://127.0.0.1 のみです。環境プロキシやリダイレクトは使用せず、検証エラーにリクエスト URL、ヘッダー、本文、それらの生の値が含まれることもありません。
• 起動前に、設定された ready_port が未使用であり、JDWP ポートと異なることが必要です。TCP プローブはローカルで行われ、アプリケーションリクエストを送信しません。
• response_headers_received が報告するのは HTTP ステータス／レスポンスヘッダーのみです。joLink はレスポンス本文を読み取ったり返したりしません。
• HTTP クライアントの待機をキャンセルすると、joLink 側の接続は閉じられますが、サーバー側のビジネス処理が取り消されたことは保証できません。
• cleanup_debug_state が成功した場合は、それ自体にデバッグ状態の検証が含まれます。別途管理される HTTP のクリーンアップ状態が settling のままでも、JVM のクリーンアップは遅延しません。
• suspension_id を受け取った後、エージェントは resume または cleanup_debug_state を呼び出す必要があります。

JDWP ポートを信頼できないネットワークに公開しないでください。

現在のアルファ版を、リモートまたは本番環境のデバッグに使用しないでください。

クライアントに関する注意事項

CodeBuddy

現在の一部の CodeBuddy 環境では、最初に次のように表示される場合があります。

Description: No description

ホストのツール定義読み込み／検索機能を使用して、実際のスキーマを取得してください。 ツール名だけから引数を推測しないでください。別途インストールする jolink-java Skill は、検出とワークフローのエントリーポイントを提供しますが、 MCP 接続に代わるものではなく、ツールの選択を保証するものでもありません。 設定ファイルが共通だと決めつけず、CodeBuddy の対象環境（CLI、IDE、 エディタープラグイン）に応じて インストールガイドに従ってください。

開発

リポジトリをクローンし、開発用の依存関係をインストールします。

uv sync --extra dev --locked

デフォルトのテストスイートを実行します。

uv run pytest

ソースチェックアウトから stdio サーバーを実行します。

uv run jolink-runtime

同等のモジュールエントリーポイント：

uv run python -m jolink_runtime.transport.stdio

汎用 MCP クライアント設定では、チェックアウトから直接起動できます。

{
  "mcpServers": {
    "jolink-runtime": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/jolink-runtime",
        "run",
        "jolink-runtime"
      ]
    }
  }
}

テスト

joLink のソースを変更した後、MCP サーバーを終了させれば既存の ホストツールハンドルが再接続すると考えないでください。実際の stdio プロトコルを通じて、 現在の作業ツリーから新しいサーバーを起動してください。

uv run python scripts/jolink_mcp_dev_client.py

クライアントは JSONL tools/call リクエストを受け付ける前に、Git コミット、作業ツリーの変更状態、ソースフィンガープリント、 Python 実行ファイル、stderr のパスを出力します。{"command":"quit"} を送信すると、 クライアントを閉じ、サーバーの通常のクリーンアップが実行されます。これは、 未コミットのコードを対話形式で検証するための標準的な手順です。Codex／IDE の MCP 接続は、 テスト対象のコードを確定してから確立してください。

実際のサブプロセス受け入れテストでは、MCP stdio の境界を検証します。

uv run pytest -q tests/e2e/test_stdio_mcp.py

以下を実行します。

initialize
-> tools/list
-> java_status(status)
-> close the stdio client
-> wait for the server process to exit

負荷の高い実際の MCP／JVM テストスイートは、ローカルではオプトイン方式です。

JOLINK_RUN_MCP_JAVA_E2E=1 \
  uv run pytest -q -m mcp_java_e2e tests/e2e/test_stdio_mcp_java.py

管理対象の Temurin 21 Worker と Java 8 アプリケーションのライフサイクルには、独立した 詳細バリデーターがあります（Worker の JDK とアプリケーション／ターゲットの JDK は異なる役割です）。

uv run python scripts/validate_jdt_worker_matrix.py \
  --target-java-home <jdk8> \
  --worker-java-home <jdk21>

uv run python scripts/validate_jdt8_product_mcp.py \
  --jdk8-home <jdk8> \
  --maven-home <maven-home>

JOLINK_RUN_FAST_TEST_E2E=1 \
JOLINK_FAST_TEST_JAVA8_HOME=<jdk8> \
  uv run pytest -q -m fast_test_e2e \
  tests/e2e/test_fast_test_product.py

uv run python scripts/validate_fast_test_build_jdk_matrix.py \
  --target-java8-home <jdk8> \
  --build-java-home <jdk8> \
  --build-java-home <jdk11> \
  --build-java-home <jdk17>

uv run python scripts/build_jdt_worker_release.py \
  --java-home <jdk8> \
  --maven <maven-executable> \
  --gradle <gradle-executable>

負荷の高いテストスイートの標準的な CI 環境は次のとおりです。

Linux
Python 3.11
Application/target JDK 8/11/17/21; managed Worker JDK 21

コントラクト

現行ドキュメント、製品の Java ソースとビルド、 過去の調査記録を参照してください。アーカイブされた実験用の コマンドや制限は、現在の製品インターフェイスではありません。

• MCP v0.1： docs/mcp-contract-v0.1.md
• ランタイムの系譜 2.4.0： docs/runtime-lineage-contract-2.4.0.md

ライセンス

joLink 独自のコードはMIT ライセンスです。ダウンロードした Eclipse／Temurin ランタイムと インストールした Python 依存関係には、それぞれ独自のライセンスが適用されます。 サードパーティに関する通知と該当するソースを参照してください。 オフラインランタイムキットには、対応するソースキットと通知を同梱する必要があります。