joLink Runtime
English | 简体中文
A lightweight, headless Java IDE for AI coding agents.
Closing the loop for autonomous Java development.
Design principle: Everything exists to reduce uncertainty for the LLM.
Power your agent
คำสั่งของผู้เผยแพร่เอง ไม่ใช่เอนด์พอยต์ของ PlugMCP
Host a copy with our keys and logs.
uvx jolink-runtime==0.1.0a10Claude Code ไม่มีลิงก์ติดตั้งสำหรับคำสั่งแบบโลคัล ให้คัดลอกคำสั่งด้านล่างแล้วรันในเทอร์มินัล
JOLINK_DOWNLOAD_MIRROR=<value> JOLINK_JDT_GC_AFTER_BUILD=<value> claude mcp add io.github.l1ch404-jolink-runtime -- uvx jolink-runtime==0.1.0a10รันในเทอร์มินัล
{ "mcpServers": { "io.github.l1ch404-jolink-runtime": { "command": "uvx", "args": [ "jolink-runtime==0.1.0a10" ], "env": { "JOLINK_DOWNLOAD_MIRROR": "<value>", "JOLINK_JDT_GC_AFTER_BUILD": "<value>" } } }}claude_desktop_config.json
URL แบบรีโมตหรือคำสั่งบนเครื่องของคุณ? การติดตั้งสองแบบต่างกันอย่างไร
รันบน PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
เปิดจากผู้เผยแพร่
English | 简体中文
A lightweight, headless Java IDE for AI coding agents.
Closing the loop for autonomous Java development.
Design principle: Everything exists to reduce uncertainty for the LLM.
A lightweight Java IDE for AI agents: incremental builds, fast tests, HotSwap and live debugging.
joLink does not provide an editor UI. Instead, it exposes incremental compilation, testing, application startup and breakpoint debugging through MCP to the coding agent you already use—so it can run the code, inspect real state, and verify its own changes.
Persistent compilation state and HotSwap reduce repeated full rebuilds and JVM restarts. When tests, logs and endpoint responses are not enough, the agent can use breakpoints and inspect exception events, stack frames and variables.
Free and local. It does not require a joLink account, model API key, inference provider, or separate agent application.
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.
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.
The guide provides official client-specific locations and examples for Codex,
Claude Code, Cursor, VS Code/Copilot, CodeBuddy, Gemini CLI, OpenCode, Cline,
Roo Code, Windsurf and Kiro. All start MCP with uvx jolink-runtime@latest and use the same
English Skill; no plugin bundle or universal installer
is required. MCP performs the work; the Skill explains the workflows; the optional
global verification rule makes proportionate
Java verification part of implementation tasks across projects. The prompt above
explicitly enables it; remove that line if you only want MCP and the Skill.
The guide also covers uv setup, preserving configuration, reconnection and verification.
For Chinese instructions, use the Chinese installation guide.
Coding agents are good at reading and changing code, but they can become stuck in a loop of static assumptions:
analyze
-> patch
-> assume the patch works
-> patch again
joLink adds the missing runtime feedback loop:
analyze
-> change
-> run
-> observe
-> update the hypothesis
-> change again if necessary
This is useful when:
The goal is not to use a debugger for every problem.
Start with the cheapest useful evidence:
application status
-> logs and actual outputs
-> exception events
-> executed path
-> breakpoints, stack frames, and variables
Debug deeper only when necessary.
joLink exposes four focused MCP tools:
java_application — project launch, compile-aware restart (HotSwap by default),
stop, and attach;java_fast_test — selected Java tests, result details and cancellation, without an application launch;java_status — Java process discovery, compact status, on-demand details and logs;java_debugger — breakpoints, exception events, stacks, variables, and resume.After editing a managed project, call java_application(action=restart).
It incrementally compiles changes in the existing JDT workspace and prefers
HotSwap; incompatible changes restart the JVM using those same compiled outputs.
Set hotswap=false to force process/application reinitialization. The result's
apply_method distinguishes HotSwap from a real restart. See
restart workflow.
Fast Test uses a Maven or Gradle Probe only when its small configuration cache is absent or changed. The exported test Build World and JDT workspace persist across MCP processes. JDT keeps main and test classes current and runs explicit JUnit 4/5 or TestNG tests in an isolated 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 stays compact. If compilation fails before run
returns, its reply includes compiler diagnostics directly. Errors that occur after
a timeout reply and failed-test details are available through result; follow
the summary's next_action or use its test_run_id, without rerunning tests.
Full compiler file lists are omitted. Only the active
and most recently completed test attempts are retained in the current MCP session;
an unavailable ID returns TEST_RUN_NOT_FOUND.
passed=false means the selected tests executed and found a failure; it is not
a Tool infrastructure error. Fast Test does not require or modify a running
application. The current JDT supports Java 8 through 26 source/target levels;
product regression covers 8, 11, 17 and 21, including separate main/test levels.
Target libraries and application/test JDKs still follow the project. Supported
build layouts include Maven jar projects, one
explicitly selected jar module in a standard Reactor, and Gradle Java builds
including multi-Project dependencies (tested with 7.4.2, 8.10 and 8.14).
Maven and Gradle multi-module launch and Fast Test resolve the selected
module's upstream dependencies into separate JDT projects in one Worker.
Unchanged modules reuse their output; JavaBuilder propagates changed APIs and
constants to affected downstream sources. Local module dependencies use current
workspace output rather than installed JARs; Maven also supports test-jar
dependencies. See Gradle multi-module flow and evidence.
From an unexpected API response to runtime investigation.
Reading source code tells an agent what might happen. Running the application and inspecting its state helps the agent check what actually happens.
The screenshots below show a debugging example: an agent starts a Java application, checks an endpoint, notices an unexpected result, and uses joLink to investigate the execution path.
This is a constructed demonstration scenario, not a record of an actual business incident. Some sensitive information in the screenshots has been redacted for privacy.
The agent uses java_application to launch the application and java_status
to check its state, then sends an HTTP request to a sample risk-scoring endpoint.
For score=80, the expected category is High Risk, but the agent reports
Medium Risk. It checks additional boundary values before investigating further.
The agent uses java_debugger to set a breakpoint on the Medium Risk branch,
triggers another request, and inspects the variables after the breakpoint is hit.
The conversation shows score=80 while execution is in the Medium Risk
branch. This gives the agent runtime evidence to investigate its
boundary-condition hypothesis, rather than relying only on source-code assumptions.
This example demonstrates application startup and runtime investigation. It is not a Fast Test performance benchmark; the screenshots cover the investigation stage, not the subsequent fix and re-verification.
joLink keeps stdout exclusively for MCP JSON-RPC. Python lifecycle logs and tracebacks are also written to a bounded private rotating file:
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 does not return mcp.log paths or logging configuration, even with details=true.
Read the local file at the path above when diagnosing joLink itself. A diagnostic-file
failure never prevents the MCP server from starting. The file is limited to
4 MiB with three rotated backups; stdout remains untouched.
java_status(action=status) is a compact overview: readiness, process/debug state,
active operation and recent restart/Test summaries. Read java_status(action=status, details=true)
for current launch errors, full last_reload, compiler/cache settings and timings.
Completed launch/restart calls already return their own detailed result; the
flag is useful when an operation continued after the synchronous reply timeout.
Neither call reads or embeds build logs. Use java_status(action=logs, source=build)
for the current launch's build log, or omit source to read application output;
both accept tail. Restart summaries include a next_action pointing to details.
launch/restart replies include previous_startup_ms: the prior successful JVM
startup duration saved locally for the same launch, captured before
the new operation. It excludes Probe/JDT compilation. With ready_port it
measures startup through observed TCP readiness; otherwise it only measures JVM/
JDWP startup. HotSwap and failed startups do not replace this observation.
It is written once when startup succeeds to a small JSON file under the joLink
cache's startup-timings/ directory. Stop, a new conversation or an MCP restart
does not discard it. The next launch reads that file; no expiry, build-input
validation or repeated status writes are involved. An unseen launch returns
null. Treat it as a waiting reference, not a prediction or a readiness check.
Set JOLINK_LOG_LEVEL in the MCP server's environment and restart it:
WARNING (default) keeps warnings/errors only; INFO records JDT
cache/source/build/save summaries and native FULL fallback reasons;
DEBUG also retains detailed Worker output; ERROR keeps errors only;
OFF disables joLink diagnostic logging. Application logs and tool results are
unaffected. The Worker uses a fixed incremental propagation limit of 10 rounds.
See JDT build diagnostics.
The public actions are:
launch
stop
restart
attach
detach
breakpoint
exception
wait_event
threads
stack
variables
resume
cleanup_debug_state
processes / status / logs
These actions support:
project_path and main_class, or
optionally importing an IntelliJ IDEA Application/Spring Boot configuration,
exporting its Build World without running Maven/Gradle compilation, compiling
with JDT before JVM startup, and launching without packaging a fat JAR;Current package version:
0.1.0a9
Status:
Alpha / controlled dogfood
The first adapter targets local Java applications through JDWP.
The current MCP implementation includes:
TextContent with matching structuredContent;ok=false mapped to MCP isError=true;wait_event;arm and await;blocking shortcut or explicit arm/await;The current two-phase implementation is intended for controlled dogfood. Known cancellation, cleanup-preemption, handle-publication, and response delivery limitations are tracked in:
Do not use this alpha release for unattended production JVM debugging.
uv manages the Python environment automatically. A separate Python
installation is normally not required.
Confirm the requirements with:
java -version
uv --version
After the MCP server is connected, confirm that these tools are available:
java_application
java_fast_test
java_status
java_debugger
Open a local Java project and ask the coding agent:
Use joLink to start this Java application, inspect its status and logs,
and verify the latest code changes against real runtime behavior.
For a problem that has already survived multiple attempted fixes:
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.
For deeper investigation:
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 starts and observes the Java application. The coding agent may use its normal HTTP, terminal, browser, or testing tools to trigger the scenario.
For a method-body edit in an application launched with project_path, the
agent can avoid a full Maven rebuild/restart:
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 automatically detects and incrementally compiles source changes, then
uses HotSwap by default. Deleted/unloaded classes, generated resource changes or
explicit JVM rejection select a real restart using those already compiled outputs.
hotswap=false forces process reinitialization. No pending code changes restart
without compiling. Compilation errors leave the old process running. Lost
HotSwap replies remain unknown rather than being mistaken for explicit rejection.
The call waits up to timeout (maximum 30 seconds); if unfinished, it returns
restart_started plus the existing reload_id, observable through
active_operation and last_reload. apply_method distinguishes HotSwap from
process restart. Completed builds immediately save JDT state and source indexes
in the local persistent workspace. There are no extra class-output copies.
HotSwap does not rerun initialization or refresh Spring metadata; verify with a
fresh request. Breakpoints in redefined classes become stale and must be reset.
The locked JDT Worker is installed into a content-addressed user cache on
first use. Valid Eclipse bundles are reused from older joLink caches; missing
bundles are downloaded and verified, while the product Worker and Equinox
configuration ship inside the Python package. A changed build configuration or
unavailable session refreshes via the existing project launch path. Use
restart(hotswap=false) when startup/framework state must be recreated.
The product uses Eclipse 4.40 / JDT 3.46 with matching APT bundles. Its Worker
targets Java 17 bytecode and defaults to a private, pinned Temurin 21 runtime,
installed once in the user cache. Maven/Gradle and application/test JVMs keep
their project JDKs. JOLINK_WORKER_JAVA_HOME can select a corporate-provided
64-bit JDK 17+ instead. Old Lombok 1.18.20 compatibility issues remain recorded,
not silently fixed by replacing project dependencies. See
JDT 3.46 and private Worker JDK for offline setup
and actual compatibility results.
First-time JDK/Eclipse downloads use their pinned official URLs by default.
Set JOLINK_DOWNLOAD_MIRROR=cn to try TUNA, then the joLink mirror at
https://7355608.net/jolink/assets, then upstream on connection/transfer failure.
A custom mirror base URL uses that mirror followed by upstream; official
(or an empty value) uses upstream only. No IP/geolocation detection is performed.
Existing SHA256 checks and installed caches are unaffected. TUNA access was
blocked during local verification; selecting cn does not guarantee its availability.
See runtime mirror setup.
The imported IDEA Make/Build flag does not cause Maven or Gradle compilation. On the first launch, the Probe exports compiler/runtime facts and JDT performs FULL compilation. Later launches reuse the persisted Probe model and use saved source size/mtime to detect edits. Changes to tracked Maven/Gradle configuration refresh the model. Untracked external scripts and hidden inputs remain recorded in the compatibility follow-up; cache deletion is not a routine startup or installation step.
See JDT-first startup for the current single-module startup and cache behavior.
A normal verification flow looks like this:
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
A deeper debugging flow looks like this:
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
For a local HTTP endpoint, blocking composes the existing
arm -> trigger -> await lifecycle into one call:
{
"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
}
}
Use explicit arm followed by await when an external action must occur
between arming and observation. A terminal result consumes its wait_handle;
the handle observes Runtime events and is not an HTTP-response handle.
For an HTTP application launched by joLink, distinguish process/debugger startup from application TCP readiness:
{
"action": "launch",
"jar_path": "target/app.jar",
"jdwp_port": 5005,
"ready_port": 8080,
"timeout": 30
}
For java_application(launch/restart) and java_fast_test, timeout limits the synchronous result wait, including
runtime preparation and compilation. It defaults to 30 seconds; larger values
are accepted but wait only 30 seconds. Zero returns after task submission.
The original task continues after this reply deadline. Test Runner execution
has a separate internal 300-second limit; timeout no longer configures it.
If still running, choose a waiting interval appropriate to the stage (for
example using sleep or PowerShell Start-Sleep), then query java_status.
Do not rapidly poll or resubmit the task. The old readiness-wait argument has
been removed, not retained as an alias.
Direct JAR/classpath launches still perform their existing process creation
and JDWP handshake before returning a task observation. timeout=0 skips the
additional readiness wait; it does not make that initial handshake asynchronous.
If the process is alive but the application port is not accepting connections,
the result remains successful with startup_state=starting; the process is
kept alive and next_action=status. Each later status call probes the stored
port again. startup_state=ready means only that the configured loopback TCP
port accepted a connection; it does not prove that every dependency, cache, or
business endpoint is healthy.
When ready_port is omitted, joLink reports startup_state=unverified rather
than claiming application readiness. An HTTP trigger remains allowed for
attached and otherwise unverified JVMs, but its result includes a warning.
When configured readiness is still starting, joLink rejects an HTTP trigger
without sending it.
joLink 0.1.0a9 is designed for local, trusted development environments.
Current safety boundaries:
http://127.0.0.1, do not use environment
proxies or redirects, and never return the request URL, headers, body, or
their raw values in validation errors;ready_port must be unused before launch and must differ from
the JDWP port; the TCP probe is local and does not send an application
request;response_headers_received reports only the HTTP status/response headers;
joLink does not read or return the response body;cleanup_debug_state includes its own debug-state verification;
a separate HTTP cleanup state may remain settling without delaying JVM
cleanup;suspension_id, the agent must call resume or
cleanup_debug_state.Do not expose the JDWP port to an untrusted network.
Do not use the current alpha release for remote or production debugging.
Some current CodeBuddy environments may initially display:
Description: No description
Use the host's tool-definition loading/search facility to obtain the actual schema.
Do not infer arguments from a tool name alone. The independently installed
jolink-java Skill provides a discovery and workflow entry point; it does not
replace the MCP connection or guarantee tool selection. Follow the
installation guide for the specific CodeBuddy surface (CLI, IDE or
editor plugin), rather than assuming their configuration files are interchangeable.
Clone the repository and install development dependencies:
uv sync --extra dev --locked
Run the default test suite:
uv run pytest
Run the stdio server from the source checkout:
uv run jolink-runtime
Equivalent module entry point:
uv run python -m jolink_runtime.transport.stdio
A generic MCP client configuration can launch it directly from a checkout:
{
"mcpServers": {
"jolink-runtime": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/jolink-runtime",
"run",
"jolink-runtime"
]
}
}
}
After changing joLink source, do not kill an MCP server and assume an existing host tool handle will reconnect. Start a fresh server from the current worktree through the real stdio protocol:
uv run python scripts/jolink_mcp_dev_client.py
The client prints the Git commit, dirty-worktree state, source fingerprint,
Python executable, and stderr path before accepting JSONL tools/call
requests. Send {"command":"quit"} to close the client and trigger normal
server cleanup. This is the canonical interactive verification path for
uncommitted code; a Codex/IDE MCP connection should be established only after
the code under test is frozen.
The real subprocess acceptance test exercises the MCP stdio boundary:
uv run pytest -q tests/e2e/test_stdio_mcp.py
It performs:
initialize
-> tools/list
-> java_status(status)
-> close the stdio client
-> wait for the server process to exit
The heavier real MCP/JVM suite is opt-in locally:
JOLINK_RUN_MCP_JAVA_E2E=1 \
uv run pytest -q -m mcp_java_e2e tests/e2e/test_stdio_mcp_java.py
The managed Temurin 21 Worker and Java 8 application lifecycle have standalone deep validators (Worker JDK and application/target JDK are different roles):
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>
The canonical CI environment for the heavier suite is:
Linux
Python 3.11
Application/target JDK 8/11/17/21; managed Worker JDK 21
See current documentation, product Java sources and builds, and historical research records. Archived experiment commands and limits are not the current product interface.
docs/mcp-contract-v0.1.mddocs/runtime-lineage-contract-2.4.0.mdjoLink's own code is MIT-licensed. Downloaded Eclipse/Temurin runtimes and installed Python dependencies retain their own licenses. See third-party notices and corresponding sources. Offline runtime kits must be accompanied by the matching source kit and notices.
A lightweight Java IDE for AI agents: incremental builds, fast tests, HotSwap and live debugging.
{ "mcpServers": { "io.github.l1ch404-jolink-runtime": { "command": "uvx", "args": [ "jolink-runtime==0.1.0a10" ], "env": { "JOLINK_DOWNLOAD_MIRROR": "<value>", "JOLINK_JDT_GC_AFTER_BUILD": "<value>" } } }}เครื่องมือ
ยังไม่มีรายการเครื่องมือ เซิร์ฟเวอร์แบบรีโมตจะได้รายการหลังการตรวจสอบสถานะครั้งแรก
FAQ
คัดลอกคอนฟิก stdio สำหรับ Cursor, Claude Desktop, Claude Code หรือ VS Code ได้ในหน้านี้ คอนฟิกนี้ใช้การติดตั้งของผู้เผยแพร่ ไม่ใช่พร็อกซีของ PlugMCP
ผู้เผยแพร่ระบุตัวแปรสภาพแวดล้อมเหล่านี้: JOLINK_DOWNLOAD_MIRROR, JOLINK_JDT_GC_AFTER_BUILD
JoLink ทำงานแบบโลคัลผ่าน stdio
ตรวจสอบล่าสุดเมื่อ 2026-11-14 A lightweight Java IDE for AI agents: incremental builds, fast tests, HotSwap and live debugging.