ShowDoc2MD

Liest ShowDoc-Projekte mit bekanntem Zugriffspasswort und konvertiert sie in Markdown, zur Nutzung mit KI / Agent / RAG.

Drei Verwendungsmöglichkeiten werden unterstützt:

• MCP Server (empfohlen): KI-Clients wie Cursor, Codex, Claude, AgentDock entdecken die Tools automatisch und rufen sie auf.

• CLI: Manueller oder skriptbasierter Batch-Export von Markdown.

• Legacy HTTP API: Behält die kompatible /convert-Schnittstelle bei.

ShowDoc2MD dient ausschließlich zum Lesen von Dokumenten, für die du bereits legal Zugriffsrechte und das Passwort besitzt. Es errät, knackt oder brute-forct keine Passwörter.

Warum dieses Projekt

Passwortgeschützte ShowDoc-Seiten verlangen normalerweise, dass der Browser zuerst eine Captcha-/Passwort-Interaktion durchführt, was für KI-Agenten beim automatischen Lesen von Dokumenten sehr unpraktisch ist.

Die schreibgeschützte Schnittstelle von ShowDoc erlaubt es, Anfragen mit _item_pwd=<bekanntes Dokumentpasswort> zu versehen. ShowDoc2MD nutzt diesen normalen Lese-Parameter, um auf Projektverzeichnisse und Seiten zuzugreifen, sodass die KI keinen Browser-Captcha-Ablauf simulieren muss.

Derzeit werden hauptsächlich gelesen:

• /api/item/info

• /api/page/info

Related MCP server: mkdocs-mcp

Installation

Voraussetzung: Python 3.10+.

Windows

powershell -ExecutionPolicy Bypass -File .\scripts\windows_install.ps1

macOS / Linux

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .

MCP: Empfohlener KI-Anschluss

ShowDoc2MD verwendet das offizielle Python-MCP-SDK und unterstützt:

• stdio: Geeignet für KI-Clients auf derselben Maschine.

• Streamable HTTP: Geeignet für die Bereitstellung auf einer festen Maschine, auf die andere KI-Clients über das Netzwerk zugreifen.

Für die KI bereitgestellte Tools

Nach der Verbindung erhält der KI-Client diese Tools mit ihren Parametern und Beschreibungen automatisch über das MCP-Schema – es ist nicht nötig, dem Modell das HTTP-JSON-Format separat mitzuteilen.

Variante 1: stdio auf derselben Maschine

Zuerst ShowDoc2MD installieren, dann in einem MCP-Client einen stdio-Server konfigurieren. Allgemeine Konfigurationsübersicht:

{
  "mcpServers": {
    "showdoc2md": {
      "command": "showdoc2md",
      "args": ["mcp", "--transport", "stdio"],
      "env": {
        "SHOWDOC_PASSWORD": "your-document-password"
      }
    }
  }
}

Wenn verschiedene ShowDoc-Projekte unterschiedliche Passwörter verwenden, kann SHOWDOC_PASSWORD weggelassen werden; die KI übergibt dann password bei jedem Tool-Aufruf.

Variante 2: Streamable HTTP auf einer festen Maschine bereitstellen

Nur lokaler Zugriff:

$env:SHOWDOC_PASSWORD='your-document-password'
.\showdoc2md.cmd mcp

Standard-MCP-Adresse:

http://127.0.0.1:18765/mcp

Linux / macOS:

export SHOWDOC_PASSWORD='your-document-password'
showdoc2md mcp

Der KI-Client muss nur die MCP-URL konfigurieren:

http://127.0.0.1:18765/mcp

LAN / Remote-Maschinen

Das MCP-SDK aktiviert standardmäßig DNS-Rebinding-Schutz. ShowDoc2MD setzt für Remote-Listener außerdem sichere Standardwerte:

• Erlaubte Hosts/IPs müssen explizit deklariert werden.

• Standardmäßig muss SHOWDOC_MCP_TOKEN gesetzt werden; der Client authentifiziert sich über ein Bearer-Token.

Serverbeispiel:

$env:SHOWDOC_MCP_TOKEN='replace-with-a-long-random-token'
.\showdoc2md.cmd mcp `
  --host 0.0.0.0 `
  --port 18765 `
  --allowed-host 192.168.1.20

Dann verbindet sich der KI-Client:

http://192.168.1.20:18765/mcp

Und für diese MCP-Verbindung wird ein HTTP-Header konfiguriert:

Authorization: Bearer replace-with-a-long-random-token

Die MCP-Konfigurationsdateiformate verschiedener KI-Clients unterscheiden sich, aber solange sie benutzerdefinierte Header für Streamable HTTP unterstützen, ist das ausreichend.

Bei Zugriff über eine Domain:

showdoc2md mcp \
  --host 0.0.0.0 \
  --port 18765 \
  --allowed-host mcp.example.com

--allowed-host mcp.example.com erlaubt gleichzeitig mcp.example.com:*.

Browserbasierte MCP-Clients, die einen Origin senden, können zusätzlich ergänzt werden:

--allowed-origin https://app.example.com

Wenn MCP nur in einem vollständig vertrauenswürdigen privaten Netzwerk/VPN läuft und das Bearer-Token ausdrücklich deaktiviert werden soll, kann explizit hinzugefügt werden:

--allow-unauthenticated-remote

Sicherheitshinweis: Setze einen MCP-Dienst ohne Authentifizierung niemals direkt ins öffentliche Internet aus. Ein statisches Bearer-Token eignet sich für persönliche/Kleinteam-Bereitstellungen; für öffentliche Dienste in Produktion wird empfohlen, ihn hinter TLS, VPN/Tailscale, einem authentifizierenden Reverse-Proxy oder einem MCP-konformen OAuth-2.1-Ressourcenserver zu platzieren.

Die zwei verschiedenen Passwörter nicht verwechseln

• SHOWDOC_PASSWORD: Das Zugriffspasswort für die ShowDoc-Dokumente selbst.

• SHOWDOC_MCP_TOKEN: Das Bearer-Token, das KI-Clients beim Verbinden mit dem ShowDoc2MD-MCP-Server verwenden.

Sie haben unterschiedliche Zwecke und werden von den MCP-Tools nie zurückgegeben.

Docker

Das Repository enthält eine Dockerfile und docker-compose.example.yml. Beispiel für lokale Bereitstellung:

export SHOWDOC_PASSWORD='your-document-password'
export SHOWDOC_MCP_TOKEN='replace-with-a-long-random-token'
docker compose -f docker-compose.example.yml up -d --build

Standardmäßig wird der Port nur auf 127.0.0.1:18765 des Hosts gemappt. Für den Zugriff von anderen Maschinen müssen sowohl das Port-Mapping als auch der --allowed-host-Parameter im Container-Startbefehl auf die tatsächlich von der KI verwendete Server-IP/Domain geändert werden.

Wie die KI sie verwenden sollte

Normalerweise sind keine speziellen Prompts nötig – der MCP-Server bringt eigene Anweisungen mit. Empfohlene Aufrufreihenfolge:

1. Bei unsicherer Berechtigung: showdoc_probe

2. Zuerst die Struktur ansehen: showdoc_list_pages

3. Nur wenige Inhalte benötigt: showdoc_read_page

4. Analyse des gesamten Projekts: showdoc_read_full

5. Dateien auf der Festplatte benötigt: showdoc_export

Du kannst der KI zum Beispiel direkt sagen:

阅读这个 ShowDoc 并总结它的 API 认证方式：
https://www.showdoc.com.cn/100200/300400

Wenn das Passwort bereits in der Umgebungsvariable SHOWDOC_PASSWORD des MCP-Servers konfiguriert ist, muss die KI das Passwort nicht mehr erhalten.

CLI

Prüfen, ob Zugriff möglich ist

$env:SHOWDOC_PASSWORD='your-document-password'
.\showdoc2md.cmd probe 'https://www.showdoc.com.cn/100200/300400'

Vollständiger Export

.\showdoc2md.cmd export 'https://www.showdoc.com.cn/100200/300400' --output .\output

Das Passwort kann auch direkt übergeben werden:

showdoc2md export 'https://www.showdoc.com.cn/100200/300400' \
  --password 'your-document-password' \
  --output ./output

Die Umgebungsvariable wird empfohlen, damit das Passwort nicht in den Shell-Verlauf gelangt.

Exportstruktur

output/
└── ProjectName_itemId/
    ├── 完整文档.md
    ├── manifest.json
    ├── assets/
    └── pages/
        ├── 0001_Overview.md
        └── API/
            └── 0002_CreateOrder.md

• Normale ShowDoc-Markdown-Seiten werden möglichst originalgetreu gespeichert.

• RunAPI/API-JSON-Seiten werden in lesbares Markdown konvertiert.

• Bilder in Seiten werden standardmäßig nach assets/ heruntergeladen und Links umgeschrieben.

• 完整文档.md fasst die Seiten in Verzeichnisreihenfolge zusammen.

• manifest.json protokolliert Seiten, fehlgeschlagene Einträge und den complete-Status.

Integritätsschutz

ShowDoc2MD tarnt „Teilerfolg" nicht als vollständigen Erfolg:

• Wenn das Projektverzeichnis 0 Seiten zurückgibt, wird direkt ein Fehler gemeldet.

• Wenn eine Seite oder eine angeforderte Ressource fehlschlägt, gilt complete=false.

• Die CLI gibt bei unvollständigem Export einen Exit-Code ungleich 0 zurück.

• MCP-/HTTP-Ergebnisse geben den Integritätsstatus explizit zurück.

Legacy HTTP API

Wenn ein bestehendes System bereits /convert verwendet, kann es weiterlaufen:

.\showdoc2md.cmd serve --host 127.0.0.1 --port 18765

Schnittstelle:

GET  /health
POST /convert

Für neue KI-Integrationen wird empfohlen, direkt MCP zu verwenden, nicht diese Schnittstelle.

Entwicklung und Tests

.\.venv\Scripts\python.exe -m unittest discover -s tests -v

Die Tests verwenden fiktive URLs, fiktive Projekte und einen Fake-Client; sie enthalten keine ShowDoc-Adressen, Dokumentpasswörter oder Exportinhalte des Maintainers.

Aktuelle Grenzen

• Derzeit wird vorrangig der Typ „Projektzugriffspasswort" von ShowDoc abgedeckt.

• Wenn eine ShowDoc-Instanz eine Kontoanmeldung erzwingt (z. B. force_login), reicht möglicherweise nur das Projektpasswort nicht aus.

• Bilder in Seiten werden beim Herunterladen unterstützt; die eigenständige Anhangsliste von ShowDoc ist noch nicht als separate Anhangsfunktion vollständig abgedeckt.

Lizenz

MIT-Lizenz. Siehe LICENSE.