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

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

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-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), optional JDWP port, and Java 21 compatibility
• 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 17 or newer. If you're on Java 21, see Java 21 compatibility mode before continuing.

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.7.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.

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.

Java 21 Compatibility Mode

Required if your target JVM runs on Java 21. Enables ByteBuddy's experimental support for newer JVM internals.

Default is false.

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.