pebble-index-mcp

MCP-Brücke, die einen lokalen Obsidian-Vault und eine Hermes-Agent-Instanz für die Doppelklick-MCP-Sandbox des Pebble Index 01 Smart Rings bereitstellt. Sprachaufnahmen vom Ring werden vom Cloud-Agenten der Pebble-App an die Tools dieses Servers weitergeleitet, und die Antwort kommt als Telefonbenachrichtigung zurück.

Architektur

[Index ring] → [Pebble app] → [Pebble cloud agent] → [this MCP server]
                                                        ├─ vault tools (local files)
                                                        └─ ask_hermes → Hermes API server

• Der Server spricht MCP über Streamable HTTP (offizielles mcp SDK, FastMCP).

• Jede Anfrage muss ein Bearer-Token enthalten; alles andere erhält 401.

• FastMCPs DNS-Rebinding-Schutz ist aktiv: erlaubte Hosts sind Loopback plus alles, was in MCP_ALLOWED_HOSTS aufgeführt ist.

• Die öffentliche Bereitstellung erfolgt über einen cloudflared-Tunnel zum Loopback-Port; darüber hinaus ist keine Cloud-Infrastruktur erforderlich.

Related MCP server: mcp-obsidian

Komponenten

Tools

• vault_search(query, max_results=5) — case-insensitiv Textsuche; gibt path: excerpt-Zeilen zurück.

• vault_read(note_path, max_chars=1500) — liest den Kopf einer Notiz.

• vault_append(note_path, text) — hängt eine mit Zeitstempel versehene - HH:MM text-Zeile an, erstellt die Notiz bei Bedarf.

• ask_hermes(question) — leitet an den Hermes-API-Server weiter; 60s Timeout mit einer ehrlichen Bestätigung bei Fehlschlag.

Sicherheit

• Auth: statisches Bearer-Token (MCP_BEARER_TOKEN), konstanten Zeitvergleich, bei jeder Anfrage erforderlich. Ein leeres Token schlägt fehl (alle Anfragen 401) und protokolliert eine Warnung beim Start.

• Transport: TLS endet am Tunnelrand; der Ursprung lauscht nur auf Loopback.

• Host-Validierung: DNS-Rebinding-Schutz lehnt Anfragen ab, deren Host-Header nicht Loopback oder in MCP_ALLOWED_HOSTS ist.

• Pfad-Sandbox: Vault-Tools lösen alle Pfade auf und verlangen, dass sie innerhalb des Vault-Roots bleiben; Symlink-Escapes werden abgelehnt und Dateiöffnungen verwenden O_NOFOLLOW auf der letzten Komponente. Die Sandbox schützt vor versehentlichem und remote Missbrauch; ein feindlicher lokaler Prozess, der einen Elternverzeichnis-Tausch gewinnt, kann immer noch gewinnen (dokumentierte TOCTOU-Grenze — der Vault wird als vertrauenswürdiges Einzelbenutzerverzeichnis angenommen).

• Konfiguration wird einmal beim Import gelesen: Das Rotieren des Bearer-Tokens oder das Ändern der erlaubten Hosts erfordert einen Neustart des Dienstes.

• Geheimnisse: Der Hermes-API-Schlüssel und das MCP-Token liegen in einer 0600-Env-Datei außerhalb dieses Repos, niemals in Code, Logs oder Commits.

• Datenschutzhinweis: Aufnahmen, die durch die Doppelklick-Sandbox geleitet werden, durchlaufen den Cloud-Agenten der Pebble-App. Einzelklick-Aufnahmen bleiben auf dem Gerät. Sensible Gedanken gehören zum Einzelklick.

Konfiguration (env)

HERMES_API_URL akzeptiert jeden OpenAI-kompatiblen Chat-Completions-Endpunkt, sodass ask_hermes direkt mit OpenRouter, Ollama oder jeder anderen kompatiblen API funktioniert — Hermes ist nur die Standardeinstellung.

Entwicklung

python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest -v

Lokal ausführen: Setzen Sie die obigen Umgebungsvariablen und führen Sie python -m pebble_index_mcp.server aus.

Bereitstellung

deploy/ enthält eine systemd-User-Unit-Vorlage und eine cloudflared-Tunnel-Vorlage (Hostname und Anmeldedaten werden auf dem Host ausgefüllt, nicht in diesem Repo). Siehe docs/ring-checklist.md für die Einrichtung auf der Telefonseite und die Testmatrix.

Lizenz

MIT — siehe LICENSE.