vaultbeat-mcp 0.1.0__tar.gz

vaultbeat_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fino-wind (Tether — AI Health Sync)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vaultbeat_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: vaultbeat-mcp
+Version: 0.1.0
+Summary: Local MCP server for Vaultbeat — AI Health Sync: your AI agent reads your end-to-end-encrypted Apple Health data (sleep, cycle, weight, water), decrypted only on your machine
+Requires-Python: >=3.11
+License-File: LICENSE
+Requires-Dist: cryptography<47.0.0,>=42.0.0
+Requires-Dist: httpx<1.0.0,>=0.28.0
+Requires-Dist: keyring>=24
+Requires-Dist: mcp<2.0.0,>=1.13.0
+Provides-Extra: dev
+Requires-Dist: pytest<9.0.0,>=8.3.0; extra == "dev"
+Requires-Dist: ruff<1.0.0,>=0.11.0; extra == "dev"
+Requires-Dist: mypy<2.0.0,>=1.13.0; extra == "dev"
+Provides-Extra: qr
+Requires-Dist: qrcode<9.0.0,>=8.0.0; extra == "qr"
+Dynamic: license-file

vaultbeat_mcp-0.1.0/README.md

@@ -0,0 +1,123 @@
+# Vaultbeat MCP Server
+
+**Let your own AI agent read your health data — without the cloud ever seeing it.**
+
+This is the official local [MCP](https://modelcontextprotocol.io) server for [Vaultbeat — AI Health Sync](https://apps.apple.com/us/app/tether-ai-health-sync/id6759241985) (formerly named *Tether*), the iOS app that syncs Apple Health data (sleep, heart rate, menstrual cycle, weight, water, symptoms) between partners and to your own AI — end-to-end encrypted.
+
+Vaultbeat embeds no AI and runs no model on your phone. Intelligence lives where you control it: Claude Code, Claude Desktop, or any MCP-capable agent running on your own machine. This server is the bridge — it holds a private key that never leaves your computer, pulls ciphertext from the cloud, and decrypts **only locally**.
+
+```
+iPhone (Apple Health) ──E2EE──▶ cloud (ciphertext only) ──E2EE──▶ this server (your machine) ──▶ your AI agent
+```
+
+## Requirements
+
+- [Vaultbeat — AI Health Sync](https://apps.apple.com/us/app/tether-ai-health-sync/id6759241985) on iOS, with a **Pro** subscription (the AI-agent interface is the Pro tier)
+- Python 3.11+ on the machine where your agent runs (macOS / Linux / Windows)
+
+## Quick start
+
+### 1. Install
+
+With [uv](https://docs.astral.sh/uv/) (recommended — no clone needed):
+
+```bash
+uvx vaultbeat-mcp status
+```
+
+Or with pip:
+
+```bash
+pip install 'vaultbeat-mcp[qr]'
+```
+
+> Upgrading from the old `tether-mcp` package? Same code, new name — your existing binding and config carry over unchanged. Just swap the package name in your install command and MCP client config.
+
+### 2. Bind your phone
+
+```bash
+vaultbeat-mcp bind
+```
+
+This generates a keypair on your machine and prints a QR code. In the Vaultbeat iOS app, open **Settings → Data & AI → MCP Server** and scan it (or import a QR screenshot from Photos). The app authorizes this machine and starts sealing your health envelopes to its public key. The private key stays in `~/.tether/mcp-local/` (owner-only `0600` permissions, OS keychain where available) — it is never uploaded anywhere. (The directory keeps its original pre-rename path so existing bindings survive upgrades.)
+
+### 3. Connect your agent
+
+**Claude Code** (one line):
+
+```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"]
+    }
+  }
+}
+```
+
+Any other MCP client: run `vaultbeat-mcp serve --transport stdio`, or `serve --transport http` for a loopback streamable-HTTP endpoint with bearer-token auth.
+
+> **Claude Desktop note**: it does not inherit your shell `PATH`. If `uvx` isn't found, use the absolute path (`which uvx`) as `command`.
+
+Debugging: `npx @modelcontextprotocol/inspector uvx vaultbeat-mcp serve --transport stdio`
+
+Then just ask your agent: *“How did we sleep last night?”*
+
+## MCP tools (16)
+
+| Tool | Returns |
+|---|---|
+| `vaultbeat_status` | Local binding state (never exposes keys or tokens) |
+| `vaultbeat_start_binding` | A fresh QR binding payload for the iOS app to scan |
+| `vaultbeat_poll_binding` | One poll for the iOS authorization to complete binding |
+| `vaultbeat_sync_sleep` | Recent sleep sessions incl. heart-rate samples, per-day primary-session selection matching the iOS app |
+| `get_sleep_detail` | Per-night heart-rate + respiratory-rate + sleep-stage timeline |
+| `get_water_intake` | Daily water intake + computed daily average |
+| `get_weight_trend` | Daily weights + latest/avg/min/max + weekly trend rate |
+| `get_menstrual_cycle` | Cycle samples + next-period prediction *(sensitive — explicit iOS opt-in required)* |
+| `get_symptoms` | HealthKit symptom days grouped by data owner *(sensitive)* |
+| `get_notes` | Free-text day annotations with their writer *(sensitive)* |
+| `get_activity` | Daily activity rings: steps / energy / exercise minutes / stand hours / distance |
+| `get_resting_hr` | Resting heart-rate records + window mean |
+| `get_workouts` | Workout records: type / duration / calories / distance |
+| `get_mindfulness` | Mindful sessions and minutes per day |
+| `get_hrv` | Heart-rate variability (SDNN) records + window mean |
+| `get_wrist_temp` | Sleeping wrist-temperature baseline deviation |
+
+Every data tool accepts `owner` (a user-ID prefix) to filter to one person — the server may hold both your and your partner's shared records, and omitting `owner` mixes them into one pool, so per-person questions should always pass it. (Earlier releases named some tools `get_partner_*` / `tether_*`; they were renamed in the 16-tool and Vaultbeat releases.)
+
+Reads are cache-first: decrypted records are cached locally (owner-only files, 600 s TTL, `VAULTBEAT_MCP_CACHE_TTL` to override — the pre-rename `TETHER_MCP_*` spellings still work) so repeat queries answer in ~0.2 s with zero network; pass `fresh=true` to force a cloud round trip. The same service layer backs a full CLI (`vaultbeat-mcp sleep / water / weight / …` — every data subcommand takes `--owner` too) if you prefer scripts over MCP.
+
+## Privacy & security model
+
+- **End-to-end encryption**: Curve25519 ECDH + HKDF-SHA256 + AES-GCM. Every health record is sealed on-device to each authorized recipient's public key (your partner, and this server once bound).
+- **The cloud only ever holds ciphertext.** Vaultbeat's backend cannot read your health data — architecturally, not just by policy.
+- **Decryption happens here**, on hardware you own. The private key and server token are never exposed through any tool result.
+- **Sensitive kinds** (menstrual cycle, symptoms, notes) reach this server only if explicitly opted in inside the iOS app, and are never re-exported by the server.
+- HTTP transport binds to loopback by default and requires a bearer token; binding a non-loopback address fails closed unless explicitly allowed — front it with TLS if you must expose it.
+
+You can audit all of the above in this repository — that is why it is open source.
+
+## Development
+
+```bash
+pip install -e '.[dev,qr]'
+pytest
+```
+
+## License
+
+[MIT](LICENSE). The Vaultbeat iOS app and cloud service are separate proprietary components; this repository covers the local MCP server only.
+
+---
+
+*Website: [tetherme.app](https://tetherme.app) · App Store: [Vaultbeat — AI Health Sync](https://apps.apple.com/us/app/tether-ai-health-sync/id6759241985) · Bugs & feedback: [vaultbeat-community](https://github.com/Fino-wind/vaultbeat-community/issues)*
+
+<!-- mcp-name: io.github.fino-wind/vaultbeat -->

vaultbeat_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vaultbeat-mcp"
+version = "0.1.0"
+description = "Local MCP server for Vaultbeat — AI Health Sync: your AI agent reads your end-to-end-encrypted Apple Health data (sleep, cycle, weight, water), decrypted only on your machine"
+requires-python = ">=3.11"
+dependencies = [
+  "cryptography>=42.0.0,<47.0.0",
+  "httpx>=0.28.0,<1.0.0",
+  "keyring>=24",
+  "mcp>=1.13.0,<2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.3.0,<9.0.0",
+  "ruff>=0.11.0,<1.0.0",
+  "mypy>=1.13.0,<2.0.0",
+]
+qr = [
+  "qrcode>=8.0.0,<9.0.0",
+]
+
+[project.scripts]
+vaultbeat-mcp = "vaultbeat_mcp_local.cli:main"
+# Back-compat alias: pre-rename installs and docs invoke vaultbeat-mcp-local.
+vaultbeat-mcp-local = "vaultbeat_mcp_local.cli:main"
+
+[tool.pytest.ini_options]
+# src-layout: make vaultbeat_mcp_local importable for the test run without depending
+# on an editable install being present. The editable .pth can silently drop out
+# when the venv is rebuilt (e.g. via `uv sync`), which otherwise breaks collection.
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.mypy]
+python_version = "3.11"
+check_untyped_defs = true
+warn_unused_ignores = true
+warn_return_any = true
+
+[tool.setuptools.packages.find]
+where = ["src"]

vaultbeat_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vaultbeat_mcp-0.1.0/src/vaultbeat_mcp.egg-info/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: vaultbeat-mcp
+Version: 0.1.0
+Summary: Local MCP server for Vaultbeat — AI Health Sync: your AI agent reads your end-to-end-encrypted Apple Health data (sleep, cycle, weight, water), decrypted only on your machine
+Requires-Python: >=3.11
+License-File: LICENSE
+Requires-Dist: cryptography<47.0.0,>=42.0.0
+Requires-Dist: httpx<1.0.0,>=0.28.0
+Requires-Dist: keyring>=24
+Requires-Dist: mcp<2.0.0,>=1.13.0
+Provides-Extra: dev
+Requires-Dist: pytest<9.0.0,>=8.3.0; extra == "dev"
+Requires-Dist: ruff<1.0.0,>=0.11.0; extra == "dev"
+Requires-Dist: mypy<2.0.0,>=1.13.0; extra == "dev"
+Provides-Extra: qr
+Requires-Dist: qrcode<9.0.0,>=8.0.0; extra == "qr"
+Dynamic: license-file

vaultbeat_mcp-0.1.0/src/vaultbeat_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,23 @@
+LICENSE
+README.md
+pyproject.toml
+src/vaultbeat_mcp.egg-info/PKG-INFO
+src/vaultbeat_mcp.egg-info/SOURCES.txt
+src/vaultbeat_mcp.egg-info/dependency_links.txt
+src/vaultbeat_mcp.egg-info/entry_points.txt
+src/vaultbeat_mcp.egg-info/requires.txt
+src/vaultbeat_mcp.egg-info/top_level.txt
+src/vaultbeat_mcp_local/__init__.py
+src/vaultbeat_mcp_local/cache.py
+src/vaultbeat_mcp_local/cli.py
+src/vaultbeat_mcp_local/client.py
+src/vaultbeat_mcp_local/crypto.py
+src/vaultbeat_mcp_local/mcp_server.py
+src/vaultbeat_mcp_local/service.py
+src/vaultbeat_mcp_local/store.py
+tests/test_cache.py
+tests/test_cli.py
+tests/test_crypto.py
+tests/test_mcp_server.py
+tests/test_service.py
+tests/test_store.py

vaultbeat_mcp-0.1.0/src/vaultbeat_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

vaultbeat_mcp-0.1.0/src/vaultbeat_mcp.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+vaultbeat-mcp = vaultbeat_mcp_local.cli:main
+vaultbeat-mcp-local = vaultbeat_mcp_local.cli:main

vaultbeat_mcp-0.1.0/src/vaultbeat_mcp.egg-info/requires.txt

@@ -0,0 +1,12 @@
+cryptography<47.0.0,>=42.0.0
+httpx<1.0.0,>=0.28.0
+keyring>=24
+mcp<2.0.0,>=1.13.0
+
+[dev]
+pytest<9.0.0,>=8.3.0
+ruff<1.0.0,>=0.11.0
+mypy<2.0.0,>=1.13.0
+
+[qr]
+qrcode<9.0.0,>=8.0.0

vaultbeat_mcp-0.1.0/src/vaultbeat_mcp.egg-info/top_level.txt

@@ -0,0 +1 @@
+vaultbeat_mcp_local

vaultbeat_mcp-0.1.0/src/vaultbeat_mcp_local/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

vaultbeat_mcp-0.1.0/src/vaultbeat_mcp_local/cache.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+import json
+import logging
+import os
+import time
+from pathlib import Path
+from typing import Any
+
+from vaultbeat_mcp_local.store import write_secret_file
+
+_LOG = logging.getLogger("vaultbeat_mcp_local.cache")
+
+# Cache freshness window. Health data lands in the cloud at the phone's
+# background-sync cadence (minutes-to-hours), so an agent asking twice within a
+# few minutes should not pay a second cloud round trip. Override with
+# VAULTBEAT_MCP_CACHE_TTL (seconds); 0 disables the cache entirely.
+DEFAULT_TTL_SECONDS = 600.0
+TTL_ENV = "VAULTBEAT_MCP_CACHE_TTL"
+# Pre-rename env var, honored as a fallback so existing setups keep working.
+_LEGACY_TTL_ENV = "TETHER_MCP_CACHE_TTL"
+
+
+def _ttl_from_env(default: float) -> float:
+    raw = os.getenv(TTL_ENV, "").strip() or os.getenv(_LEGACY_TTL_ENV, "").strip()
+    if not raw:
+        return default
+    try:
+        return max(float(raw), 0.0)
+    except ValueError:
+        _LOG.warning("Ignoring non-numeric %s=%r", TTL_ENV, raw)
+        return default
+
+
+class LocalRecordCache:
+    """Decrypted-record cache on the user's own machine.
+
+    Stores DECRYPTED plaintext JSON — acceptable by design: the whole point of
+    the local MCP server is that decryption happens in the user's trusted
+    environment, and the files are owner-only (0600 via `write_secret_file`,
+    0700 directory). E2EE protects the wire and the cloud, not the user's own
+    disk from the user.
+
+    One file per metric_type (plus one for the unfiltered "all" set), each
+    stamped with the server_id it was fetched for, a fetch timestamp, and the
+    fetch's decrypt-error list (a cache hit must report the same errors the
+    fetch did): a bind to a different server or an expired TTL reads as a miss.
+    """
+
+    def __init__(self, directory: Path, *, ttl_seconds: float | None = None):
+        self.directory = directory
+        # An explicit ttl_seconds always wins; the env var only replaces the
+        # built-in default — so `LocalRecordCache(dir, ttl_seconds=0)` really
+        # disables the cache regardless of the caller's shell environment.
+        self.ttl_seconds = (
+            _ttl_from_env(DEFAULT_TTL_SECONDS) if ttl_seconds is None else max(ttl_seconds, 0.0)
+        )
+
+    @property
+    def enabled(self) -> bool:
+        return self.ttl_seconds > 0
+
+    def _path(self, metric_type: str | None) -> Path:
+        return self.directory / f"records-{metric_type or 'all'}.json"
+
+    def load(
+        self, *, server_id: str, metric_type: str | None
+    ) -> tuple[list[dict[str, Any]], list[str]] | None:
+        """Cached (records, errors), or None on miss/stale/mismatch/disabled.
+
+        The early `return None`s below are ordinary cache-miss control flow,
+        not swallowed failures — the caller answers a miss with a cloud fetch.
+        """
+
+        if not self.enabled:
+            return None
+        path = self._path(metric_type)
+        try:
+            raw = json.loads(path.read_text(encoding="utf-8"))
+        except FileNotFoundError:
+            return None
+        except (OSError, json.JSONDecodeError) as error:
+            _LOG.warning("Discarding unreadable cache %s: %s", path.name, type(error).__name__)
+            return None
+
+        if not isinstance(raw, dict) or raw.get("server_id") != server_id:
+            return None
+        fetched_at = raw.get("fetched_at")
+        if not isinstance(fetched_at, (int, float)):
+            return None
+        if (time.time() - float(fetched_at)) > self.ttl_seconds:
+            return None
+        records = raw.get("records")
+        if not isinstance(records, list):
+            return None
+        errors = raw.get("errors")
+        if not isinstance(errors, list):
+            errors = []
+        return (
+            [row for row in records if isinstance(row, dict)],
+            [str(item) for item in errors],
+        )
+
+    def save(
+        self,
+        records: list[dict[str, Any]],
+        *,
+        server_id: str,
+        metric_type: str | None,
+        errors: list[str] | None = None,
+    ) -> None:
+        """Persist a FULL (never limit-truncated) result set; best-effort.
+
+        `errors` carries the fetch's per-envelope decrypt failures so a cache
+        hit reports the same problem set the underlying fetch did — without it,
+        a poisoned envelope's error (and the CLI's exit code 3) would flap
+        with cache warmth.
+        """
+
+        if not self.enabled:
+            return
+        payload = {
+            "server_id": server_id,
+            "metric_type": metric_type,
+            "fetched_at": time.time(),
+            "records": records,
+            "errors": errors or [],
+        }
+        try:
+            write_secret_file(
+                self._path(metric_type),
+                json.dumps(payload, separators=(",", ":"), sort_keys=True) + "\n",
+                harden_parent=True,
+            )
+        except OSError as error:
+            _LOG.warning("Cache write failed (%s); continuing uncached", type(error).__name__)
+
+    def clear(self) -> None:
+        """Drop every cached record file (used when (re)binding)."""
+
+        try:
+            entries = list(self.directory.glob("records-*.json"))
+        except OSError as error:
+            _LOG.warning(
+                "Cache clear could not list %s (%s); stale plaintext may remain",
+                self.directory,
+                type(error).__name__,
+            )
+            return
+        for path in entries:
+            try:
+                path.unlink()
+            except OSError as error:
+                _LOG.warning(
+                    "Cache clear could not remove %s (%s); stale plaintext may remain",
+                    path.name,
+                    type(error).__name__,
+                )
+                continue