docs2mcp

Verwandeln Sie ein Verzeichnis mit Markdown-, HTML- oder TXT-Dateien in einen entfernten, schreibgeschützten MCP-Server, mit dem sich jeder kompatible MCP-Client oder Agent zur Dokumentationsabfrage verbinden kann. Dazu gehören AskMesh, Claude-Integrationen, Codex und benutzerdefinierte MCP-Clients.

Schnellstart

uvx docs2mcp serve ./docs \
  --base-url https://docs.example.com/docs \
  --host 0.0.0.0 \
  --port 8765

uvx erstellt eine isolierte Umgebung von PyPI und führt die veröffentlichte docs2mcp-CLI ohne manuellen Installationsschritt aus. Für die lokale Entwicklung aus einem Checkout verwenden Sie stattdessen python -m docs2mcp.runtime.

Aktivieren Sie die inkrementelle Synchronisierung mit Dateiüberwachung und periodischem Abgleich:

uvx docs2mcp serve ./docs \
  --host 0.0.0.0 \
  --port 8765 \
  --watch \
  --sync-interval 30

Beim ersten Start wird das gesamte Verzeichnis gescannt. Spätere Änderungen werden pro Dokument angewendet: Neue Dateien werden eingefügt, geänderte Dateien neu indiziert, gelöschte Dateien entfernt und unveränderte Dateien übersprungen. Der Watcher verwendet ein kurzes Entprellungsfenster und der periodische Scan bietet einen Fallback für Dateisysteme, die keine zuverlässigen Ereignisse ausgeben.

Wenn Sie an eine bestimmte öffentliche Adresse mit aktiviertem DNS-Rebinding-Schutz binden, erlauben Sie den eingehenden Host-Header explizit:

uvx docs2mcp serve ./docs \
  --host 0.0.0.0 \
  --port 8765 \
  --allowed-host 'docs.example.com:*'

Verwenden Sie für Installation und Start denselben Python-Interpreter. docs2mcp erfordert das offizielle MCP-Python-SDK mcp>=1.27.0,<2; ein älteres oder nicht verwandtes Paket namens mcp stellt mcp.server.fastmcp nicht bereit.

Der Legacy-Befehl doc2mcp bleibt als Kompatibilitätsalias verfügbar.

Der Prozess gibt die MCP-Verbindungskonfiguration beim Start aus. Die Authentifizierung ist optional: Übergeben Sie --token, um die Bearer-Authentifizierung zu aktivieren, oder lassen Sie es weg, um ohne Authentifizierung zu laufen.

{
  "endpoint": "http://127.0.0.1:8765/mcp",
  "auth_type": "none",
  "token": null,
  "search_tool": "search_docs",
  "read_tool": "get_document",
  "contract_version": "agent-qa.docs/v1"
}

Geben Sie die Werte für endpoint, Authentifizierungsmodus, search_docs und get_document in Ihrer MCP-Client-Konfiguration ein. Wenn auth_type den Wert none hat, wählen Sie keine Authentifizierung und lassen Sie das Token leer. Clients, die Streamable HTTP unterstützen, können sich ohne einen AskMesh-spezifischen Adapter mit demselben Endpunkt verbinden.

GET /readyz meldet die Dokumentanzahl und die neuesten Synchronisierungszähler, einschließlich hinzugefügt, aktualisiert, gelöscht, übersprungen, fehlgeschlagen, Dauer und den letzten Fehler.

Related MCP server: Synapse

Unterstützte Formate

Das MVP unterstützt .md, .markdown, .txt, .html und .htm. Die Indizierung verwendet SQLite FTS5, sodass keine separate Vektordatenbank erforderlich ist.

MCP-Vertrag

Der Server implementiert den interoperablen Dokumentvertrag agent-qa.docs/v1 und stellt zwei schreibgeschützte Tools bereit:

• search_docs(query, limit): gibt route, title, url, snippet und score zurück.

• get_document(route, max_characters): gibt Dokumentinhalt, Abschnitte und eine Zitier-URL zurück.

search_docs.query verwendet die SQLite-FTS5-Syntax. Leerzeichen sind eine UND-Abfrage, OR entspricht einem der Begriffe, in Anführungszeichen gesetzter Text sucht nach einer exakten Phrase, NOT schließt einen Begriff aus und * ermöglicht Präfixabgleich. Es handelt sich nicht um eine semantische Suche in natürlicher Sprache; Clients sollten diese Syntax den Benutzern anzeigen.

Verbindung von jedem MCP-Client

Verwenden Sie den Streamable-HTTP-Endpunkt und die beiden Toolnamen in jedem Client, der entfernte MCP-Verbindungen unterstützt. AskMesh ist eine unterstützte Integration; Claude-basierte Clients, Codex und benutzerdefinierte Agenten können denselben Endpunkt und denselben schreibgeschützten Vertrag verwenden.

Aktuelle Einschränkungen

Diese Version ist ein Single-Host-MVP: Dokumente werden aus einem lokalen Verzeichnis importiert und der Index wird in SQLite gespeichert. Git-Synchronisierung, PDF-Parsing, Objektspeicher, Vektorsuche und eine Multi-Tenant-Kontrollebene sind für spätere Versionen geplant.