Metadata-Version: 2.4
Name: mcp-server-spectrum-stravision
Version: 2.0.11
Summary: Enhanced Spectrum MCP Server for Stravision IoT Platform with real-time MQTT data acquisition and historical data tracking
Requires-Python: >=3.8
Requires-Dist: mcp[cli]>=1.26.0
Requires-Dist: paho-mqtt>=1.6.1
Description-Content-Type: text/markdown

# Spectrum MCP Server

这个项目将来自 ESP32 上 AS7341 光谱传感器的数据通过 MQTT 发布，并在本地运行一个 FastMCP 服务器将最新光谱封装为 MCP 资源与工具接口，方便其它程序/服务调用。

## 🚀 版本 2.0.4 新特性

- ✨ 增强的数据返回格式，包含状态码和完整元数据
- 📊 扩展历史数据容量到 100 条记录
- 🔍 新增服务器状态监控工具 `get_server_status`
- 📡 实时 MQTT 连接状态追踪
- ⏱️ 数据时效性追踪（data_age_seconds）
- 🛡️ 改进的错误处理和详细日志
- 🔧 支持自定义历史数据查询数量

## 目录结构

- `server.py` — 本地 FastMCP 服务，订阅 MQTT 主题并暴露 MCP 接口
- `1panel-config.json` — 1Panel MCP 配置文件
- `DEPLOYMENT.md` — 详细的部署指南
- `build-and-deploy.ps1` — 自动化构建和部署脚本
- `test-server.ps1` — 服务器测试脚本
- `esp32/main.txt` — ESP32 上的 MicroPython 主程序
- `esp32/as7341.txt` — AS7341 驱动（MicroPython）

注意：ESP32 代码以 `.txt` 附件形式保存在仓库以便在 PC 上编辑；部署到设备时应保存为 `main.py` 和 `as7341.py`。

## 快速开始

### 方法一：使用 uvx（推荐）

```bash
# 直接运行（uvx 会自动下载和安装）
uvx mcp-server-spectrum-stravision
```

### 方法二：从源码安装

1. 克隆或下载项目

2. 安装依赖：
```bash
pip install -e .
```

3. 运行服务器：
```bash
python server.py
```

### 方法三：使用构建脚本

```powershell
# Windows PowerShell
.\build-and-deploy.ps1
```

## MCP 接口

### 工具（Tools）

#### 1. get_all_spectrum()
获取完整的光谱数据，包含所有通道值和元数据。

返回示例：
```json
{
  "status": "ok",
  "channels": {
    "channel1": 1234,
    "channel2": 2345,
    ...
  },
  "channel_count": 18,
  "last_update": "2024-01-15 10:30:45",
  "mqtt_connected": true,
  "data_age_seconds": 2
}
```

#### 2. get_channel(name: str)
获取指定通道的光谱值。

参数：
- `name`: 通道名称（如 'channel1', 'channel2' 等）

返回示例：
```json
{
  "status": "ok",
  "channel": "channel1",
  "value": 1234,
  "last_update": "2024-01-15 10:30:45"
}
```

#### 3. get_spectrum_history(limit: int = 10)
获取历史光谱数据记录。

参数：
- `limit`: 返回的记录数量（默认 10，最大 100）

返回示例：
```json
{
  "status": "ok",
  "count": 10,
  "requested_limit": 10,
  "history": [
    {
      "timestamp": "2024-01-15 10:30:45",
      "channels": { "channel1": 1234, ... }
    },
    ...
  ],
  "mqtt_connected": true
}
```

#### 4. get_server_status()
获取 MCP 服务器和 MQTT 连接的状态信息。

返回示例：
```json
{
  "status": "running",
  "mqtt_connected": true,
  "mqtt_broker": "be18721454da4600b14a92424bb1181c.s1.eu.hivemq.cloud",
  "mqtt_topic": "meimeifarm/Spectrum",
  "has_data": true,
  "history_count": 45,
  "last_update": "2024-01-15 10:30:45",
  "data_age_seconds": 2
}
```

### 资源（Resources）

#### 1. spectrum://latest
返回最新的光谱数据和元数据。

#### 2. spectrum://channels
返回所有通道的光谱值（整数格式）。

#### 3. spectrum://history
返回完整的历史记录（最多 100 条）。

## 部署到 1Panel

详细的部署说明请参考 [DEPLOYMENT.md](DEPLOYMENT.md)。

快速配置：

```json
{
  "mcpServers": {
    "spectrum-stravision": {
      "command": "uvx",
      "args": ["mcp-server-spectrum-stravision"],
      "env": {
        "MQTT_BROKER": "be18721454da4600b14a92424bb1181c.s1.eu.hivemq.cloud",
        "MQTT_PORT": "8883",
        "MQTT_TOPIC": "meimeifarm/Spectrum",
        "MQTT_USER": "meimeifarm",
        "MQTT_PASSWORD": "Meimei83036666",
        "MCP_TRANSPORT": "stdio"
      },
      "disabled": false
    }
  }
}
```

## 配置说明

### 环境变量

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| MQTT_BROKER | be18721454da4600b14a92424bb1181c.s1.eu.hivemq.cloud | MQTT Broker 地址 |
| MQTT_PORT | 8883 | MQTT 端口（8883 为 TLS） |
| MQTT_TOPIC | meimeifarm/Spectrum | 订阅的 MQTT 主题 |
| MQTT_USER | meimeifarm | MQTT 用户名 |
| MQTT_PASSWORD | Meimei83036666 | MQTT 密码 |
| MCP_TRANSPORT | stdio | MCP 传输方式 |

### 命令行参数

- `--no-mqtt`: 不启动 MQTT 客户端（用于测试）

## 测试

### 使用测试脚本

```powershell
# Windows PowerShell
.\test-server.ps1
```

### 手动测试

```bash
# 完整测试（包含 MQTT）
python server.py

# 不连接 MQTT 的测试
python server.py --no-mqtt
```

## 在 ESP32 上部署

1. 修改 `esp32/main.txt` 中的 WiFi 和 MQTT 配置
2. 将 `esp32/as7341.txt` 重命名为 `as7341.py`
3. 将 `esp32/main.txt` 重命名为 `main.py`
4. 使用 `mpremote` / `ampy` / `rshell` 上传到设备

```bash
# 使用 mpremote 示例
mpremote connect auto fs cp esp32/as7341.py :
mpremote connect auto fs cp esp32/main.py :
mpremote connect auto run :
```

## 故障排除

### MQTT 连接失败
- 检查网络连接和防火墙设置
- 验证 Broker 地址、端口、用户名和密码
- 使用 `get_server_status` 工具检查连接状态

### 没有数据
- 确认 ESP32 设备在线并正常工作
- 检查 MQTT 主题是否正确
- 查看服务器日志中的 MQTT 消息

### TLS 错误
- 确保系统有最新的 CA 证书
- 检查系统时间是否正确
- 可以尝试使用非 TLS 端口（1883）进行测试

## 开发

### 构建包

```bash
uv build
```

### 发布到 PyPI

```bash
uv publish
```

## 版本历史

### v2.0.4 (2024)
- 增强的数据返回格式
- 扩展历史数据容量到 100 条
- 新增服务器状态监控工具
- 改进的错误处理和日志
- 添加连接状态追踪
- 完整的 1Panel 部署支持

### v2.0.3
- 初始版本
- 基础 MQTT 连接
- 基本工具和资源

## 许可证

MIT License

## 支持

如有问题，请联系 Stravision 技术支持或查看 [DEPLOYMENT.md](DEPLOYMENT.md) 获取更多信息。 
