# Blueprint: MCP-Anbindung für Seiten ohne API Version 1.0 · denzer.ai · Lizenz: frei nutzbar mit Quellenangabe Ein wiederverwendbares Muster, um deinen Agent an Web-Anwendungen anzudocken, die keine offene Programmier-Schnittstelle (API) haben. Also dort, wo bisher ein Mensch sich mit Login und Klicks durchhangeln musste. **Fallbeispiel, das wir durchziehen.** Ein Handwerksbetrieb bestellt regelmäßig bei drei regionalen Lieferanten. Jeder Lieferant hat eine eigene Web-Plattform mit Login. Erst nach Anmeldung sieht der Betrieb sein persönliches Leistungsverzeichnis mit aktuellen Tagespreisen. Die manuelle Preisabfrage frisst dem Inhaber pro Woche mehrere Stunden, und Kostenvoranschläge basieren oft auf veralteten Zahlen. Ziel: einmalig drei kleine MCP-Server bauen, die im Hintergrund die Logins halten und dem Agent stabile Werkzeuge wie `liste_artikel`, `preis_fuer(artikelnr)`, `synchronisiere_katalog` anbieten. --- ## Teil B — Für dich (Operator) Vorgezogen, damit du zuerst verstehst was passiert, bevor wir technisch werden. ### Was ist das? Stell dir vor, einer deiner Lieferanten hat eine Internetseite, auf der du dich anmelden musst, um deine Preise zu sehen. Du willst aber nicht jeden Tag selbst auf die Seite klicken, sondern dein Agent soll dir die Daten holen. Ein MCP-Server ist ein kleiner Helfer, den du einmal einrichtest und der dann im Hintergrund genau das macht: er klickt sich für dich ein, holt die Daten ab und liefert sie deinem Agent in einer immer gleichen Form. Wichtig: dieser Helfer simuliert keinen Hacker. Er meldet sich mit deinen echten Zugangsdaten an, genauso wie du es selbst tun würdest. Er macht es nur regelmäßig, schneller und ohne Tippfehler. ### Warum so und nicht anders? Du könntest ein eigenes Python- oder Node-Skript bauen, das deinem Agent direkt antwortet. Funktioniert, aber jeder Agent (Claude, ChatGPT, Cursor, eigenes Frontend) braucht einen eigenen Wrapper. **MCP ist ein offener Standard**, ursprünglich von Anthropic vorgeschlagen, inzwischen auch von OpenAI und Google adoptiert. Heißt: derselbe Server funktioniert mit allen kompatiblen Agenten, ohne Anpassung. Browser-Automation (Playwright) statt API-Reverse-Engineering, weil API-Reversing rechtlich heikel und stabil schwer ist. Browser-Klicken ist genau das, was du selbst tust — nur automatisiert. Das hält dich auf der sicheren Seite der AGB der meisten Plattformen. Ein MCP-Server pro Quelle (statt ein großer für alles), weil so jede Plattform isoliert läuft: wenn Lieferant X sein Layout ändert, muss nur ein Server angepasst werden, die anderen laufen weiter. ### Was brauchst du dafür? - Deine Zugangsdaten zur jeweiligen Seite (Benutzername, Passwort) - Eine kurze Liste der Aktionen, die der Helfer können soll (Preise lesen, Bestände prüfen, Bestellungen abschicken) - Einen Rechner, auf dem der Helfer laufen kann (eigener Mac, kleiner Server, oder Cloud) ### Wie startest du? Du lädst dir unten den Starter (Markdown + Code-Snippets) und gibst beides deinem Agent. Du sagst zum Beispiel "richte mir nach diesem Blueprint einen MCP-Server für meinen Lieferanten X ein". Dein Agent liest die Spezifikation, fragt dich nach Zugangsdaten und gewünschten Werkzeugen, und baut den Server in deinem Projekt zusammen mit dir auf. Den ersten Login führst du einmal manuell mit dem Browser durch, danach läuft es allein. ### Wo sind die Grenzen? - Wenn die Seite ein Captcha verlangt, geht es nicht ohne Mensch — der Helfer pausiert dann und meldet sich bei dir - Wenn die Seite ihr Layout grundlegend ändert, muss der Helfer angepasst werden (1–2× pro Jahr pro Quelle normal) - Banken und sehr streng abgesicherte Seiten erkennen Automation und blockieren — dort lieber eine offizielle Schnittstelle suchen - Achte auf die AGB der Plattform: erlaubt sie automatisierten Zugriff für eigene Daten? Meistens ja, manchmal nicht ### Was kostet das? - Einmal-Aufbau pro Quelle: meist halber bis ganzer Tag Bauzeit - Betrieb: ein paar Cent pro Tag (kurzer Browser-Start) - Modell-Kosten: nahezu null, die KI ruft nur die Werkzeuge ### Wann lohnt es sich, wann nicht? Lohnt sich, sobald du dieselbe manuelle Klickerei mehr als einmal pro Woche machst, oder wenn du mehrere Quellen vergleichen willst (z. B. drei Lieferanten parallel). Lohnt sich nicht für eine einmalige Datenabfrage — dann ist Copy-Paste schneller. ### Wie weißt du, dass es funktioniert? Der Helfer schickt dir bei jedem Bruch eine Mail mit Screenshot. Wenn lange nichts kommt, ist alles ok. Zusätzlich gibt es einen Schema-Check: wenn die Datenmenge plötzlich um mehr als die Hälfte abweicht, gilt das als verdächtig und wird gemeldet. --- ## Teil A — Für deinen Agent Maschinenlesbare Spezifikation. Dein Agent liest diesen Block und baut zusammen mit dem Operator das System auf. ### Agent-Triggersätze So spricht der Operator dich an, wenn er diesen Blueprint einsetzen will. Erkenne den Auftrag und folge dem Ablauf unten. - "Richte mir einen MCP-Server für `` ein" - "Bau einen MCP-Connector zu meinem Lieferanten-Login bei ``" - "Ich brauche einen Helfer, der mir nachts die Preise bei `` abruft" ### Ziel Pro Quelle (Lieferant, Plattform, Login-Seite) ein eigener MCP-Server, der dem Agent Werkzeuge zum Lesen und (optional) Schreiben anbietet. Der Server kapselt Login, Session, Browser-Automation, Selektoren und Normalisierung — der Agent sieht nur Werkzeuge mit klaren Argumenten und einem stabilen Antwortformat. ### Erfolgskriterien - Ein MCP-Server pro Quelle, unter `/mcp//` - Werkzeuge funktional benannt (`liste_artikel`, `preis_fuer`), nicht technisch (`scrape_table_2`) - Login passiert beim Setup einmalig manuell, Session läuft danach ohne Hand - Session-Erneuerung automatisch, spätestens 1× pro Nacht - Jeder Werkzeug-Aufruf antwortet im selben normalisierten JSON-Schema - Schema-Check nach jedem Lauf, Bruch wird per Mail oder Notification gemeldet - Setup-README beim Operator (Black-Box-Verbot) ### Eingabe-Schema (Variablen, die der Operator setzt) ```yaml quelle: name: "Lieferant-Name" slug: "lieferant-x" base_url: "https://portal.lieferant-x.de" login_url: "https://portal.lieferant-x.de/login" auth_method: "form" | "saml" | "oauth" credentials_env: "LIEFERANT_X_USER,LIEFERANT_X_PASS" werkzeuge: - name: "liste_artikel" input: {kategorie: "string?"} output: list[ArtikelRecord] - name: "preis_fuer" input: {artikelnr: "string"} output: ArtikelRecord session: cookie_jar: "/mcp//state/cookies.json" refresh_cron: "0 4 * * *" ttl_hours: 24 normalisierung: artikel_schema: artikelnr: string name: string preis_netto: number einheit: string bestand: number? stand_iso: string qualitaet: schema_check: bool min_records: int on_failure: "mail" | "log" | "both" ``` ### Verarbeitung 1. **Setup** — Zugangsdaten in `.env`, einmaliger manueller Login im headful-Browser, Cookie-Jar wird gespeichert 2. **Werkzeug-Aufruf** — Agent ruft Werkzeug, MCP-Server lädt Cookie-Jar, startet headless Browser 3. **Extraktion** — Selektoren oder strukturierte DOM-Reads, kein Freitext-Parsing 4. **Normalisierung** — Rohdaten in das Schema überführen, Einheiten vereinheitlichen 5. **Schema-Check** — Pflichtfelder vorhanden? Mindestmenge? Sonst Alarm + Screenshot 6. **Antworten** — JSON gemäß Schema zurück an den Agent 7. **Session-Pflege** — Cron prüft 1× pro Nacht ob Cookie noch gültig, sonst Re-Login ### Output-Schema (Beispiel `ArtikelRecord`) ```json { "artikelnr": "12345-AB", "name": "Kabelrohr DN 25, grau", "preis_netto": 1.42, "einheit": "m", "bestand": 480, "stand_iso": "2026-05-12T08:00:00+02:00", "quelle": "lieferant-x" } ``` ### Bausteine | Aufgabe | Bibliothek | Zweck | |---|---|---| | Browser-Steuerung | playwright | Zuverlässiger als Selenium | | MCP-Server-Gerüst | @modelcontextprotocol/sdk (Node) oder mcp (Python) | offizielle SDKs | | Cookie-Persistenz | playwright `storageState` | speichert Session als JSON | | Cron | system cron oder launchd | regelmäßiger Re-Login | | Secrets | `.env` + dotenv | nie in Code | ### Sicherheit - Zugangsdaten ausschließlich aus `.env`, nie in Code oder Repo - Cookie-Jar mit chmod 600, Verzeichnis chmod 700 - Headless-Browser mit eingeschränktem Profil - Werkzeug-Argumente nie direkt in URLs oder Shell einsetzen - Logs ohne Klartext-Credentials ### Fehler-/Edge-Cases - Login schlägt fehl → 1× Retry, dann Alarm, kein endloses Login-Hämmern (Account-Sperre) - Selektor nicht gefunden → HTML-Snapshot speichern, Schema-Check fällt, Alarm - Captcha taucht auf → menschlichen Reset triggern, Server pausiert sich selbst - Plattform liefert leere Liste → "wirklich leer" vs. "Layout geändert" über Mindestmenge unterscheiden - Mehrere Werkzeuge gleichzeitig → Mutex auf Session ### Verzeichnisstruktur ``` /mcp// ├── server.ts # MCP-Server, registriert Werkzeuge ├── browser.ts # Login, Cookie-Pflege, Page-Navigation ├── extract/ │ ├── artikel.ts │ └── preis.ts ├── schemas/artikel.json ├── state/cookies.json # gitignored ├── README.md # Setup-Anleitung └── .env.example ``` ### Code-Snippets Im Starter-ZIP findest du fertige Vorlagen für `server.ts`, `browser.ts`, `.env.example` und `README.md`. Dein Agent passt sie an die konkrete Plattform an. --- ## Teil C — Was du als Nächstes tust 1. Starter unten herunterladen 2. Markdown + ZIP deinem Agent geben 3. Sagen: "richte einen MCP-Server für `` nach diesem Blueprint ein" 4. Auf die Rückfragen antworten (Login-Daten in `.env`, gewünschte Werkzeuge) 5. Den manuellen Login einmal durchklicken 6. Test-Werkzeug aufrufen und Antwort prüfen 7. Nach einer Woche Schema-Brüche in den Logs anschauen ### Lern-Checkliste Bevor du produktiv gehst, solltest du folgende Fragen beantworten können. Wenn nicht, frag deinen Agent — er kennt diesen Blueprint und führt dich durch. - Wo liegen meine Zugangsdaten und warum nicht im Code? - Was passiert, wenn die Sitzung abläuft, und wann erneuert sie sich? - Welche Werkzeuge habe ich dem Agent freigegeben? - Wie merke ich, wenn die Plattform ihr Layout ändert? - Wo finde ich die Logs und Screenshots bei einem Fehler? Fragen: christian@denzer.ai