forked from DevOps/deploy.stack
297 lines
7.1 KiB
Markdown
297 lines
7.1 KiB
Markdown
# MCP Server Go
|
||
|
||
一个使用Golang实现的MCP（Master Control Program）服务器，能够对接开放的AI API（如OpenAI），提供数据分析和处理功能。
|
||
|
||
## 项目特点
|
||
|
||
- 基于Golang开发，高性能、低资源占用
|
||
- 使用slog标准库进行日志管理，支持多级别、多格式日志输出
|
||
- 使用TOML格式配置文件，配置简单明了
|
||
- 支持对接OpenAI API，可扩展支持其他AI服务
|
||
- 提供健康检查、Prometheus监控指标
|
||
- 实现CORS跨域支持、请求速率限制、请求日志等中间件
|
||
- 支持配置文件热重载
|
||
- 优雅关闭机制
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
mcp_server_go/
|
||
├── main.go # 主程序文件
|
||
├── config.toml # 配置文件
|
||
├── README.md # 项目说明文档
|
||
├── go.mod # Go模块定义
|
||
├── go.sum # 依赖版本锁定
|
||
└── logs/ # 日志文件目录
|
||
└── mcp_server.log # 日志文件
|
||
```
|
||
|
||
## 配置说明
|
||
|
||
配置文件`config.toml`包含以下主要配置项：
|
||
|
||
```toml
|
||
# 服务器基本配置
|
||
[server]
|
||
listen_addr = "0.0.0.0:8080" # 监听地址和端口
|
||
read_timeout = 30 # 读取超时时间(秒)
|
||
write_timeout = 30 # 写入超时时间(秒)
|
||
max_header_bytes = 1048576 # 最大请求头大小(字节)
|
||
|
||
# OpenAI API 配置
|
||
[openai]
|
||
api_key = "your_api_key_here" # OpenAI API密钥
|
||
base_url = "https://api.openai.com/v1" # API基础URL
|
||
model = "gpt-3.5-turbo" # 使用的模型
|
||
temperature = 0.7 # 生成内容的随机性
|
||
max_tokens = 1000 # 最大生成token数
|
||
request_timeout = 60 # 请求超时时间(秒)
|
||
|
||
# 日志配置
|
||
[logging]
|
||
level = "info" # 日志级别: debug, info, warn, error
|
||
format = "text" # 日志格式: text, json
|
||
output_path = "logs/mcp_server.log" # 日志文件路径
|
||
max_size = 100 # 单个日志文件最大大小(MB)
|
||
max_age = 7 # 日志保留天数
|
||
max_backups = 5 # 最大备份文件数
|
||
compress = false # 是否压缩归档日志
|
||
|
||
# 安全配置
|
||
[security]
|
||
allowed_origins = ["*"] # 允许的源
|
||
allowed_methods = ["GET", "POST", "OPTIONS"] # 允许的HTTP方法
|
||
allowed_headers = ["Content-Type", "Authorization"] # 允许的HTTP头
|
||
```
|
||
|
||
## 安装与依赖
|
||
|
||
### 前提条件
|
||
|
||
- Go 1.21或更高版本
|
||
- 有效的OpenAI API密钥（或其他兼容的AI服务API密钥）
|
||
|
||
### 安装依赖
|
||
|
||
```bash
|
||
# 初始化Go模块（如果尚未初始化）
|
||
go mod init mcp_server_go
|
||
|
||
# 安装依赖包
|
||
go get github.com/sashabaranov/go-openai
|
||
go get github.com/spf13/viper
|
||
go get github.com/fsnotify/fsnotify
|
||
go get github.com/prometheus/client_golang/prometheus
|
||
go get github.com/prometheus/client_golang/prometheus/promhttp
|
||
go get github.com/google/uuid
|
||
go get golang.org/x/time/rate
|
||
|
||
# 生成go.sum文件
|
||
go mod tidy
|
||
```
|
||
|
||
## 运行方法
|
||
|
||
### 直接运行
|
||
|
||
```bash
|
||
# 确保配置文件正确设置
|
||
# 启动服务器
|
||
go run main.go
|
||
```
|
||
|
||
### 编译后运行
|
||
|
||
```bash
|
||
# 编译项目
|
||
go build -o mcp_server
|
||
sudo chmod +x mcp_server
|
||
|
||
# 运行编译后的二进制文件
|
||
./mcp_server
|
||
```
|
||
|
||
### 作为系统服务运行
|
||
|
||
可以创建一个systemd服务文件来管理MCP服务器：
|
||
|
||
```bash
|
||
sudo nano /etc/systemd/system/mcp_server.service
|
||
```
|
||
|
||
添加以下内容（根据实际路径修改）：
|
||
|
||
```ini
|
||
[Unit]
|
||
Description=MCP Server Go
|
||
After=network.target
|
||
|
||
[Service]
|
||
Type=simple
|
||
User=your_user
|
||
WorkingDirectory=/home/geng/mydate/deploy.stack/mcp_server_go
|
||
ExecStart=/home/geng/mydate/deploy.stack/mcp_server_go/mcp_server
|
||
Restart=on-failure
|
||
RestartSec=5s
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target
|
||
```
|
||
|
||
然后启用并启动服务：
|
||
|
||
```bash
|
||
sudo systemctl daemon-reload
|
||
sudo systemctl enable mcp_server
|
||
sudo systemctl start mcp_server
|
||
```
|
||
|
||
## API接口文档
|
||
|
||
### 健康检查接口
|
||
|
||
**GET /health**
|
||
|
||
检查服务器和OpenAI连接状态
|
||
|
||
**响应示例**：
|
||
|
||
```json
|
||
{
|
||
"status": "ok",
|
||
"version": "1.0.0",
|
||
"timestamp": 1634567890,
|
||
"openai_health": true
|
||
}
|
||
```
|
||
|
||
### MCP数据提交接口
|
||
|
||
**POST /mcp/v1/submit**
|
||
|
||
提交数据到MCP服务器进行处理和AI分析
|
||
|
||
**请求体示例**：
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"disk_id": "sda",
|
||
"smart_data": {
|
||
"temperature": 38,
|
||
"power_on_hours": 12345,
|
||
"read_errors": 0,
|
||
"write_errors": 0
|
||
},
|
||
"performance_data": {
|
||
"read_speed": 120,
|
||
"write_speed": 90
|
||
}
|
||
},
|
||
"type": "disk_inspection",
|
||
"metadata": {
|
||
"server_id": "server-001",
|
||
"location": "data_center_a"
|
||
},
|
||
"timestamp": 1634567890
|
||
}
|
||
```
|
||
|
||
**响应示例**：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "数据提交成功",
|
||
"data": {"disk_id": "sda", ...}, // 原始提交的数据
|
||
"ai_result": {
|
||
"analysis": "硬盘状态良好，温度正常，无错误记录。",
|
||
"recommendations": "建议定期进行数据备份，继续监控硬盘健康状态。",
|
||
"health_score": 98
|
||
},
|
||
"request_id": "req-1634567890-ab12cd34",
|
||
"timestamp": 1634567891
|
||
}
|
||
```
|
||
|
||
### Prometheus监控指标
|
||
|
||
**GET /metrics**
|
||
|
||
提供Prometheus格式的监控指标
|
||
|
||
## 日志说明
|
||
|
||
日志配置在`[logging]`部分，支持以下特性：
|
||
|
||
- 可配置日志级别（debug、info、warn、error）
|
||
- 支持文本和JSON两种日志格式
|
||
- 日志文件自动轮转（基于大小和时间）
|
||
- 同时输出到控制台和文件
|
||
|
||
## 安全配置
|
||
|
||
- 配置CORS策略，限制允许的源、方法和头部
|
||
- 实现请求速率限制，防止滥用
|
||
- 支持配置文件中的安全设置热重载
|
||
|
||
## 与disk_inspection.py的对接
|
||
|
||
MCP服务器可以直接接收`disk_inspection.py`脚本发送的数据：
|
||
|
||
1. 确保`disk_inspection.py`中的`submit_to_mcp`方法配置正确的MCP服务器地址（http://localhost:8080/mcp/v1/submit）
|
||
2. 确保`disk_inspection.py`安装了requests依赖：`pip install requests`
|
||
3. 运行MCP服务器和disk_inspection.py脚本
|
||
|
||
## 故障排除
|
||
|
||
### 常见问题
|
||
|
||
1. **OpenAI API调用失败**
|
||
- 检查API密钥是否正确配置
|
||
- 确认网络连接正常，特别是可以访问OpenAI API
|
||
- 查看日志文件获取详细错误信息
|
||
|
||
2. **配置文件不生效**
|
||
- 确认配置文件路径正确
|
||
- 检查配置项格式是否符合TOML规范
|
||
|
||
3. **端口被占用**
|
||
- 修改`config.toml`中的`listen_addr`配置，使用其他可用端口
|
||
|
||
4. **请求速率限制**
|
||
- 如果遇到"请求过于频繁"的错误，可以调整代码中的速率限制参数
|
||
|
||
### 日志分析
|
||
|
||
日志文件默认位于`logs/mcp_server.log`，包含详细的请求处理信息、错误信息和OpenAI API调用情况。可以使用以下命令查看日志：
|
||
|
||
```bash
|
||
# 实时查看日志
|
||
tail -f logs/mcp_server.log
|
||
|
||
# 搜索错误信息
|
||
grep -i error logs/mcp_server.log
|
||
```
|
||
|
||
## 开发与扩展
|
||
|
||
### 添加新的AI服务支持
|
||
|
||
可以扩展代码以支持其他AI服务提供商，只需实现相应的客户端初始化和请求处理逻辑。
|
||
|
||
### 自定义数据处理逻辑
|
||
|
||
可以修改`analyzeWithOpenAI`函数，根据不同的数据类型和需求定制AI分析的提示词和处理逻辑。
|
||
|
||
### 添加新的API端点
|
||
|
||
可以在`main.go`中添加新的HTTP处理函数并注册到路由器，扩展服务器功能。
|
||
|
||
## 许可证
|
||
|
||
MIT License
|
||
|
||
## 版本历史
|
||
|
||
- v1.0.0: 初始版本，支持OpenAI API对接、基本的MCP功能和监控 |