Spring Mcp Generator

CI

Spring MCP Generator is a Java/Maven tool that turns existing API definitions or Spring code into a generated Spring Boot MCP server project.

It supports three input flows: OpenAPI 3.x, Spring MVC @RestController scanning, and Spring @Service scanning. All flows map into one canonical model, then generate deterministic and readable code you can inspect and customize.

Status: release-candidate baseline (1.0.0). OpenAPI remains the most mature generation path.

Compatibility

• Java 17
• Maven 3.9+

Support and maturity matrix

Capability	Maturity label	Notes
OpenAPI flow	primary	Most complete and most stable path for external evaluation.
Controller flow	supported subset	Works for supported Spring MVC patterns; unsupported mappings fail clearly.
Service flow	supported subset	Works for supported @Service + @McpTool patterns; unsupported shapes fail clearly.
Regeneration planning goals	supported subset	Planning is deterministic and useful, but still conservative by design.
Multi-module Maven support	supported subset	Practical and tested for explicit module configuration scenarios.

Why this project exists

Most teams already have API contracts or Spring code, but not MCP-ready server projects. This project gives you a practical bridge: analyze what you already have, generate a working Spring Boot MCP server skeleton, then adapt it to your runtime and governance needs.

What it can do today

• Generate Spring Boot MCP server code from OpenAPI, controllers, or services.
• Analyze controller/service inputs before generation.
• Apply deterministic override/governance config from mcp-generator.yaml.
• Support incremental and merge-safe regeneration with planning goals.
• Produce machine-readable outputs:
  • analysis export (analysis-export-v1)
  • generated governance manifest (governance-manifest-v1)

Which flow should I use?

Choose this flow	When it is the best fit
OpenAPI flow	You already have a maintained OpenAPI 3.x contract and want the most mature path.
Controller flow	Your source of truth is Spring MVC endpoints and you want tool mapping from HTTP controllers.
Service flow	You want to expose service-layer capabilities (annotated with @McpTool) instead of controller endpoints.

If you are trying the project for the first time, start with OpenAPI.

Quick start (OpenAPI, first success)

1. Build the project:

mvn clean test

2. Generate from the provided example:

mvn -pl spring-mcp-generator-maven-plugin -am \
  dev.markozivkovic:spring-mcp-generator-maven-plugin:1.0.0:generate \
  -DspringMcp.inputSpec="$(pwd)/examples/minimal-order-api/openapi.yaml" \
  -DspringMcp.generatorConfig="$(pwd)/examples/minimal-order-api/mcp-generator.yaml" \
  -DspringMcp.outputDirectory="$(pwd)/target/generated-mcp-server"

3. Inspect generated output in target/generated-mcp-server.

What gets generated

Generated output is standard Spring Boot source code and resources, not opaque runtime magic. Typical files include:

• pom.xml and Spring Boot application entrypoint
• MCP tool registration/config classes
• Tool handler classes
• HTTP delegation client (UpstreamApiClient)
• Governance runtime hooks (auth/audit/rate-limit extension points)
• application.yml
• src/main/resources/governance-manifest.json (effective post-override tool governance inventory)

Maven plugin goals (at a glance)

• OpenAPI: validate, dry-run, generate, plan-regeneration
• Controller: analyze-controllers, generate-from-controllers, plan-regeneration-from-controllers
• Service: analyze-services, generate-from-services, plan-regeneration-from-services

Modules

• spring-mcp-generator-core: canonical model, shared contracts, override/config logic
• spring-mcp-generator-openapi: OpenAPI parsing and canonical mapping
• spring-mcp-generator-scanner-springmvc: controller scanning and mapping
• spring-mcp-generator-scanner-service: service scanning and mapping
• spring-mcp-generator-codegen: deterministic Spring Boot project generation (FreeMarker templates)
• spring-mcp-generator-maven-plugin: Maven goals and orchestration

Documentation map

• Getting started
• OpenAPI flow
• Controller flow
• Service flow
• Configuration
• Regeneration
• Troubleshooting
• Releasing
• Architecture (for contributors)
• Roadmap

Current limitations

• OpenAPI flow is primary and most mature.
• Controller/service flows are usable and tested, but support conservative subsets with explicit unsupported reporting.
• No built-in enterprise IAM platform integration.
• No distributed rate-limit backend or distributed audit backend by default (extension points are generated).

Contributing

Issues and PRs are welcome. Start with docs/getting-started.md for local setup, then docs/architecture.md for contributor context.