deploy.stack/mcp_server_go/README.md

# 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功能和监控