# THQMcpServe

**Repository Path**: TouHouQing/thqmcp-serve

## Basic Information

- **Project Name**: THQMcpServe
- **Description**: No description available
- **Primary Language**: Java
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-06-13
- **Last Updated**: 2025-06-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# THQMCP Server

基于Spring Boot和Spring AI的MCP (Model Context Protocol) 服务器

## 项目简介

本项目是一个实现了MCP (Model Context Protocol) 协议的服务器，使用Java语言开发，基于以下技术栈：

- **Spring Boot** - 应用框架
- **Spring AI** - AI集成框架
- **Spring MVC** - Web框架
- **WebSocket** - 实时通信支持
- **Maven** - 项目构建工具

## 功能特性

- ✅ 完整的MCP协议支持
- ✅ RESTful API接口
- ✅ WebSocket实时通信
- ✅ 工具调用机制
- ✅ Spring AI集成
- ✅ 可扩展的架构设计

## 快速开始

### 环境要求

- Java 17+
- Maven 3.6+
- 可选：OpenAI API密钥（用于AI功能）

### 安装步骤

1. **克隆项目**
   ```bash
   git clone <repository-url>
   cd thqmcp-serve
   ```

2. **配置环境变量**
   ```bash
   export OPENAI_API_KEY=your-openai-api-key
   export OPENAI_BASE_URL=https://api.openai.com
   ```

3. **编译项目**
   ```bash
   mvn clean compile
   ```

4. **运行测试**
   ```bash
   mvn test
   ```

5. **启动服务器**
   ```bash
   mvn spring-boot:run
   ```

服务器将在 `http://localhost:8080` 启动。

## API接口

### HTTP接口

- `GET /mcp/info` - 获取服务器信息
- `GET /mcp/tools` - 获取可用工具列表
- `POST /mcp/tools/call` - 调用指定工具
- `POST /mcp/message` - 处理MCP消息

### WebSocket接口

- `ws://localhost:8080/mcp/ws` - WebSocket连接端点

### 示例请求

获取服务器信息：
```bash
curl http://localhost:8080/mcp/info
```

获取工具列表：
```bash
curl http://localhost:8080/mcp/tools
```

调用工具：
```bash
curl -X POST http://localhost:8080/mcp/tools/call \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "calculator",
    "params": {"expression": "2+2"},
    "id": "1"
  }'
```

## 项目结构

```
src/
├── main/
│   ├── java/com/thqmcp/server/
│   │   ├── ThqmcpServerApplication.java    # 主启动类
│   │   ├── controller/
│   │   │   └── McpController.java          # MCP控制器
│   │   ├── service/
│   │   │   ├── McpService.java             # MCP服务接口
│   │   │   └── impl/
│   │   │       └── McpServiceImpl.java     # MCP服务实现
│   │   ├── model/
│   │   │   ├── McpMessage.java             # MCP消息模型
│   │   │   ├── McpError.java               # MCP错误模型
│   │   │   └── McpTool.java                # MCP工具模型
│   │   ├── config/
│   │   │   └── WebSocketConfig.java        # WebSocket配置
│   │   └── websocket/
│   │       └── McpWebSocketHandler.java    # WebSocket处理器
│   └── resources/
│       └── application.yml                 # 应用配置
└── test/
    └── java/com/thqmcp/server/
        └── ThqmcpServerApplicationTests.java # 测试类
```

## 配置说明

主要配置项在 `src/main/resources/application.yml` 中：

```yaml
server:
  port: 8080                    # 服务器端口

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}  # OpenAI API密钥
      base-url: ${OPENAI_BASE_URL} # OpenAI API地址

app:
  mcp:
    server:
      name: "THQMCP Server"       # 服务器名称
      version: "1.0.0"            # 版本号
```

## 开发指南

### 添加新工具

1. 在 `McpServiceImpl.getAvailableTools()` 中注册新工具
2. 在 `McpServiceImpl.callTool()` 中添加工具处理逻辑
3. 实现具体的工具功能方法

### 扩展功能

- 添加新的MCP协议方法
- 集成更多AI模型
- 实现资源和提示功能
- 添加认证和权限控制

## 监控和运维

- 健康检查：`http://localhost:8080/actuator/health`
- 应用信息：`http://localhost:8080/actuator/info`
- 指标监控：`http://localhost:8080/actuator/metrics`

## 常见问题

### Q: 如何更换AI模型？
A: 修改 `application.yml` 中的 `spring.ai.openai.chat.options.model` 配置。

### Q: 如何部署到生产环境？
A: 
1. 构建JAR包：`mvn clean package`
2. 运行：`java -jar target/thqmcp-serve-1.0.0.jar`
3. 配置环境变量和外部配置文件

### Q: 如何开启HTTPS？
A: 在 `application.yml` 中配置SSL证书：
```yaml
server:
  ssl:
    key-store: classpath:keystore.p12
    key-store-password: password
    key-store-type: PKCS12
```

## 许可证

本项目基于 [许可证名称] 开源许可证。

## 贡献

欢迎提交Issue和Pull Request！

## 联系方式

如有问题，请联系：[联系信息]