Examples¶
1.x reference: These examples show the older command list and response shapes. For the current 2.0 interface, use the quickstart and tool catalog.
Concrete, end-to-end examples for Maven, Gradle, and SBT. Each shows the tool call arguments the agent sends and a representative response shape. The JSON below illustrates the structure the server returns — exact values depend on your project and toolchain.
How to read these
You normally won't write tool calls yourself — your agent does. The arguments are shown so you can see exactly what each tool needs. Responses are example shapes, not metrics from a specific run.
Discover the available tools¶
"What build tools are available?"
The agent calls list_build_tools (no arguments). The server returns the registered tools and their allowlisted commands:
maven: clean, compile, test, package, install, deploy, validate
gradle: clean, build, test, compileJava, compileTestJava, jar, assemble,
check, publishToMavenLocal, dependencies, projects, tasks
sbt: compile, test, run, package, clean, assembly, publishLocal,
publish, update, doc, console
Detect a project's build tool¶
"Detect the build tool for /path/to/my-project"
When several markers are present (a hybrid project), the server lists all detected tools and prioritises Maven for auto-detection. Pass buildToolName explicitly to override.
Maven: clean and test¶
"Run 'clean test' on /path/to/my-maven-app"
This returns the raw build log as text. To get a parsed result instead, use analyze_build_output (below).
Maven: structured test results¶
"Build and test /path/to/my-maven-app and tell me what failed"
{
"success": false,
"tool": "maven",
"command": "clean test",
"testSummary": { "total": 42, "passed": 41, "failed": 1, "skipped": 0 },
"errors": [
{
"file": "src/test/java/com/example/OrderServiceTest.java",
"line": 88,
"message": "expected:<3> but was:<2>"
}
],
"warnings": [],
"errorCount": 1,
"warningCount": 0,
"duration": "PT12.4S"
}
The parser extracts the success flag, test counts, errors with file:line, and warnings, so an agent can reason about failures programmatically.
Gradle: build with the wrapper¶
"Run 'build' on /path/to/my-gradle-app"
Gradle needs no installation: the server auto-detects the project's gradlew wrapper and falls back to gradle on PATH. It always appends --no-daemon --console=plain, so do not add those flags yourself.
Multi-module Gradle
Use colon syntax to target a submodule task, e.g. :web:build. The task name is taken from the last colon-separated segment and validated against the allowlist.
SBT: compile then test¶
"Compile and test the SBT project at /path/to/my-sbt-app"
SBT chains tasks with semicolons, not spaces. The server appends --no-colors for machine-readable output.
First SBT run is slow
The first execute_build_command for an SBT project may take 1–3 minutes while SBT downloads its launcher and compiles the build definition.
Analyse an SBT build configuration¶
"Analyse the SBT build at /path/to/my-sbt-app"
The SbtProjectService also provides detect_sbt_modules (multi-module structure) and detect_sbt_test_frameworks (e.g. ScalaTest, Specs2, MUnit).
Check a dependency version¶
"What's the latest version of com.google.guava:guava?"
currentVersionis optional — omit it to just fetch the latest version.versionPreferenceis one ofRELEASE(default),LATEST,SNAPSHOT, orALL.- When
projectDiris supplied, the server auto-detects the build tool and returns the dependency declaration in that tool's syntax (Maven XML, Gradle string notation, or SBTlibraryDependencies).
This tool queries Maven Central over HTTPS (5-second timeout) and classifies versions by stability (stable, RC, milestone, beta, alpha, snapshot).
Validate a build file without building¶
"Validate the build configuration in /path/to/my-project"
This is a fast, static check (no build process is spawned). It validates pom.xml, build.gradle, and build.gradle.kts. SBT build.sbt validation is not yet implemented.
Detect dependency conflicts¶
"Are there dependency version conflicts in /path/to/my-project?"
scope may be maven, gradle, sbt, or all (the default).
Check Java compatibility¶
"Is /path/to/my-project compatible with Java 17?"
Omit targetVersion to check against the project's configured target.
For the precise inputs and outputs of every tool, continue to the Tools / MCP API reference.