READMEmain

Spring AI + DeepSeek + MCP 集成演示

这个项目展示了如何使用 Spring AI 框架与 DeepSeek 大语言模型集成，并通过 MCP (Model Context Protocol) 实现工具调用功能。通过这个演示项目，开发者可以学习如何构建和部署一个具有文件系统工具能力的 AI 应用。

项目概述

本项目包含两个主要模块：

filesystem-mcp-service: 一个 MCP 服务，提供文件系统操作工具
sample-client: 一个示例客户端，通过 DeepSeek 模型调用 MCP 工具

项目通过 Spring AI 框架的 OpenAI 兼容接口连接 DeepSeek 模型，并利用 MCP 协议实现工具调用，让 AI 模型能够安全地读取和列出文件。

特性

🔄 通过 Spring AI 集成 DeepSeek 大语言模型
🛠️ 使用 MCP (Model Context Protocol) 实现工具调用
📁 提供文件系统操作工具（读取文件、列出目录）
🔒 安全的文件访问控制（仅允许访问配置的目录）
🔍 调试工具和状态查看功能

技术栈

Java 17
Spring Boot 3.4.5
Spring AI 1.0.0-M8
DeepSeek AI 模型
MCP 工具协议

项目结构

mcp-deepseek-demo/
├── filesystem-mcp-service/          # MCP 服务器模块
│   ├── src/
│   │   └── main/
│   │       ├── java/
│   │       │   └── com/mcp_deepseek_demo/
│   │       │       ├── service/
│   │       │       │   └── FileSystemService.java   # 文件系统核心服务
│   │       │       └── tools/
│   │       │           └── FileSystemTools.java     # 文件系统MCP工具
│   │       └── resources/
│   │           └── application.yml                  # MCP服务配置
│   └── pom.xml                                      # 模块依赖配置
│
├── sample-client/                   # 示例客户端模块
│   ├── src/
│   │   └── main/
│   │       ├── java/
│   │       │   └── com/mcp_deepseek_demo/
│   │       │       ├── config/
│   │       │       │   └── DeepSeekConfig.java      # DeepSeek配置
│   │       │       ├── controller/
│   │       │       │   ├── FileSystemController.java # 文件系统HTTP接口
│   │       │       │   └── DebugController.java      # 调试接口
│   │       │       ├── service/
│   │       │       │   └── FileSystemMcpService.java # MCP服务集成
│   │       │       └── SampleClient.java             # 示例客户端启动类
│   │       └── resources/
│   │           └── application.yml                   # 客户端配置
│   └── pom.xml                                       # 模块依赖配置
│
└── pom.xml                                           # 父项目POM

快速开始

前提条件

Java 17 或更高版本
Maven 3.6 或更高版本
DeepSeek API密钥

安装与配置

克隆本仓库:

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

配置 DeepSeek API 密钥: 在 sample-client/src/main/resources/application.yml 中设置你的 API 密钥:
```
spring:
  ai:
    openai:
      api-key: "你的DeepSeek API密钥"
```
配置允许访问的目录: 在 filesystem-mcp-service/src/main/resources/application.yml 中设置允许访问的目录:
```
app:
  allowed-directories: ./benchmark,/path/to/your/directory
```

运行

首先启动 MCP 服务:

cd filesystem-mcp-service
mvn spring-boot:run

在另一个终端窗口中启动示例客户端:
```
cd sample-client
mvn spring-boot:run
```
访问示例接口:
- 列出目录文件: http://localhost:8080/filesystem/list?directory=./benchmark
- 读取特定文件: http://localhost:8080/filesystem/read-file?filename=./benchmark/example.txt
- 查看MCP状态: http://localhost:8080/debug/mcp-status

架构说明

MCP 服务 (filesystem-mcp-service)

MCP 服务实现了文件系统操作工具，并通过 MCP 协议将这些工具暴露给客户端。主要组件：

FileSystemService: 提供文件读取和目录列表功能，并实现安全控制
FileSystemTools: 将文件操作包装为 MCP 工具
FileSystemMCPService: 配置和启动 MCP 服务

示例客户端 (sample-client)

客户端展示如何通过 Spring AI 和 DeepSeek 模型调用 MCP 工具。主要组件：

DeepSeekConfig: 配置 DeepSeek 模型和 MCP 工具集成
FileSystemController: 提供 HTTP 接口来访问文件系统
DebugController: 提供调试接口和 MCP 状态查看
FileSystemMcpService: 使用 ChatClient 和 MCP 工具调用文件操作

安全考虑

项目实现了文件访问安全控制，只允许访问配置中指定的目录。关键实现在 FileSystemService 的 isPathAllowed 方法中，确保所有文件操作都在安全允许的范围内。

扩展与自定义

添加新的 MCP 工具

在 filesystem-mcp-service 模块创建新的服务类
创建对应的工具类，使用 @Tool 注解标记工具方法
将工具类添加到 MCP 服务的工具提供者中

使用其他 AI 模型

本项目使用 DeepSeek 模型，但通过修改 DeepSeekConfig 和 application.yml，可以轻松切换到其他支持 OpenAI 兼容接口的模型。

许可证

本项目使用 MIT 许可证。

致谢

Spring AI 项目团队
DeepSeek 团队
MCP (Model Context Protocol) 社区

mcp-deepseek-demo