diff --git a/.gitignore b/.gitignore index 3422d4d..2a309ca 100644 --- a/.gitignore +++ b/.gitignore @@ -4,6 +4,7 @@ __pycache__/ tokens.json config.json .active_tokens.json +service_tokens.json *.before-* .token_audit.log *.bak-* diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..ffc6b71 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,209 @@ +# mcp-home + +Self-hosted MCP (Model Context Protocol) servers for the OpenClaw assistants (mycroft/jarvis). Provides access to personal data services via HTTP endpoints with OAuth (client_credentials). + +## Architecture + +8 independent MCP servers, each on its own port, bound to 0.0.0.0: + +- **Mail** (Port 5100) — searches IMAP backup Maildirs, reads attachments, creates drafts +- **Calendar** (Port 5101) — CalDAV against Baikal (Produktiv; Radicale-Fallback nur fuer Test-User mcptest) (events + tasks/reminders, travel time, geocoding, alarms) +- **Contacts** (Port 5102) — CardDAV against Baikal (Produktiv; Radicale-Fallback nur fuer Test-User mcptest) (contacts + photos) +- **Files** (Port 5103) — WebDAV against oCIS (full CRUD, images inline, documents as blobs) +- **Notes** (Port 5104) — Joplin Data API (notes + attachments) +- **OpenWearables** (Port 5105) — read-only Wearable-Daten (Sleep, Activity, Workouts, Timeseries) aus Open Wearables (`/opt/openwearables`), nur eigene Daten (s. u.) +- **Ghostfolio** (Port 5120) — Portfolio-Tracker via Ghostfolio-REST-API (Port 3333); read+write (Konten, Activities, Performance, Dividenden) +- **ActualBudget** (Port 5121) — Haushaltsbudget; read+write via Node-Sidecar `/opt/actualbudget-mcp/sidecar` (systemd `actualbudget-sidecar`, 127.0.0.1:5106) auf ActualBudget-Server (Port 5006) + +Zugriff intern (Standard): Die OpenClaw-Container (mycroft/jarvis) erreichen die Server +ueber das Docker-Gateway `172.26.0.1:/mcp` (openclaw-net). Die URLs stehen in den +Container-Configs `/mnt/ssd/openclaw//data/openclaw.json` (mcp.servers.*.url). + +Zugriff oeffentlich (seit 2026-09-18): notes, calendar, mail, contacts, files, openwearables, +ghostfolio und owamail sind zusaetzlich unter `https://.mcp.slohmaier.de/mcp` +erreichbar (nginx -> 127.0.0.1:, Let's-Encrypt-SAN, Rate-Limit auf /authorize+/token). +OpenClaw nutzt fuer diese die oeffentlichen URLs (bewusste Abweichung von der Regel "lokale +Routen", damit die Config bei einem Umzug unveraendert bleibt). Weitere Server bei Bedarf nach +demselben Muster (vhost + Cert-SAN). +Details: README.md, Abschnitt "Oeffentliche Endpunkte". + +Auth fuer oeffentliche Clients: OAuth (claude.ai) ODER nicht-ablaufende Service-Tokens +(`service_tokens.json`, Verwaltung `./mint-service-token.sh`); common.py prueft Service-Tokens +vor den OAuth-Access-Tokens. Zukunfts-Option OAuth/DCR (ChatGPT) siehe README.md. + +Firewall: iptables raw-PREROUTING blockt die Ports 5100-5105,5120,5121 fuer alle Quellen +ausserhalb `172.26.0.0/16` (openclaw-net). nginx erreicht die Ports via 127.0.0.1 (ACCEPT-Regel). +Regel in `/etc/iptables/rules.v4` (netfilter-persistent). + +### OpenWearables (Port 5105) + +Server: `/opt/mcp-servers/openwearables/server.py`, Config `/opt/mcp-servers/openwearables/config.json` +(chmod 600, enthaelt den gemeinsamen OpenWearables-API-Key und das User-ID-Mapping). + +Tools: `get_users`, `get_sleep_summary`, `get_activity_summary`, `get_workout_events`, `get_timeseries`. +Alle read-only, gegen die interne Open-Wearables-API (`http://127.0.0.1:8000`), NIE ueber Cloudflare. + +**User-Trennung (wichtig):** Der OpenWearables-API-Key ist GLOBAL (nicht pro User gescoped). Die +Trennung passiert im Server: `config.json` mappt den OAuth-User (`stefan`/`kati`) auf die jeweilige +OpenWearables-User-UUID (`user_id_map`). Die OpenWearables-User-ID wird IMMER aus dem Login des +Clients bestimmt, nie aus Tool-Argumenten. mycroft sieht also nur Stefans Daten, jarvis nur Katis. + +- MCP-Server in openclaw.json: `openwearables` -> `http://172.26.0.1:5105/mcp` +- systemd: `mcp-openwearables.service` + +All servers share `common.py` for OAuth + user resolution. + +## Auth Flow + +claude.ai uses OAuth 2.0 **Authorization Code + PKCE**. client_credentials is also supported (used by tests). + +1. claude.ai discovers `/.well-known/oauth-authorization-server` +2. `GET /authorize` → auto-approves valid client_id, redirects with code +3. `POST /token` (authorization_code + code_verifier, optional client_secret) → access_token +4. `Authorization: Bearer ` on MCP requests + +Access tokens are stored in a shared file `.active_tokens.json` so all 5 services validate tokens issued by any service. client_secret is verified at token exchange when provided. + +## User Separation + +`tokens.json` (not in git, chmod 600) maps client_id (`stefan`, `kati`, `test`) → secret. `USER_ALIASES` in `common.py` maps `test` → `stefan`. Each user sees only their own data; shared CalDAV calendars are visible to both. + +## Config + +- `tokens.json` — OAuth client_id/secret per user (gitignored) +- `config.json` — all backend credentials (Baikal + Radicale, oCIS, Joplin, IMAP), gitignored. See `config.json.example`. +- `.active_tokens.json` — runtime OAuth tokens (gitignored) + +## Backends + +- **Mail**: reads Maildirs under `/mnt/ssd/Backup/{stefan,kati}/imap/`. Drafts via IMAP APPEND (1blu / Gmail). +- **Calendar/Contacts**: Baikal CalDAV/CardDAV on `https://baikal.slohmaier.de` (Produktiv, seit 2026-09-11). Basen: + `dav.php/calendars//` und `dav.php/addressbooks//`; Baikal liefert hrefs pfad-absolut (`/dav.php/...`) und + calendar-data/address-data mit Namespace-Prefix `cal:`/`card:` — der Parser ist Namespace-agnostisch + (`(?:[a-zA-Z][a-zA-Z0-9_]*):calendar-data|address-data`). sabre inbox/outbox werden herausgefiltert. + Backend-Auswahl pro User ueber `_serve(user)`: User in `baikal_users` (stefan/kati = mycroft/jarvis) → Baikal; + andere (Test-User `mcptest`) → Radicale-Fallback `http://127.0.0.1:5232` (Radicale laeuft weiter fuer Tests, + mirror-first bis Geraete-Umstellung abgeschlossen). Radicale-URL/Creds/Pfade bleiben in `config.json` + (`radicale_url`, `radicale_users`, `radicale_calendar_paths`, `radicale_addressbook_paths`). +- **Files**: oCIS WebDAV on `127.0.0.1:9200/remote.php/dav/files//`. oCIS username may differ from MCP user (mapping in config). +- **Notes**: Joplin **Data API** via joplin-cli sync clients on `127.0.0.1:41184` (stefan) / `41185` (kati). See `/opt/joplin-mcp/README.md`. NOT the Joplin Server sync API (that has no clean REST/search). +- **Ghostfolio**: Ghostfolio-REST-API on `127.0.0.1:3333` (JWT-Token `/opt/ghostfolio/migration/.auth-token`). Read+write. +- **ActualBudget**: Node-Sidecar (`/opt/actualbudget-mcp/sidecar`, systemd `actualbudget-sidecar`) on `127.0.0.1:5106` (RPC), der `@actual-app/api` kapselt und den ActualBudget-Server (Port 5006) anspricht. + +## Files + +- `common.py` — OAuth (authorize/token/metadata), Bearer middleware, user resolution (contextvars), config loader +- `mail/server.py` — Maildir reader; tools: list_accounts, list_folders, search_mail, read_mail (lists attachments), read_attachment, create_draft +- `calendar/server.py` — CalDAV REPORT + vobject; events/tasks CRUD, travel time, geocoding, reminders. Timed events/tasks werden mit TZID=Europe/Berlin (pytz) geschrieben (naive Eingaben lokalisiert, Offsets/Z konvertiert; Bugfix 2026-09-30, vorher floating -> Baikal las +2h). Delete/Update loesen den echten Ressourcenpfad per UID auf (`_find_href`), da der Dateiname nicht die UID sein muss (Importe wie medatixx). +- `contacts/server.py` — CardDAV; search/get/create, contact photos +- `files/server.py` — WebDAV; list/read/write/delete/move/search, images + documents +- `notes/server.py` — Joplin Data API; list/search/read/create notes, list_note_resources, read_resource, add/update/delete_attachment +- `ghostfolio/server.py` — Ghostfolio-REST-API; portfolio_details, get_performance, get_dividends, list_accounts, create_account, import_activities, list_activities, delete_activity. Schreib-Tools stoessen automatisch `update-report.sh` an -> accessible-dashboard-Report wird sofort neu gebaut (Details im ghostfolio/README) +- `actualbudget/server.py` — Node-Sidecar-RPC; budgets/accounts/transactions/categories/budget/payees CRUD + aql_query +- `tests/` — Schichten: `test_smoke.py` (NIGHTLY via `mcp-tests.timer`, nur up+Auth+1 Read/Connector), `test_edge.py`+`test_stress.py`+`test_all.py` (ON-DEMAND via `run_full_tests.sh`). Doku `tests/MCPTEST.md` + +## Dependencies + +``` +pip install mcp[cli] httpx vobject python-dateutil pytest +``` + +Python 3.12+, venv at `./venv/`. joplin-cli (npm global) for Notes backend. + +## Deployment + +Each server is a systemd unit `mcp-.service` (uvicorn), bound to 0.0.0.0. Zugriff intern via openclaw-net (172.26.0.1:/mcp); einzelne Server zusaetzlich oeffentlich via nginx/TLS (notes/calendar, s. o.). Joplin: `joplin-cli-{stefan,kati}.service` + `joplin-sync.timer` (15 min). + +## Content Types (returning binary) + +- Text → `TextContent` +- Images (jpg/png/gif/webp) → `ImageContent` (base64 inline) +- PDFs → server-seitig zu Text extrahiert bzw. gescannte Seiten als PNG+OCR gerendert (`pdfutil.py`). claude.ai nimmt KEINE PDF/Dokument-Blobs aus Tool-Results nativ entgegen (nur Text + Bild). Andere Binaerdateien → `EmbeddedResource`/`BlobResourceContents` (Blob; wird von claude.ai nicht als Dokument verarbeitet) + +## Robustheit / Limits + +Alle Such-/List-Tools sind gegen grosse Datenmengen abgesichert (single-threaded Server darf nicht haengen): Mail per-Mail try/except + `DEADLINE_S`/`MAX_SCAN`; Files `search_files` `SEARCH_DEADLINE_S`/`SEARCH_MAX_DIRS`; Calendar/Contacts `PARSE_DEADLINE_S` + `MAX_RESULTS`-Output-Cap. Details + Messwerte: `tests/MCPTEST.md`. + +## Adding a New Service + +1. `/server.py` with `FastMCP` instance + `create_app()` (copy mail/server.py pattern) +2. Import `get_current_user`, `OAUTH_ROUTES`, `BearerAuthMiddleware`, `load_config` from `common.py` +3. systemd unit `mcp-.service` (bind 0.0.0.0) + iptables-Regel fuer den Port (nur openclaw-net 172.26.0.0/16) + URL in den Container-Configs eintragen +4. systemd unit `mcp-.service` +5. Backend creds in `config.json` +6. Tests: Smoke-Read in `test_smoke.py` + Edge in `test_edge.py` + Stress in `test_stress.py` (Funktional in `test_all.py`); Dashboard + dieses File aktualisieren + +## Tool Design Guidelines + +- Docstring is the first thing Claude sees — make it actionable ("Call this first", "Use the UID from search results") +- `Annotated[str, Field(description="...")]` with example values for every parameter +- Mark optional params ("Leave empty for all") +- Reference other tools ("Use read_attachment with the index from read_mail") +- Return structured text, not JSON +- Include IDs/keys in output so Claude can chain to detail tools + +## Test-/Dev-User mcptest + +Die Test-Suite laeuft auf einem isolierten `mcptest`-User (NICHT Stefans Daten): +`USER_ALIASES = {"test": "mcptest"}`. Eigene Backends: Radicale-User mcptest (Calendar/Contacts laufen ueber den +Radicale-Fallback in `_serve(user)`, da es keinen Baikal-mcptest gibt), oCIS-User +mcptest, lokales Joplin-Profil (:41186, `joplin-cli-mcptest.service`), Test-Maildir +`tests/testdata/maildir/`. Dient auch als Dev-Sandbox. Vollstaendige Doku + Provisioning: +`tests/MCPTEST.md`. Creds: `/root/.mcptest-creds` (600) + `config.json`. + +## User nova (stefan@slohmaier.com, fuer OpenClaw-Agent Nova) + +Nova (Agent im mycroft-Gateway) braucht Business-Mails statt Stefans privater .de-Mails. +Dafuer: +- tokens.json: User `nova` mit eigenem Client-Secret (token). +- config.json mail_roots.nova -> `/mnt/ssd/Backup/stefan/nova-imap` (Symlink auf das + .com-Maildir d370128_0-stefanlohmaier). Nova sieht damit NUR das .com-Postfach. +- Im mycroft-Gateway gibt es einen zusaetzlichen MCP-Server `mail-com` (Bearer des nova- + Users) auf demselben Port 5100. Nova nutzt mail-com, Mycroft nutzt `mail` (.de). +- Zugriffstoken fuer nova per `mcp-token-refresh`-Mechanik oder manuell: + POST /token client_credentials mit client_id=nova + secret aus tokens.json. + +## Calendar: Namens-Aufloesung (exakt vor Teilstring) + +Seit 2026-08-20 loest `_match_cols` Kalender-/Listen-Namen bei allen +Schreib-/Loesch-Operationen (create_event, create_task, delete_event, +delete_task) so auf: exakter Namens-Treffer zuerst, sonst Teilstring. +Grund: Die Shared-Kalender "Kati Stefan" (beschreibbar) und "Kati Stefan +JaSi" (read-only, Google-Sync) kollidierten bei Teilstring-Match — ein PUT +auf "Kati Stefan" traf sonst den read-only JaSi-Kalender (HTTP 403), obwohl +der User (kati/stefan) Schreibrechte auf den richtigen Kalender hat. + +## Calendar: Loeschen + +Der Calendar-MCP hat seit 2026-08-13 `delete_event` und `delete_task` (Loeschen per UID). +UID kommt aus `get_events` / `get_tasks`. Loeschung direkt via CalDAV an das aktive Backend (Baikal fuer stefan/kati, +Radicale-Fallback fuer mcptest). + +## Mail-Drafts mit Anhang + +`create_draft` unterstuetzt seit 2026-08-13 Anhaenge ueber Base64: +- `attachment_filenames` (Liste), `attachment_contents` (Liste, Base64-kodierte Bytes), + optional `attachment_mimetypes` (Liste; sonst application/octet-stream). +- Der Agent erzeugt einen mehrteiligen (multipart) Draft im IMAP-Drafts-Ordner. +- Test ok: "Entwurf erstellt mit 1 Anhang/Anhaengen". + +## Notes: Anhaenge (Attachments) + +Der Notes-MCP kann seit 2026-09-16 Anhaenge an Notizen anlegen, aendern und +loeschen (vorher nur lesen: `list_note_resources` / `read_resource`): + +- `add_attachment(note_id, filename, content_base64, mime?, title?)` — laedt die + Datei via `POST /resources` hoch (multipart/form-data: Datei im Feld `data`, + Properties als JSON im Feld `props`) und haengt `[title](:/resourceId)` ans + Ende des Notiz-Bodys an (bei Bildern `![...]`, damit es inline rendert). + Max 25 MB; Inhalt Base64 (data-URL-Prefix und Zeilenumbrueche erlaubt). +- `update_attachment(resource_id, content_base64?, filename?, mime?, title?)` — + ersetzt den Datei-Inhalt (`PUT /resources/:id`, multipart) und/oder aendert + Titel/MIME (JSON-PUT, wenn kein Inhalt uebergeben wird). +- `delete_attachment(resource_id, note_id?, remove_links?)` — loescht das + Resource endgueltig (Joplin hat fuer Resources keinen Papierkorb) und entfernt + die Markdown-/HTML-Referenzen aus dem Notiz-Body. `note_id` angeben, damit der + Link sicher bereinigt wird: Joplins Endpoint `/resources/:id/notes` ist + unzuverlaessig (Link-Tabelle kann leer bleiben, dann bliebe der Link verwaist). +- MIME wird aus der Dateiendung geraten, wenn nicht uebergeben. +- Getestet in `tests/test_all.py::TestNotes::test_attachment_crud` (mcptest). diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 4fc5dc6..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1,101 +0,0 @@ -# mcp-home - -Self-hosted MCP (Model Context Protocol) servers for Claude. Provides access to personal data services via remote HTTP endpoints with OAuth (Authorization Code + PKCE, and client_credentials). - -## Architecture - -5 independent MCP servers, each on its own subdomain + port: - -- **Mail** (`mail.mcp.home.slohmaier.de`, Port 5100) — searches IMAP backup Maildirs, reads attachments, creates drafts -- **Calendar** (`calendar.mcp.home.slohmaier.de`, Port 5101) — CalDAV against Radicale (events + tasks/reminders, travel time, geocoding, alarms) -- **Contacts** (`contacts.mcp.home.slohmaier.de`, Port 5102) — CardDAV against Radicale (contacts + photos) -- **Files** (`files.mcp.home.slohmaier.de`, Port 5103) — WebDAV against oCIS (full CRUD, images inline, documents as blobs) -- **Notes** (`notes.mcp.home.slohmaier.de`, Port 5104) — Joplin Data API (notes + attachments) - -Each subdomain is its own nginx vhost proxying to the local port. All servers share `common.py` for OAuth + user resolution. - -## Auth Flow - -claude.ai uses OAuth 2.0 **Authorization Code + PKCE**. client_credentials is also supported (used by tests). - -1. claude.ai discovers `/.well-known/oauth-authorization-server` -2. `GET /authorize` → auto-approves valid client_id, redirects with code -3. `POST /token` (authorization_code + code_verifier, optional client_secret) → access_token -4. `Authorization: Bearer ` on MCP requests - -Access tokens are stored in a shared file `.active_tokens.json` so all 5 services validate tokens issued by any service. client_secret is verified at token exchange when provided. - -## User Separation - -`tokens.json` (not in git, chmod 600) maps client_id (`stefan`, `kati`, `test`) → secret. `USER_ALIASES` in `common.py` maps `test` → `stefan`. Each user sees only their own data; shared CalDAV calendars are visible to both. - -## Config - -- `tokens.json` — OAuth client_id/secret per user (gitignored) -- `config.json` — all backend credentials (Radicale, oCIS, Joplin, IMAP), gitignored. See `config.json.example`. -- `.active_tokens.json` — runtime OAuth tokens (gitignored) - -## Backends - -- **Mail**: reads Maildirs under `/mnt/ssd/Backup/{stefan,kati}/imap/`. Drafts via IMAP APPEND (1blu / Gmail). -- **Calendar/Contacts**: Radicale CalDAV/CardDAV on `127.0.0.1:5232`. Note: Radicale uses default `DAV:` namespace (no `d:` prefix) and `CR:` for CardDAV — regex must match both. -- **Files**: oCIS WebDAV on `127.0.0.1:9200/remote.php/dav/files//`. oCIS username may differ from MCP user (mapping in config). -- **Notes**: Joplin **Data API** via joplin-cli sync clients on `127.0.0.1:41184` (stefan) / `41185` (kati). See `/opt/joplin-mcp/README.md`. NOT the Joplin Server sync API (that has no clean REST/search). - -## Files - -- `common.py` — OAuth (authorize/token/metadata), Bearer middleware, user resolution (contextvars), config loader -- `mail/server.py` — Maildir reader; tools: list_accounts, list_folders, search_mail, read_mail (lists attachments), read_attachment, create_draft -- `calendar/server.py` — CalDAV REPORT + vobject; events/tasks CRUD, travel time, geocoding, reminders -- `contacts/server.py` — CardDAV; search/get/create, contact photos -- `files/server.py` — WebDAV; list/read/write/delete/move/search, images + documents -- `notes/server.py` — Joplin Data API; list/search/read/create notes, list_note_resources, read_resource -- `tests/` — Schichten: `test_smoke.py` (NIGHTLY via `mcp-tests.timer`, nur up+Auth+1 Read/Connector), `test_edge.py`+`test_stress.py`+`test_all.py` (ON-DEMAND via `run_full_tests.sh`). Doku `tests/MCPTEST.md` - -## Dependencies - -``` -pip install mcp[cli] httpx vobject python-dateutil pytest -``` - -Python 3.12+, venv at `./venv/`. joplin-cli (npm global) for Notes backend. - -## Deployment - -Each server is a systemd unit `mcp-.service` (uvicorn). Each subdomain is an nginx vhost with rate-limited `/authorize` + `/token`. TLS via Certbot (shared cert on mail.mcp...). Joplin: `joplin-cli-{stefan,kati}.service` + `joplin-sync.timer` (15 min). - -## Content Types (returning binary) - -- Text → `TextContent` -- Images (jpg/png/gif/webp) → `ImageContent` (base64 inline) -- PDFs → server-seitig zu Text extrahiert bzw. gescannte Seiten als PNG+OCR gerendert (`pdfutil.py`). claude.ai nimmt KEINE PDF/Dokument-Blobs aus Tool-Results nativ entgegen (nur Text + Bild). Andere Binaerdateien → `EmbeddedResource`/`BlobResourceContents` (Blob; wird von claude.ai nicht als Dokument verarbeitet) - -## Robustheit / Limits - -Alle Such-/List-Tools sind gegen grosse Datenmengen abgesichert (single-threaded Server darf nicht haengen): Mail per-Mail try/except + `DEADLINE_S`/`MAX_SCAN`; Files `search_files` `SEARCH_DEADLINE_S`/`SEARCH_MAX_DIRS`; Calendar/Contacts `PARSE_DEADLINE_S` + `MAX_RESULTS`-Output-Cap. Details + Messwerte: `tests/MCPTEST.md`. - -## Adding a New Service - -1. `/server.py` with `FastMCP` instance + `create_app()` (copy mail/server.py pattern) -2. Import `get_current_user`, `OAUTH_ROUTES`, `BearerAuthMiddleware`, `load_config` from `common.py` -3. nginx vhost `.mcp.home.slohmaier.de` + Certbot -4. systemd unit `mcp-.service` -5. Backend creds in `config.json` -6. Tests: Smoke-Read in `test_smoke.py` + Edge in `test_edge.py` + Stress in `test_stress.py` (Funktional in `test_all.py`); Dashboard + dieses File aktualisieren - -## Tool Design Guidelines - -- Docstring is the first thing Claude sees — make it actionable ("Call this first", "Use the UID from search results") -- `Annotated[str, Field(description="...")]` with example values for every parameter -- Mark optional params ("Leave empty for all") -- Reference other tools ("Use read_attachment with the index from read_mail") -- Return structured text, not JSON -- Include IDs/keys in output so Claude can chain to detail tools - -## Test-/Dev-User mcptest - -Die Test-Suite laeuft auf einem isolierten `mcptest`-User (NICHT Stefans Daten): -`USER_ALIASES = {"test": "mcptest"}`. Eigene Backends: Radicale-User mcptest, oCIS-User -mcptest, lokales Joplin-Profil (:41186, `joplin-cli-mcptest.service`), Test-Maildir -`tests/testdata/maildir/`. Dient auch als Dev-Sandbox. Vollstaendige Doku + Provisioning: -`tests/MCPTEST.md`. Creds: `/root/.mcptest-creds` (600) + `config.json`. diff --git a/README.md b/README.md index 42eba77..df812e7 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,72 @@ -# mcp-home Self-hosted [MCP](https://modelcontextprotocol.io) servers for Claude. Gives Claude access to your email, calendar, contacts, files, and notes — all running on your own hardware, behind OAuth. ## Services & Tools -- **Mail** — `list_accounts`, `list_folders`, `search_mail` (full text), `read_mail` (lists attachments), `read_attachment` (image/PDF/text), `create_draft` +- **Mail** — `list_accounts`, `list_folders`, `search_mail` (full text), `read_mail` (lists attachments), `read_attachment` (image/PDF/text), `download_attachment` (Anhang als Datei ins Agent-Workspace), `create_draft` + - **download_attachment (2026-09-04):** schreibt den Anhang (account/folder/key aus search_mail, Index aus read_mail) als echte Datei ins Workspace des Agenten (mycroft/jarvis) und gibt den Container-Pfad zurueck. Zielverzeichnis pro User in `config.json` unter `mail_attachment_dirs` (host + container Pfad; mycroft: `/mnt/ssd/openclaw/mycroft/data/workspace/mail-attachments` -> `/home/node/.openclaw/workspace/mail-attachments`). UID 1000 (stefan/node) identisch, keine Permissions-Probleme. Kollisionen bekommen Suffix ` (1)`. Sinn: Der Agent kann den Anhang mit seinen Datei-/Shell-Tools weiterverarbeiten, nicht nur inline ansehen. + - **read_mail/read_attachment/download_attachment Key-Fix (2026-09-09):** Der FTS-Index speichert den vollen Maildir-Dateinamen inkl. Dovecot-Flags-Suffix (`...:2,T`), waehrend Python `mailbox.Maildir` als Key nur den Teil vor `:2,` nutzt. Dadurch schlug `read_mail` mit "Message not found" fehl, obwohl `search_mail` die Mail fand (betrifft alle Clients: OpenClaw + Hermes). Fix in `server.py`: `_norm_key(key)` schneidet das `:2,...`-Suffix ab und wird in `read_mail`, `read_attachment`, `download_attachment` angewandt. Backup: `server.py.bak-maileade-20260909`. + - **Nova .com voll in Betrieb (2026-09-10):** `imap_passwords.nova` + `IMAP_ACCOUNTS['nova']` (imap.1blu.de, user `d370128_0-stefanlohmaier`) ergaenzt. Verifiziert per Bearer per User: `stefan` sieht nur `d370128_0-slohmaier` (.de), `nova` nur `d370128_0-stefanlohmaier` (.com), `kati` nur `akpolke@gmail.com`. Real-Login gegen imap.1blu.de ok. Backups: `config.json.bak-novacom-20260910-110015`, `server.py.bak-novacom-20260910-*`. + - **create_draft Gmail-Quoting-Fix (2026-09-11):** `create_draft` fuer Katis Gmail-Account schlug mit `IMAP-Fehler: APPEND command error: BAD [b'Could not parse command']` fehl. Ursache: Python-imaplib quotet den Ordnernamen bei `append()`/`select()` mit Literal-Syntax ({n}) NICHT; Gmail bricht bei Ordnernamen mit Sonderzeichen ab (Drafts-Ordner `[Google Mail]/Entw&APw-rfe` enthaelt `&` und `[]`). Fix: Helper `_imap_quote_folder()` in `server.py`, der Ordnernamen mit Sonderzeichen (` &[]\\"`) in doppelte Anführungszeichen setzt und beim `append` anwendet. 1blu-Accounts (stefan/nova, `Drafts`) bleiben unquotiert. Verifiziert: echter APPEND an Gmail-Drafts mit gequotetem Namen -> OK, Test-Draft danach wieder geloescht. Backup: `server.py.bak-20260911-095326`. + - **Account-Isolierung pro Agent (2026-09-09):** `server.py` filtert die sichtbaren Mail-Accounts je User via Config `mail_account_allow` (config.json): `stefan` (mycroft/.de) -> nur `d370128_0-slohmaier`; `nova` (.com) -> nur `d370128_0-stefanlohmaier`. `_discover_accounts` wendet den Filter fuer alle Tools an (list/search/read/attachment). Fuer nova liegt der .com-Account als Symlink in `/mnt/ssd/Backup/stefan/nova-imap/`; `index_maildirs.py`/`_discover_folders` nutzen `os.walk(..., followlinks=True)`, damit Volltext-Index und Ordner-Scan den Symlink durchlaufen. Config-Backup: `config.json.bak-20260909`. + - **Volltextindex (2026-09-03):** `search_mail` nutzt einen SQLite-FTS5-Index statt des + Maildir-Vollscans (der bei Katis Gmail-Archiv, 16 GB / ~30k Mails, das Gateway-Request-Timeout + sprengte). Index-DBs: `/var/lib/mail-index/.sqlite` (stefan, kati, nova, mcptest); + Build/Update: `/opt/mcp-servers/mail/index_maildirs.py`, getaktet via `mail-index.timer` + (alle 5 Min, versetzt zum mail-backup.timer). Such-Strategie: FTS5-Prefix-Treffer auf + sender/to/subject/body; E-Mail-Adressen (mit @) ueber LIKE. Erst-Build bereit, wenn + `.ready` existiert; ohne ready faellt `search_mail` auf den alten Scan zurueck. + - **Ungelesene Mails im Maildir-`new/` (2026-09-26):** mbsync legt Gmail-Mails ohne + `\Seen`-Flag in `/new/` ab (nicht `cur/`). Index und `_discover_folders` sahen + aber nur `cur/` -> jede ungelesene Mail war fuer `search_mail` unsichtbar (kati 762, + stefan 577, nova 960 zusaetzliche Mails; neueste zuerst betroffen). Fix: + `mailindex.py::update_user` walkt jetzt `cur` **und** `new`; `server.py::_discover_folders` + akzeptiert Ordner mit `cur` oder `new`. `_parse_file`/`_norm_key` waren bereits + pfad-korrekt, `read_mail` funktionierte (Maildir vereint new+cur). Verifiziert per + MCP-Call als kati (`search_mail`/`read_mail` auf eine neue `new/`-Mail), Index-Neuaufbau + korrekt, `test_smoke.py` gruen und `test_all.py`+`test_edge.py` 96 passed. Backups: + `mailindex.py.bak-newdir-*`, `server.py.bak-newdir-*`, `kati.sqlite.bak-newdir-*`. - **Calendar + Tasks** — `list_calendars`, `get_events`, `search_events`, `list_task_lists`, `get_tasks`, `create_event` (travel time + geocoding + reminders), `create_task` + - **Zeitzonen-Fix (2026-09-30):** Timed-Events/Tasks wurden ohne TZID (floating) geschrieben; Baikal las sie als UTC, in der CalDAV-Suite +2h verschoben. Jetzt: naive Eingaben werden als `Europe/Berlin` lokalisiert (pytz), explizite Offsets/`Z` konvertiert. Betroffen waren alle per MCP angelegten Timed-Termine; per Einmal-Skript (alle stefan/kati-Kalender) auf TZID umgeschrieben. Anzeige normalisiert aware Zeiten nach Berlin. `delete_event`/`update_event`/`delete_task`/`update_task` loesen den echten Ressourcenpfad per UID auf (`_find_href`), da der `.ics`-Dateiname bei Importen (medatixx) nicht die UID ist (Delete lief sonst ins Leere, Update erzeugte Duplikate). - **Contacts** — `search_contacts`, `get_contact` (with photo), `create_contact`, `set_contact_photo` - **Files** — `list_files`, `read_file` (image/document/text), `file_info`, `search_files`, `write_file`, `create_folder`, `delete_file`, `move_file` + - **URL-Pfad-Encoding-Fix (2026-09-11):** `_dav()` setzte User-Pfade roh in die WebDAV-URL. httpx encodiert Leerzeichen/Umlaute automatisch, aber `#` (wurde Fragment) und `?` (wurde Query-Start) im Dateinamen zerlegten die URL; ein literales `%` erzeugte Ambiguitaet mit bereits-encodierten `%XX`-Sequenzen (oCIS liefert hrefs wie `Entw%C3%BCrfe` zurueck). Fix: `_enc_path()` in `server.py` encodiert `#`->`%23`, `?`->`%3F` und `%` nur ausserhalb gueltiger `%XX`-Folgen (roundtrip-sicher). Anwendung zentral in `_dav()` -> wirkt auf alle 7 Datei-Tools. Verifiziert ueber mcptest-Account (Dateien mit `#`/`%`/`?`/Umlaut/Leerzeichen anlegen/lesen/loeschen) + neuer Edge-Test `test_url_special_chars_roundtrip`. Backup: `files/server.py.bak-20260911-113635`. - **Notes** — `list_notebooks`, `list_notes`, `search_notes`, `read_note`, `create_note`, `list_note_resources`, `read_resource` (attachments) +- **Ghostfolio** — `portfolio_details`, `get_performance`, `get_dividends`, `list_accounts`, `create_account`, `import_activities`, `list_activities`, `delete_activity` (Portfolio-Tracker) + - **Kaltstart-Latenz (2026-09-11):** Der erste MCP-Call nach laengerer Inaktivitaet kann 6-26 s dauern (Ghostfolio laedt dann historische Wechselkurse ueber `ExchangeRateDataService`, z.B. AUDEUR ab 2023, von externen Quellen). Warm sind Calls 0.6-1 s. Kein Bug -- der naechtliche Smoke-Test (05:00) lief in diesem Kaltfenster und ueberschritt das 60-s-Timeout. Test-Timeout fuer ghostfolio auf 180 s erhoeht (test_smoke.py). + +## owamail (BBS-Postfach, Port 5131) + +Separater MCP-Server fuer Katis BBS-Arbeitsmail (Exchange 2019, S25-EXCHANGE, +https://bbsbex.bbsb.org/owa/). Tools: `login`, `list_folders`, `search_mail`, +`read_mail`, `download_attachments` (Anhaenge via GetFileAttachment ins +jarvis-Workspace owa-attachments), `create_draft` (Entwurf im Drafts-Ordner, +KEIN Senden). + +- **Implementierung (2026-09-11):** Nutzt den klassischen OWA-Formular-Login + (POST /owa/auth.owa, Sperrschutz: GENAU EIN Login-Versuch, kein Retry -- Katis + Arbeitspasswort darf nie durch Auto-Wiederholungen gesperrt werden) und die interne + OWA-JSON-API: POST /owa/service.svc?action=&EP=1&ID=-1&AC=1 mit Action-Header, + X-OWA-CANARY und Exchange-JSON-Payloads. API-Muster aus + https://github.com/nhype/owa-exchange-mcp (MIT, Referenz unter + /opt/mcp-servers/owamail/vendor/exchange_mcp/). Systemd `mcp-owamail` (Port 5131). + EWS-Basic-Auth ist serverseitig deaktiviert (401), IMAP/POP3-Ports sind von aussen zu -- + daher nur ueber die OWA-API. Nicht mit dem mail-Server (5100, Gmail/1blu) verwechseln. + Zugriff: Katis Bearer (client_id `kati`) im jarvis-openclaw.json unter `mcp.servers.owamail` + (http://172.26.0.1:5131/mcp). Nur User `kati`/`mcptest` duerfen die Tools (ALLOWED_USERS), + andere Bearer werden abgewiesen. +- **Sicherheit:** Credentials in /opt/mcp-servers/owamail/auth.txt (chmod 600). Der Server + bindet nur an localhost; Zugriff ueber Bearer-Auth (OAuth client_credentials). +- **Gemeinsamer Client (2026-09-16):** Login/API-Transport liegt in + `owamail/owa_client.py` (Klasse `OWAClient`, Modul-Instanz `client`). `server.py` + importiert daraus; der Kalender-Fetcher `/opt/owa-kati-calendar/owa_fetch.py` + nutzt denselben Client (Einweg-Sync Katis Arbeitskalender -> Baikal "Arbeit", + stuendlich). Aenderungen am Client betreffen beide -> `mcp-owamail.service` neu starten. +- **Vollständige Mail-Abdeckung (2026-09-11):** `search_mail` unterstuetzt Offset-Paging + (`offset`/`limit`, zeigt "Ordner hat N Mails; mehr vorhanden (Offset X)") -- damit erreicht + Jarvis auch die aeltesten Mails eines Ordners (Inbox: ~3700+ bis 2023, Archiv: bis 2024). + Zusaetzlich `scan_all=true` mit Suchbegriff: blaettert automatisch durch bis 2000 Mails und + findet alte Treffer (z.B. Betriebsrats-Newsletter 2025), ohne manuelles Paging. ## Setup @@ -21,6 +79,8 @@ cp config.json.example config.json # set backend credentials Notes needs joplin-cli sync clients exposing the Data API (see `/opt/joplin-mcp/`). +Ghostfolio braucht das JWT-Token in `/opt/ghostfolio/migration/.auth-token`. + ## Usage with claude.ai Settings → Integrations → Custom MCP Server: @@ -39,6 +99,93 @@ venv/bin/python -m pytest tests/test_all.py -v 54 integration tests (OAuth, all tools, CRUD in isolated test collections). Run daily via `mcp-tests.timer`. +## Fix 2026-09-06: actualbudget-Test aus Smoke entfernt + +Der Smoke-Test (`test_smoke.py`) und `SERVERS` in `test_all.py` referenzierten einen +`actualbudget`-MCP-Server auf Port 5121, der nie existiert (kein Verzeichnis, keine +systemd-Unit, kein Prozess — verworfen). Folge: der +naechtliche `mcp-tests.timer` schlug jede Nacht mit 2 failed auf (aktualbudget-read + +server_up), was die urgent-NTFY "MCP Smoke-Tests fehlgeschlagen" ausloeste. actualbudget +aus `SERVERS` und `test_actualbudget_read` entfernt -> Smoke laeuft wieder gruen +(12 passed). Backups: `tests/test_all.py.bak-20260906`, `tests/test_smoke.py.bak-20260906`. + +## Oeffentliche Endpunkte (2026-09-18) + +Oeffentlich erreichbar (nginx -> 127.0.0.1:, Let's-Encrypt-SAN, Rate-Limit +`mcp_auth` auf `/authorize` und `/token`): + +- https://notes.mcp.slohmaier.de/mcp (Notes, 5104) +- https://calendar.mcp.slohmaier.de/mcp (Calendar, 5101) +- https://mail.mcp.slohmaier.de/mcp (Mail, 5100; deckt auch den nova/.com-Bearer ab) +- https://contacts.mcp.slohmaier.de/mcp (Contacts, 5102) +- https://files.mcp.slohmaier.de/mcp (Files, 5103) +- https://openwearables.mcp.slohmaier.de/mcp (OpenWearables, 5105) +- https://owamail.mcp.slohmaier.de/mcp (OWA Mail, 5131; nur kati/mcptest) + +- DNS: Wildcard `*.mcp.slohmaier.de` (1blu) -> home.slohmaier.de -> poloschwabing.home64.de +- Cert: zentrales `akpo.slohmaier.de` (SAN-Liste, HTTP-01 webroot). Neue Hosts dort ergaenzen: + `certbot certonly --webroot -w /var/www/html --cert-name akpo.slohmaier.de --expand -d -d ` +- nginx: `/etc/nginx/sites-available/.mcp.slohmaier.de` (Symlink in sites-enabled) +- iptables unveraendert: nginx erreicht die Ports via 127.0.0.1 (ACCEPT-Regel), kein direkter Port. +- **Ghostfolio-MCP (5120) am 2026-09-18 entfernt** (0 Tool-Calls in 7 Tagen; vhost deaktiviert, + unit disabled). Portfolio weiter ueber die REST-API `https://portfolio.slohmaier.de`. + +### Auth: OAuth + nicht-ablaufende Service-Tokens + +1. OAuth 2.0 Authorization Code + PKCE (claude.ai), client_id/secret aus `tokens.json`. +2. Service-Tokens fuer Maschinen-Clients (opencode, Skripte), die einen statischen + `Authorization: Bearer`-Header setzen. Ablage: `service_tokens.json` + (`{"": {"user": "stefan", "label": "opencode-polo"}}`), chmod 600. + `common.py` prueft Service-Tokens in `_resolve_access_token()` vor den OAuth-Access-Tokens + (konstanter Vergleich via `secrets.compare_digest`), sie laufen nie ab. Widerruf = `rm`. + Verwaltung: `./mint-service-token.sh add