SpringAi MCP服务开发

发表于 | 分类于
SpringAi MCP服务开发

前言

Spring AI 对 MCP（Model Context Protocol，模型上下文协议） 提供了原生支持，使 Java 开发者可以轻松构建 MCP 服务端（Server）或客户端（Client），从而让大语言模型（LLM）通过标准化方式调用外部工具、访问数据源、执行业务逻辑。

下面是一份 完整的 Spring AI MCP 服务开发指南，涵盖核心概念、两种通信模式（stdio / SSE）、代码示例与配置说明。

什么是 MCP？

  • MCP（Model Context Protocol） 是由 Anthropic 于 2024 年 11 月推出的开放协议。

  • 它定义了 LLM 与外部系统（如数据库、API、文件系统）交互的标准方式。

  • 类比：MCP = AI 领域的 USB-C 接口 —— 统一插拔，即插即用。

  • 底层基于 JSON-RPC 2.0，支持两种通信模式：

    • stdio（标准输入输出）：本地进程通信，适合嵌入式工具。
  • SSE（Server-Sent Events）：HTTP 长连接，适合远程部署、多客户端共享。

Spring AI MCP 服务端开发

1. 创建项目 & 添加依赖

使用 start.spring.io 或手动创建 Maven 项目。

pom.xml（以 SSE 模式 为例）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
<properties>
    <java.version>17</java.version>
    <spring-ai.version>1.0.0-M7</spring-ai.version>
</properties>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-bom</artifactId>
            <version>${spring-ai.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <!-- Web 支持（SSE 需要） -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <!-- Spring AI MCP Server (SSE 模式) -->
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
    </dependency>
</dependencies>

若使用 stdio 模式，则替换为：

1
2
3
4
<dependency>
 <groupId>org.springframework.ai</groupId>
 <artifactId>spring-ai-starter-mcp-server</artifactId>
</dependency>

2. 配置 application.yml

SSE 模式（远程 HTTP 服务）

1
2
3
4
5
6
7
8
9
10
11
server:
  port: 8080

spring:
  ai:
    mcp:
      server:
        name: math-mcp-server
        version: 1.0.0
        # SSE 端点默认为 /mcp/message，可自定义
        sse-message-endpoint: /mcp/math

stdio 模式（本地子进程）

1
2
3
4
5
6
7
8
9
10
spring:
  main:
    web-application-type: none   # 必须禁用 Web 容器
    banner-mode: off             # 避免 banner 输出干扰 stdio
  ai:
    mcp:
      server:
        stdio: true
        name: local-math-server
        version: 1.0.0

⚠️ stdio 模式下：不能有任何日志输出到 stdout，否则会破坏 MCP 协议通信。建议重定向日志到文件。

3. 定义 MCP 工具（使用 @Tool 注解）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
@Service
public class MathService {

    @Tool(description = "计算两个数的加法")
    public String add(
        @ToolParameter(description = "第一个加数") double a,
        @ToolParameter(description = "第二个加数") double b
    ) {
        return String.valueOf(a + b);
    }

    @Tool(description = "计算两个数的乘积")
    public String multiply(
        @ToolParameter(description = "被乘数") double x,
        @ToolParameter(description = "乘数") double y
    ) {
        return String.valueOf(x * y);
    }
}
  • @Tool：暴露方法为 MCP 工具。
  • @ToolParameter：描述参数，帮助 LLM 理解如何调用。

4. 注册工具到 MCP 服务器

1
2
3
4
5
6
7
8
9
10
@Configuration
public class McpToolConfig {

    @Bean
    public ToolCallbackProvider mathTools(MathService mathService) {
        return MethodToolCallbackProvider.builder()
                .toolObjects(mathService)
                .build();
    }
}

Spring AI 会自动扫描 @Tool 方法并注册为可用工具。

5. 启动应用

1
2
3
4
5
6
@SpringBootApplication
public class McpServerApplication {
    public static void main(String[] args) {
        SpringApplication.run(McpServerApplication.class, args);
    }
}

启动后：

  • SSE 模式：访问 http://localhost:8080/mcp/math（需通过 SSE 客户端连接）
  • stdio 模式：打包成 JAR，由 MCP 客户端（如 CherryStudio、Trae）通过 java -jar xxx.jar 启动子进程

测试 MCP 服务

方式 1

使用 CherryStudio / Trae / Cursor 等 AI IDE

在 mcp.json 中配置：

1
2
3
4
5
6
7
8
{
  "mcpServers": {
    "math-service": {
      "type": "sse",
      "url": "http://localhost:8080/mcp/math"
    }
  }
}

然后在聊天中问：

“计算 12 乘以 15 是多少？”

AI 会自动调用你的 multiply 工具。

方式 2

Postman（仅 SSE）

  1. 新建 SSE 请求，URL 填 http://localhost:8080/mcp/math
  2. 连接后，另开一个 POST 请求 发送 JSON-RPC 调用：
1
2
3
4
5
6
{
  "jsonrpc": "2.0",
  "method": "add",
  "params": { "a": 10, "b": 20 },
  "id": "1"
}

结果会通过 SSE 流返回。

关键注意事项

项目 说明
JDK 版本 必须 ≥ JDK 17
日志输出 stdio 模式下禁止 System.out.println()，用 System.err 或日志文件
工具命名 方法名和参数名需清晰，LLM 依赖这些信息做推理
安全 生产环境建议加认证（如 API Key、OAuth），MCP 本身不包含认证机制
多模态 MCP 支持文本、图像、音频等，但 Spring AI 当前主要支持文本

扩展能力（高级）

  • 动态上下文管理：通过 ContextManager 传递用户会话状态
  • 资源（Resources）：暴露静态内容（如文档片段、图片 URI）
  • 提示模板（Prompts）：注册可复用的 prompt 模板
  • 进度反馈：长时间任务可通过 progress 通知客户端

参考资源