Files
mcp-home/tests/MCPTEST.md
T

12 KiB

mcptest — isoliertes Test-/Dev-Backend

Die MCP-Test-Suite (test_all.py, taeglich via mcp-tests.timer) laeuft NICHT mehr auf Stefans echten Daten, sondern auf einem dedizierten mcptest-User mit eigenen Backends. Dieselbe Umgebung dient als isolierte Dev-Sandbox fuer die MCP-Server.

Routing

common.py: USER_ALIASES = {"test": "mcptest"}. Der Test-OAuth-Client client_id=test (Secret in config.json -> test.token) wird also auf den User mcptest gemappt. Alle Server lesen pro User aus config.json.

Backends pro Dienst

  • Calendar/Contacts (Baikal auf 1blu): User mcptest (Baikal-auth via digesta1). Collections im calendar-home /dav.php/calendars/mcptest/: calendar-test (VEVENT+VTODO) und calendar-test-second (VEVENT). Addressbook /dav.php/addressbooks/mcptest/contacts-test (VADDRESSBOOK). calendar_paths/addressbook_paths[mcptest]=["/dav.php/calendars|addressbooks/mcptest/"].
  • Files (oCIS): kompletter User mcptest (angelegt via Graph-API POST /graph/v1.0/users als admin). ocis_users[mcptest]. Tests legen /.mcp-tests selbst an + raeumen auf.
  • Notes (Joplin): lokales joplin-cli-Profil /mnt/ssd/joplin-mcp/profiles/mcptest (sync.target=0, kein Server-Sync), Data API auf :41186 via joplin-cli-mcptest.service. Notizbuecher Inbox + MCP Test mit Beispielnotizen. joplin_data_api[mcptest].
  • Mail: statische Test-Maildir /opt/mcp-servers/tests/testdata/maildir/ mit Konten mcp-test-mail (INBOX: "Willkommen" + "Rechnung"+PDF-Anhang, Sent) und mcp-test-empty. mail_roots[mcptest] zeigt dahin. (Der Mail-MCP liest Maildirs, kein Live-IMAP.)

Credentials

  • Klartext-Backup: /root/.mcptest-creds (chmod 600). Baikal-mcptest-Passwort zusaetzlich unter ~/1bluapps/.secrets-mcptest/ (mcptest-baikal.password + .digesta1, chmod 600).
  • Aktiv genutzt: config.json (gitignored) — baikal/ocis Passwoerter, joplin Token. Radicale-Keys sind entfernt.
  • oCIS-Admin (fuer User-Anlage): /mnt/ssd/ocis/auth.txt.

Tests laufen lassen

/opt/mcp-servers/venv/bin/python -m pytest /opt/mcp-servers/tests/test_all.py -q
# oder der taegliche Runner:
sudo /opt/mcp-servers/tests/run_tests.sh

Testablauf und Selbstreinigung (Kalender/Kontakte)

  • Smoke (taeglich, read-only): prueft, dass BEIDE Test-Kalender (calendar-test + calendar-test-second) in list_calendars sichtbar sind. Kein Schreiben.
  • Full CRUD (test_all.py, on-demand): erzeugt Events/Tasks/Kontakte via MCP (create_event mit vollen Feldern inkl. Apple-Reise, create_task, create_contact), aendert sie via update_event/update_task/update_contact (alle Felder, beide Kalender) und loescht am Ende alles wieder via delete_event/delete_task/delete_contact (try/finally je Testmethode). Nach dem Lauf ist der mcptest-Account wieder LEER (Collections vorhanden, keine Objekte). Nur MCP-Methoden, kein direkter DAV-Zugriff.

Neue MCP-Tools (Calendar/Contacts)

  • update_event(uid, ...) — Feld-Overwrite wie create_event, auf bestehender UID.
  • update_task(uid, ...) — wie create_task auf bestehender UID.
  • update_contact(uid, ...) — wie create_contact auf bestehender UID.
  • delete_contact(uid) — loescht Kontakt per UID.
  • create_event/update_event unterstuetzen zusaetzlich travel_mode (walking/driving/transit/biking) und travel_advisory (true = Apple berechnet die Reise-Erinnerung dynamisch aus der Route via X-APPLE-TRAVEL-ADVISORY-BEHAVIOR:AUTOMATIC).
  • Bugfix: _parse/_get_contacts dekodieren jetzt XML-Entities per html.unescape (zuvor brachen "-Werte wie X-TITLE das vobject-Roundtrip-Parsing).

Als Dev-Sandbox nutzen

  • Direkt gegen die Backends: Baikal https://baikal.slohmaier.de/dav.php/calendars|addressbooks/mcptest/ (User mcptest), Joplin Data API http://127.0.0.1:41186 (Token aus config.json), Maildir s.o.
  • Ueber die MCP-Server: mit dem test-OAuth-Client verbinden -> trifft automatisch mcptest.
  • Testdaten zuruecksetzen: Collections/Notebooks neu seeden (siehe Provisioning unten).

Provisioning (Recreate)

  1. Baikal (MySQL auf 1blu, ~/1bluapps/mysql-baikal): principal principals/mcptest, user mit digesta1=md5-hex("mcptest:BaikalDAV:"), zwei Kalender (calendar-test VEVENT+VTODO, calendar-test-second VEVENT) + calendarinstances (access=1) + addressbooks contacts-test.
  2. oCIS: POST /graph/v1.0/users als admin (onPremisesSamAccountName=mcptest, passwordProfile).
  3. Joplin: Profil anlegen (joplin --profile DIR config api.token ...; sync.target 0), api.port=41186 in settings.json, joplin-cli-mcptest.service (Kopie von -stefan), Notebooks/Notizen via Data API seeden.
  4. Mail: tests/testdata/maildir/ (im Repo) — Maildir-Konten mit cur/-Nachrichten.
  5. config.json: mcptest in baikal_users, ocis_users, joplin_data_api, mail_roots, calendar_paths, addressbook_paths.
  6. common.py: USER_ALIASES = {"test": "mcptest"}.

Verwandt: /opt/mcp-servers/CLAUDE.md.

Testdaten (Dateien + Mail-Anhaenge)

Reichhaltiges Set ueber alle gaengigen Typen (fuer read_file-/Attachment-Tests + Dev):

  • oCIS unter /testdata/{images,audio,video,documents,text,archives}/: Bilder (jpg/png/webp/bmp/gif/tiff/svg), Audio (mp3/ogg/m4a/flac/wav), Video (mp4), PDFs (Text-PDF document.pdf + Scan-PDF scanned.pdf), Office (docx/xlsx/pptx), Text/Daten (md/txt/csv/json/xml/yaml/html/py/vcf/ics), Archive (zip/tar.gz).
  • Mail-Maildir tests/testdata/maildir/mcp-test-mail/INBOX: Mails mit diversen Anhaengen (Rechnung Text+Scan-PDF, Fotos, Word+Excel, MP3, ZIP+CSV, PPTX+MP4).

TestFileTypes (test_all.py) liest je Typ eine /testdata-Datei und prueft den zurueckgegebenen Content-Typ (image/text/resource). Office-Docs liefert der Files-MCP als extrahierten Text.

Neu generieren

Wegwerf-venv + ffmpeg noetig:

sudo apt-get install -y ffmpeg
python3 -m venv /tmp/gen && /tmp/gen/bin/pip install fpdf2 python-docx openpyxl python-pptx Pillow
/tmp/gen/bin/python tests/testdata/gen_testfiles.py      # -> /tmp/mcptest-files
sudo tests/testdata/upload_ocis.sh                       # -> mcptest oCIS /testdata/
/tmp/gen/bin/python tests/testdata/gen_maildir.py        # -> maildir mit Anhaengen

Edge-Cases

/testdata/edge/ + TestFileEdgeCases: leere Datei, 0-Byte-Binary, Name mit Umlauten/Leerzeichen/Klammern, Unicode/Emoji/RTL-Inhalt, Datei ohne Endung, passwortgeschuetztes PDF + ZIP, uebergrosse Datei (26 MB > 25-MB-Limit -> "Datei zu gross"). Alle werden graceful behandelt (kein Crash). Generator: gen_edge.py (braucht pikepdf + zip), Upload via upload_ocis.sh.

Verbesserung: bildbasierte/gescannte PDFs (2026-06-19)

Frueher gab read_file bei Scan-PDFs (kein extrahierbarer Text) nur Rohbytes (EmbeddedResource) zurueck — claude.ai konnte den Inhalt nicht lesen. Jetzt werden solche PDFs mit PyMuPDF seitenweise als PNG-Bilder (150 dpi, max 20 Seiten) gerendert und als ImageContent zurueckgegeben -> das LLM liest sie per Vision. Zusaetzlich OCR (tesseract deu+eng) -> durchsuchbarer Text neben den Bildern. Gemeinsames Modul pdfutil.py wird von Files-MCP (read_file) UND Mail-MCP (read_attachment) genutzt -> Scan-PDF-Mailanhaenge werden genauso gerendert. Produktiv-Feature (alle User). Test: TestFileTypes scanned.pdf -> image. Runtime-Deps: pymupdf, pytesseract + System tesseract-ocr/-deu (s. requirements-extra.txt).

Test-Schichten (2026-06-24)

Drei Schichten, NUR Smoke laeuft naechtlich:

  • Smoke (test_smoke.py, Marker smoke): NIGHTLY via mcp-tests.timer (05:00) -> run_tests.sh -> pytest test_smoke.py test_public_smoke.py test_search_smoke.py. Pro Connector: Server up + OAuth + tools/list + EIN read-only Call. Schnell (~0.5s), schreibt keine Testdaten. Faengt Totalausfaelle ab.
  • Public-Smoke (test_public_smoke.py, Marker smoke): NIGHTLY im selben Lauf. Prueft die oeffentliche Route (DNS, nginx-vhost, TLS/Cert-SAN, Bearer) fuer alle 9 Server ueber https://<name>.mcp.slohmaier.de/mcp: ohne Token -> 401, mit Token -> initialize (serverInfo)
    • tools/list. Nutzt das nicht-ablaufende Service-Token mit Label smoketest (User mcptest) aus service_tokens.json; keine /token-Aufrufe, damit das nginx-Rate-Limit mcp_auth (10/min) unberuehrt bleibt. Read-only, kein Datenzugriff.
  • SearXNG-Smoke (test_search_smoke.py, Marker smoke): NIGHTLY im selben Lauf. Prueft die interne SearXNG-Instanz ueber die lokale Host-Route 127.0.0.1:8888 (/search?q=...&format=json, kein Token noetig, Token-Gate nur in nginx). Assert: HTTP 200 + results ist eine Liste. Bewusst kein "nicht leer", da geratelimitete Engines ein bekannter Degraded-Zustand sind. Ersetzt den frueheren searxng-Eintrag im Dashboard-service-check (2026-09-17).
  • Edge (test_edge.py, Marker edge): ON-DEMAND. Boese/ungewoehnliche Eingaben pro Connector: Unicode/Emoji-Roundtrips, Sonderzeichen, riesige Limits/Bodies, kaputte Datumsangaben, Path-Traversal-Block (Files). Muss graceful sein, nichts leaken/crashen.
  • Stress (test_stress.py, Marker stress): ON-DEMAND. 40-60 gleichzeitige Requests pro Connector + Mischlast ueber alle 5; danach Responsiveness-Check. Faengt den Klassiker "single-threaded Server haengt unter Last" (genau der Mail-Haenger 2026-06-23).
  • Funktional (test_all.py): CRUD + OAuth + Datei-Typen/-Edge. ON-DEMAND.

Helper (SERVERS, get_token, tool_call, mcp_call) liegen in test_all.py; smoke/edge/ stress importieren sie. Marker in conftest.py.

Runner:

  • Nightly (Smoke): automatisch via Timer, ODER run_tests.sh.
  • On-demand (Funktional+Edge+Stress): run_full_tests.sh (Log /var/log/mcp-tests-full.log), oder eine Schicht: run_full_tests.sh -m stress (bzw. -m edge).
  • Log /var/log/mcp-tests.log muss stefan:stefan gehoeren (Service laeuft als User=stefan).

Mail-Server-Haertung (2026-06-23/24)

mcp-mail hing 24h an einem Such-CallToolRequest (single-threaded -> Connector tot). Ursache: eine kaputte Mail (charset x-unknown -> LookupError) plus fehlende per-Mail- Fehlerbehandlung. Fix in BEIDEN Servern (/opt/mcp-servers/mail/server.py remote, /opt/mcp-mail/server.py lokal fuer Claude Code):

  • _safe_decode (unbekannte Charsets), _iter_messages (per-Mail try/except statt md.items()), per-Treffer try/except -> eine kaputte Mail killt die Suche NICHT mehr (findet so auch uralte Mails nach der kaputten).
  • Vollscan + Datum-Sortierung (neueste zuerst) statt frueher Abbruch bei limit.
  • MAX_SCAN=2000 + DEADLINE_S=120 Wall-Clock -> Server heilt sich selbst, nie wieder Endlos-Haenger. Volltext-Scan ueber die echten 3.3GB dauert ~60-70s fuer seltene Begriffe; per account/folder eingrenzen ist deutlich schneller.

Connector-Skalierung (Stand 2026-06-24, gegen ECHTE Daten gemessen)

Frage: verkraften die Connector "viel durchwuehlen" wie der Mail-Vollscan?

  • Notes: unkritisch. Joplin server-seitige FTS (/search), paginiert mit Cap (max 50 Seiten), Timeouts. Alle Ops <0.1s auch bei vielen Notizen.
  • Files: list_files/read_file ok (1 PROPFIND bzw. 25MB-Cap, Timeouts). ABER search_files war riskant: client-seitige Rekursion = 1 PROPFIND pro Ordner, kein Deadline. Real gemessen: Miss-Suche 35s/449 PROPFINDs, wachsend mit dem Baum -> haette den single-threaded Server blockiert. Fix: SEARCH_DEADLINE_S=20 + SEARCH_MAX_DIRS=400
    • Truncation-Hinweis ("Begriff praezisieren / 'path' enger"). Worst-Case jetzt ~20s gekappt. Langfristig besser: oCIS server-seitige Suche (Graph/REPORT) statt Client-Rekursion.
  • Calendar: get_events ist server-seitig zeitgefiltert (gut). ABER bei ~6000 Test-Events gemessen: search_events 6-8s (vobject parst ALLE Events im ~15-Mon- Fenster client-seitig), get_events lieferte 10939 Zeilen (KEIN Result-Limit -> Token- Explosion). Real schon 5s bei 29 Kalendern. Fix: _parse mit PARSE_DEADLINE_S=12 + get_events/get_tasks Output-Cap MAX_RESULTS=300 + Hinweise; search_events Top-30 + Deadline. Danach get_events 1501 statt 10939 Zeilen.
  • Contacts: search_contacts parst ALLE vCards client-seitig (real 0.2s, wenige Kontakte; skaliert linear). Fix: PARSE_DEADLINE_S=12 in _get_contacts + Hinweis.
  • Rest-Kosten = CalDAV/CardDAV-REPORT-Transfer selbst (kein Server-Result-Limit im Protokoll); in der Praxis durch Datumsbereich/Begriff eingrenzbar. Langfristig: server-seitige Suche.