Spring Toolkit MCP

Spring Toolkit MCP is a secure-by-default MCP server and CLI for agentic review of real Spring Boot repositories. It focuses on the practical developer workflow teams need in production: inspect a Java/Spring codebase, expose safe tools to an AI agent, and produce review signals around controllers, configuration, Flyway migrations, JPA, and test opportunities.

The second design goal is simple: Spring Boot Admin for AI agents. Human operators use dashboards; agents need structured tools. Spring Toolkit MCP now has both workspace inspection and runtime Actuator access, with mutating actions behind explicit policy flags.

This first version is intentionally dependency-free Python. It can run as:

• an MCP stdio server for clients that support tools/list and tools/call
• a local CLI that prints Markdown or JSON reports
• a Python library for future integrations with Continue, OpenHands, Aider, or CI

Features

• Detects Maven and Gradle build metadata
• Scans Spring annotations such as controllers, services, repositories, entities, mappers, configuration classes, and application entrypoints
• Extracts endpoint mappings and security annotations from Java sources
• Reads application*.properties, application*.yml, and application*.yaml while redacting likely secrets
• Scans Flyway migrations for risky operations
• Lists configured Spring Boot Actuator applications
• Reads Actuator endpoint index, health, info, audit events, beans, conditions, config properties, mappings, metrics, env, loggers, thread dumps, heap metrics, startup steps, scheduled tasks, caches, HTTP exchanges/traces, Flyway and Liquibase status, Spring Integration graph, Quartz, sessions, SBOM, Prometheus, bounded log files, and heap dump metadata
• Changes logger levels, deletes sessions, and reads sensitive Actuator downloads only when explicitly enabled by policy
• Reads Maven Surefire and JaCoCo reports
• Runs Maven or Gradle tests only when explicitly enabled by policy
• Generates pragmatic Markdown review reports
• Suggests MockMvc test skeletons for controllers
• Guards MCP access to configured workspace roots

Quick Start

From a fresh checkout, install the package in editable mode:

python -m pip install -e .

Run a Markdown review for the current directory:

spring-toolkit review .

Run a JSON summary:

spring-toolkit summary . --json

Start the MCP server:

spring-toolkit-mcp

Modes

Workspace mode inspects a local repository:

spring-toolkit review C:\work\orders-service
spring-toolkit mockmvc C:\work\orders-service --controller OrderController

Runtime mode connects to Spring Boot Actuator:

$env:SPRING_TOOLKIT_ACTUATOR_BASE_URLS = "orders=http://localhost:8080/actuator;billing=http://localhost:8081/actuator"
spring-toolkit apps
spring-toolkit actuator --application orders
spring-toolkit health --application orders
spring-toolkit metrics --application orders --metric http.server.requests
spring-toolkit mappings --application orders

Full mode combines both in the MCP client: the agent can inspect code, read runtime health/metrics, read reports, and propose a fix from one tool surface.

By default, workspace MCP tool calls can only inspect the current working directory. To allow other roots, set SPRING_TOOLKIT_ALLOWED_ROOTS to a semicolon-separated list of absolute paths:

$env:SPRING_TOOLKIT_ALLOWED_ROOTS = "C:\work\project-a;C:\work\project-b"
spring-toolkit-mcp

When running directly from the checkout without installing, set PYTHONPATH:

$env:PYTHONPATH = "src"
python -m spring_toolkit_mcp.cli review .

Runtime Configuration

Configure one Actuator app:

$env:SPRING_TOOLKIT_ACTUATOR_BASE_URL = "http://localhost:8080/actuator"

Configure multiple named apps:

$env:SPRING_TOOLKIT_ACTUATOR_BASE_URLS = "orders=http://localhost:8080/actuator;billing=http://localhost:8081/actuator"

Optional Basic Auth:

$env:SPRING_TOOLKIT_ACTUATOR_USERNAME = "admin"
$env:SPRING_TOOLKIT_ACTUATOR_PASSWORD = "secret"

Mutating logger changes are disabled by default:

$env:SPRING_TOOLKIT_ENABLE_LOGGER_MUTATION = "true"

Sensitive Actuator downloads are disabled by default. Enable them before using logfile or heap dump metadata tools:

$env:SPRING_TOOLKIT_ENABLE_ACTUATOR_DOWNLOADS = "true"

Session deletion is disabled by default:

$env:SPRING_TOOLKIT_ENABLE_SESSION_MUTATION = "true"

Build/test execution is also disabled by default:

$env:SPRING_TOOLKIT_ENABLE_TEST_RUNS = "true"
spring-toolkit maven-test C:\work\orders-service --test OrderServiceTest

Runtime CLI commands mirror the MCP runtime surface: apps, actuator, health, info, auditevents, beans, conditions, configprops, mappings, metrics, env, loggers, set-logger-level, threaddump, heap-info, heapdump, scheduledtasks, caches, httpexchanges, actuator-flyway, liquibase, integrationgraph, quartz, sessions, delete-session, startup, sbom, prometheus, and logfile.

MCP Tools

spring_project_summary

Returns structured metadata for a Spring Boot repository: build files, dependencies, source roots, components, endpoint mappings, config keys, and Flyway migrations.

analyze_project_structure, list_rest_controllers, list_endpoints, inspect_application_properties, inspect_flyway_migrations

Workspace aliases with names that are easy for agents to select during codebase inspection.

spring_code_review

Returns a pragmatic Markdown or JSON review focused on missing authorization signals, risky migrations, sensitive configuration, missing test directories, and common Spring/JPA footguns.

spring_flyway_risk_scan

Returns a focused Flyway migration report.

spring_generate_mockmvc_tests

Generates starter MockMvc test skeletons for detected controllers.

list_applications, list_actuator_endpoints, get_health_status, get_info, get_audit_events, get_beans, get_conditions, get_config_properties, get_mappings, get_flyway_status, get_liquibase_status, get_integration_graph, get_metrics, get_env_properties, get_loggers, get_thread_dump, get_startup, get_heap_info, get_heap_dump_metadata, get_scheduled_tasks, get_cache_stats, get_http_traces, get_quartz, get_sessions, get_sbom, get_prometheus, get_log_file

Actuator-backed runtime tools. get_env_properties and get_config_properties redact likely secrets. get_log_file and get_heap_dump_metadata require SPRING_TOOLKIT_ENABLE_ACTUATOR_DOWNLOADS=true.

change_logger_level, delete_session

Actuator-backed mutations. Logger changes require SPRING_TOOLKIT_ENABLE_LOGGER_MUTATION=true; session deletion requires SPRING_TOOLKIT_ENABLE_SESSION_MUTATION=true.

run_maven_tests, run_gradle_tests, run_specific_test, read_surefire_report, read_jacoco_report

Quality-gate tools. Report readers are passive; test runners require SPRING_TOOLKIT_ENABLE_TEST_RUNS=true.

Demo Flow

User prompt:

Analyze why orders-service is slow before I open the PR.

An agent can call:

get_health_status(application="orders")
get_metrics(application="orders", metric="http.server.requests")
get_heap_info(application="orders")
list_endpoints(path="C:\work\orders-service")
read_surefire_report(path="C:\work\orders-service")
spring_code_review(path="C:\work\orders-service")

Then it can summarize runtime symptoms, related controller/service code, test status, migration risk, and concrete next steps.

MCP Client Configuration Example

{
  "mcpServers": {
    "spring-toolkit": {
      "command": "python",
      "args": ["-m", "spring_toolkit_mcp.server"],
      "env": {
        "SPRING_TOOLKIT_ALLOWED_ROOTS": "C:\\work\\my-spring-app",
        "SPRING_TOOLKIT_ACTUATOR_BASE_URLS": "orders=http://localhost:8080/actuator"
      }
    }
  }
}

Development

Run tests:

python -m unittest discover -s tests

The project has no runtime dependencies. That is deliberate for the MVP: agents can run it in locked-down enterprise environments, and the MCP surface stays easy to audit.

Roadmap

• Maven and Gradle test execution tools with explicit allowlists
• SonarQube report ingestion
• PostgreSQL schema introspection
• Spring Security 6 focused checks
• MapStruct and Lombok deeper analysis
• Continue/OpenHands recipes and CI examples

License

Spring Toolkit MCP is open source software released under the MIT License.