Spring Web to MCP Converter 🚀

Spring Web 到 MCP 转换器 🚀

一个 OpenRewrite 配方集合，可自动将 Spring Web REST API 转换为 Spring AI 模型上下文协议（MCP）服务工具。

📋 简介

本项目提供了一组 OpenRewrite 配方，帮助你将传统的 Spring Web REST API 迁移为 Spring AI 的模型上下文协议（MCP）服务工具。转换包括：

1. 🔄 将 Spring Web 注解转换为 Spring AI MCP @Tool 注解
2. 🔧 添加必要的 MCP 配置和组件
3. 📦 更新 Maven 依赖，以包含 Spring AI MCP 服务组件

这些配方会自动从现有 REST 控制器中提取文档，创建文档完善的 MCP 工具，使 AI Agent 能够通过模型上下文协议访问你的 API。

如需详细了解 Spring AI 对 MCP 的实现，请参阅 Spring AI MCP 文档。

🛠️ 构建和安装

前置条件

• Java 17 或更高版本
• Maven 3.6+

目标 REST API 项目的前置条件

要成功将 Spring Web REST API 迁移到 MCP，你的项目应当：

• 使用 Spring Boot 3.2+（3.2.0 或更高版本）
• 使用 Spring Web MVC 编写 REST 控制器
• 使用 Maven 构建工具

该配方会自动向你的项目添加 Spring AI MCP 依赖（版本 1.0.0-SNAPSHOT 或更高版本）。

构建步骤

1. 克隆此仓库：

   git clone https://github.com/yourusername/web-to-mcp.git
   cd web-to-mcp
   

2. 构建项目：

   mvn clean install
   

此操作会编译代码，并将构件安装到本地 Maven 仓库。

🔥 使用方法

要将这些配方应用到 Spring Web 项目，请运行以下 Maven 命令：

mvn org.openrewrite.maven:rewrite-maven-plugin:6.4.0:run \
  -Drewrite.activeRecipes=RewriteWebToMCP \
  -Drewrite.recipeArtifactCoordinates=com.atbug.rewrite:web-to-mcp:1.0-SNAPSHOT \
  -Drewrite.exportDatatables=true

重要：此命令需要执行两次：

1. 首次执行会更新 pom.xml，以添加必要的仓库和依赖项
2. 第二次执行会实际将 Spring Web 控制器代码转换为 MCP 工具

✨ 功能

该配方会执行多项转换，分为三个主要组件：

1. POM 更新（UpdatePom）

• 添加 Spring Snapshots 仓库（https://repo.spring.io/snapshot）
• 添加 Central Portal Snapshots 仓库（https://central.sonatype.com/repository/maven-snapshots/）
• 添加 Spring AI MCP 服务 WebMVC 依赖（spring-ai-starter-mcp-server-webmvc）

2. 代码转换

• AddToolAnnotationToMappingMethod：自动将 Spring Web 控制器方法转换为 MCP 工具

  • 为带有 Spring Web 映射注解（@GetMapping、@PostMapping 等）的方法添加 @Tool 注解
  • 从 JavaDoc 注释中提取方法描述，用于填充 description 属性
  • 为方法参数添加 @ToolParam 注解，并保留 JavaDoc 中的参数描述

• AddToolCallbackProviderBean：创建或更新 Bean，以注册 MCP 工具

  • 识别 Spring Boot 应用程序的入口类
  • 创建 ToolCallbackProvider Bean，以注册所有带有 @Tool 注解的控制器
  • 如果已有 Provider Bean，则智能地更新它

• AddSpringAIMcpProperties：配置 MCP 服务属性

  • 将必需的 MCP 服务配置添加到 application.properties 或 application.yml
  • 设置服务名称、版本、类型和消息端点
  • 同时支持 YAML 和 Properties 文件格式

🧪 示例

转换前（Spring Web 控制器）

@RestController
@RequestMapping("/api/users")
public class UserController {
    
    /**
     * Get a user by ID
     * @param id The user identifier
     * @return The user details
     */
    @GetMapping("/{id}")
    public User getUserById(@PathVariable Long id) {
        // Implementation
    }
}

转换后（MCP 工具）

@RestController
@RequestMapping("/api/users")
public class UserController {
    
    /**
     * Get a user by ID
     * @param id The user identifier
     * @return The user details
     */
    @GetMapping("/{id}")
    @Tool(description = "Get a user by ID")
    public User getUserById(@ToolParam(description = "The user identifier") @PathVariable Long id) {
        // Implementation
    }
}

生成的 MCP 配置

该配方还会自动将 MCP 服务配置添加到应用程序属性中：

spring.ai.mcp.server.name=webmvc-mcp-server
spring.ai.mcp.server.sse-message-endpoint=/mcp/messages
spring.ai.mcp.server.type=SYNC
spring.ai.mcp.server.version=1.0.0

并通过向 Spring Boot 应用程序类添加 ToolCallbackProvider Bean，自动注册你的工具：

@Bean
ToolCallbackProvider toolCallbackProvider(UserController userController) {
    return MethodToolCallbackProvider.builder()
            .toolObjects(userController)
            .build();
}

🌟 演示

你可以使用一个已准备好进行转换的 Spring Boot 3 REST API 示例项目，试用此转换工具。

示例项目设置

1. 克隆示例项目：

   git clone https://github.com/addozhang/spring-boot-3-rest-api-sample.git
   cd spring-boot-3-rest-api-sample
   

2. 查看示例项目结构：

   • 这是一个带有 REST 控制器的标准 Spring Boot 3 应用程序
   • 包含使用各种 HTTP 方法（GET、POST、PUT、DELETE）的典型 REST 端点
   • 包含规范的 JavaDoc 注释，这些注释将转换为 MCP 工具描述

转换流程

1. 首先，运行 Maven 命令，用所需依赖项更新 POM 文件：

   mvn org.openrewrite.maven:rewrite-maven-plugin:6.4.0:run \
     -Drewrite.activeRecipes=RewriteWebToMCP \
     -Drewrite.recipeArtifactCoordinates=com.atbug.rewrite:spring-rest-to-mcp:1.0-SNAPSHOT \
     -Drewrite.exportDatatables=true
   

2. 然后，再次运行相同的命令，执行实际的代码转换：

   mvn org.openrewrite.maven:rewrite-maven-plugin:6.4.0:run \
     -Drewrite.activeRecipes=RewriteWebToMCP \
     -Drewrite.recipeArtifactCoordinates=com.atbug.rewrite:spring-rest-to-mcp:1.0-SNAPSHOT \
     -Drewrite.exportDatatables=true
   

3. 验证更改：

   • 检查控制器类，确认是否添加了 @Tool 和 @ToolParam 注解
   • 查看主应用程序类中是否新增了 ToolCallbackProvider Bean
   • 检查 application.properties 或 application.yml 是否包含 MCP 服务配置

4. 运行应用程序：

   mvn spring-boot:run
   

5. 使用官方 MCP Inspector 测试 MCP 服务：

   • 克隆 MCP Inspector 仓库：

     git clone https://github.com/modelcontextprotocol/inspector.git
     cd inspector
     

   • 安装依赖项并启动 inspector：

     npm install
     npm run dev
     

   • 在浏览器中访问 http://localhost:5173/ 打开 inspector
   • 在左侧面板中配置 MCP 服务：
     • 类型：SSE
     • 地址：http://localhost:8080/sse
   • 连接成功后，你可以：
     • 在主面板中查看所有可用工具
     • 交互式测试每个工具
     • 查看 MCP 服务的响应

预期效果

转换后，你的 Spring Boot 应用程序将同时作为传统 REST API 和 MCP 服务运行。这意味着：

• 你现有的所有端点都会继续正常工作
• 支持 MCP 协议的应用程序可以发现并与你的 API 交互
• AI 助手可以通过 MCP 协议的标准化格式了解如何使用你的工具

使用 MCP 服务的应用程序可以通过以下配置连接到该服务：

{
  "mcpServers": {
    "spring-ai-mcp-sample": {
      "autoApprove": [],
      "disabled": false,
      "timeout": 60,
      "url": "http://localhost:8080/sse",
      "transportType": "sse"
    }
  }
}

这样，客户端应用程序便可无缝发现并使用转换后的 API 所提供的工具。

📄 许可证

本项目采用 Apache License 2.0 许可，详情请参阅 LICENSE 文件。

👥 贡献

欢迎贡献！请随时提交 Pull Request。

📞 支持

如有任何问题或需要帮助，请在 GitHub 上提交 issue。