Files
mcp-home/README.md
T

193 lines
16 KiB
Markdown

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), `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/<user>.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
`<user>.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 `<folder>/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).
- **Auslands-Zeitzonen (2026-10-01):** `create/update_event` + `create/update_task` haben ein `timezone`-Argument (IANA, Default `Europe/Berlin`). Fuer Termine im Ausland (z.B. Hongkong) `timezone="Asia/Hong_Kong"` setzen und die lokale Ortszeit eintragen; gespeichert wird `TZID=Asia/Hong_Kong`, die Ausgabe zeigt den passenden Offset (`+08:00`). Ungueltige Zonen liefern einen klaren Fehler. Naive Zeiten ohne `timezone` bleiben Europe/Berlin.
- **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=<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
```bash
python3 -m venv venv
venv/bin/pip install mcp[cli] httpx vobject python-dateutil pytest
cp tokens.json.example tokens.json # set OAuth client secrets
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:
- **URL**: `https://<service>.mcp.your-domain/mcp` (mail, calendar, contacts, files, notes)
- **OAuth Client ID**: your username (e.g. `stefan`)
- **OAuth Client Secret**: from `tokens.json`
claude.ai runs the OAuth Authorization Code + PKCE flow automatically.
## Tests
```bash
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:<port>, 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 <alle> -d <neu>`
- nginx: `/etc/nginx/sites-available/<name>.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`
(`{"<token>": {"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 <user> <label> | rm <label> | list`.
### Raw-Endpunkte (Rohdateien/Binaer, token-geschuetzt)
Fuer beliebige Binaerdateien/-groessen (ersetzen Direkt-Mounts/rclone). Auth ueber dieselbe
`BearerAuthMiddleware` (Service-Token oder OAuth), kein anonymer Zugriff:
- files: `GET /raw?path=<ocis>` (Download, gestreamt) und `PUT /raw?path=<ocis>` (Upload, Body = Rohbytes)
- mail: `GET /raw?account=&folder=&key=&index=` (roher Anhang, Content-Disposition)
- notes: `GET /raw?resource_id=<id>` (roher Resource); Upload/Ersetzen: `PUT /raw?note_id=<id>&filename=<name>` (neue Resource anlegen + in Notiz verlinken) bzw. `PUT /raw?resource_id=<id>` (vorhandene ersetzen)
- contacts: `GET /raw?uid=<uid>` (Kontaktfoto roh) und `PUT /raw?uid=<uid>[&type=jpeg|png|gif]` (Foto aus Rohbytes setzen/ersetzen)
Beispiel Download: `curl -H "Authorization: Bearer $TOKEN" "https://files.mcp.slohmaier.de/raw?path=/x.pdf" -o /tmp/x.pdf`
Beispiel Upload: `curl -X PUT -H "Authorization: Bearer $TOKEN" --data-binary @/tmp/x.pdf "https://files.mcp.slohmaier.de/raw?path=/Ziel/x.pdf"`
Limits: nginx `client_max_body_size 5g` (Uploads), notes `MAX_ATTACHMENT_BYTES` 2GB. Downloads gestreamt (kein Body-Limit).
### OpenClaw (mycroft/jarvis)
Alle MCP-Server (notes, calendar, mail, contacts, files, openwearables, owamail) in `/mnt/ssd/openclaw/<agent>/data/openclaw.json` zeigen seit 2026-09-18 auf die
oeffentlichen URLs; Bearer ist ein nicht-ablaufendes Service-Token (`${MCP_BEARER}`, Labels
openclaw-mycroft/jarvis/nova). ghostfolio wurde entfernt. Bewusste Abweichung von der
AGENTS-Regel "lokale Routen", damit die Config bei einem Umzug (z. B. nach Odin) unveraendert
bleibt. Verifiziert: beide Container erreichen alle oeffentlichen Endpunkte mit HTTP 200.
### Monitoring
Der naechtliche Smoke (`mcp-tests.timer` 05:00) prueft die oeffentliche Route mit
`tests/test_public_smoke.py`: pro Server ohne Token 401, mit Service-Token (Label
`smoketest`) initialize + tools/list ueber `https://<name>.mcp.slohmaier.de/mcp`.
Faengt DNS-, vhost-, TLS-/Cert- und Auth-Ausfaelle ab (der interne Smoke testet nur
`127.0.0.1:<port>`).
### Zukunfts-Option: OAuth/DCR fuer ChatGPT & spec-konforme Clients
Service-Tokens funktionieren nur bei Clients, die einen eigenen Header setzen koennen
(opencode, OpenAI-Responses-API ueber das `authorization`-Feld, Cursor, mcp-remote usw.).
Die ChatGPT-App-Connectoren und strikt spec-konforme OAuth-Clients koennen das nicht; sie
brauchen OAuth mit Dynamic Client Registration. Dafuer waeren noetig:
- `registration_endpoint` (POST /register, RFC 7591) im AS-Metadata (`common.py`)
- `/.well-known/oauth-protected-resource` (RFC 9728) + passendes `WWW-Authenticate`
- Redirect-Allowlist in `oauth_authorize()` ueber claude.ai hinaus erweitern (ChatGPT-Callback)
- Consent-Schritt (aktuell Auto-Approve)
- Audience-/`resource`-Pruefung (RFC 8707)
Service-Tokens koennen parallel bestehen bleiben (Bearer-Middleware akzeptiert beides).
## License
MIT