avr-docs-mcp

Serveur MCP AVR Docs avec intégration Wiki.JS

Ce serveur MCP (Model Context Protocol) fournit une intégration avec Wiki.JS pour rechercher et lister des pages depuis votre instance Wiki.JS.

Fonctionnalités

• Rechercher des pages Wiki.JS : Recherchez des pages à l'aide de mots-clés ou de sujets
• Lister les pages Wiki.JS : Obtenez une liste paginée de toutes les pages disponibles
• Obtenir une page spécifique : Récupérez une page spécifique par son ID
• Test de connexion : Testez la connexion à votre instance Wiki.JS
• Modes de transport multiples : Prise en charge des modes stdio et flux HTTP
• Support Docker : Image Docker prête à l'emploi avec vérifications de santé

Configuration

Prérequis

1. Une instance Wiki.JS en cours d'exécution
2. Une clé API avec les autorisations appropriées pour lire les pages

Variables d'environnement

Vous pouvez définir les variables d'environnement de deux manières :

Option 1 : Utiliser un fichier .env (Recommandé)

1. Copiez le fichier d'environnement d'exemple :

cp .env.example .env

2. Modifiez le fichier .env avec vos valeurs réelles :

# 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 : Utiliser les variables d'environnement système

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. Installez les dépendances :

npm install

2. Construisez le projet :

npm run build

3. Testez la connexion (optionnel) :

npm test

4. Lancez le serveur :

npm start

Pour le développement :

npm run dev

Modes de fonctionnement

Le serveur prend en charge deux modes de fonctionnement :

Mode Stdio (Par défaut)

Le serveur fonctionne en mode stdio par défaut, communiquant via l'entrée/sortie standard. C'est le mode MCP traditionnel.

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

Mode Flux HTTP

Le serveur peut également fonctionner en mode HTTP, fournissant une API REST avec des événements envoyés par le serveur (SSE) pour la communication MCP.

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

Lorsqu'il fonctionne en mode HTTP, le serveur fournit :

• Vérification de santé : GET /health - Renvoie l'état du serveur
• Point de terminaison MCP : POST /mcp - Point de terminaison de communication MCP utilisant JSON-RPC 2.0

Test du mode HTTP

Vous pouvez tester le mode HTTP en utilisant curl ou Postman :

# 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
      }
    }
  }'

Ou utilisez le client de test intégré :

npm run test:http

Utilisation de Docker

Utilisation de l'image Docker

# 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

Outils disponibles

1. search_wiki_pages

Recherchez des pages dans Wiki.JS à l'aide de mots-clés.

Paramètres :

• query (requis) : La requête de recherche
• page (optionnel) : Numéro de page pour la pagination (par défaut : 1)
• limit (optionnel) : Nombre de résultats par page (par défaut : 10, max : 50)

2. list_wiki_pages

Listez toutes les pages disponibles dans Wiki.JS.

Paramètres :

• page (optionnel) : Numéro de page pour la pagination (par défaut : 1)
• limit (optionnel) : Nombre de résultats par page (par défaut : 20, max : 50)

3. get_wiki_page

Obtenez une page spécifique par son ID ou son chemin.

Paramètres :

• pageId (requis) : L'ID (numérique) ou le chemin (chaîne) de la page à récupérer. Exemples : '3' pour l'ID, 'deepgram' pour le chemin

Configuration de l'API Wiki.JS

Ce serveur MCP utilise l'API GraphQL de Wiki.JS (point de terminaison /graphql). Assurez-vous que votre instance Wiki.JS a l'accès API activé et que votre clé API dispose des autorisations suivantes :

• page:read - Pour lire le contenu des pages
• page:list - Pour lister les pages
• search:read - Pour rechercher des pages

Le serveur gère automatiquement les requêtes et réponses GraphQL pour toutes les opérations. Notez que l'API GraphQL de Wiki.JS a certaines limitations :

• Les opérations de recherche et de liste ne prennent pas en charge la pagination native, donc la pagination est simulée côté client
• Les résultats de recherche n'incluent pas le contenu complet des pages
• Les résultats de liste n'incluent pas le contenu complet des pages (utilisez get_wiki_page pour le contenu complet)
• Les balises sont renvoyées sous forme de tableaux de chaînes, pas de chaînes séparées par des virgules

Journalisation

Le serveur inclut une journalisation complète avec des niveaux de journalisation configurables :

• debug - Informations de débogage détaillées
• info - Informations générales (par défaut)
• warn - Messages d'avertissement uniquement
• error - Messages d'erreur uniquement

Définissez la variable d'environnement LOG_LEVEL pour contrôler la verbosité de la journalisation.

Gestion des erreurs

Le serveur inclut une gestion complète des erreurs pour :

• Variables d'environnement manquantes
• Problèmes de connectivité réseau
• Échecs d'authentification API
• IDs de page invalides
• Limitation de débit

Développement

Pour exécuter en mode développement avec rechargement à chaud :

npm run watch

Construction

Pour construire pour la production :

npm run build

Le JavaScript compilé se trouvera dans le répertoire dist/.

Support & Communauté

• GitHub : https://github.com/agentvoiceresponse - Signalez des problèmes, contribuez au code.
• Discord : https://discord.gg/DFTU69Hg74 - Rejoignez la discussion communautaire.
• Docker Hub : https://hub.docker.com/u/agentvoiceresponse - Trouvez des images Docker.
• Wiki : https://wiki.agentvoiceresponse.com/en/home - Documentation du projet et guides.

Soutenir AVR

AVR est gratuit et open-source. Tout soutien est entièrement volontaire et destiné à être un geste personnel d'appréciation. Les dons ne donnent pas accès à des fonctionnalités, services ou avantages spéciaux, et le projet reste entièrement disponible indépendamment des dons.

Licence

Licence MIT - voir le fichier LICENSE pour plus de détails.