dalingring-mcp
by Swellyhow
README.md
# dalingring-mcp
**A Model Context Protocol server for DalingRing smart rings — bring your own account, read your own data, analyze it locally.**
把 DalingRing 智能戒指的数据接进 Codex / Claude Desktop / Cursor 等支持 MCP 的 AI 工具,
或用自带的 web 面板直接看图表。所有数据只存在本机。
> 非官方第三方客户端。做的事情等价于你在手机上打开 App 看到的内容,只是把数据落成本地
> SQLite,让 AI 能算、能比、能画。
---

---
## 目录
- [它解决什么问题](#它解决什么问题)
- [系统架构](#系统架构)
- [快速开始](#快速开始)
- [工具清单](#工具清单23-个)
- [可视化面板](#可视化面板)
- [报告解析](#报告解析)
- [适用场景](#适用场景)
- [功能限制](#功能限制)
- [路线图](#路线图)
- [开发与测试](#开发与测试)
- [许可证](#许可证)
---
## 它解决什么问题
手机 App 只能**看**,不能**问**。
| 你想知道的 | App 能不能回答 |
|---|---|
| 我最近睡眠是不是在变差? | 给一张图,自己判断 |
| 睡得少的那几天,压力是不是更高? | 不提供 |
| 把 9 月和 10 月的静息心率对比一下 | 只能手动翻 |
| 报告说我 HRV 偏低,那我实际 HRV 是多少? | 要跨两个页面自己找 |
接上 MCP 之后这些都变成一句话:
```
你:帮我看看这个月睡眠和压力的关系
模型:(sync → analyze_sleep → analyze_stress → correlate)
30 天里睡眠时长均值 317 分钟,低于 7 小时的有 18 天;
压力均值 44,高压日集中在周三周四;
两者相关系数 -0.62,中等负相关——睡得短的那几天压力确实更高。
```
---
## 系统架构
```
┌──────────────────────┐ ┌──────────────────────┐
│ AI 工具 │ MCP (stdio) │ MCP server │
│ Codex / Claude │◀──────────────────▶│ server.py │
│ Cursor / Cline │ 23 个 tools │ 23 tools │
└──────────────────────┘ └──────────┬───────────┘
│
┌──────────────────────┐ │
│ 浏览器 │ HTTP :8770 │
│ 可视化面板 │◀──────────────────┐ │
└──────────────────────┘ │ │
▼ ▼
┌────────────────────────────┐
│ web/server.py 9 个 API │
└────────────┬───────────────┘
│
┌──────────────────────────┴─────────────────────────┐
▼ ▼
┌────────────────────┐ ┌────────────────────┐
│ client.py │ 只读 GET/POST │ store.py │
│ 请求头 + token 注入 │ ───────────────────────────▶ │ SQLite 本地缓存 │
└────────────────────┘ api.dalingring.com └─────────┬──────────┘
▼
┌────────────────────┐
│ analyze.py │
│ report_parse.py │
│ 纯函数统计 / 报告解析 │
└────────────────────┘
```
**一条设计主线**:云端数据只拉一次,之后所有计算都在本地。
```
sync(days=90) → 约 450 次请求 → SQLite 落盘
↓
analyze_* / correlate / report_parse
↓
纯 SQL 查询 + 标准库统计,零请求、断网可用、无限次
```
这是它和"随手写个脚本"的本质区别——你问十遍「这月对比上月」,服务器一次都不用碰。
---
## 快速开始
### 环境
- Python 3.10+
- 一个能登录 DalingRing App 的手机号(密码或短信验证码)
### 安装
```bash
git clone https://github.com/Swellyhow/dalingRing-R-G.git
cd dalingRing-R-G
# 方式一:安装为包
pip install -e .
# 方式二:不安装,直接用 PYTHONPATH(下面配置里就是这么写的)
```
### 验证
```bash
# Linux / macOS
PYTHONPATH=src python -m dalingring_mcp
# Windows PowerShell
$env:PYTHONPATH="src"; python -m dalingring_mcp
```
进程挂在那儿等输入就对了(stdio 模式,没有输出是正常现象)。
### 接进 AI 工具
<details open>
<summary><b>Codex CLI</b> — <code>~/.codex/config.toml</code></summary>
```toml
[mcp_servers.dalingring]
command = "python"
args = ["-m", "dalingring_mcp"]
env = { PYTHONPATH = "/absolute/path/to/dalingRing-R-G/src" }
```
</details>
<details>
<summary><b>Claude Desktop</b> — <code>claude_desktop_config.json</code></summary>
```json
{
"mcpServers": {
"dalingring": {
"command": "python",
"args": ["-m", "dalingring_mcp"],
"env": { "PYTHONPATH": "/absolute/path/to/dalingRing-R-G/src" }
}
}
}
```
</details>
<details>
<summary><b>Cursor</b> — <code>~/.cursor/mcp.json</code></summary>
```json
{
"mcpServers": {
"dalingring": {
"command": "python",
"args": ["-m", "dalingring_mcp"],
"env": { "PYTHONPATH": "/absolute/path/to/dalingRing-R-G/src" }
}
}
}
```
</details>
### 第一次使用
```
你:登录我的 DalingRing 账号,手机号 1xxxxxxxxxx,密码 xxxxxx
模型:调 login_password → token 存到 ~/.dalingring/token.json
你:同步最近 90 天的数据
模型:调 sync(days=90) → 拉取睡眠/心率/血氧/HRV/压力/报告
你:我最近睡眠怎么样
模型:调 analyze_sleep(30) → 给结论
```
---
## 工具清单(23 个)
### 认证
| 工具 | 说明 |
|---|---|
| `login_password(mobile, password)` | 手机号 + 密码,优先走 v2 登录(能读新版报告),失败回退 v1 |
| `login_send_code(mobile)` | 发短信验证码(服务端有频率限制,别连点) |
| `login_with_sms(mobile, code)` | 验证码登录 |
| `whoami()` | 当前账号 + 绑定设备 |
| `logout()` | 清除本地 token |
### 同步
| 工具 | 说明 |
|---|---|
| `sync(days=30, end_date=None)` | 拉最近 N 天数据入库,`end_date` 可指定历史某天往前拉 |
| `sync_reports(limit=20)` | 下载报告全文到本地 |
### 查询
| 工具 | 说明 | 数据源 |
|---|---|---|
| `profile()` | 昵称/性别/生日/身高体重/设备 MAC | 云端 |
| `daily_snapshot(date)` | 某天全部指标快照 | 云端 |
| `trends(days)` | 9 个心脏趋势指标 | 云端 |
| `sleep(days)` | 睡眠明细 | 本地 |
| `heart_rate(days)` | 心率/静息心率/HRV/血氧 | 本地 |
| `stress(days)` | 压力值 | 本地 |
| `reports(limit)` | 报告列表 | 本地 |
| `report_detail(report_id)` | 报告原始 JSON(自动选 v1/v2) | 云端 |
| `report_markdown(report_id)` | 渲染成 App 里那份报告的排版 | 云端→解析 |
| `report_structured(report_id)` | 报告结构化字段 | 云端→解析 |
### 分析(全部离线)
| 工具 | 说明 |
|---|---|
| `analyze_sleep(days)` | 均值/中位数/标准差/趋势斜率/最差日/不足 7 小时天数 |
| `analyze_heart(days)` | 日均心率、静息心率趋势、HRV 分布 |
| `analyze_stress(days)` | 日均、波动、高压异常日(>2σ) |
| `analyze_overview(days)` | 三块合一 |
| `correlate(a, b, days)` | 皮尔逊相关系数 + 强弱判定 |
| `export_json(kind, days)` | 导出 JSON 供模型直接读 |
**可用指标名**:`sleep_duration` `sleep_score` `heart_rate_avg` `heart_rate_rest`
`hrv_avg` `spo2_avg` `stress_avg` `stress_week_avg` `sleep_week_duration` `sleep_week_score`
---
## 可视化面板
不想跟模型对话、只想看图表的时候:
```bash
python web/server.py # http://127.0.0.1:8770
python web/server.py --port 9000
```
| 区块 | 内容 |
|---|---|
| 顶栏 | 昵称、性别年龄、设备型号、MAC、绑定状态 |
| 指标卡 | 睡眠时长 / 静息心率 / HRV / 压力,各带「相对均值」的差值与涨跌色 |
| 趋势 | 6 张 SVG 折线,可切 7/30/90 天 |
| 指标对比 | 双 Y 轴折线,任选两个指标叠加 + 皮尔逊相关系数 |
| 健康报告 | 分数环 + 检测时间,点开是完整报告 |
| 数据概况 | 库路径、原始行数、指标行数、报告数、日期范围 |

**深链**:`http://127.0.0.1:8770/?report=<reportId>` 直接打开某份报告。
技术选择上刻意保持零依赖:后端 `http.server`,前端原生 JS + 手写 SVG 折线,
不引 ECharts/CDN。断网也能用。
### 指标对比为什么值得单独做
单指标趋势只能看"自己在变好还是变差",看不出"两件事有没有关系"。对比面板把两个指标
放到同一张图(左右各一根 Y 轴、实线 + 虚线区分),下面直接给结论:
```
r = -0.62 负相关 · 中等 样本 30 天
```
样本不足 8 天时不会硬算,而是明确告诉你「只有 2 天共同数据,至少需要 8 天」——
这是 `analyze.correlate` 的保护,避免从两三个点编出结论。
### API
| 方法 | 路径 | 作用 |
|---|---|---|
| GET | `/api/summary` | 账号 + 最新指标 + 全部序列 + 分析摘要 |
| GET | `/api/reports` | 报告列表 |
| GET | `/api/report?id=` | 单份报告(结构化 + markdown) |
| GET | `/api/correlate?a=&b=&days=` | 两指标相关性 + 两条原始序列 |
| GET | `/api/sync/status` | 同步进度 |
| POST | `/api/sync` | 触发同步 `{"days": 30}` |
| POST | `/api/login` | 页面里直接登录 `{"mobile","password"}` |
| GET | `/api/health` | 健康检查 |
---
## 报告解析
App 里的「健康评估报告」是 `report/v2/find` 返回的一坨嵌套 JSON。`report_parse.py`
按 App 的渲染顺序把它拆成 8 段:
```
intro 标题 + 描述
overallAssessment 总分 / 状态名 / 一句话概述
healthSignalObservations 健康信号卡(脾胃负担、睡眠恢复…)
vitalSigns 生命体征,分 3 组:心肺与循环 / 恢复与压力 / 日常状态
tcmConstitution 中医体质(主体质、脉象、舌象四要素)
constitutionRelatedTrends 体质相关趋势(分数 + 优先级 + 依据)
dualSystemInterpretation 综合建议 + 行动建议 + 三餐饮食建议
disclaimer 免责声明
```
| 用途 | 工具 | 返回 |
|---|---|---|
| 贴给用户看 | `report_markdown(report_id)` | 3000+ 字 markdown |
| 给模型算 | `report_structured(report_id)` | 结构化字段 |
有了这两个工具,就能问出 App 问不出来的问题:
```
我三份报告里气虚质是变好还是变差?
把最近两份报告的体质相关趋势做个 diff
报告说我 HRV 偏低,那我实际 HRV 是多少?
```
> 新版报告必须用 `login/v2` 拿 token 才能访问 `report/v2/find`(`type=0` 走密码,
> `type=1` 走验证码)。`login_password` 已默认走 v2,失败自动回退 v1。
---
## 适用场景
**适合:**
- 想批量导出自己的健康数据做长期跟踪
- 想让 AI 帮忙做趋势分析、相关性分析,而不是每张图自己看
- 多个季度 / 多份报告的对比(体质变化、指标漂移)
- 把数据接进自己的看板、Notion、Excel
- 学习 MCP server 怎么写(代码量小、结构完整、有真实数据)
**不适合:**
- 想绕过 App 做破解或改数据——本项目只有读接口
- 想要实时数据——它是同步式,不是流式
- 多用户服务端部署——设计上是单机单账号工具
---
## 功能限制
诚实列出,避免踩坑:
| 限制 | 说明 |
|---|---|
| **数据取决于戒指** | 没戴、没同步、没充电,云端就是空的。`sync` 返回 `metrics_written: 0` 不代表工具坏了 |
| **只有读接口** | 刻意没做写入(改体重、绑设备、删记录),避免误操作 |
| **服务端限流** | `captcha` 对同一号码有明显频率限制,验证码登录失败要等 10 分钟以上 |
| **token 有时效** | JWT 过期后需重新登录,`whoami` 会提示 |
| **不支持多设备** | 一次只能持有一个账号的 token;多账号靠 `DALINGRING_HOME` 隔离 |
| **依赖非公开接口** | 服务端一改接口就可能失效,见 [路线图](#路线图) |
| **不做数据校验** | 拿到什么就是什么,不纠正服务端的异常值(比如 HRV 显示 0) |
| **协议版本** | 基于 `mcp >= 2.0`(`MCPServer`);1.x 会自动 fallback 到 `FastMCP` |
---
## 路线图
- [x] MCP server,21 个基础工具
- [x] 报告解析(markdown + 结构化)
- [x] v2 登录与 v2 报告接口
- [x] 可视化面板(趋势 + 报告 + 对比)
- [x] 双 Y 轴指标对比 + 相关系数
- [ ] 散点图 + 线性拟合
- [ ] 批量补拉历史(指定起始日往回翻 90 天)
- [ ] web 面板多账号切换
- [ ] 报告时间序列(多份报告的体质分数排成曲线)
- [ ] CSV / Excel 导出
- [ ] 接口失效时的降级与告警
---
## 开发与测试
```
dalingring-mcp/
├── src/dalingring_mcp/
│ ├── config.py 环境变量与路径
│ ├── client.py HTTP 层(请求头/token/重试/错误归一化)
│ ├── auth.py 登录 + token 落盘(JWT payload 解码)
│ ├── store.py SQLite(raw / daily / reports 三张表)
│ ├── sync.py 批量拉取 + 指标抽取
│ ├── analyze.py 统计函数(无 pandas 依赖)
│ ├── report_parse.py 报告解析与渲染
│ └── server.py MCP 工具定义 + 入口
├── web/
│ ├── server.py 面板后端(http.server)
│ └── static/ 前端(原生 JS + SVG)
├── tests/fixtures/ 脱敏后的报告样例
└── test_*.py 三个测试脚本
```
```bash
python test_smoke.py # 协议层:list_tools + 调一个离线工具
python test_e2e.py # 登录 → 同步 → 分析(需 DR_MOBILE / DR_PASSWORD)
python test_report.py # 报告解析(需账号)
```
环境变量:
```bash
export DR_MOBILE=1xxxxxxxxxx
export DR_PASSWORD=xxxxxx
```
### 加一个新接口
1. 在 `client.py` 或 `sync.py` 里加调用
2. 在 `store.save_daily()` 里定一个指标名
3. 在 `analyze.py` 里加一个 `xxx_summary()`
4. 在 `server.py` 里加 `@mcp.tool()` 包一层
四步,没有别的魔法。
---
## 数据与隐私
- token 存 `~/.dalingring/token.json`,权限收到当前用户(POSIX 600 / Windows ACL)
- 数据存 `~/.dalingring/data.sqlite3`
- 多账号:`DALINGRING_HOME=~/.dalingring/alice python -m dalingring_mcp`
- **不会**:代登录、缓存别人的 token、把数据发给任何第三方
- 仓库里不含任何真实账号、token 或健康数据;测试用 `tests/fixtures/` 下的脱敏样例
---
## 许可证
[MIT](LICENSE) © 2026 dalingring-mcp contributors
仅对**本项目代码**授权。DalingRing 品牌、App、服务端接口及其返回数据的所有权归原权利人,
不在此授权范围内。
---
## 免责声明
本项目是非官方的个人数据导出工具,依赖公开的客户端接口。使用者需自行确保:
- 对所操作的账号有合法使用权
- 导出的健康数据按当地法规妥善保管
- 不用于商业分发或规避服务条款
健康数据仅供参考,不构成医学诊断。作者不对数据准确性及使用后果负责。
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues