Skip to main content
Glama
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 能算、能比、能画。

---

![dashboard](web/screenshot-dashboard.png)

---

## 目录

- [它解决什么问题](#它解决什么问题)
- [系统架构](#系统架构)
- [快速开始](#快速开始)
- [工具清单](#工具清单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 轴折线,任选两个指标叠加 + 皮尔逊相关系数 |
| 健康报告 | 分数环 + 检测时间,点开是完整报告 |
| 数据概况 | 库路径、原始行数、指标行数、报告数、日期范围 |

![report](web/screenshot-report.png)

**深链**:`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、服务端接口及其返回数据的所有权归原权利人,
不在此授权范围内。

---

## 免责声明

本项目是非官方的个人数据导出工具,依赖公开的客户端接口。使用者需自行确保:

- 对所操作的账号有合法使用权
- 导出的健康数据按当地法规妥善保管
- 不用于商业分发或规避服务条款

健康数据仅供参考,不构成医学诊断。作者不对数据准确性及使用后果负责。