Atmosphere777

一个可自托管的室内外环境观测站：把和风天气、室内温湿度、MCP 工具、只读 REST API 和黑白像素风 PWA 放在同一个轻量项目里。

它包含什么

• 5 个 MCP 工具：实时天气、24 小时预报、7 日预报、天气预警、室内温湿度；
• 4 个供网页调用的只读天气 REST 端点；
• 1 个带 Bearer Token 的室内传感器上报端点；
• 响应式 PWA 前端，支持手机、桌面与低刷新墨水屏；
• Docker Compose、Nginx 示例和严格的容器资源限制；
• 面向人类和 AI 编程助手的部署、定制与交接文档。

室内传感器是可选项。只有 VPS、没有任何温湿度硬件，也可以运行完整的室外天气、预报、预警、MCP 和 PWA。把 frontend/config.js 中的 indoorEnabled 改为 false，房间模块就会干净地隐藏。

架构

QWeather ──> atmosphere-mcp ──> /mcp ──> Claude / Codex / other agents
        └──> weather-api ─────> /weather/* ─┐
BLE / other sensor ─> sensor-api ─> /sensor ├──> PWA frontend
                              └──> indoor_climate_now

完整说明见 docs/architecture.md。

只在家庭局域网使用也没问题，见 docs/lan-deployment.md。

快速开始

1. 准备配置

cp .env.example .env
cp sensor.env.example sensor.env
mkdir -p keys

在和风天气开发控制台创建 JWT 凭据，把 Ed25519 私钥保存为：

keys/qweather-ed25519-private.pem

然后填写 .env 中的 API Host、Project ID、Key ID 和默认位置。真实配置和私钥已被 .gitignore 排除，绝不要提交。

2. 启动服务

docker compose up -d --build
docker compose ps

本机端口：

服务	地址
MCP	http://127.0.0.1:8001/mcp
室内传感器	http://127.0.0.1:8002/sensor
天气 REST	http://127.0.0.1:8003/weather/now

3. 上报一条室内数据

curl -X POST http://127.0.0.1:8002/sensor/update \
  -H "Authorization: Bearer YOUR_SENSOR_INGEST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"temperature":24.6,"humidity":46.0}'

也可以使用 examples/push_sensor.py 从任意脚本或蓝牙采集程序上报。

没有传感器时跳过本步骤，并把 frontend/config.js 的 indoorEnabled 设为 false。indoor_climate_now 会返回 freshness: "unavailable"，不会令整个 MCP 服务失败。

4. 发布网页与 HTTPS

把 frontend/ 中的静态文件放到 /var/www/atmosphere，将 frontend/atmosphere.nginx.conf 里的 atmosphere.example.com 替换成自己的域名，再申请证书并启用站点。完整步骤见 docs/deployment.md。

MCP 客户端配置

部署 HTTPS 后，把下面的 URL 添加到支持 Streamable HTTP 的 MCP 客户端：

https://atmosphere.example.com/mcp

工具名称是稳定接口，不应在普通定制中修改：

• outdoor_weather_now
• outdoor_weather_hourly
• outdoor_weather_daily
• weather_alerts
• indoor_climate_now

给 AI 编程助手

让 AI 先读取仓库根目录的 AGENTS.md，再读取 docs/ai-handoff.md。它们明确写出了秘密边界、允许修改范围、部署顺序和验收清单。

安全边界

• 和风私钥只挂载到后端容器，前端永远不接触它；
• 传感器写入使用独立 Bearer Token；读取接口默认公开，若数据敏感请在 Nginx 增加认证；
• MCP、REST 和传感器服务仅监听 127.0.0.1，由反向代理暴露必要路由；
• 容器使用只读文件系统、移除 Linux capabilities，并设置 CPU/内存限制。

许可证

MIT。可以使用、修改、再发布，也欢迎保留出处。