Readeck MCP

Ein MCP-Server, der eine Readeck-Bibliothek in eine Schreib-/Lese-Wissensdatenbank für KI-Agenten verwandelt: Agenten können das von ihnen erzeugte HTML direkt in Readeck ablegen (vom LLM automatisch verschlagwortet) und diese Dokumente später wieder abrufen und lesen. Gebaut mit FastMCP – derselbe Code läuft als lokaler stdio-Server oder als entfernter HTTP-Server hinter einem Reverse-Proxy.

Anders als bestehende Readeck-MCPs (die reine Lese-Assistenten sind), nimmt dieser hier agentengeneriertes HTML auf und versieht es automatisch mit einem LLM-Label aus einer festen Taxonomie.

Werkzeuge

readeck_save nutzt die JSON-Erstellungs-API von Readeck mit dem html-Feld für rohes HTML (Base64-/Data-URIs funktionieren nicht). Es sendet einen Browser-User-Agent, damit eine WAF (z. B. Cloudflare-Fehler 1010) es nicht blockiert, und fragt kurz nach, um die neue Lesezeichen-id, word_count und reading_url zurückzugeben.

Related MCP server: Doc Monitor MCP

Automatische Beschriftung

Wenn Sie readeck_save ohne labels aufrufen, klassifiziert ein LLM das Dokument. Es ist konstruktionsbedingt injektionsresistent: Das Modell darf nur aus einer festen Taxonomie (LABEL_TAXONOMY) wählen, und das Ergebnis wird serverseitig mit dieser Liste geschnitten, sodass nicht im Vokabular enthaltene Labels unmöglich sind. Ein Herkunftslabel (ORIGIN_LABEL, Standard propio) wird immer per Code hinzugefügt, nie vom LLM.

Anbieterunabhängig (OpenAI-kompatibel oder Anthropic). Funktioniert mit kostenlosen Stufen wie Groq – für Reasoning-Modelle wie gpt-oss setzen Sie großzügige LLM_MAX_TOKENS; der Server sendet automatisch reasoning_effort: low.

Schutzmaßnahmen

• Fail-closed-HTTP-Authentifizierung: Über HTTP-Transport erfordert jeder Tool-Aufruf Authorization: Bearer $MCP_AUTH_TOKEN (Konstantzeitvergleich).

• Eingabevalidierung: HTML-Größenlimit, Ablehnung von Nicht-HTML, URL-Schema-Whitelist, Label-Bereinigung + -Limit.

• Token-Bucket-Ratenbegrenzung pro Prozess.

• LLM-Aufrufe werden bei 429/5xx mit Backoff wiederholt und verschlechtern sich elegant (Beschriftung ist Best-Effort; ein Fehler blockiert das Speichern nie).

Konfiguration (Umgebung)

Lokal (stdio)

READECK_TOKEN=... uv run --script server.py --selftest   # smoke test

Bei einem MCP-Client (mcpServers) registrieren, z. B.:

{
  "mcpServers": {
    "readeck": {
      "command": "uv",
      "args": ["run", "--script", "/path/to/readeck-mcp/server.py"],
      "env": { "READECK_URL": "https://readeck.example.com", "READECK_TOKEN": "..." }
    }
  }
}

Remote (HTTP / Docker)

Mit READECK_MCP_TRANSPORT=http ausführen (siehe Dockerfile). Hinter dem eigenen Reverse-Proxy / Tunnel platzieren, z. B. https://mcp-readeck.example.com. Wenn Readeck auf demselben Host läuft, READECK_URL=http://readeck:8000 setzen, um den öffentlichen Umweg zu vermeiden. Clients auf den Endpunkt verweisen:

{
  "mcpServers": {
    "readeck": {
      "type": "http",
      "url": "https://mcp-readeck.example.com/mcp",
      "headers": { "Authorization": "Bearer <MCP_AUTH_TOKEN>" }
    }
  }
}

Hinweis: Den Endpunktpfad ohne abschließenden Schrägstrich verwenden (/mcp, nicht /mcp/) – manche Proxys wandeln die Weiterleitung mit Schrägstrich in einen 307 um, der Streamable-HTTP-Clients stört.

Setzen Sie immer ein starkes MCP_AUTH_TOKEN, bevor Sie den Endpunkt freigeben – das Token gewährt Schreibzugriff auf Ihre Bibliothek.

Lizenz

MIT