Spring Boot Stater MCP

Spring Boot Starter MCP（注：MCP在此处可能代表特定的模块、组件或配置，但根据上下文无法确定具体含义，因此直接保留原样翻译）

Spring Boot启动器，用于自动将REST端点作为MCP（模型上下文协议）工具暴露出来。

什么是MCP？

模型上下文协议（MCP）是一项开放标准，它使得应用程序能够与大型语言模型（LLM），如Claude、GPT-4等进行集成。MCP允许你暴露AI可以调用的工具，以执行特定任务。

特点/功能

• 自动注册添加 @McpTool 为控制器或方法添加注解，端点将自动作为MCP工具暴露出来
• 参数映射REST参数到MCP工具参数的自动映射，支持类型转换
• 符合JSON-RPC 2.0规范全面实现MCP所要求的JSON-RPC 2.0协议
• Spring Boot 自动配置零配置 - 只需将启动器添加到您的项目中
• 定制化对名称、描述和参数模式拥有完全控制权

安装

Gradle（注：这是一个专有名词，通常直接音译，不进行意译）

dependencies {
    implementation 'pl.asenet:spring-boot-starter-mcp:0.1.0-SNAPSHOT'
}

Maven

    pl.asenet
    spring-boot-starter-mcp
    0.1.0-SNAPSHOT

快速入门

1. 创建一个带有@McpTool注解的REST控制器

@RestController
@RequestMapping("/api/weather")
public class WeatherController {

    @McpTool(
        name = "get_weather",
        description = "Gets current weather for a given city"
    )
    @GetMapping
    public WeatherResponse getWeather(
        @McpParameter(description = "City name", example = "Warsaw")
        @RequestParam String city
    ) {
        // Your business logic
        return weatherService.getWeather(city);
    }

    @McpTool(
        name = "get_forecast",
        description = "Gets weather forecast for a specified number of days"
    )
    @GetMapping("/forecast")
    public ForecastResponse getForecast(
        @McpParameter(description = "City name", example = "Warsaw")
        @RequestParam String city,

        @McpParameter(description = "Number of forecast days", example = "7")
        @RequestParam int days
    ) {
        return weatherService.getForecast(city, days);
    }
}

2. 运行应用程序

就是这么简单！启动器会自动：

• 扫描控制器，使用 @McpTool 注释
• 将它们注册为MCP工具
• 揭露了 /mcp 支持JSON-RPC 2.0协议的端点

3. 测试

检查已注册的工具：

curl http://localhost:8080/mcp/tools

调用一个MCP工具：

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_weather",
      "arguments": {
        "city": "Warsaw"
      }
    }
  }'

注释

@McpTool（这个标签或用户名直接翻译为中文可能保持原样，因为“@McpTool”通常是一个特定的用户名或标签，没有直接的中文含义，但如果需要解释性翻译，可以理解为“@MCP工具”或“@MCP工具账号”，具体取决于上下文）

将控制器或方法标记为MCP工具。

参数：

• name - 工具名称（默认：根据方法名称生成的 snake_case 格式）
• description - 人工智能工具描述
• enabled - 工具是否处于激活状态（默认：true）

示例：

// At class level - all methods with @RequestMapping will become tools
@McpTool
@RestController
public class CalculatorController {
    // ...
}

// At method level - only this method will be a tool
@RestController
public class UserController {

    @McpTool(name = "find_user", description = "Finds user by ID")
    @GetMapping("/users/{id}")
    public User findUser(@PathVariable Long id) {
        // ...
    }
}

@McpParameter（注：这是一个特定于编程或框架的参数注解，直接翻译为中文可能无法完全传达其含义，但可大致理解为“MCP参数注解”或“用于指定MCP参数的注解”，具体翻译需根据上下文确定）

为MCP工具参数添加元数据。

参数：

• description - AI的参数说明
• required - 是否需要该参数（默认：true）
• example - 示例值

示例：

@McpTool(name = "create_user", description = "Creates a new user")
@PostMapping("/users")
public User createUser(
    @McpParameter(description = "User email", example = "john@example.com")
    @RequestParam String email,

    @McpParameter(description = "User name", example = "John")
    @RequestParam String name,

    @McpParameter(description = "User age (optional)", required = false, example = "25")
    @RequestParam(required = false) Integer age
) {
    // ...
}

配置

在 application.yml 或者 application.properties:

spring:
  mcp:
    enabled: true           # Enable/disable MCP server (default: true)
    path: /mcp             # Base path for MCP endpoints (default: /mcp)
    stdio-enabled: false   # Enable STDIO mode for CLI (default: false)

spring.mcp.enabled=true
spring.mcp.path=/mcp
spring.mcp.stdio-enabled=false

MCP 终点（或：MCP 端点）

启动应用程序后，可访问以下端点：

POST /mcp

主要JSON-RPC 2.0终端，符合MCP协议。

支持的方法：

• initialize - 初始化MCP连接
• tools/list - 列出所有可用工具
• tools/call - 调用一个工具

GET /mcp/health 翻译为中文是：“获取 /mcp/health（资源）”。不过，具体翻译可能会根据上下文有所调整，因为“/mcp/health”可能是一个特定系统或应用中的路径，其确切含义可能需要根据该系统或应用的文档来确定。但基本的翻译思路是，GET 方法用于请求获取某个资源，这里的资源就是“/mcp/health”

健康检查端点。

GET /mcp/tools 翻译为中文是：“获取 /mcp/tools（资源）”。不过，在实际应用中，我们通常不会直接翻译URL路径，而是理解为访问或请求某个特定的工具或资源页面。所以，也可以简化为“访问/mcp/tools工具”或“获取/mcp/tools工具资源”，具体取决于上下文和使用场景

所有已注册工具的列表（用于调试目的）。

MCP协议

初始化

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "clientInfo": {
      "name": "my-client",
      "version": "1.0.0"
    }
  }
}

列出工具

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

回答：

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "get_weather",
        "description": "Gets current weather for a given city",
        "inputSchema": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "description": "City name",
              "example": "Warsaw"
            }
          },
          "required": ["city"]
        }
      }
    ]
  }
}

调用一个工具

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": {
      "city": "Warsaw"
    }
  }
}

回答：

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"city\":\"Warsaw\",\"temperature\":15,\"condition\":\"Cloudy\"}"
      }
    ]
  }
}

与Claude桌面/MCP客户端的集成

克劳德桌面配置

添加到Claude桌面配置文件中（~/Library/Application Support/Claude/claude_desktop_config.json （在 macOS 上）：

{
  "mcpServers": {
    "my-spring-app": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

示例交互

配置完成后，您可以询问Claude：

"What's the weather in Warsaw?"

克劳德将自动检测并使用 get_weather 从你的Spring Boot应用程序中获取工具。

类型映射

启动器自动将Java类型映射到JSON Schema类型：

使用示例

示例1：简单计算器

@McpTool(description = "Calculator tools")
@RestController
@RequestMapping("/api/calculator")
public class CalculatorController {

    @GetMapping("/add")
    public double add(
        @McpParameter(description = "First number") @RequestParam double a,
        @McpParameter(description = "Second number") @RequestParam double b
    ) {
        return a + b;
    }

    @GetMapping("/multiply")
    public double multiply(
        @McpParameter(description = "First number") @RequestParam double a,
        @McpParameter(description = "Second number") @RequestParam double b
    ) {
        return a * b;
    }
}

示例2：任务管理

@RestController
@RequestMapping("/api/tasks")
public class TaskController {

    @McpTool(
        name = "create_task",
        description = "Creates a new task in the system"
    )
    @PostMapping
    public Task createTask(
        @McpParameter(description = "Task title")
        @RequestParam String title,

        @McpParameter(description = "Task description", required = false)
        @RequestParam(required = false) String description,

        @McpParameter(description = "Priority: LOW, MEDIUM, HIGH")
        @RequestParam Priority priority
    ) {
        return taskService.create(title, description, priority);
    }

    @McpTool(
        name = "list_tasks",
        description = "Lists all tasks"
    )
    @GetMapping
    public List listTasks() {
        return taskService.findAll();
    }

    @McpTool(
        name = "complete_task",
        description = "Marks a task as completed"
    )
    @PutMapping("/{id}/complete")
    public Task completeTask(
        @McpParameter(description = "Task ID")
        @PathVariable Long id
    ) {
        return taskService.complete(id);
    }
}

示例3：数据库集成

@RestController
@RequestMapping("/api/products")
public class ProductController {

    @Autowired
    private ProductRepository productRepository;

    @McpTool(
        name = "search_products",
        description = "Searches products by name or category"
    )
    @GetMapping("/search")
    public List
 search(
        @McpParameter(description = "Search query", required = false)
        @RequestParam(required = false) String query,

        @McpParameter(description = "Product category", required = false)
        @RequestParam(required = false) String category,

        @McpParameter(description = "Maximum price", required = false)
        @RequestParam(required = false) Double maxPrice
    ) {
        return productRepository.search(query, category, maxPrice);
    }
}

禁用工具

您可以临时禁用某个工具：

@McpTool(enabled = false)
@GetMapping("/admin/dangerous-operation")
public void dangerousOperation() {
    // This method will NOT be available as an MCP tool
}

调试

启用调试日志 application.yml:

logging:
  level:
    pl.asenet.mcp: DEBUG

要求

• Java 17及以上版本
• Spring Boot 3.2.0及以上版本

许可证

麻省理工学院许可证

作者

阿萨内特

贡献

欢迎提交拉取请求！对于重大更改，请先打开一个议题进行讨论，说明您希望做出的更改。

路线图

• \[ \] 支持实时通信的WebSocket
• \[ \] 对CLI工具的STDIO支持
• \[ \] MCP资源支持
• \[ \] MCP提示支持
• \[ \] Spring Security 集成
• \[ \] 指标和监控
• \[ \] OpenAPI/Swagger 集成