mcp-deepseek-demo

Spring AI + DeepSeek + MCP 集成演示

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

项目概述

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

1. filesystem-mcp-service: 一个 MCP 服务，提供文件系统操作工具
2. 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密钥

安装与配置

1. 克隆本仓库:

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

2. 配置 DeepSeek API 密钥:
   在 sample-client/src/main/resources/application.yml 中设置你的 API 密钥:

   spring:
     ai:
       openai:
         api-key: "你的DeepSeek API密钥"
   

3. 配置允许访问的目录:
   在 filesystem-mcp-service/src/main/resources/application.yml 中设置允许访问的目录:

   app:
     allowed-directories: ./benchmark,/path/to/your/directory
   

运行

1. 首先启动 MCP 服务:

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

2. 在另一个终端窗口中启动示例客户端:

   cd sample-client
   mvn spring-boot:run
   

3. 访问示例接口:

   • 列出目录文件: 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 工具

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

使用其他 AI 模型

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

许可证

本项目使用 MIT 许可证。

致谢

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