Spring Boot Runtime Diagnostics

Name: Spring Boot Runtime Diagnostics
Author: neilmorse

Local

github.com/neilmorseDeveloper Tools1Updated 1w ago

Repository

About Spring Boot Runtime Diagnostics

Spring Boot Runtime Diagnostics is a read-only MCP server that inspects authorized Actuator and OpenAPI data from a running Spring Boot application. It helps developers and coding agents investigate beans, routes, health, migrations, configuration sources, and startup behavior while reporting incomplete evidence as partial or unknown.

Key features

01Bean dependencies and condition reports
02Registered routes and controller mappings
03Health and readiness status
04Flyway and Liquibase migration records
05Startup steps and configuration sources

Use cases

01Find why a Spring Bean was not created
02Verify routes without calling business endpoints
03Inspect unhealthy components or failed migrations
04Investigate slow startup and property origins

MCP support

It provides diagnostic tools to MCP clients by reading authorized Actuator endpoints and `/actuator/openapi`. The server is read-only and restricts connections to loopback addresses.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config

{
  "mcpServers": {
    "neilmorse-spring-runtime": {
      "command": "uvx",
      "args": [
        "spring-runtime-mcp"
      ]
    }
  }
}

Run commanduvx spring-runtime-mcp

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages

pypispring-runtime-mcp0.2.12stdio

Tools

Saved tool list · updated 1w ago

Parameter	Type	Required	Description
cursor	string	No
maxDepth	integer	No
targetId	string	No
maxResults	integer	No
minDurationMs	number	No
beanNamePattern	string	No	Bounded case-sensitive glob: only * and ? are wildcards; all other allowed characters are literal. No regex.
stepNamePattern	string	No	Bounded case-sensitive glob: only * and ? are wildcards; all other allowed characters are literal. No regex.

Details

From the project README

Spring Boot Runtime Diagnostics MCP

Chinese README

Give your coding assistant access to what is actually running in a Spring Boot application. This MCP server reads authorized Actuator and OpenAPI data to help investigate Beans, routes, health, database migrations and startup problems.

What can it check?

Your question	What it provides
Why was a Bean not created?	Beans, dependencies and condition reports, with blocking chains when evidence is sufficient
Is this route registered?	Actual paths, HTTP methods, Controllers and MVC/WebFlux mappings
What is unhealthy?	Visible components and liveness/readiness status
Did a migration fail?	Reported Flyway/Liquibase records, states and checksums
What made startup slow?	Slow steps and their parent chains
Where did a configuration value come from?	Sources for registered properties; configuration diagnostics require opt-in
Is this API in OpenAPI?	Operations, schemas and references within the document
Does the process match my expectations?	Compare the Bean, route, migration version and profile expectations you supply

For example, ask: “Check whether GET /orders/{id} is registered and tell me which Controller handles it.” The server reads mapping metadata without calling the business endpoint.

Get started

You need Python 3.11+, uv and an authorized local Spring Boot application. Confirm its management endpoints and permissions using the target setup guide, then check and start 0.2.12 Alpha:

uvx --default-index https://pypi.org/simple spring-runtime-mcp==0.2.12 --version
uvx --default-index https://pypi.org/simple spring-runtime-mcp==0.2.12 --base-url http://127.0.0.1:18081

Use the second command as your MCP client's STDIO server command. In a terminal it waits for client requests. Follow the English first-query guide; additional client configuration templates cover other clients.

Try the synthetic route demo using the public package without preparing an application, then share first-query feedback. The replay needs no Spring process and does not establish live application or client compatibility.

Boundaries

The server connects only to loopback addresses, uses fixed endpoints and supports optional Bearer authentication from a named environment variable. OpenAPI uses /actuator/openapi. Configuration diagnostics are disabled by default and require explicit opt-in via CLI flags (--config-prefix, --config-property, --config-profiles). When enabled, values remain hidden unless both --config-allow-values and the tool’s includeValues=true are set. Output is sanitized, and each tool response is capped at 16 KiB. Missing evidence is reported as partial/unknown.

Tools do not write to the target, restart applications, or read heap dumps or raw logs. The complete Boot/Java/client matrix, Windows/macOS and production-cluster compatibility remain unverified.

Documentation · Tool contract · Source facts · Development and checks

Apache-2.0 · Contributing · Report a security issue

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

Read the getting-started guide

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.