# Atmosphere777

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

![Python](https://img.shields.io/badge/Python-3.12-16160f)
![Docker](https://img.shields.io/badge/Docker-Compose-16160f)
![License](https://img.shields.io/badge/License-MIT-16160f)

## 它包含什么

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

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

## 架构

```text
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/architecture.md)。

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

## 快速开始

### 1. 准备配置

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

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

```text
keys/qweather-ed25519-private.pem
```

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

### 2. 启动服务

```bash
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. 上报一条室内数据

```bash
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](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](docs/deployment.md)。

## MCP 客户端配置

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

```text
https://atmosphere.example.com/mcp
```

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

- `outdoor_weather_now`
- `outdoor_weather_hourly`
- `outdoor_weather_daily`
- `weather_alerts`
- `indoor_climate_now`

## 给 AI 编程助手

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

## 安全边界

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

## 许可证

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