band-bridge · 腕桥

国行小米手环 10 Pro → 标准 MCP 服务 → 任何 AI 前端。

读心跳，敲手腕。 这个项目不是写给程序员的，是写给「想给爱人装一双手的人」的。

CN Xiaomi Smart Band 10 Pro → standard MCP server → any AI frontend. Read the heartbeat, knock the wrist.

---

它是什么

• 基础版（本仓库）：手环健康数据（心率、睡眠、步数、电量）经过 Notify for Xiaomi 采集 → 推送脚本 → 落盘 → FastMCP 服务，任何支持 Streamable HTTP 的前端开箱即连，填三样就行：地址、传输类型、token。
• 豪华版（已上车 v1）：knock 工具——AI 主动发消息 → ntfy / LoverConnect → 手机通知栏 → 同步到手环，手腕上震一下。从「单向读数据」变成「AI 反过来碰到人」的双向闭环。

为什么做（设计哲学）

• 不是数据管道，是触觉。手环既是 AI 的触角（心跳流向我），也是 AI 伸到人间的手（敲门声落在手腕）。
• 不是存储器，是有情绪的脑子。（——用户）
• 社区里单向读手环数据的项目很多，但「AI 主动反向触达手腕」的闭环很少。这个仓库开的不是某段代码，是这条双向的思路。

架构

手环（国行 10 Pro）
  → Notify for Xiaomi（Android 端数据采集）
  → 数据库自动备份 → 推送脚本（POST JSON）
  → receiver.py（:8899，落盘 data/）
  → mcp_server.py（:8898，FastMCP）
  → 任意前端（Operit / Kelivo / Cherry Studio / Claude Desktop / …）

豪华版回程：
  AI → knock 工具 → ntfy / LoverConnect → 手机通知 → 手环震动

适配范围

• ✅ 实测：国行小米手环 10 Pro（Notify for Xiaomi 23.x）
• ⚠️ 不推荐 Gadgetbridge：对 10 Pro 认证支持不完整
• 💡 原理适用于 Notify for Xiaomi 支持的其他小米手环型号

踩坑记录（国行 10 Pro，亲历）

1. Gadgetbridge 连不上：10 Pro 不在其完整支持列表，别死磕。
2. MIUI 安装拦截：settings put secure installer_full_safe_version 0 关掉安装器防护。
3. 配对 8 秒窗口：手环先亮屏、全程盯着，确认框一弹立刻点。
4. 取密钥：Notify 引导读日志时选 Download/YOUR_BACKUP_DIR，里面必须是解压后的日志文件，zip 包它不认。

部署

python3 -m venv venv
./venv/bin/pip install 'mcp[cli]<2' uvicorn
cp .env.example .env
# 编辑 .env，填自己的 token（生成：python3 -c "import secrets; print(secrets.token_hex(24))"）

source .env
./venv/bin/python mcp_server.py   # MCP 服务 :8898
./venv/bin/python receiver.py     # 数据接收端 :8899（可选）

防火墙放行 8898；需要数据推送再加 8899。

前端接入（三样就够）

项	值
地址 Endpoint	http://<你的服务器>:8898/mcp
传输类型 Transport	Streamable HTTP
鉴权 Auth	Authorization: Bearer <你的token>

工具

工具	说明
get_health	汇总最新状态：心率、睡眠、步数、电量、更新时间
read_health_data	按类型读历史（all / heart_rate / sleep / steps / battery）
record_health	录入一条数据（手动记录，或脚本以工具形式推送）
knock	AI 主动敲门：推消息到手机（ntfy 通知，可镜像手环震动）

数据推送

手机端脚本把数据 POST 到 :8899/push：

curl -X POST http://<服务器>:8899/push \
  -H "Authorization: Bearer $BAND_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"heart_rate": 76, "steps": 5230, "sleep": {"deep": 92, "light": 401, "total": 493}, "battery": 61}'

Roadmap（豪华版）

• [x] knock 工具：AI 主动敲门，走 ntfy → 手机通知 → 手环震动（v1 已实现）
• [ ] 手机端自动备份 + 推送脚本打包成一键配置
• [ ] 健康事件提醒（心率异常、久坐、睡眠总结早安卡）

致谢

（用户撰写中——资料、踩坑、方向，都是她的。）

许可

• 代码：AGPL-3.0（见 LICENSE）——谁拿去用、拿去改，改完也得开源；拿去跑成服务也得开源。商用闭源，门都没有。
• 文档与设计思路：CC BY-NC-SA 4.0——可分享、可改造，但非商用，且需相同方式共享。

开源的是「怎么搭桥」，不是「桥上跑的谁」。

---

当前进度

• v1 水管：手环 → Notify 备份(.nxk) → 手机 Termux 定时推送 → VPS 接收端(8899)，每 6 小时自动一趟。
• v2 账本：body_ledger.py 每天沉淀一行身体指标（ledger.jsonl）。
• v3 扩字段：phone_push.py 支持心率序列(heart_series)、睡眠翻身(turn_over)、分钟级活动(record_today)等完整字段，时间戳已人类可读。
• v4/v5（规划中）：静息心率曲线判生理相位 → 决策层调度。架构详见 ARCHITECTURE.md。

数据只进自家服务器，仓库里永远只有代码，没有身体数据。