# mcp4java

**Repository Path**: jhliu20/mcp4java

## Basic Information

- **Project Name**: mcp4java
- **Description**: mcp4java - 基于Spring AI的MCP协议聊天demo
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-03
- **Last Updated**: 2026-02-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# mcp4java - 基于Spring AI的MCP协议聊天演示

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.x-green.svg)](https://spring.io/projects/spring-boot)
[![Spring AI](https://img.shields.io/badge/Spring%20AI-alpha-orange.svg)](https://github.com/spring-projects/spring-ai)

一个基于Spring AI和MCP(Model Context Protocol)协议的智能聊天演示项目，支持动态工具调用和流式对话。

## 🌟 特性

- 🤖 **智能对话**: 集成主流AI大模型(DeepSeek、Qwen等)
- 🔧 **MCP协议支持**: 动态加载和调用MCP服务器提供的工具
- 💬 **流式交互**: 支持SSE流式响应，实时显示AI回复
- 🎯 **工具选择**: 可动态选择启用的MCP服务器和工具
- 📱 **响应式界面**: 现代化的Web聊天界面
- 🔄 **会话管理**: 支持多轮对话和会话状态管理

## 🏗️ 技术栈

- **后端**: Spring Boot 3.x, Spring AI
- **前端**: HTML5, CSS3, Vanilla JavaScript
- **协议**: MCP (Model Context Protocol)
- **AI模型**: DeepSeek, Qwen, OpenAI兼容模型
- **构建工具**: Maven

## 🚀 快速开始

### 环境要求

- Java 17+
- Maven 3.6+
- 网络访问权限(用于调用AI API)

### 1. 克隆项目

```bash
git clone <your-repo-url>
cd mcp4java
```

### 2. 配置AI密钥

修改 `src/main/resources/application.yml`:

```yaml
spring:
  ai:
    openai:
      base-url: https://api.deepseek.com  # 或其他兼容的API地址
      api-key: your-api-key-here          # 替换为你的API密钥
```

### 3. 配置MCP服务器

编辑 `src/main/java/org/example/mcp4java/mcp.txt`:

```json
{
  "mcpServers": {
    "bing-cn-mcp-server": {
      "type": "streamable_http",
      "url": "https://mcp.api-inference.modelscope.net/139365090fee44/mcp",
      "headers": {
        "Authorization": "Bearer your-token-here"
      }
    }
  }
}
```

### 4. 构建和运行

```bash
# 清理并编译
mvn clean compile

# 运行项目
mvn spring-boot:run
```

或者使用jar包方式运行:

```bash
# 打包
mvn clean package

# 运行
java -jar target/mcp4java-0.0.1-SNAPSHOT.jar
```

### 5. 访问应用

打开浏览器访问: http://localhost:8080/index.html

## 📖 使用指南

### 基本使用流程

1. **创建会话**: 页面加载时自动创建聊天会话
2. **选择MCP服务器**: 在左侧边栏选择要使用的MCP服务器
3. **选择工具**: 选择该服务器下需要启用的具体工具
4. **开始对话**: 在输入框中输入问题，点击发送或按回车键

### 使用示例

#### 示例1: 查询天气信息
```
用户: 上海今天的天气怎么样？
AI: (调用天气工具) 上海今天晴转多云，气温15-22℃...
```

#### 示例2: 查询时间
```
用户: 现在北京时间是几点？
AI: (调用时间工具) 北京时间现在是 2024年X月X日 XX:XX:XX
```

#### 示例3: 多轮对话
```
用户: 你好！
AI: 你好！我是AI助手，有什么可以帮助你的吗？

用户: 我想了解一下上海的情况
AI: 上海是中国的经济中心，位于长江三角洲...

用户: 那里的天气如何？
AI: (基于上下文调用天气工具) 上海目前天气状况是...
```

## 🔧 配置说明

### application.yml 配置项

```yaml
spring:
  ai:
    openai:
      base-url: https://api.deepseek.com    # AI API基础URL
      api-key: sk-your-api-key             # API密钥
server:
  port: 8080                               # 服务端口
```

### 支持的AI模型提供商

| 提供商 | base-url | 备注 |
|--------|----------|------|
| DeepSeek | https://api.deepseek.com | 默认配置 |
| 阿里云百炼 | https://dashscope.aliyuncs.com/compatible-mode | 需要相应API密钥 |
| OpenAI | https://api.openai.com | 需要OpenAI API密钥 |

## 🛠️ 开发指南

### 项目结构

```
src/main/java/org/example/mcp4java/
├── controller/           # REST控制器
│   └── ChatController.java
├── model/               # 数据模型
│   ├── ChatRequest.java
│   ├── ChatResponse.java
│   └── ...
├── service/             # 业务服务
│   ├── ChatService.java
│   ├── McpConfigLoader.java
│   └── ...
├── transport/           # MCP传输层
│   └── CustomHeaderHttpTransport.java
└── runner/             # 命令行测试工具
    └── ...
```

### API接口

#### 会话管理
- `POST /api/chat/session` - 创建新会话
- `GET /api/chat/session/{sessionId}` - 获取会话信息
- `DELETE /api/chat/session/{sessionId}` - 删除会话

#### MCP相关
- `GET /api/chat/mcp-servers` - 获取MCP服务器列表
- `GET /api/chat/tools/{serverName}` - 获取指定服务器的工具列表

#### 聊天接口
- `POST /api/chat/stream` - 流式聊天(SSE)

### 自定义MCP服务器

在 `mcp.txt` 中添加新的MCP服务器配置:

```json
{
  "mcpServers": {
    "your-server-name": {
      "type": "streamable_http",  // 或 "sse"
      "url": "https://your-mcp-server.com/mcp",
      "headers": {
        "Authorization": "Bearer your-token",
        "Custom-Header": "value"
      }
    }
  }
}
```

## 🧪 测试

项目包含多个测试运行器:

```bash
# 运行特定的测试类
mvn spring-boot:run -Dspring-boot.run.arguments="--spring.profiles.active=test"

# 或者取消注释相应的@Component注解来运行
```

## 📊 架构设计

### 核心组件

1. **ChatController**: 处理HTTP请求和响应
2. **ChatService**: 核心聊天业务逻辑
3. **McpConfigLoader**: 加载和解析MCP配置
4. **ChatSessionManager**: 管理会话状态
5. **CustomHeaderHttpTransport**: MCP协议传输层封装

### 数据流向

```
用户请求 → ChatController → ChatService → MCP客户端 → AI模型 → 流式响应 → 前端展示
```

## 🤝 贡献指南

欢迎提交Issue和Pull Request！

### 开发规范

1. 遵循现有代码风格
2. 添加必要的单元测试
3. 更新相关文档
4. 提交前运行 `mvn clean test`

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情

## 🙏 致谢

- [Spring AI](https://github.com/spring-projects/spring-ai) - AI集成框架
- [MCP](https://modelcontextprotocol.io/) - Model Context Protocol
- [DeepSeek](https://www.deepseek.com/) - AI模型提供商

## 📞 联系方式

如有问题或建议，请通过以下方式联系:

- 提交 [GitHub Issue](https://github.com/yourusername/mcp4java/issues)
- 邮箱: 782593062@qq.com

---
⭐ 如果你觉得这个项目有用，请给个Star支持一下！