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 工具，使您的 API 可通过 模型上下文协议 访问到 AI 代理。

有关 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 快照存储库 (https://repo.spring.io/snapshot)
• 添加中央门户快照存储库 (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 注解的控制器
  • 如果已存在，则智能地更新现有的提供者 Bean

• AddSpringAIMcpProperties：配置 MCP 服务器属性

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

🧪 示例

之前（Spring Web 控制器）

@RestController
@RequestMapping("/api/users")
public class UserController {
    
    /**
     * 根据ID获取用户
     * @param id 用户标识符
     * @return 用户详细信息
     */
    @GetMapping("/{id}")
    public User getUserById(@PathVariable Long id) {
        // 实现
    }
}

之后（MCP 工具）

@RestController
@RequestMapping("/api/users")
public class UserController {
    
    /**
     * 根据ID获取用户
     * @param id 用户标识符
     * @return 用户详细信息
     */
    @GetMapping("/{id}")
    @Tool(description = "根据ID获取用户")
    public User getUserById(@ToolParam(description = "用户标识符") @PathVariable Long id) {
        // 实现
    }
}

自动生成的 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

并自动通过添加一个 ToolCallbackProvider Bean 到您的 Spring Boot 应用程序类来注册您的工具：

@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. 查看样本项目结构：

   • 它是一个标准的 Spring Boot 3 应用程序，具有 REST 控制器
   • 包含各种 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
     

   • 安装依赖项并启动检查器：

     npm install
     npm run dev
     

   • 在浏览器中访问检查器：http://localhost:5173/
   • 在左侧面板中，配置您的 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 许可证 2.0 下发布 - 详情见 LICENSE 文件。

👥 贡献

欢迎贡献！请随时提交拉取请求。

📞 支持

如果您有任何问题或需要帮助，请在 GitHub 上打开一个问题。