内容
# Vaultbeat 本地服务器
**让您自己的 AI 代理读取您的健康数据 — 而无需云端知晓。**
这是 [Vaultbeat — AI 健康同步](https://apps.apple.com/us/app/tether-ai-health-sync/id6759241985)（原名 *Tether*）的官方本地 [MCP](https://modelcontextprotocol.io) 服务器，一款 iOS 应用，用于在伴侣之间以及与您自己的 AI 同步 Apple Health 数据（睡眠、心率、月经周期、体重、水分、症状）— 端到端加密。
Vaultbeat 不嵌入任何 AI，也不运行手机上的模型。智能生活在您控制的地方：Claude Code、Claude Desktop 或任何运行在您自己机器上的 MCP 兼容代理。这个服务器是桥梁 — 它持有私钥，从不离开您的计算机，从云端拉取密文，并在**仅本地**解密。
```
iPhone (Apple Health) ──E2EE──▶ 云端（仅密文） ──E2EE──▶ 本地服务器（您的机器） ──▶ 您的 AI 代理
```
## 要求
- [Vaultbeat — AI 健康同步](https://apps.apple.com/us/app/tether-ai-health-sync/id6759241985) 在 iOS 上，具备 **Pro** 订阅（AI 代理界面是 Pro 级别）
- 在运行代理的机器上安装 Python 3.11+（macOS / Linux / Windows）
## 快速开始
### 1. 安装
使用 [uv](https://docs.astral.sh/uv/)（推荐 — 无需克隆）：
```bash
uvx vaultbeat-mcp status
```
或使用 pip：
```bash
pip install 'vaultbeat-mcp[qr]'
```
> 从旧的 `tether-mcp` 包升级？相同的代码，新的名称 — 现有绑定和配置保持不变。只需在安装命令和 MCP 客户端配置中替换包名称。
### 2. 绑定您的手机
```bash
vaultbeat-mcp bind
```
这会在您的机器上生成一对密钥并打印一个二维码。在 Vaultbeat iOS 应用中，打开 **设置 → 数据与 AI → MCP 服务器** 并扫描它（或从照片中导入二维码截图）。应用授权这台机器并开始将您的健康信封密封到其公钥。私钥保留在 `~/.tether/mcp-local/`（仅所有者权限 `0600`，如有 OS 密钥链）— 它永远不会被上传到任何地方。（目录保留其原始预重命名路径，因此现有绑定在升级后仍然存在。）
### 3. 连接您的代理
**Claude Code**（一行代码）：
```bash
claude mcp add vaultbeat-health -- uvx vaultbeat-mcp serve --transport stdio
```
**Claude Desktop**（`claude_desktop_config.json`）：
```json
{
"mcpServers": {
"vaultbeat-health": {
"command": "uvx",
"args": ["vaultbeat-mcp", "serve", "--transport", "stdio"]
}
}
}
```
任何其他 MCP 客户端：运行 `vaultbeat-mcp serve --transport stdio`，或 `serve --transport http` 以获取带有 bearer-token 身份验证的循环可流式 HTTP 端点。
> **Claude Desktop 注意**：它不会继承您的 shell `PATH`。如果找不到 `uvx`，请使用绝对路径（`which uvx`）作为 `command`。
调试：`npx @modelcontextprotocol/inspector uvx vaultbeat-mcp serve --transport stdio`
然后只需问您的代理：“昨晚我们睡得怎么样？”
## MCP 工具（16）
| 工具 | 返回 |
|---|---|
| `vaultbeat_status` | 本地绑定状态（从不暴露密钥或令牌） |
| `vaultbeat_doctor` | 完整的自我诊断：安装/绑定链 **以及** 哪些数据类型有数据，哪些需要更新的 iOS 版本 — 在得出数据缺失的结论之前调用此命令 |
| `vaultbeat_start_binding` | iOS 应用扫描的新绑定二维码有效载荷 |
| `vaultbeat_poll_binding` | iOS 授权完成绑定的一个轮询 |
| `vaultbeat_sync_sleep` | 最近的睡眠会话，包括心率样本，每日主要会话选择与 iOS 应用匹配 |
| `get_sleep_detail` | 每晚心率 + 呼吸率 + 睡眠阶段时间线 |
| `get_water_intake` | 每日水分摄入量 + 计算出的每日平均值 |
| `get_weight_trend` | 每日体重 + 最新/平均/最小/最大 + 每周趋势率 |
| `get_menstrual_cycle` | 月经周期样本 + 下一次月经预测 *(敏感 — 需要 iOS 明确选择加入)* |
| `get_symptoms` | HealthKit 症状日，按数据所有者分组 *(敏感)* |
| `get_notes` | 带有作者的自由文本日注释 *(敏感)* |
| `get_activity` | 每日活动环：步数 / 能量 / 运动分钟 / 站立小时 / 距离 |
| `get_resting_hr` | 静息心率记录 + 窗口平均值 |
| `get_workouts` | 运动记录：类型 / 时长 / 卡路里 / 距离 |
| `get_mindfulness` | 每日正念会话和分钟数 |
| `get_hrv` | 心率变异性（SDNN）记录 + 窗口平均值 |
| `get_wrist_temp` | 睡眠手腕温度基线偏差 |
| `get_hrv_hourly` *(通过 `get_hrv(granularity="hourly")`)* | 30 天内每小时 HRV 平均值 — 上下文便宜的默认值；`granularity="raw"` 保持分钟级峰值精度 |
| `get_vo2max` | VO₂ 最大记录 + 最新 / 峰值 / 最低 / 窗口平均值 |
| `get_basal_energy` | 每小时基础能量消耗 |
| `get_total_energy_burned` | **TDEE** — 每日基础 + 活动能量消耗，测量而非估计，今天标记为部分数据，不计入平均值 |
| `get_strength_log` | 结构化力量训练：运动、组数、次数、每日重量 |
| `get_food_log` | 自由文本餐食，带有可选份量和时间 |
| `log_weight_entry` | **写入** 一个体重记录（可选地镜像到 Apple Health，当用户选择加入时） |
| `log_strength_entry` | **写入** 一个给定日期的力量训练记录 |
| `log_food_entry` | **写入** 一个给定日期的餐食记录 |
| `log_note` | **写入** 一个给定日期的情绪或一般性注释 |
每个数据工具都接受 `owner`（用户 ID 前缀）以过滤到某个人 — 服务器可能持有您和您的伴侣的共享记录，并且省略 `owner` 会将它们混合成一个池，因此个人问题应该始终传递它。（早期版本将一些工具命名为 `get_partner_*` / `tether_*`；它们在 16 工具和 Vaultbeat 版本中被重命名。）
读取优先缓存：解密记录缓存在本地（仅所有者文件，600 秒 TTL，可覆盖 `VAULTBEAT_MCP_CACHE_TTL` — 预重命名 `TETHER_MCP_*` 拼写仍然有效），因此重复查询在 ~0.2 秒内以零网络响应；传递 `fresh=true` 以强制云端往返。相同的服务层支持完整的 CLI（`vaultbeat-mcp sleep / water / weight / …` — 每个数据子命令也接受 `--owner`），如果您更喜欢脚本而不是 MCP。
## 隐私与安全模型
- **端到端加密**：Curve25519 ECDH + HKDF-SHA256 + AES-GCM。每个健康记录都密封到每个授权接收者的公钥（您的伴侣和此服务器一旦绑定）。
- **云端仅持有密文**。Vaultbeat 的后端无法读取您的健康数据 — 从架构上讲，而不仅仅是政策上。
- **解密发生在您拥有的硬件上**。私钥和服务器令牌从未通过任何工具结果暴露。
- **敏感类型**（月经周期、症状、注释）仅在 iOS 应用中明确选择加入后才到达此服务器，并且从不被服务器重新导出。
- HTTP 传输默认绑定到环回地址，并要求 bearer token；绑定非环回地址在未明确允许的情况下关闭 — 如果必须公开，请使用 TLS。
您可以审计上述所有内容 — 这就是它开源的原因。
## 开发
```bash
pip install -e '.[dev,qr]'
pytest
```
## 许可证
[MIT](LICENSE)。Vaultbeat iOS 应用和云服务是单独的专有组件；此存储库仅涵盖本地 MCP 服务器。
---
*网站：[vaultbeat.app](https://vaultbeat.app) · 应用商店：[Vaultbeat — AI 健康同步](https://apps.apple.com/us/app/tether-ai-health-sync/id6759241985) · 错误和反馈：[vaultbeat-community](https://github.com/Fino-wind/vaultbeat-community/issues)*
<!-- mcp-name: io.github.Fino-wind/vaultbeat -->
