# Capillus Hermes MCP

Local-first Bluetooth tracking and MCP tools for Bluetooth-enabled Capillus caps.

This repo has two pieces:

- `monitor/`: a Python BLE monitor that detects a Capillus cap when it powers on for treatment, logs local observations, and infers completed treatment sessions.
- `src/`: a read-only Model Context Protocol server for Hermes, Claude Desktop, or any MCP client. It reads the monitor's local files and exposes status, sessions, adherence, observations, and device identity.

No Capillus account, cloud API, private endpoint, scraping, or app automation is required.

## What It Tracks

Bluetooth-enabled Capillus caps appear only during the treatment power window. The monitor watches for a cap-like BLE advertisement, then records:

- cap present/offline state
- latest RSSI and BLE identity
- inferred treatment start/end
- completed sessions
- raw observed BLE duration, inference window, credited treatment duration, and completion basis
- daily adherence and streaks

The default matcher looks for names like `Capillus_CAP`, manufacturer data keys, and optional pinned addresses. You can use your own cap by turning it on once and letting the monitor auto-detect it, then pinning the discovered identity in `monitor/config.json`.

By default a session is marked complete after a full 360-second observed treatment window, a near-full observed cap power window within `complete_grace_seconds`, or a near-full stale-close window where the monitor saw the cap recently enough to infer that the treatment cycle kept running after the last advertisement. The raw BLE window is preserved as `observed_duration_seconds`; the stale-close span is preserved as `inference_window_seconds` and `close_detected_at`; the credited treatment duration is exposed as `inferred_duration_seconds` with a `completion_basis` such as `observed_full_window`, `inferred_cap_power_cycle`, or `inferred_stale_power_window`. Much shorter observations remain incomplete, because dropped BLE advertisements should not become false adherence credit.

On macOS, the default `subprocess_scanner` mode runs each BLE discovery in a short-lived child process. This keeps any Bleak/CoreBluetooth heap growth out of the always-on monitor process; if the platform scanner leaks over repeated discoveries, the memory is released when the child exits. If subprocess scanning is unavailable in a given macOS privacy context, the monitor can fall back to in-process scans and cleanly self-recycle after `max_runtime_seconds` or `max_scans_per_process`; with launchd `KeepAlive`, it restarts automatically.

## Install The Monitor

```bash
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
```

Run once from a GUI terminal and turn the cap on:

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

On macOS you must grant Bluetooth permission to the Python process in System Settings. For always-on tracking, edit `monitor/deploy/launchd/com.example.capillus-monitor.plist`, replace `/Users/YOU`, copy it to `~/Library/LaunchAgents/`, and bootstrap it with `launchctl`.

## Optional Open Brain Sync

If you run Open Brain locally, the included sync loop can capture durable adherence facts through Open Brain's normal `capture_thought` path. It captures each completed session once and, after the configured local evening hour, captures one missing-treatment alert if the daily goal has not been met.

In `monitor/config.json`, enable and point the sync at your local Open Brain checkout:

```json
{
  "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."
  }
}
```

Run once:

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

For always-on sync, edit `monitor/deploy/launchd/com.example.capillus-openbrain-sync.plist`, replace `/Users/YOU`, copy it to `~/Library/LaunchAgents/`, and bootstrap it with `launchctl`.

## Install The MCP Server

```bash
npm install
npm run build
```

Point the MCP at your monitor data:

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

For Hermes, configure a stdio MCP server equivalent to:

```yaml
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 exposes the tools with its normal `mcp_<server>_<tool>` prefix, for example `mcp_capillus_capillus_today`.

## Tools

- `capillus_status`: current presence, latest seen time, active session, device identity.
- `capillus_today`: local-day treatment completion and active session.
- `capillus_sessions`: recent inferred treatment sessions, including observed duration, inference window, credited duration, and completion basis.
- `capillus_adherence`: daily adherence, missed days, and current streak.
- `capillus_observations`: recent matched BLE observations and optional nearby candidates.
- `capillus_device`: pinned identity and observed proprietary BLE service notes.

## Observed BLE Shape

The cap observed during development advertised as `Capillus_CAP`. A read-only GATT probe showed a proprietary UART-style service:

- service: `49535343-fe7d-4ae5-8fa9-9fafd205e455`
- characteristic: `49535343-1e4d-4bd9-ba61-23c647249616`
- characteristic properties: `write`, `notify`, `indicate`, `write-without-response`

The public monitor does not send control commands. It uses local Bluetooth presence and timing only.

## Safety

This is adherence telemetry, not medical advice. It does not evaluate hair growth, alter treatment, or control the cap.