avr-docs-mcp

AVR Docs MCP Server mit Wiki.JS-Integration

Dieser MCP-Server (Model Context Protocol) bietet Integration mit Wiki.JS zum Suchen und Auflisten von Seiten Ihrer Wiki.JS-Instanz.

Funktionen

• Wiki.JS-Seiten durchsuchen: Suchen Sie nach Seiten mit Schlüsselwörtern oder Themen
• Wiki.JS-Seiten auflisten: Erhalten Sie eine paginierte Liste aller verfügbaren Seiten
• Bestimmte Seite abrufen: Rufen Sie eine bestimmte Seite anhand ihrer ID ab
• Verbindungstest: Testen Sie die Verbindung zu Ihrer Wiki.JS-Instanz
• Mehrere Transportmodi: Unterstützung für stdio- und HTTP-Stream-Modi
• Docker-Unterstützung: Einsatzbereites Docker-Image mit Health Checks

Einrichtung

Voraussetzungen

1. Eine laufende Wiki.JS-Instanz
2. Ein API-Schlüssel mit entsprechenden Berechtigungen zum Lesen von Seiten

Umgebungsvariablen

Sie können Umgebungsvariablen auf zwei Arten setzen:

Option 1: Verwendung einer .env-Datei (Empfohlen)

1. Kopieren Sie die Beispiel-Umgebungsdatei:

cp .env.example .env

2. Bearbeiten Sie die Datei .env mit Ihren tatsächlichen Werten:

# Wiki.JS Configuration
WIKI_JS_BASE_URL=https://your-wiki-instance.com
WIKI_JS_API_KEY=your-api-key-here
LOG_LEVEL=info

# MCP Server Configuration
MCP_MODE=stdio
PORT=3000

Option 2: Verwendung von System-Umgebungsvariablen

export WIKI_JS_BASE_URL="https://your-wiki-instance.com"
export WIKI_JS_API_KEY="your-api-key-here"
export LOG_LEVEL="info"
export MCP_MODE="stdio"
export PORT="3000"

Installation

1. Abhängigkeiten installieren:

npm install

2. Projekt bauen:

npm run build

3. Verbindung testen (optional):

npm test

4. Server starten:

npm start

Für die Entwicklung:

npm run dev

Betriebsmodi

Der Server unterstützt zwei Betriebsmodi:

Stdio-Modus (Standard)

Der Server läuft standardmäßig im stdio-Modus und kommuniziert über Standardeingabe/-ausgabe. Dies ist der traditionelle MCP-Modus.

npm start
# or
npm run start:http  # for HTTP mode
# or
MCP_MODE=stdio npm start

HTTP-Stream-Modus

Der Server kann auch im HTTP-Modus betrieben werden und stellt eine REST-API mit Server-Sent Events (SSE) für die MCP-Kommunikation bereit.

npm run start:http
# or
MCP_MODE=http npm start

Im HTTP-Modus bietet der Server:

• Health Check: GET /health – Gibt den Serverstatus zurück
• MCP-Endpunkt: POST /mcp – MCP-Kommunikationsendpunkt mit JSON-RPC 2.0

Testen des HTTP-Modus

Sie können den HTTP-Modus mit curl oder Postman testen:

# Health check
curl http://localhost:3000/health

# Initialize MCP session
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {
        "name": "curl-client",
        "version": "1.0.0"
      }
    }
  }'

# List available tools (use session ID from initialize response)
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: <session-id-from-initialize>" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

# Call a tool (use session ID from initialize response)
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: <session-id-from-initialize>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "search_wiki_pages",
      "arguments": {
        "query": "deepgram",
        "page": 1,
        "limit": 10
      }
    }
  }'

Oder verwenden Sie den integrierten Testclient:

npm run test:http

Docker-Nutzung

Das Docker-Image verwenden

# Run in stdio mode (default)
docker run -d \
  --name avr-docs-mcp \
  -e WIKI_JS_BASE_URL="https://your-wiki-instance.com" \
  -e WIKI_JS_API_KEY="your-api-key-here" \
  agentvoiceresponse/avr-docs-mcp:latest

# Run in HTTP mode
docker run -d \
  --name avr-docs-mcp \
  -p 3000:3000 \
  -e WIKI_JS_BASE_URL="https://your-wiki-instance.com" \
  -e WIKI_JS_API_KEY="your-api-key-here" \
  -e MCP_MODE="http" \
  -e PORT="3000" \
  agentvoiceresponse/avr-docs-mcp:latest

Docker Compose

version: '3.8'

services:
  avr-docs-mcp:
    image: agentvoiceresponse/avr-docs-mcp:latest
    container_name: avr-docs-mcp
    ports:
      - "3000:3000"  # Only needed for HTTP mode
    environment:
      - WIKI_JS_BASE_URL=https://your-wiki-instance.com
      - WIKI_JS_API_KEY=your-api-key-here
      - MCP_MODE=http
      - PORT=3000
      - LOG_LEVEL=info
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

Verfügbare Werkzeuge

1. search_wiki_pages

Durchsuchen Sie Seiten in Wiki.JS mit Schlüsselwörtern.

Parameter:

• query (erforderlich): Die Suchanfrage
• page (optional): Seitennummer für Paginierung (Standard: 1)
• limit (optional): Anzahl der Ergebnisse pro Seite (Standard: 10, max: 50)

2. list_wiki_pages

Alle verfügbaren Seiten in Wiki.JS auflisten.

Parameter:

• page (optional): Seitennummer für Paginierung (Standard: 1)
• limit (optional): Anzahl der Ergebnisse pro Seite (Standard: 20, max: 50)

3. get_wiki_page

Eine bestimmte Seite anhand ihrer ID oder ihres Pfads abrufen.

Parameter:

• pageId (erforderlich): Die ID (numerisch) oder der Pfad (Zeichenkette) der abzurufenden Seite. Beispiele: '3' für ID, 'deepgram' für Pfad

Wiki.JS API-Konfiguration

Dieser MCP-Server verwendet die Wiki.JS GraphQL-API (Endpunkt /graphql). Stellen Sie sicher, dass Ihre Wiki.JS-Instanz API-Zugriff aktiviert hat und Ihr API-Schlüssel über die folgenden Berechtigungen verfügt:

• page:read – Zum Lesen von Seiteninhalten
• page:list – Zum Auflisten von Seiten
• search:read – Zum Durchsuchen von Seiten

Der Server verarbeitet GraphQL-Abfragen und -Antworten automatisch für alle Operationen. Beachten Sie, dass die Wiki.JS GraphQL-API einige Einschränkungen hat:

• Such- und Auflistungsoperationen unterstützen keine native Paginierung, daher wird die Paginierung clientseitig simuliert
• Suchergebnisse enthalten keinen vollständigen Seiteninhalt
• Listenergebnisse enthalten keinen vollständigen Seiteninhalt (verwenden Sie get_wiki_page für vollständigen Inhalt)
• Tags werden als Arrays von Zeichenketten zurückgegeben, nicht als kommagetrennte Zeichenketten

Protokollierung

Der Server umfasst umfassende Protokollierung mit konfigurierbaren Protokollstufen:

• debug – Detaillierte Debug-Informationen
• info – Allgemeine Informationen (Standard)
• warn – Nur Warnmeldungen
• error – Nur Fehlermeldungen

Setzen Sie die Umgebungsvariable LOG_LEVEL, um die Ausführlichkeit der Protokollierung zu steuern.

Fehlerbehandlung

Der Server umfasst umfassende Fehlerbehandlung für:

• Fehlende Umgebungsvariablen
• Netzwerkverbindungsprobleme
• API-Authentifizierungsfehler
• Ungültige Seiten-IDs
• Ratenbegrenzung

Entwicklung

Um im Entwicklungsmodus mit Hot Reloading zu starten:

npm run watch

Bauen

Für die Produktion bauen:

npm run build

Das kompilierte JavaScript befindet sich im Verzeichnis dist/.

Support & Community

• GitHub: https://github.com/agentvoiceresponse – Probleme melden, Code beitragen.
• Discord: https://discord.gg/DFTU69Hg74 – An der Community-Diskussion teilnehmen.
• Docker Hub: https://hub.docker.com/u/agentvoiceresponse – Docker-Images finden.
• Wiki: https://wiki.agentvoiceresponse.com/en/home – Projektdokumentation und Anleitungen.

AVR unterstützen

AVR ist kostenlos und quelloffen. Jegliche Unterstützung ist vollkommen freiwillig und als persönliche Geste der Wertschätzung gedacht. Spenden gewähren keinen Zugang zu Funktionen, Diensten oder besonderen Vorteilen, und das Projekt bleibt unabhängig von Spenden vollständig verfügbar.

Lizenz

MIT-Lizenz – siehe die Datei LICENSE für Details.