mcp-java-dev-tools

MCP Java Dev Tools bridges agentic coding tools and live Java runtime behavior through a lightweight sidecar agent.

Static analysis only gets you so far. By attaching directly to a running JVM, this tool surfaces bytecode-level runtime signals that static analysis alone can't see — enabling probe-verified inspection, targeted regression checks, runtime-path validation, and deterministic debugging workflows.

The runtime agent is built with ByteBuddy and works alongside JDWP rather than replacing it. On top of the probe layer, the system adds framework-aware data synthesis and strict, fail-closed tool contracts — so agent orchestrators can make decisions grounded in actual runtime proof, not inference.

The current focus is HTTP entrypoints. Non-HTTP protocol support is on the horizon but not yet implemented — it will need concrete models and validation targets before the core contracts can be generalized.

For operator workflows and end-to-end execution flows, see docs/how-it-works/README.md.

Requirements

Related MCP server: jdwp-mcp

Build

npm.cmd install
npm.cmd run build
mvn -f java-agent\pom.xml package

This produces two artifacts:

• MCP server → dist/server.js

• Java agent bundle → java-agent/core/core-probe/target/mcp-java-dev-tools-agent-0.1.0-all.jar

The Java 21 lifecycle helper is packaged separately at java-agent/core/core-jvm-attach/target/mcp-java-dev-tools-core-jvm-attach-0.1.8.jar.

Installation

Installer

Installer flow is split into install and update scripts (Codex and Kiro skills).

./scripts/install.sh

This installs the default skill set:

• mcp-java-dev-tools-line-probe-run

• mcp-java-dev-tools-regression-suite

• mcp-java-dev-tools-regression-plan-crafter

• mcp-java-dev-tools-regression-result

• mcp-java-dev-tools-issue-report

• mcp-java-dev-tools-bug-drill

• mcp-java-dev-tools-bug-fix

• mcp-java-dev-tools-failure-lens

• mcp-java-dev-tools-probe-registry-manager

To update/overwrite existing installed skills (and add missing new skills):

./scripts/update.sh

Both scripts:

• run npm run build:compile

• run mvn -f java-agent/pom.xml package

• sync shipped skills into the target client skill directory

• by default prompt for a first workspace and generate MCP env config block output (client-specific)

Kiro and Claude Code behavior during install/update:

• stale managed skills matching mcp-java-dev-tools-* are detected and can be deleted interactively

• installed managed skills are validated after sync (SKILL.md + expected folder presence)

• restart/reload guidance is printed so the visible tool/skill list refreshes from the synced skill directory

Default MCP registry env input can be skipped:

./scripts/install.sh --client codex --no-configure-mcp-env
# Or: ./scripts/install.sh --client claude --no-configure-mcp-env

MCP env input captures:

• MCP_JAVA_AGENT_JAR (required; absolute path to built Java agent jar)

Spring Integration Launcher

Use the helper launcher to run a Spring app with auto-inferred Java agent include scope and probe port:

./spring-integration/run-spring-app-with-mcp.sh

Behavior:

• prompts for Spring project absolute path, app port (default 8080), and optional JDWP port

• infers include package from src/main/java

• assigns probe port starting at 9173 and increments if occupied

• opens a new Git Bash window and starts the Spring app with JAVA_TOOL_OPTIONS including -javaagent

Manual Setup

Java Agent Setup

The target JVM must run on Java 21 or newer. Java 17 is unsupported because the Java reactor and dynamic lifecycle helper compile for Java 21.

Add the following as a JVM argument when launching your application, replacing {desktopName}:

-javaagent:C:\Users\{desktopName}\repository\mcp-java-dev-tools\java-agent\core\core-probe\target\mcp-java-dev-tools-agent-0.1.8.jar=host=0.0.0.0;port=9191;exclude=com.nimbly.mcpjavadevtools.agent.**,**.config.**,**Test

Tip: The include filter is optional. If omitted, the agent infers an include scope from startup command metadata (sun.java.command), usually the startup class package (for example com.acme.app.**). Set include explicitly when inference is ambiguous or too broad.

include supports comma-separated basepaths:

• package globs (for example com.thirdparty.service.**)

• exact class FQCNs (for example com.example.ApiClass)

• mixed module/class targeting in one value (for example com.example.app.**,com.example.api.**,com.thirdparty.SomeClass)

To confirm the agent is instrumenting your classes, check the startup logs for lines like:

[mcp-probe]: com.yourpackagename.yourclassname

If you don't see your classes listed, check your include filter.

Dynamic Attach (Java 21+)

The separate lifecycle helper discovers local JVM PIDs and dynamically loads only an agent JAR with the expected Sidecar Agent manifest. It requires an exact PID and explicit confirmation; discovery is intentionally unverified and does not expose target command lines or properties.

java -jar java-agent\core\core-jvm-attach\target\mcp-java-dev-tools-core-jvm-attach-0.1.8.jar discover
java -jar java-agent\core\core-jvm-attach\target\mcp-java-dev-tools-core-jvm-attach-0.1.8.jar attach --pid {pid} --agent-jar {absolute-agent-jar-path} --confirm true
java -jar java-agent\core\core-jvm-attach\target\mcp-java-dev-tools-core-jvm-attach-0.1.8.jar deactivate --pid {pid} --agent-jar {absolute-agent-jar-path} --confirm true

On Java 21, dynamic agent loading succeeds by default but emits the JEP 451 warning. -XX:+EnableDynamicAgentLoading suppresses that warning only when operators explicitly choose it. -XX:-EnableDynamicAgentLoading and -XX:+DisableAttachMechanism return Fail-Closed lifecycle results. VirtualMachine.detach() closes the helper session; it does not unload agent classes. Deactivation disables Sidecar Agent-owned instrumentation and reports non-restorable classes.

1. Open Run > Edit Configurations... from the top menu

2. Select the run configuration for your target application (or create one if it doesn't exist)

3. Expand the Modify options dropdown and enable Add VM options if it isn't already visible

4. In the VM options field, paste the full -javaagent:... argument from above

5. Click Apply, then OK

6. Run your application normally — the agent attaches on startup

Finding the JAR path: If you're unsure of the absolute path, right-click the agent JAR in the Project panel and choose Copy Path > Absolute Path.

On Windows, use backslashes in the path (C:\Users\...). On macOS/Linux, use forward slashes (/home/... or /Users/...).

1. Go to Run > Run Configurations... (or Debug Configurations... if you're debugging)

2. Select your application under Java Application, or create a new one

3. Open the Arguments tab

4. In the VM arguments field, paste the full -javaagent:... argument from above

5. Click Apply, then Run (or Debug)

Finding the JAR path: Navigate to the JAR in your file system, right-click it, and copy the full path. Paste it into the agent argument, replacing the placeholder path.

On Windows, Eclipse accepts both forward and backslashes in paths, but backslashes are safer. Wrap the path in quotes if it contains spaces: -javaagent:"C:\path with spaces\agent.jar"=...

Runtime Configuration

Java Agent Options

Capture History Buffer Size

Controls how many method captures the agent retains per probe point.

Default is 3. Increase this if you need deeper capture history for a single probe point.

MCP Server Environment Variables

Required

Optional

Configuration Scope Matrix

Probe Endpoints

These paths are fixed and cannot be overridden.

Skills

Contributing

Contribution guidance lives in CONTRIBUTING.md.

The guide distinguishes between:

• synthesizer and adapter contributions

• probe tools and recipe generation contributions

Start there before opening a large pull request or changing public tool contracts.

MCP Tools

Probe config Artifact runtime behavior:

• Registry config is loaded from discovered workspace .mcpjvm/probe-config.json.

• File edits are auto-reloaded with debounce.

• artifact_management with artifactType=probe_config and action=reload remains available as deterministic manual refresh/fallback.