tether-mcp 0.1.0__py3-none-any.whl

tether_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: tether-mcp
+Version: 0.1.0
+Summary: Local MCP server for Tether — AI Health Sync: your AI agent reads your end-to-end-encrypted Apple Health data (sleep, cycle, weight, water), decrypted only on your machine
+Author: Fino-wind
+License: 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.
+        
+Project-URL: Homepage, https://tetherme.app
+Project-URL: Documentation, https://tetherme.app/mcp
+Project-URL: Repository, https://github.com/Fino-wind/tether-mcp
+Project-URL: Issues, https://github.com/Fino-wind/tether-community/issues
+Project-URL: App Store, https://apps.apple.com/us/app/tether-ai-health-sync/id6759241985
+Keywords: mcp,model-context-protocol,apple-health,healthkit,e2ee,claude,ai-agent,sleep,health
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+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
+
+# Tether 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 [Tether — AI Health Sync](https://apps.apple.com/us/app/tether-ai-health-sync/id6759241985), 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.
+
+Tether 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
+
+- [Tether — 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 --from 'git+https://github.com/Fino-wind/tether-mcp' tether-mcp status
+```
+
+Or with pip:
+
+```bash
+pip install 'tether-mcp[qr] @ git+https://github.com/Fino-wind/tether-mcp'
+```
+
+### 2. Bind your phone
+
+```bash
+tether-mcp bind
+```
+
+This generates a keypair on your machine and prints a QR code. In the Tether 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.
+
+### 3. Connect your agent
+
+**Claude Code** (one line):
+
+```bash
+claude mcp add tether-health -- uvx --from 'git+https://github.com/Fino-wind/tether-mcp' tether-mcp serve --transport stdio
+```
+
+**Claude Desktop** (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "tether-health": {
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/Fino-wind/tether-mcp", "tether-mcp", "serve", "--transport", "stdio"]
+    }
+  }
+}
+```
+
+Any other MCP client: run `tether-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 --from 'git+https://github.com/Fino-wind/tether-mcp' tether-mcp serve --transport stdio`
+
+Then just ask your agent: *“How did we sleep last night?”*
+
+## MCP tools (16)
+
+| Tool | Returns |
+|---|---|
+| `tether_status` | Local binding state (never exposes keys or tokens) |
+| `tether_start_binding` | A fresh QR binding payload for the iOS app to scan |
+| `tether_poll_binding` | One poll for the iOS authorization to complete binding |
+| `tether_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_*`; they were renamed in the 16-tool release since they return whichever owners' records this server holds, not specifically the partner's.)
+
+Reads are cache-first: decrypted records are cached locally (owner-only files, 600 s TTL, `TETHER_MCP_CACHE_TTL` to override) 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 (`tether-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.** Tether'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 Tether 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: [Tether — AI Health Sync](https://apps.apple.com/us/app/tether-ai-health-sync/id6759241985) · Bugs & feedback: [tether-community](https://github.com/Fino-wind/tether-community/issues)*
+
+<!-- mcp-name: io.github.fino-wind/tether -->

tether_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+tether_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=e6YRPkoYVJJ__Cu8PhSbj_i8w7fAnQxnX2fUswa58tw,1094
+tether_mcp_local/__init__.py,sha256=Osv-JZSy8d2Pkf7ZQ2B4ulIhVc7XhWZDeJgRmpiDezg,85
+tether_mcp_local/cache.py,sha256=f_FfwTus-ewMQC1zw-waxpOtRReQQVyZRdYhHG-mQy0,5643
+tether_mcp_local/cli.py,sha256=JwlSYUIox940-4_JiTc4dQNKN3hlriDpxybuPH84L34,22676
+tether_mcp_local/client.py,sha256=Pd_jzz7mtSOJi2dfkUD6o8TCJCYd1fUpjdFwOIqACEk,3810
+tether_mcp_local/crypto.py,sha256=l3jUXXBcSxDl98rJDn_VYdfrNoB93olR7XDjq2W_4Aw,9463
+tether_mcp_local/mcp_server.py,sha256=lY8we04cGDpBl-SPqeW7t9IjFF-KqnAJATm_W8Pd8cs,14150
+tether_mcp_local/service.py,sha256=52q4afTTMbbk6e9yYIsDB3U671OuO_UiQ1tYYIS7etE,80996
+tether_mcp_local/store.py,sha256=63M5Nm81d86W7ekzs5UG8a90stzZLGgKXsum4C8HfY4,10980
+tether_mcp-0.1.0.dist-info/METADATA,sha256=UWifwkkoGCF4hy8DmgGRO2aVPUQHgWysJ4E-kDscC6g,9442
+tether_mcp-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+tether_mcp-0.1.0.dist-info/entry_points.txt,sha256=CCu044oVcIax7pgxSHpMS0hiY590iyIg178U2m_pUeg,102
+tether_mcp-0.1.0.dist-info/top_level.txt,sha256=ssiRFfAkXLgg4VUu0I8GKeN0Uk0MiBthhMZuhUDjT9c,17
+tether_mcp-0.1.0.dist-info/RECORD,,

tether_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

tether_mcp-0.1.0.dist-info/entry_points.txt

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

tether_mcp-0.1.0.dist-info/licenses/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.

tether_mcp-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+tether_mcp_local

tether_mcp_local/__init__.py

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

tether_mcp_local/cache.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+import json
+import logging
+import os
+import time
+from pathlib import Path
+from typing import Any
+
+from tether_mcp_local.store import write_secret_file
+
+_LOG = logging.getLogger("tether_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
+# TETHER_MCP_CACHE_TTL (seconds); 0 disables the cache entirely.
+DEFAULT_TTL_SECONDS = 600.0
+TTL_ENV = "TETHER_MCP_CACHE_TTL"
+
+
+def _ttl_from_env(default: float) -> float:
+    raw = os.getenv(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