使用说明
Spring Boot AI MCP客户端
Java 21 | 弹簧靴3.4.2 | 春季AI | 码头工人 | MIT许可证
生产准备就绪 模型上下文协议（MCP）客户端 使用Spring Boot和Spring AI构建，实现AI模型和MCP服务器之间的无缝集成，以实现智能、上下文感知的操作。
目录
概述
这 MCP客户端 充当智能中介，将AI语言模型（通过Ollama）与MCP服务器连接起来，以执行上下文感知操作。它使人工智能模型能够通过标准化的协议与外部工具和服务进行交互，从而创建强大的人工智能驱动的工作流程。
目的
- Bridge AI模型和工具：将Ollama驱动的AI模型与MCP服务器功能连接起来
- 启用工具执行：允许AI模型以编程方式调用外部工具和服务
- 简化工作流程：通过自然语言命令自动化复杂操作
- 增强人工智能能力：将AI功能从文本生成扩展到可操作的操作
核心功能
AI集成
- Olama支持：与本地或远程Ollama实例直接集成
- 模型灵活性：支持多种型号（Mistral、Llama等）
- 可配置参数：微调温度、令牌限制和模型行为
- 实时通信：通过服务器发送事件（SSE）实现高效的流式响应
MCP协议
- 苏格兰和南方能源公司运输：与MCP服务器的低延迟、持久连接
- 工具发现：自动检测可用的MCP服务器工具
- 动态调用：基于AI决策的运行时工具执行
- 错误恢复：对连接失败和超时的巧妙处理
身份验证和安全
- 基于令牌的身份验证：使用MCP服务器进行安全的JWT身份验证
- API密钥管理：基于环境的凭证处理
- 滑动令牌刷新：连续会话的自动令牌续订
- 安全配置：通过环境变量将秘密外部化
生产准备就绪
- 虚拟线程：用于高并发的Java 21虚拟线程
- 健康监测：用于健康检查和诊断的执行器端点
- 结构化日志记录：全面的请求/响应跟踪
- Docker支持：使用Docker Compose实现完全容器化
建筑
系统架构
┌─────────────────────────────────────────────────────────────────┐
│ MCP Client Application │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────┐ │
│ │ │ │ │ │ │ │
│ │ User/API │────────▶│ Spring AI │────────▶│ Ollama │ │
│ │ Request │ │ Controller │ │ Model │ │
│ │ │ │ │ │ │ │
│ └──────────────┘ └──────┬───────┘ └──────────┘ │
│ │ │
│ │ │
│ ┌───────▼────────┐ │
│ │ │ │
│ │ MCP Client │ │
│ │ (SSE) │ │
│ │ │ │
│ └───────┬────────┘ │
│ │ │
└───────────────────────────────────┼─────────────────────────────┘
│
│ SSE Connection
│
┌───────────▼────────────┐
│ │
│ MCP Server │
│ (Port 8088) │
│ │
└───────────┬────────────┘
│
│
┌───────────▼────────────┐
│ │
│ GitHub API / Tools │
│ │
└────────────────────────┘
请求流
1. User Input
↓
2. Spring AI Controller receives request
↓
3. AI Model (Ollama) processes natural language
↓
4. Model determines if tool execution is needed
↓
5. MCP Client authenticates with MCP Server (JWT)
↓
6. MCP Client sends tool request via SSE
↓
7. MCP Server executes tool (e.g., GitHub API)
↓
8. Server returns results to MCP Client
↓
9. AI Model incorporates results into response
↓
10. Final response returned to user
组件交互
| 组件 | 责任 | 技术 |
|---|---|---|
| 用户界面 | 接收自然语言请求 | REST API |
| Spring AI控制器 | 协调AI和MCP交互 | Spring WebFlux |
| Ollama客户 | 与AI模型沟通 | Spring AI Ollama |
| MCP客户端 | 管理MCP服务器连接 | Spring AI MCP |
| MCP服务器 | 执行工具和操作 | 远程服务 |
| 认证层 | 保护MCP通信 | JWT令牌 |
快速开始
先决条件
- Java 21+
- Maven 3.9+
- 奥拉玛 （本地或远程运行）
- MCP服务器 （运行且可访问）
- Docker&Docker编写 （用于集装箱化部署）
本地开发
- 克隆仓库
git clone https://github.com/yourusername/spring_boot_ai_mcp_client.git
cd spring_boot_ai_mcp_client
- 配置环境
# Set required environment variables
export SPRING_AI_MCP_CLIENT_SSE_URL=http://localhost:8088/mcp/sse
export MCP_SERVER_AUTH_API_KEY=your-api-key
export SPRING_AI_OLLAMA_BASE_URL=http://localhost:11434
- 构建并运行
mvn clean install
mvn spring-boot:run
- 验证启动
curl http://localhost:8089/actuator/health
Docker部署
- 创建环境文件
cp .env.example .env
nano .env # Add your configuration
- 使用Docker Compose进行部署
docker-compose up -d --build
- 验证部署
docker-compose ps
curl http://localhost:8089/actuator/health
配置
环境变量
创建一个 .env 具有以下配置的文件：
# MCP Server Connection
SPRING_AI_MCP_CLIENT_SSE_URL=http://localhost:8088/mcp/sse
MCP_SERVER_AUTH_API_KEY=your-secure-api-key
MCP_SERVER_AUTH_TOKEN_ENDPOINT=http://localhost:8088/mcp/auth/token
# Ollama Configuration
SPRING_AI_OLLAMA_BASE_URL=http://localhost:11434
SPRING_AI_OLLAMA_CHAT_OPTIONS_MODEL=mistral
Docker网络配置
| 场景 | MCP服务器URL | Ollama URL |
|---|---|---|
| 本地开发 | http://localhost:8088 |
http://localhost:11434 |
| Docker中的客户端，主机上的服务 | http://host.docker.internal:8088 |
http://host.docker.internal:11434 |
| Docker中的所有服务 | http://mcp-server:8088 |
http://ollama:11434 |
健康检查
# Application health
curl http://localhost:8089/actuator/health
# Container status
docker-compose ps
# View detailed logs
docker-compose logs --tail=100 mcp-client
API终点
健康与监测
| 端点 | 方法 | 描述 |
|---|---|---|
/actuator/health |
GET | 应用程序运行状况 |
/actuator/info |
GET | 应用程序信息 |
/actuator/beans |
获取 | 春豆信息 |
请求示例
健康检查：
curl http://localhost:8089/actuator/health
答复：
{
"status": "UP"
}
用例
1.人工智能驱动的GitHub运营
脚本： 使用自然语言查询和管理GitHub拉取请求
例子：
User: "Show me all open pull requests in the java-must-read repository"
→ AI Model processes request
→ MCP Client calls GitHub tool via MCP Server
→ Results formatted and returned
2.自动化工作流执行
脚本： 基于AI分析执行多步操作
例子：
User: "Analyze the latest PRs and summarize common issues"
→ AI fetches PRs via MCP
→ AI analyzes content
→ AI generates summary report
3.智能数据检索
脚本： 通过自然语言查询外部系统
例子：
User: "What's the status of PRs from last week?"
→ AI interprets date range
→ MCP Client retrieves filtered data
→ AI presents formatted results
优势
面向开发者
简化集成：无手动API编码-AI处理工具选择
类型安全：强类型Spring Boot架构
快速发展：Spring AI抽象了复杂的集成
可测试性：用于监测的全面执行器端点
可扩展性：虚拟线程支持高并发性
用于操作
Docker就绪：使用Docker Compose进行一次命令部署
健康监测：内置执行器端点
配置管理：基于环境的设置
资源效率：轻量级JRE运行时映像
自动重启：故障自动恢复
适用于人工智能应用
工具增强：将人工智能功能扩展到文本生成之外
情境感知：AI可以访问实时外部数据
灵活执行：基于上下文的动态工具选择
错误处理：工具故障时性能下降
多型号支持：适用于多种Olama车型
技术栈
| 技术 | 版本 | 目的 |
|---|---|---|
| Java | 21 | 具有虚拟线程的运行时环境 |
| Spring Boot | 3.4.2 | 应用框架 |
| 春季AI | 2.0.0-M2 | AI模型集成 |
| 春季AI MCP | 2.0.0-M2 | MCP协议实现 |
| Spring WebFlux | 6.2.2 | 响应式web框架 |
| 奥拉玛 | - | 本地AI模型服务 |
| 梅文 | 3.9+ | 构建自动化 |
| 码头工人 | - | 集装箱化 |
故障排除
客户端无法启动
症状： 集装箱立即出口
解决方案：
# Check logs
docker-compose logs mcp-client
# Common issues:
# - Port 8089 already in use → Change port in docker-compose.yml
# - Java version mismatch → Verify Dockerfile uses Java 21
身份验证失败
症状： 401未经授权的错误
解决方案：
# Verify API key matches server
# In server .env:
MCP_SERVER_SHARED_API_KEY=secret-key
# In client .env:
MCP_SERVER_AUTH_API_KEY=secret-key # Must match!
许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
支持
- 问题: GitHub 问题
- 文档: 维基
- MCP协议: 模型上下文协议文档
- 春季AI: Spring AI文档
内置于️ 使用Spring Boot、Spring AI和Docker
