Metadata-Version: 2.5
Name: spring-runtime-mcp
Version: 0.2.12
Summary: Read-only, sanitized Spring Boot runtime diagnostics for coding agents over MCP.
Project-URL: Homepage, https://github.com/neilmorse/spring-runtime-mcp
Project-URL: Repository, https://github.com/neilmorse/spring-runtime-mcp
Project-URL: Issues, https://github.com/neilmorse/spring-runtime-mcp/issues
Project-URL: Changelog, https://github.com/neilmorse/spring-runtime-mcp/blob/master/CHANGELOG.md
Author: Kaelenx
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: actuator,diagnostics,mcp,model-context-protocol,openapi,spring-boot
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: jsonschema==4.25.1
Requires-Dist: mcp<3,>=2.3
Description-Content-Type: text/markdown

# Spring Boot Runtime Diagnostics MCP

[Chinese README](README.zh-CN.md)

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](https://docs.astral.sh/uv/) and an authorized local Spring Boot application. Confirm its management endpoints and permissions using the [target setup guide](docs/target-app-setup.md), then check and start **0.2.12 Alpha**:

```bash
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](docs/first-query.md); additional [client configuration templates](docs/client-configuration.md) cover other clients.

Try the [synthetic route demo](docs/demo.md) using the public package without preparing an application, then [share first-query feedback](docs/trial-feedback.md). 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](docs/README.md) · [Tool contract](src/spring_runtime_mcp/schemas/tools-contract.json) · [Source facts](docs/source-catalog.md) · [Development and checks](docs/launch/README.md)

[Apache-2.0](LICENSE) · [Contributing](CONTRIBUTING.md) · [Report a security issue](SECURITY.md)

<!-- mcp-name: io.github.neilmorse/spring-runtime-mcp -->
