mcpserver-spectrum 0.1.0

Spectrum MCP Server - AS7341 sensor data via MQTT

Spectrum MCP Server — 使用与服务配置

本仓库包含一个将 ESP32 上 AS7341 光谱传感器数据通过 MQTT 收集并暴露为 MCP 资源的服务。该 README 重点说明如何在本地与平台上运行此服务，以及平台所需的启动配置说明。

快速安装（从 PyPI）

使用 pip 安装

pip install mcpserver-spectrum

使用 uvx 运行（推荐）

uvx mcpserver-spectrum

配置环境变量

运行前请配置 MQTT 连接信息：

export MQTT_BROKER=your-mqtt-broker
export MQTT_PORT=8883
export MQTT_TOPIC=your-topic
export MQTT_USER=your-user
export MQTT_PASSWORD=your-password
uvx mcpserver-spectrum

核心文件

• server.py — FastMCP 服务实现，订阅 MQTT 主题并暴露资源 spectrum://latest 与工具 get_channel()。
• mcp-config.json — 平台启动配置（请务必包含在仓库根目录，平台据此知道如何安装并启动服务）。

快速开始（开发机器）

1. 创建并激活虚拟环境（可选但推荐）：

python -m venv .venv
.\.venv\Scripts\Activate.ps1

2. 安装依赖：

python -m pip install --upgrade pip
pip install -e .
# 或： pip install -r requirements.txt

3. 运行 MCP 服务器（开发）：

python server.py

可选参数：--no-mqtt（不启动 MQTT 客户端，便于在无设备/无 Broker 场景测试）。

服务接口

• 资源 spectrum://latest — 返回最近一次接收到的光谱 JSON（字典，通常包含 channel1..channel11）。
• 工具 get_channel(name) — 返回指定通道的整数值。

检查与调试

• HTTP 健康/数据检查：/api/latest 返回当前 latest_spectrum 的 JSON 副本。
• 我们在响应中加入了诊断头 X-Served-By: mcpserver，平台请求返回该头则表示请求命中了本服务。
• 使用 curl 验证（检查 Content-Type 与自定义头）：

curl -I 'http://YOUR_HOST:8000/api/latest' -H 'Accept: application/json'

平台说明（重要） 平台不会自动猜测如何运行你的代码：请确保仓库根目录包含 mcp-config.json（或平台指定的等价文件），其中必须明确：

• 安装依赖命令（如 pip install -r requirements.txt 或 pip install -e .）
• 启动命令与参数（例如 python server.py，以及可选 --no-mqtt）
• 运行时环境变量（如 HTTP_BIND/HTTP_PORT/MCP_TRANSPORT）
• 服务监听端口与协议（例如 HTTP port 8000，health-check 路径 /api/latest）

仓库中已加入示例配置文件：mcp-config.json。平台应读取该文件并据此安装依赖、启动服务并进行健康检查。

部署建议

• 临时公开测试：使用 ngrok 暴露本地端口：

ngrok http 8000
# 将 ngrok 返回的 https://xxxxx.ngrok.io 指定为平台的服务 URL（/api/latest）

• 生产/稳定：部署到 VPS、Render、Railway、Fly 或 Heroku，并将平台指向部署后的 HTTPS URL（确保 /api/latest 可访问）。

容器化部署

使用 Docker 构建并运行

1. 构建 Docker 镜像：

docker build -t mcpserver-spectrum .

2. 运行 Docker 容器：

docker run -d \
  -p 8000:8000 \
  -e MQTT_BROKER=your-mqtt-broker \
  -e MQTT_PORT=8883 \
  -e MQTT_TOPIC=your-topic \
  -e MQTT_USER=your-user \
  -e MQTT_PASSWORD=your-password \
  mcpserver-spectrum

使用 Docker Compose

1. 复制环境变量示例文件：

cp .env.example .env

2. 编辑 .env 文件，配置你的 MQTT 连接信息

3. 启动服务：

docker-compose up -d

4. 查看日志：

docker-compose logs -f

5. 停止服务：

docker-compose down

环境变量说明

• MQTT_BROKER: MQTT 代理地址
• MQTT_PORT: MQTT 端口（默认 8883）
• MQTT_TOPIC: MQTT 主题
• MQTT_USER: MQTT 用户名
• MQTT_PASSWORD: MQTT 密码
• HTTP_BIND: HTTP 绑定地址（默认 0.0.0.0）
• HTTP_PORT: HTTP 端口（默认 8000）
• MCP_TRANSPORT: MCP 传输方式（默认 sse）

常见问题

• 我把仓库放到 GitHub，平台却拿到 HTML：如果平台的 URL 指向 https://github.com/...（仓库页面），它会返回 HTML 页面而非运行中的 API。平台需要指向正在运行的服务地址（或 raw.githubusercontent.net 的静态文件 URL）。
• 平台请求时显示 HTML 登录页（例如 GitHub）：说明平台没有启动服务或 URL 指向了静态仓库页面。

后续可选操作

• 我可以帮你生成 requirements.txt（从 pyproject.toml 提取依赖）并提交到仓库；
• 我也可以添加一个小的 systemd/Procfile 或 GitHub Actions 示例以便自动部署到云平台；
• 如果你想快速测试，我可以给出 ngrok 的完整步骤并协助启动。

---

发布到 PyPI

详细的 PyPI 发布指南请参考 PUBLISH.md。

---

文件引用：启动配置位于仓库根目录的 mcp-config.json（请在平台上确认该文件被识别）。