mcp-server-spectrum-stravision 2.0.4

Enhanced Spectrum MCP Server for Stravision IoT Platform with real-time MQTT data acquisition and historical data tracking

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（推荐）

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

方法二：从源码安装

1. 克隆或下载项目

2. 安装依赖：

pip install -e .

3. 运行服务器：

python server.py

方法三：使用构建脚本

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

MCP 接口

工具（Tools）

1. get_all_spectrum()

获取完整的光谱数据，包含所有通道值和元数据。

返回示例：

{
  "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' 等）

返回示例：

{
  "status": "ok",
  "channel": "channel1",
  "value": 1234,
  "last_update": "2024-01-15 10:30:45"
}

3. get_spectrum_history(limit: int = 10)

获取历史光谱数据记录。

参数：

• limit: 返回的记录数量（默认 10，最大 100）

返回示例：

{
  "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 连接的状态信息。

返回示例：

{
  "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。

快速配置：

{
  "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 客户端（用于测试）

测试

使用测试脚本

# Windows PowerShell
.\test-server.ps1

手动测试

# 完整测试（包含 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 上传到设备

# 使用 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）进行测试

开发

构建包

uv build

发布到 PyPI

uv publish

版本历史

v2.0.4 (2024)

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

v2.0.3

• 初始版本
• 基础 MQTT 连接
• 基本工具和资源

许可证

MIT License

支持

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