# Boulderai MCP Client

**Repository Path**: yanxxcloud/boulderai-mcp-client

## Basic Information

- **Project Name**: Boulderai MCP Client
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-01
- **Last Updated**: 2025-08-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MCP Client - Spring Boot + React

一个基于Spring Boot后端和React前端的Model Context Protocol (MCP) 客户端应用程序。

## 项目架构

### 后端 (Spring Boot)
- **技术栈**: Spring Boot 3.2.0, Java 17, WebSocket
- **主要功能**: 
  - REST API接口
  - WebSocket实时通信
  - MCP协议客户端封装
  - 跨域支持

### 前端 (React)
- **技术栈**: React 18, Axios, WebSocket
- **主要功能**:
  - 现代化用户界面
  - 实时连接状态显示
  - 工具和资源管理
  - 响应式设计

## 项目结构

```
boulderai-mcp-client/
├── src/main/java/com/boulderai/mcp/
│   ├── McpClientApplication.java          # Spring Boot主应用类
│   ├── controller/
│   │   └── McpController.java             # REST API控制器
│   ├── service/
│   │   └── McpService.java                # 业务逻辑服务层
│   ├── config/
│   │   └── WebSocketConfig.java           # WebSocket配置
│   ├── websocket/
│   │   └── McpWebSocketHandler.java       # WebSocket处理器
│   ├── client/                            # MCP客户端接口和实现
│   └── model/                             # 数据模型
├── src/main/resources/
│   ├── application.properties             # Spring Boot配置
│   └── static/                            # 静态资源(React构建输出)
├── frontend/
│   ├── src/
│   │   ├── App.js                         # React主组件
│   │   ├── App.css                        # 应用样式
│   │   ├── index.js                       # React入口文件
│   │   └── index.css                      # 全局样式
│   ├── public/
│   │   └── index.html                     # HTML模板
│   └── package.json                       # React依赖配置
├── pom.xml                                # Maven项目配置
└── start-application.sh                   # 启动脚本
```

## 环境要求

- **Java**: 17 或更高版本
- **Maven**: 3.6 或更高版本
- **Node.js**: 18 或更高版本 (用于前端构建)
- **npm**: 9 或更高版本

## 快速开始

### 1. 启动应用

```bash
# 使用启动脚本(推荐)
./start-application.sh

# 或者使用Maven命令
mvn spring-boot:run
```

### 2. 访问应用

- **Web界面**: http://localhost:8080
- **API接口**: http://localhost:8080/api/mcp
- **WebSocket**: ws://localhost:8080/ws/mcp
- **健康检查**: http://localhost:8080/actuator/health

## API接口

### REST API

| 方法 | 路径 | 描述 |
|------|------|------|
| POST | `/api/mcp/connect` | 连接到MCP服务器 |
| POST | `/api/mcp/disconnect` | 断开连接 |
| GET | `/api/mcp/status` | 获取连接状态 |
| POST | `/api/mcp/initialize` | 初始化会话 |
| GET | `/api/mcp/tools` | 获取工具列表 |
| POST | `/api/mcp/tools/{toolName}/call` | 调用工具 |
| GET | `/api/mcp/resources` | 获取资源列表 |
| GET | `/api/mcp/resources/{resourceUri}` | 读取资源 |
| POST | `/api/mcp/request` | 发送自定义请求 |

### WebSocket消息

支持以下消息类型:
- `connect` - 连接服务器
- `disconnect` - 断开连接
- `list_tools` - 获取工具列表
- `call_tool` - 调用工具
- `list_resources` - 获取资源列表
- `read_resource` - 读取资源

## 开发指南

### 后端开发

1. **添加新的API接口**:
   - 在 `McpController` 中添加新的端点
   - 在 `McpService` 中实现业务逻辑

2. **扩展WebSocket功能**:
   - 修改 `McpWebSocketHandler` 添加新的消息类型处理

3. **配置修改**:
   - 编辑 `application.properties` 调整应用配置

### 前端开发

1. **开发模式运行**:
   ```bash
   cd frontend
   npm start
   ```

2. **构建生产版本**:
   ```bash
   cd frontend
   npm run build
   ```

3. **添加新功能**:
   - 修改 `App.js` 添加新的UI组件
   - 更新 `App.css` 添加样式

## 部署

### 生产环境部署

1. **构建应用**:
   ```bash
   mvn clean package
   ```

2. **运行JAR文件**:
   ```bash
   java -jar target/mcp-client-1.0.0.jar
   ```

### Docker部署

```dockerfile
FROM openjdk:17-jdk-slim
COPY target/mcp-client-1.0.0.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "/app.jar"]
```

## 配置说明

### application.properties主要配置

```properties
# 服务器端口
server.port=8080

# 日志级别
logging.level.com.boulderai.mcp=DEBUG

# CORS配置
spring.web.cors.allowed-origins=*

# WebSocket配置
spring.websocket.sockjs.enabled=true
```

## 故障排除

### 常见问题

1. **端口占用**:
   ```bash
   # 查看端口占用
   lsof -i :8080
   # 修改application.properties中的server.port
   ```

2. **Java版本问题**:
   ```bash
   # 检查Java版本
   java -version
   # 需要Java 17或更高版本
   ```

3. **前端构建失败**:
   ```bash
   # 清理并重新安装依赖
   cd frontend
   rm -rf node_modules package-lock.json
   npm install
   ```

## 贡献指南

1. Fork项目
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开Pull Request

## 许可证

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

## 更新日志

### v1.0.0
- ✅ 完成从Python到Spring Boot + React的重构
- ✅ 实现REST API接口
- ✅ 添加WebSocket实时通信
- ✅ 创建现代化React前端界面
- ✅ 集成Maven构建系统
- ✅ 添加开发和生产环境配置