api2mcp4j

Zero-to-low code MCP integration for your Spring Boot REST APIs
Turn your existing Spring Boot controllers into an MCP (Model Context Protocol) server in minutes — no @Tool annotations everywhere, no rewriting business logic.

✨ Why api2mcp4j?

Most MCP integrations require you to:

• Add @Tool / @McpTool annotations to every method
• Duplicate or heavily refactor code
• Maintain separate tool descriptions

api2mcp4j changes that.

It automatically scans your existing @RestController / @Service beans and exposes them as MCP tools with minimal configuration — leveraging parsers from:

• Swagger/OpenAPI (v2 & v3)
• Javadoc
• Spring MVC metadata
• Jackson
• Spring AI native descriptions
• Custom @Tool / @McpTool (optional)

Result: Your current REST APIs become AI-callable tools almost for free.

🔥 Key Features

• Non-intrusive — No need to change business code (like MyBatis-Plus enhances MyBatis)
• Auto-discovery — Scans controllers/services and registers methods as MCP tools
• Multi-parser support — Smartly combines descriptions & parameter info from Swagger, Javadoc, etc.
• Custom annotations — @ToolScan, @ResourceScan, @PromptScan for fine-grained control
• Isolated MCP tool system — Uses McpTool annotation (independent of Spring AI @Tool)
• Full MCP SDK compatibility — Supports latest MCP Java SDK features (callbacks, resources, prompts)
• Easy debugging — Works great with Cursor, Continue, or any MCP client

Quick Start (≈ 5 minutes)

1. Add dependency

Note: Project not yet in Maven Central — build from source for now.

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

<!-- pom.xml -->
<dependency>
    <groupId>com.ai.plug</groupId>
    <artifactId>server2mcp-starter-webmvc</artifactId>
    <version>1.1.4-SNAPSHOT</version> <!-- or latest after build -->
</dependency>

2. Enable in application.yml

plugin:
  mcp:
    enabled: true
    # Recommended: use multiple parsers for best description quality
    parser:
      params: SWAGGER3, SWAGGER2, SpringMVC, JACKSON, TOOL  # JAVADOC needs extra setup
      des:    SWAGGER3, SWAGGER2, JAVADOC, TOOL, JACKSON
    # 'interface' = auto-register all controller methods (skip @Deprecated)
    # 'custom'   = only register via @ToolScan / manual
    scope: interface

3. (Optional) Javadoc parser setup

To enable Javadoc parsing in production (bytecode doesn't contain comments):

<!-- pom.xml - package sources -->
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-resources-plugin</artifactId>
    <executions>
        <execution>
            <id>copy-java-sources</id>
            <phase>prepare-package</phase>
            <goals><goal>copy-resources</goal></goals>
            <configuration>
                <outputDirectory>${project.build.outputDirectory}</outputDirectory>
                <resources>
                    <resource>
                        <directory>src/main/java</directory>
                        <includes><include>**/*.java</include></includes>
                    </resource>
                </resources>
            </configuration>
        </execution>
    </executions>
</plugin>

4. Start your app → Test

Your MCP endpoint is ready (default /mcp or configured via spring.ai.mcp.* properties).

Use any MCP client (Cursor, custom agent, etc.) to call your original REST methods as tools.

Comparison with Alternatives

Feature	api2mcp4j	Spring AI MCP Official	Manual @Tool everywhere
Code changes required	Minimal (config only)	Medium–High	High
Auto from existing REST	Yes (controllers)	No	No
Parser combinators	Yes (Swagger+Javadoc+…)	Limited	Manual
Non-intrusive	★★★★★	★★★	★☆
Custom scan annotations	Yes	Partial	No
Best for existing projects	Yes	New MCP-first apps	Small prototypes

Best Use Cases

• Expose internal management system APIs to AI agents quickly
• Build multi-agent systems by turning microservices into MCP tools
• Prototype AI features on top of production REST services
• Avoid duplicating logic between REST and MCP endpoints

Documentation & Roadmap

• Full docs → https://theeterna.github.io/server2mcp-docs/
• Roadmap: Publish to Maven Central, stabilize SNAPSHOT deps, more parser plugins, SSE/Stream support

Contributing

Issues, PRs, and stars are very welcome!
The project is young — your feedback can shape its future.

License

Apache License 2.0

---

作者的话
这是一个我投入大量心血的个人项目，希望能真正帮助到更多 Spring Boot 开发者快速拥抱 MCP/AI Agent 时代。感谢每一位 star 和使用它的人！

- 语言更流畅、专业、吸引人

你可以直接发给作者，建议他 review 后合并（或作为 PR）。如果需要，我可以再调整语气、加 GIF/demo 图位置提示，或写中文版。