# spring-mcp-server

**Repository Path**: wugu/spring-mcp-server

## Basic Information

- **Project Name**: spring-mcp-server
- **Description**: No description available
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 3
- **Created**: 2025-05-09
- **Last Updated**: 2025-05-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 项目简介
在本项目中，我们基于 Spring Boot 构建并通过 Docker 部署了 MCP 服务端与 MCP 客户端，通过 HTTP 协议 实现与现有系统的远程控制与集成。整个系统作为独立模块运行，服务端直接连接数据库，核心业务逻辑抽象于 tool 层中，具备良好的扩展性与解耦性。

为提升系统的实时交互能力，项目支持通过 Cherry Studio 使用 SSE（Server-Sent Events） 与 MCP 服务端保持长连接，实现消息的实时推送与指令响应。

此外，还新增了对 WebSocket 通信 的支持。相比于 HTTP 和 SSE，WebSocket 是一种 全双工、低延迟、连接持久 的通信协议，特别适用于高频次、强交互的控制场景。通过 WebSocket，客户端不仅可以实时获取状态更新，还可主动发送控制指令并立即获取响应，进一步增强了系统的交互性和用户体验。

# MCP 简介
MCP 是一种开放协议，用于标准化应用程序如何向 LLM 提供上下文。可以将 MCP 视为 AI 应用程序的 USB-C 端口。就像 USB-C 提供了一种将设备连接到各种外围设备和配件的标准化方式一样，MCP 提供了一种将 AI 模型连接到不同数据源和工具的标准化方式。

![img_8.png](img/img_8.png)

- MCP 主机 (MCP Hosts)：例如 Claude Desktop、IDE 或希望通过 MCP 访问数据的 AI 工具等程序
- MCP 客户端 (MCP Clients)：与服务器保持 1:1 连接的协议客户端
- MCP 服务器 (MCP Servers)：轻量级程序，每个程序通过标准化的模型上下文协议 (MCP) 公开特定的功能
- 本地数据源 (Local Data Sources)：您的计算机的文件、数据库和 MCP 服务器可以安全访问的服务
- 远程服务 (Remote Services)：可通过互联网访问的外部系统（例如，通过 API），MCP 服务器可以连接到这些系统

# 环境要求

- Java 环境 >= JDK17
- Spring Boot >= 3.x

![img_8_1.png](img/img_8_1.png)

# 源代码
> **注：** Java 环境必须 >= **JDK17**，否则项目编译不过。

![img_7.png](img/img_7.png)

# DeepSeek API
- 申请 API_KEY：https://platform.deepseek.com/usage

![img_13.png](img/img_13.png)

# 腾讯云版 DeepSeek API（免费额度1000000token）
- [https://cloud.tencent.com/document/product/1772/115969](https://cloud.tencent.com/document/product/1772/115969)
- [https://console.cloud.tencent.com/lkeap/api](https://console.cloud.tencent.com/lkeap/api)

![img_14.png](img/img_14.png)

# Docker

- 打包 jar 包并复制到 docker/app/ 对应目录中
- start.sh 脚本按顺序先启动 **mcp-server** 再启动 **mcp-client-ws**

![img_9.png](img/img_9.png)

- 配置 API_KEY 与 DeepSeek 模型
```bash
cd docker/app/mcp-client 或 mcp-client-ws
vim application-prod.yml
```
```yml
spring:
  ai:
    openai:
      api-key: sk-xxxxx
      base-url: https://api.deepseek.com
      chat:
        options:
          model: deepseek-chat
```

- 腾讯云版 DeepSeek API 配置
```yml
spring:
  ai:
    openai:
      api-key: sk-xxxxx
      base-url: https://api.lkeap.cloud.tencent.com/v1
      chat:
        options:
          model: deepseek-v3 # 或deepseek-v3-0324、deepseek-r1
    mcp:
      client:
        type: sync
        name: spring-mcp-client-ws
        sse:
          connections:
            server1:
              url: http://localhost:9800
```

```bash
cd docker
docker-compose up -d mcp-server
docker logs -f mcp-server
```

## sse 连接

```bash
http://127.0.0.1:9800/sse
```

## ws 连接（推荐）
```bash
ws://127.0.0.1:9802/mcp/ws
```

- js 测试脚本
```bash
cd node-ws-client
npm install
node client.js
```

![img_10.png](img/img_10.png)

- Nginx 配置 ws:// 或 wss://
```bash
location /mcp/ {
    proxy_pass http://192.168.0.160:9802/mcp/;

    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";

    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}
```

## http 连接

```bash
http://127.0.0.1:9801/mcp/mcpClient/listTools
```
![img_5.png](img/img_5.png)

```bash
http://127.0.0.1:9801/mcp/mcpClient/chat?prompt=查询章若楠用户信息
```
![img_6.png](img/img_6.png)

# vue2-chat-window
- 聊天窗口通过 ws:// 连接 mcp-client-ws 服务

![img_12.png](img/img_12.png)

```bash
cd vue2-chat-window
npm install
npm run serve
```

![img_11.png](img/img_11.png)

# Cherry Studio

- 下载地址：https://cherry-ai.com/

## 配置模型

![img.png](img/img.png)

![img_1.png](img/img_1.png)

## 配置 MCP
![img_2.png](img/img_2.png)

![img_2_1.png](img/img_2_1.png)

## 调用 MCP
![img_3.png](img/img_3.png)

![img_4.png](img/img_4.png)