avr-docs-mcp

Servidor MCP de Documentación AVR con Integración Wiki.JS

Este servidor MCP (Protocolo de Contexto de Modelo) proporciona integración con Wiki.JS para buscar y listar páginas desde tu instancia de Wiki.JS.

Características

• Buscar Páginas de Wiki.JS: Busca páginas usando palabras clave o temas
• Listar Páginas de Wiki.JS: Obtén una lista paginada de todas las páginas disponibles
• Obtener Página Específica: Recupera una página específica por su ID
• Prueba de Conexión: Prueba la conexión a tu instancia de Wiki.JS
• Múltiples Modos de Transporte: Soporte para modos stdio y flujo HTTP
• Soporte Docker: Imagen Docker lista para usar con verificaciones de estado

Configuración

Requisitos Previos

1. Una instancia de Wiki.JS en ejecución
2. Una clave API con los permisos apropiados para leer páginas

Variables de Entorno

Puedes establecer las variables de entorno de dos maneras:

Opción 1: Usando un archivo .env (Recomendado)

1. Copia el archivo de entorno de ejemplo:

cp .env.example .env

2. Edita el archivo .env con tus valores reales:

# 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

Opción 2: Usando variables de entorno del sistema

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"

Instalación

1. Instala las dependencias:

npm install

2. Construye el proyecto:

npm run build

3. Prueba la conexión (opcional):

npm test

4. Ejecuta el servidor:

npm start

Para desarrollo:

npm run dev

Modos de Ejecución

El servidor soporta dos modos de operación:

Modo Stdio (Predeterminado)

El servidor se ejecuta en modo stdio por defecto, comunicándose a través de entrada/salida estándar. Este es el modo MCP tradicional.

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

Modo de Flujo HTTP

El servidor también puede ejecutarse en modo HTTP, proporcionando una API REST con Eventos Enviados por el Servidor (SSE) para la comunicación MCP.

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

Al ejecutarse en modo HTTP, el servidor proporciona:

• Verificación de Estado: GET /health - Devuelve el estado del servidor
• Endpoint MCP: POST /mcp - Endpoint de comunicación MCP usando JSON-RPC 2.0

Probando el Modo HTTP

Puedes probar el modo HTTP usando curl o 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
      }
    }
  }'

O usa el cliente de prueba incorporado:

npm run test:http

Uso con Docker

Usando la Imagen 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

Herramientas Disponibles

1. search_wiki_pages

Busca páginas en Wiki.JS usando palabras clave.

Parámetros:

• query (requerido): La consulta de búsqueda
• page (opcional): Número de página para paginación (predeterminado: 1)
• limit (opcional): Número de resultados por página (predeterminado: 10, máx: 50)

2. list_wiki_pages

Lista todas las páginas disponibles en Wiki.JS.

Parámetros:

• page (opcional): Número de página para paginación (predeterminado: 1)
• limit (opcional): Número de resultados por página (predeterminado: 20, máx: 50)

3. get_wiki_page

Obtiene una página específica por su ID o ruta.

Parámetros:

• pageId (requerido): El ID (numérico) o ruta (cadena) de la página a recuperar. Ejemplos: '3' para ID, 'deepgram' para ruta

Configuración de la API de Wiki.JS

Este servidor MCP usa la API GraphQL de Wiki.JS (endpoint /graphql). Asegúrate de que tu instancia de Wiki.JS tenga habilitado el acceso API y que tu clave API tenga los siguientes permisos:

• page:read - Para leer el contenido de la página
• page:list - Para listar páginas
• search:read - Para buscar páginas

El servidor maneja automáticamente las consultas y respuestas GraphQL para todas las operaciones. Ten en cuenta que la API GraphQL de Wiki.JS tiene algunas limitaciones:

• Las operaciones de búsqueda y listado no soportan paginación nativa, por lo que la paginación se simula del lado del cliente
• Los resultados de búsqueda no incluyen el contenido completo de la página
• Los resultados de listado no incluyen el contenido completo de la página (usa get_wiki_page para contenido completo)
• Las etiquetas se devuelven como arrays de cadenas, no como cadenas separadas por comas

Registro

El servidor incluye registro completo con niveles de registro configurables:

• debug - Información detallada de depuración
• info - Información general (predeterminado)
• warn - Solo mensajes de advertencia
• error - Solo mensajes de error

Establece la variable de entorno LOG_LEVEL para controlar la verbosidad del registro.

Manejo de Errores

El servidor incluye manejo completo de errores para:

• Variables de entorno faltantes
• Problemas de conectividad de red
• Fallos de autenticación de API
• IDs de página inválidos
• Limitación de tasa

Desarrollo

Para ejecutar en modo desarrollo con recarga en caliente:

npm run watch

Construcción

Para construir para producción:

npm run build

El JavaScript compilado estará en el directorio dist/.

Soporte y Comunidad

• GitHub: https://github.com/agentvoiceresponse - Reporta problemas, contribuye con código.
• Discord: https://discord.gg/DFTU69Hg74 - Únete a la discusión de la comunidad.
• Docker Hub: https://hub.docker.com/u/agentvoiceresponse - Encuentra imágenes Docker.
• Wiki: https://wiki.agentvoiceresponse.com/en/home - Documentación y guías del proyecto.

Apoya a AVR

AVR es gratuito y de código abierto. Cualquier apoyo es completamente voluntario y pretende ser un gesto personal de agradecimiento. Las donaciones no proporcionan acceso a características, servicios o beneficios especiales, y el proyecto permanece completamente disponible independientemente de las donaciones.

Licencia

Licencia MIT - consulta el archivo LICENSE para más detalles.