api2mcp4j

Overview#

api2mcp4j is a non-intrusive MCP Server generator for Spring Boot that automatically scans @RestController and @Service beans, registering their methods as MCP Tools, Resources, and Prompts. No business code changes are required to expose existing REST APIs to AI Agents.

Core Capabilities#

Auto-Discovery & Registration#

• Automatically scans @RestController / @Service beans and registers methods as MCP Tools
• Automatically skips @Deprecated methods
• Fine-grained scan control via @ToolScan, @ResourceScan, @PromptScan annotations
• Two scope modes: interface (full registration) and custom (annotation-only)

Multi-Parser Intelligent Fusion#

Extracts descriptions and parameter schemas via a configurable priority chain where later parsers override earlier ones:

• Swagger/OpenAPI: v2 & v3 support for interface descriptions and parameter info
• Javadoc: Parses .java source files via JavaParser (requires source copy to classpath)
• Spring MVC metadata: Extracts paths, methods from @RequestMapping etc.
• Jackson serialization metadata: Derives parameter JSON Schemas
• Spring AI native descriptions: Compatible with Spring AI @Tool annotation
• Custom annotations: Supports proprietary @McpTool annotation

Protocol Compatibility#

• Full MCP Java SDK compatibility: callbacks, resources, prompts
• Independent McpTool annotation system, decoupled from Spring AI @Tool
• Compatible with Cursor, Continue, and any standard MCP Client

Dual Stack Support#

• server2mcp-starter-webmvc: For Spring MVC
• server2mcp-starter-webflux: For reactive WebFlux

Typical Use Cases#

• Expose internal management system APIs to AI Agents without rewriting
• Build multi-Agent systems by converting microservices to MCP Tools
• Legacy Spring Boot projects adopting MCP at minimal cost
• Prototype AI features on production REST services without dual codebase maintenance

Not Suitable For#

• Non-Spring Boot Java projects
• Pure Stdio MCP Servers (currently exposes via Web endpoint only)
• Scenarios requiring hand-crafted prompts with extreme description precision

Architecture#

Maven multi-module structure:

Core Flow: Auto-configuration trigger → Bean scanning → Multi-parser fusion → MCP Tool registration, exposed at default /mcp endpoint.

Design Philosophy: Analogous to MyBatis-Plus enhancing MyBatis — bridging REST to MCP via auto-configuration and annotation scanning without invading business code.

Key Configuration#

plugin:
  mcp:
    enabled: true
    parser:
      params: SWAGGER3, SWAGGER2, SpringMVC, JACKSON, TOOL
      des:    SWAGGER3, SWAGGER2, JAVADOC, TOOL, JACKSON
    scope: interface

Installation#

⚠️ Not yet published to Maven Central; build from source required.

git clone https://github.com/TheEterna/api2mcp4j.git
cd api2mcp4j/server2mcp-starter-webmvc
mvn clean install

<dependency>
    <groupId>com.ai.plug</groupId>
    <artifactId>server2mcp-starter-webmvc</artifactId>
    <version>1.1.4-SNAPSHOT</version>
</dependency>

WebFlux users should substitute server2mcp-starter-webflux.

Open Items#

• Maven Central release timeline: planned per README roadmap, but 1.1.4-SNAPSHOT not yet available
• MCP SDK version stability: depends on io.modelcontextprotocol.sdk 0.14.0-SNAPSHOT (non-release)
• Spring AI version compatibility: depends on Spring AI 1.1.0-SNAPSHOT, untested against stable releases
• Documentation site is SPA (JS-rendered), content cannot be fully verified
• No public production deployment cases or user feedback observed
• Currently only Web endpoint (SSE) exposure; Stdio transport support unclear