Tools / MCP API¶
1.x reference: This page documents earlier behavior and may list tools that are not public in the 2.0 development line. Use the 2.0 quickstart and 2.0 design review for the current public contract.
This is the reference for the 28 MCP tools the server registers with the tool callback provider and exposes over tools/list. Each tool is grouped by the service that implements it. Parameter names, requiredness, and descriptions are taken directly from the @Tool / @ToolParam annotations in the source.
Scope of this reference
Only tools wired into BuildToolsApplication.buildTools(...) are documented here, because those are the tools an MCP client actually discovers. See the Architecture reference for the note about additional services that exist in the source but are not currently registered.
Common conventions:
projectDiris canonicalised withPath.toRealPath()and must resolve to an existing directory.buildToolNameacceptsmaven,gradle, orsbt. When optional, omitting it triggers auto-detection from project markers.- All
execute/analyzetools enforce the security model before spawning a process.
JSON Schema 2020-12 and deterministic ordering¶
Two MCP 2026-07-28 RC conventions apply to every tool in this reference.
Input schemas are JSON Schema 2020-12 (SEP-2106)¶
Each tool's inputSchema is auto-generated by Spring AI from the @Tool / @ToolParam annotations and emitted as JSON Schema 2020-12 — the document root is stamped with "$schema": "https://json-schema.org/draft/2020-12/schema", generated object schemas set additionalProperties: false, and any $defs are hoisted to the root. A representative schema:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"projectDir": { "type": "string", "description": "Path to the project directory" },
"command": { "type": "string", "description": "Build command to execute" }
},
"required": [ "projectDir", "command" ],
"additionalProperties": false
}
A build-time guard, ToolJsonSchemaComplianceTest, boots the application context, enumerates every registered tool, and asserts each generated inputSchema:
- is a non-null JSON object with a root
type: "object"; - declares the 2020-12 dialect (which the server always stamps);
- validates against the official JSON Schema 2020-12 meta-schema (a bundled classpath resource — no network dereference) within a bounded time budget;
- compiles cleanly under 2020-12, proving every local
$refresolves; - uses only local
$reffragments — never an external (http(s):/file:/urn:) URI; - respects bounded schema depth and
$defscount.
This is a test- and documentation-only guardrail: it adds no runtime code and changes no tool definition or wire behaviour, but it fails the build if a future change ever emits a non-conforming schema.
tools/list is returned in deterministic order (SEP-2549)¶
The tool callback provider is wrapped by DeterministicToolCallbackProvider, so tools/list returns the catalogue sorted by tool name on every call (the reflective discovery order is otherwise unspecified across JVMs/restarts). A stable order improves client-side and LLM prompt-cache hit rates. The set of tools and their definitions are unchanged — only the iteration order is normalised.
Cache hints — ttlMs / cacheScope (SEP-2549)¶
The server advertises a per-method caching policy under the cacheHints key of its discovery surfaces (the server card GET /.well-known/mcp-server and server/discover):
"cacheHints": {
"tools/list": { "ttlMs": 86400000, "cacheScope": "public" },
"prompts/list": { "ttlMs": 86400000, "cacheScope": "public" },
"resources/list": { "ttlMs": 86400000, "cacheScope": "public" },
"resources/templates/list": { "ttlMs": 86400000, "cacheScope": "public" },
"resources/read": { "ttlMs": 300000, "cacheScope": "private" }
}
ttlMs is a freshness hint (milliseconds) letting clients cache responses and reduce polling; cacheScope (public / private) controls whether shared intermediaries may cache. The tool / prompt / resource catalogue is static for the process lifetime, so the list surfaces use a generous public TTL (24h); per-project content reads reflect mutable on-disk state, so resources/read uses a short private TTL (5min). Both TTLs are configurable (buildtools.cache.catalog-ttl-ms, buildtools.cache.read-ttl-ms — see the Configuration reference).
Advertised on discovery, not yet per-result
The RC CacheableResult interface adds top-level ttlMs / cacheScope fields to individual tools/list / prompts/list / resources/list / resources/read / resources/templates/list results. The bundled MCP SDK does not yet model these as typed result fields, so the policy is advertised on the discovery surfaces as an additive, backward-compatible interim. It moves to per-result fields once the upstream SDK exposes them.
BuildToolsService¶
Core build execution, detection, validation, and output analysis. 6 tools.
get_build_tool_version¶
Get the installed version of a build tool.
| Parameter | Required | Description |
|---|---|---|
buildToolName | yes | Build tool name: maven, gradle, or sbt. |
Returns: the version string for the requested tool.
execute_build_command¶
Execute a build command using Maven, Gradle, SBT, or any registered build tool.
| Parameter | Required | Description |
|---|---|---|
buildToolName | no | maven, gradle, or sbt. Omit to auto-detect from projectDir. |
buildToolHome | no | Path to the build tool installation. Required for Maven unless MAVEN_HOME is set; optional for Gradle (uses wrapper or PATH). |
projectDir | yes | Path to the project directory containing build files. |
command | yes | Build command — e.g. clean compile (Maven), build (Gradle), compile;test (SBT). |
Returns: the raw build tool output (text).
list_build_tools¶
List all registered build tools with their supported commands. No parameters.
Returns: the registered tools and their allowlisted commands.
detect_build_tool¶
Detect which build tool a project uses by scanning for marker files.
| Parameter | Required | Description |
|---|---|---|
projectDir | yes | Project directory to scan for build tool markers. |
Returns: JSON describing detected tool(s) and the markers found.
analyze_build_output¶
Execute a build command and return structured JSON with parsed test results, errors, and warnings.
| Parameter | Required | Description |
|---|---|---|
buildToolName | no | maven, gradle, or sbt. Omit to auto-detect. |
buildToolHome | no | Build tool installation path. Optional for Gradle. |
projectDir | yes | Project directory containing build files. |
command | yes | Build command to execute (e.g. clean test). |
Returns: JSON of the shape { success, tool, command, testSummary, errors, warnings, errorCount, warningCount, duration }. For Maven, testSummary uses each Surefire/Failsafe execution's final total when present. If the output ends before that total, it sums the per-class results instead. Per-class lines and their final total are never added together. If Surefire/Failsafe reports failed tests without a compiler-style error line, the result includes one generic test diagnostic for assertion failures and one for test execution errors when present. These add at most two entries to errorCount, while testSummary retains the number of failed tests. Test names, assertion values, and raw reports stay local. Up to 13 middle-stream test totals per captured stream are retained separately from compiler diagnostics. Repeated module totals count as distinct executions; when diagnosticsTruncated is true, inspect the local report for exact counts. For Gradle and sbt, a failed test summary adds a generic test diagnostic when the parsed output has no useful test diagnostic. sbt can add a separate generic execution-error diagnostic when its summary distinguishes that failure kind. These add at most two entries to errorCount; testSummary.failed still counts failed cases. Test names, assertion values, and raw reports stay local. When a Maven, Gradle, or sbt count exceeds the model-visible limit of 1,000,000, or reported test categories disagree with the total, the summary remains nonnegative and includes countsCapped: true; treat its numbers as bounded approximations.
validate_build_configuration¶
Statically validate build configuration files without running a build.
| Parameter | Required | Description |
|---|---|---|
projectDir | yes | Project directory containing build files. |
Returns: JSON validation report. Validates pom.xml (XML well-formedness, required elements, duplicate dependencies, plugin version consistency), build.gradle, and build.gradle.kts. SBT build.sbt validation is not yet implemented.
DependencyService¶
Maven Central version intelligence. 1 tool.
check_dependency_version¶
Check whether a newer version exists for a Maven Central dependency.
| Parameter | Required | Description |
|---|---|---|
groupId | yes | Maven group ID (e.g. org.springframework.boot). |
artifactId | yes | Maven artifact ID (e.g. spring-boot-starter-web). |
currentVersion | no | Version to compare against. Omit to just get the latest. |
versionPreference | no | RELEASE (default), LATEST, SNAPSHOT, or ALL. |
projectDir | no | When provided, auto-detects the build tool and returns the correct dependency declaration syntax. |
Returns: JSON with latest/stable version info and stability classification. Queries Maven Central over HTTPS with a 5-second timeout.
PromptService¶
Prompt templates that guide an LLM through multi-step build workflows. 3 tools.
prompt_build_and_test¶
| Parameter | Required | Description |
|---|---|---|
projectDir | no | Project directory. If omitted, the prompt asks the user for it. |
buildTool | no | maven, gradle, or sbt. If omitted, auto-detection is used. |
Returns: a prompt template for a build-and-test workflow.
prompt_dependency_audit¶
| Parameter | Required | Description |
|---|---|---|
projectDir | no | Project directory. If omitted, the prompt asks the user for it. |
Returns: a prompt template for auditing and upgrading dependencies.
prompt_build_diagnosis¶
| Parameter | Required | Description |
|---|---|---|
projectDir | yes | Project directory path. |
failedCommand | no | The failing command that produced the error. |
Returns: a prompt template for diagnosing and fixing build failures.
BuildResourceService¶
Access build configuration as MCP resources. 2 tools.
list_build_resources¶
| Parameter | Required | Description |
|---|---|---|
projectDir | yes | Project directory path. |
Returns: the available build resources (e.g. build://<project>/config).
read_build_resource¶
| Parameter | Required | Description |
|---|---|---|
uri | yes | Resource URI from list_build_resources (e.g. build://myproject/config). |
projectDir | yes | Project directory path. |
Returns: the contents of the requested build resource.
DependencyResourceService¶
Access extracted dependencies as MCP resources. 2 tools.
list_dependency_resources¶
| Parameter | Required | Description |
|---|---|---|
projectDir | yes | Project directory path. |
Returns: the available dependency resources for the project.
read_dependency_resource¶
| Parameter | Required | Description |
|---|---|---|
uri | yes | Resource URI (e.g. build://myproject/dependencies/maven). |
projectDir | yes | Project directory path. |
Returns: the extracted dependencies from the referenced build file.
ResourceTemplateService¶
Parameterised URI template resources. 2 tools.
list_resource_templates¶
List all available MCP resource templates with their URI patterns and parameters. No parameters.
Returns: the resource templates and their parameter definitions.
resolve_resource_template¶
Resolve a resource template URI by substituting parameter values.
| Parameter | Required | Description |
|---|---|---|
templateUri | yes | Template URI pattern (e.g. build://{projectName}/dependencies/{buildTool}). |
paramsJson | yes | Parameter values as a JSON object (e.g. {"projectName":"myapp","buildTool":"maven"}). |
Returns: the resolved resource URI / payload.
SbtProjectService¶
SBT-specific project analysis. 3 tools.
detect_sbt_modules¶
| Parameter | Required | Description |
|---|---|---|
projectDir | yes | Project directory containing build.sbt. |
Returns: the detected subprojects/modules in a multi-module SBT build.
detect_sbt_test_frameworks¶
| Parameter | Required | Description |
|---|---|---|
projectDir | yes | Project directory containing build.sbt. |
Returns: the test frameworks configured in the SBT build (e.g. ScalaTest, Specs2, MUnit).
analyze_sbt_build¶
| Parameter | Required | Description |
|---|---|---|
projectDir | yes | Project directory containing build.sbt. |
Returns: an analysis of build.sbt — plugins, Scala version, and configuration.
BuildAuthService¶
Read-only credential-configuration scanning. 1 tool.
check_credential_status¶
Scan for configured Maven and Gradle credentials. All passwords are masked (e.g. ****xyz) and never returned in plaintext.
| Parameter | Required | Description |
|---|---|---|
projectDir | no | When provided, also scans the project for credential configuration. |
scope | no | maven, gradle, or all. |
Returns: JSON summarising servers, mirrors, proxies, repositories, environment variables, gaps, and recommendations — with sensitive values masked.
DependencyConflictService¶
Dependency version-conflict detection. 1 tool.
detect_dependency_conflicts¶
| Parameter | Required | Description |
|---|---|---|
projectDir | yes | Project directory. |
scope | no | maven, gradle, sbt, or all (default). |
Returns: JSON describing detected version conflicts across the selected build files.
BuildPerformanceService¶
Build profiling and performance analysis. 2 tools.
profile_build¶
Execute a build command with timing instrumentation.
| Parameter | Required | Description |
|---|---|---|
buildToolName | no | Build tool name. Omit to auto-detect. |
buildToolHome | no | Path to the build tool installation. |
projectDir | yes | Project directory. |
command | yes | Build command to profile. |
Returns: JSON with timing data for the profiled build.
analyze_build_performance¶
Analyze build performance from historical data and configuration (read-only).
| Parameter | Required | Description |
|---|---|---|
projectDir | yes | Project directory. |
buildToolName | no | Build tool to analyze. Omit to auto-detect. |
Returns: JSON with performance findings and optimisation suggestions.
JavaVersionService¶
Java/JDK compatibility checking. 1 tool.
check_java_compatibility¶
| Parameter | Required | Description |
|---|---|---|
projectDir | yes | Project directory. |
targetVersion | no | Target Java version (8, 11, 17, 21, 22, 23, 24, 25). If omitted, checks against the project's configured version. |
Returns: JSON describing compatibility of the project and its dependencies with the target Java version.
ToolAuthorizationService¶
Scope-based authorization, audit log reads, and token validation. 4 tools. These tools are useful regardless of whether enforcement is enabled; see the Security reference for the full model.
check_tool_authorization¶
Pre-validate whether a tool is authorized for a set of permission scopes.
| Parameter | Required | Description |
|---|---|---|
toolName | yes | The MCP tool name to check (e.g. execute_build_command). |
grantedScopes | yes | Comma-separated granted scopes (e.g. build:read,build:execute). Use * for full access. |
Returns: JSON with the authorization decision, the scopes checked, and the matching scopes.
list_available_scopes¶
List all permission scopes with their tool coverage. No parameters.
Returns: JSON enumerating the 12 scopes and the tools each grants.
audit_tool_access¶
Read recent entries from the OWASP-MCP06 audit log.
| Parameter | Required | Description |
|---|---|---|
count | no | Number of most recent entries to return (default 20, max 100). |
filter | no | all (default), authorized, or denied. |
Returns: JSON with the requested audit entries.
validate_access_token¶
Validate an API key and report its granted scopes. The token value is used only for validation and is never logged or stored.
| Parameter | Required | Description |
|---|---|---|
token | yes | The access token (API key) to validate. |
Returns: JSON indicating validity and the scopes granted to the key.