Capillus Hermes MCP

本地优先的蓝牙追踪和 MCP 工具，适用于支持蓝牙的 Capillus 帽子。

本仓库包含两个部分：

• monitor/：一个 Python BLE 监控器，可在 Capillus 帽子开机治疗时检测到它，记录本地观测数据，并推断出已完成的治疗会话。

• src/：一个只读的模型上下文协议（MCP）服务器，适用于 Hermes、Claude Desktop 或任何 MCP 客户端。它读取监控器的本地文件，并暴露状态、会话、依从性、观测数据和设备身份信息。

无需 Capillus 账户、云 API、私有端点、爬虫或应用自动化。

它追踪什么

支持蓝牙的 Capillus 帽子仅在治疗供电窗口期间出现。监控器会监听类似帽子的 BLE 广播，然后记录：

• 帽子存在/离线状态

• 最新的 RSSI 和 BLE 身份

• 推断的治疗开始/结束时间

• 已完成的会话

• 原始观测到的 BLE 持续时间、推断窗口、计入的治疗时长以及完成依据

• 每日依从性和连续记录

默认匹配器会查找类似 Capillus_CAP 的名称、制造商数据键以及可选的固定地址。你可以通过打开自己的帽子一次，让监控器自动检测它，然后在 monitor/config.json 中固定检测到的身份来使用它。

默认情况下，一个会话在以下情况被标记为完成：完整的 360 秒观测治疗窗口、在 complete_grace_seconds 内的接近完整的观测帽子供电窗口，或一个接近完整的陈旧关闭窗口（监控器最近看到帽子，足以推断治疗周期在最后一次广播后仍在继续）。原始 BLE 窗口保存为 observed_duration_seconds；陈旧关闭跨度保存为 inference_window_seconds 和 close_detected_at；计入的治疗时长暴露为 inferred_duration_seconds，并带有 completion_basis，例如 observed_full_window、inferred_cap_power_cycle 或 inferred_stale_power_window。较短的观测仍保持未完成状态，因为丢失的 BLE 广播不应成为虚假的依从性积分。

在 macOS 上，默认的 subprocess_scanner 模式会在一个短暂的子进程中运行每次 BLE 发现。这可以防止 Bleak/CoreBluetooth 堆内存增长进入始终在线的监控进程；如果平台扫描器在重复发现后泄漏内存，子进程退出时内存会被释放。如果在特定的 macOS 隐私上下文中子进程扫描不可用，监控器可以回退到进程内扫描，并在 max_runtime_seconds 或 max_scans_per_process 后干净地自我重启；通过 launchd 的 KeepAlive，它会自动重新启动。

Related MCP server: BLE MCP Server

安装监控器

mkdir -p ~/.capillus-home-monitor
cp monitor/capillus_monitor.py ~/.capillus-home-monitor/
cp monitor/config.example.json ~/.capillus-home-monitor/config.json
cd ~/.capillus-home-monitor
python3 -m venv .venv
.venv/bin/pip install -r /path/to/capillus-hermes-mcp/monitor/requirements.txt

从 GUI 终端运行一次，然后打开帽子：

~/.capillus-home-monitor/.venv/bin/python ~/.capillus-home-monitor/capillus_monitor.py --config ~/.capillus-home-monitor/config.json run

在 macOS 上，你必须在系统设置中授予 Python 进程蓝牙权限。对于始终在线的追踪，编辑 monitor/deploy/launchd/com.example.capillus-monitor.plist，将 /Users/YOU 替换为你的用户名，将其复制到 ~/Library/LaunchAgents/，然后使用 launchctl 引导它。

可选的 Open Brain 同步

如果你在本地运行 Open Brain，包含的同步循环可以通过 Open Brain 正常的 capture_thought 路径捕获持久的依从性事实。它会在每次完成会话后捕获一次，并在配置的本地晚间时间后，如果每日目标未达成，则捕获一次缺失治疗提醒。

在 monitor/config.json 中，启用同步并将其指向你本地的 Open Brain 检出目录：

{
  "openbrain": {
    "enabled": true,
    "repo_path": "/Users/YOU/open-brain",
    "tenant": "default",
    "time_zone": "America/New_York",
    "person_name": "the wearer",
    "daily_rule": "Daily Capillus treatment is required and non-negotiable."
  }
}

运行一次：

/Users/YOU/open-brain/.venv/bin/python ~/.capillus-home-monitor/capillus_openbrain_sync.py --config ~/.capillus-home-monitor/config.json once

对于始终在线的同步，编辑 monitor/deploy/launchd/com.example.capillus-openbrain-sync.plist，将 /Users/YOU 替换为你的用户名，将其复制到 ~/Library/LaunchAgents/，然后使用 launchctl 引导它。

安装 MCP 服务器

npm install
npm run build

将 MCP 指向你的监控器数据：

export CAPILLUS_MONITOR_DATA_DIR="$HOME/.capillus-home-monitor/data"
node dist/src/index.js

对于 Hermes，配置一个等效于以下内容的 stdio MCP 服务器：

mcp_servers:
  capillus:
    enabled: true
    command: /usr/local/bin/node
    args:
      - /path/to/capillus-hermes-mcp/dist/src/index.js
    env:
      CAPILLUS_MONITOR_DATA_DIR: /Users/YOU/.capillus-home-monitor/data
      CAPILLUS_TIME_ZONE: America/New_York

Hermes 会以其正常的 mcp_<server>_<tool> 前缀暴露工具，例如 mcp_capillus_capillus_today。

工具

• capillus_status：当前存在状态、最近看到的时间、活动会话、设备身份。

• capillus_today：本地日期的治疗完成情况和活动会话。

• capillus_sessions：最近的推断治疗会话，包括观测时长、推断窗口、计入时长和完成依据。

• capillus_adherence：每日依从性、错过天数以及当前连续记录。

• capillus_observations：最近的匹配 BLE 观测数据和可选的附近候选设备。

• capillus_device：固定的身份和观测到的专有 BLE 服务说明。

观测到的 BLE 形态

在开发过程中观测到的帽子广播为 Capillus_CAP。一次只读的 GATT 探测显示了一个专有的 UART 风格服务：

• 服务：49535343-fe7d-4ae5-8fa9-9fafd205e455

• 特征：49535343-1e4d-4bd9-ba61-23c647249616

• 特征属性：write、notify、indicate、write-without-response

公共监控器不会发送控制命令。它仅使用本地蓝牙存在和时序信息。

安全性

这是依从性遥测数据，而非医疗建议。它不评估头发生长、不改变治疗方式，也不控制帽子。