Spring AI MCP Demo

这是一个全面的演示项目，展示了如何使用Spring AI的Model Context Protocol (MCP) 集成功能。

概述

此演示项目包含两个独立的模块，分别展示了MCP客户端和服务器的实现：

• spring-ai-mcp-client-demo - MCP客户端演示应用程序
• spring-ai-mcp-server-demo - MCP服务器演示应用程序

什么是MCP？

Model Context Protocol (MCP) 是一个开放标准，用于在AI应用程序和外部数据源及工具之间建立安全、可控的连接。它允许：

• 工具集成：AI模型可以调用外部工具和函数
• 资源访问：AI模型可以访问文件、数据库和其他资源
• 上下文共享：在AI应用程序之间共享上下文信息
• 安全控制：细粒度的权限控制和访问管理

项目结构

spring-ai-mcp-demo/
├── pom.xml                           # 主模块POM文件
├── README.md                         # 本文档
├── spring-ai-mcp-client-demo/        # MCP客户端演示
│   ├── src/main/java/                # Java源代码
│   │   └── org/springframework/ai/mcp/client/demo/
│   │       ├── McpClientDemoApplication.java      # 主应用类
│   │       ├── config/
│   │       │   └── McpClientConfiguration.java    # 客户端配置
│   │       └── controller/
│   │           └── McpToolController.java          # REST控制器
│   ├── src/main/resources/
│   │   └── application.yml           # 配置文件
│   ├── pom.xml                       # 客户端POM文件
│   └── README.md                     # 客户端文档
└── spring-ai-mcp-server-demo/        # MCP服务器演示
    ├── src/main/java/                # Java源代码
    │   └── org/springframework/ai/mcp/server/demo/
    │       ├── McpServerDemoApplication.java       # 主应用类
    │       ├── config/
    │       │   └── McpServerConfiguration.java     # 服务器配置
    │       ├── tools/
    │       │   ├── MathToolsConfiguration.java     # 数学工具
    │       │   └── TextToolsConfiguration.java     # 文本工具
    │       └── resources/
    │           └── SystemResourcesConfiguration.java # 系统资源
    ├── src/main/resources/
    │   └── application.yml           # 配置文件
    ├── pom.xml                       # 服务器POM文件
    └── README.md                     # 服务器文档

快速开始

前提条件

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

1. 克隆项目

git clone https://github.com/spring-projects/spring-ai.git
cd spring-ai/mcp/spring-ai-mcp-demo

2. 编译项目

mvn clean compile

3. 运行演示

启动MCP服务器（终端1）

cd spring-ai-mcp-server-demo
mvn spring-boot:run

服务器将在 http://localhost:8081 启动

启动MCP客户端（终端2）

首先配置客户端连接到服务器。编辑 spring-ai-mcp-client-demo/src/main/resources/application.yml：

spring:
  ai:
    mcp:
      client:
        sse:
          servers:
            demo-server:
              url: "http://localhost:8081/mcp/sse"

然后启动客户端：

cd spring-ai-mcp-client-demo
mvn spring-boot:run

客户端将在 http://localhost:8080 启动

4. 测试连接

检查可用工具

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

调用数学工具

curl -X POST http://localhost:8080/api/mcp/tools/add/call \
  -H "Content-Type: application/json" \
  -d '{"a": 10, "b": 20}'

调用文本工具

curl -X POST http://localhost:8080/api/mcp/tools/uppercase/call \
  -H "Content-Type: application/json" \
  -d '{"text": "hello world"}'

功能演示

MCP服务器提供的功能

数学工具

• add - 两数相加
• multiply - 两数相乘
• power - 幂运算

文本工具

• uppercase - 转换为大写
• analyze_text - 文本分析
• reverse - 字符串反转

系统资源

• system://info - 系统信息
• time://current - 当前时间
• app://status - 应用状态

MCP客户端功能

REST API端点

• GET /api/mcp/tools - 获取可用工具列表
• GET /api/mcp/clients - 获取客户端连接信息
• POST /api/mcp/tools/{toolName}/call - 调用指定工具

传输方式

支持的传输协议

1. STDIO传输

   • 用于进程间通信
   • 适合本地工具集成

2. SSE HTTP传输

   • 基于HTTP的服务器发送事件
   • 适合网络通信

3. WebFlux传输

   • 响应式HTTP流
   • 适合高并发场景

配置示例

客户端配置

spring:
  ai:
    mcp:
      client:
        # STDIO传输
        stdio:
          servers:
            local-server:
              command: ["java", "-jar", "mcp-server.jar"]
        
        # HTTP SSE传输
        sse:
          servers:
            remote-server:
              url: "http://localhost:8081/mcp/sse"
        
        # WebFlux传输
        webflux:
          servers:
            reactive-server:
              url: "http://localhost:8082/mcp/webflux/sse"

服务器配置

spring:
  ai:
    mcp:
      server:
        capabilities:
          tool: true
          resource: true
          prompt: true
        
        # 传输配置
        stdio:
          enabled: true
        webmvc:
          enabled: true
          endpoint: "/mcp/sse"
        webflux:
          enabled: true
          endpoint: "/mcp/webflux/sse"

架构说明

整体架构

┌─────────────────┐    MCP Protocol    ┌─────────────────┐
│   MCP Client    │◄──────────────────►│   MCP Server    │
│                 │                    │                 │
│ - Tool Discovery│                    │ - Tool Registry │
│ - Tool Execution│                    │ - Resource Mgmt │
│ - Resource Access│                   │ - Prompt System │
└─────────────────┘                    └─────────────────┘

Spring AI集成

┌─────────────────┐
│  Spring AI App  │
│                 │
│ ┌─────────────┐ │
│ │ Chat Client │ │
│ └─────────────┘ │
│        │        │
│ ┌─────────────┐ │    ┌─────────────────┐
│ │ Tool System │◄┼────┤ MCP Tool Bridge │
│ └─────────────┘ │    └─────────────────┘
└─────────────────┘            │
                               │ MCP Protocol
                    ┌─────────────────┐
                    │   MCP Server    │
                    │                 │
                    │ - Math Tools    │
                    │ - Text Tools    │
                    │ - System Info   │
                    └─────────────────┘

扩展开发

添加自定义工具

在服务器端添加新工具：

@Bean
public SyncToolSpecification customTool() {
    return SyncToolSpecification.builder()
        .tool(McpSchema.Tool.builder()
            .name("custom_tool")
            .description("自定义工具")
            .inputSchema(/* 定义输入模式 */)
            .build())
        .handler((exchange, arguments) -> {
            // 实现工具逻辑
            return McpSchema.CallToolResult.builder()
                .content(/* 返回结果 */)
                .build();
        })
        .build();
}

添加自定义资源

@Bean
public SyncResourceSpecification customResource() {
    return SyncResourceSpecification.builder()
        .resource(McpSchema.Resource.builder()
            .uri("custom://resource")
            .name("自定义资源")
            .description("自定义资源描述")
            .build())
        .handler((exchange, uri) -> {
            // 实现资源逻辑
            return McpSchema.ReadResourceResult.builder()
                .contents(/* 返回内容 */)
                .build();
        })
        .build();
}

故障排除

常见问题

1. 连接失败

   • 检查服务器是否启动
   • 验证端口和URL配置
   • 查看防火墙设置

2. 工具调用失败

   • 检查工具名称拼写
   • 验证参数格式
   • 查看服务器日志

3. 依赖问题

   • 确保使用正确的Spring AI版本
   • 检查Maven依赖冲突

调试技巧

启用调试日志：

logging:
  level:
    org.springframework.ai.mcp: DEBUG
    io.modelcontextprotocol: DEBUG

相关资源

• Spring AI官方文档
• MCP规范文档
• MCP Java SDK
• Spring AI GitHub仓库

许可证

本项目基于Apache License 2.0许可证开源。详情请参见LICENSE文件。