RAG Documentation MCP Server

Recupera y procesa documentación utilizando búsqueda vectorial para proporcionar contexto relevante a asistentes de IA.

GitHub
64
Prueba este MCPPatrocinado

Documentación

Servidor MCP de Documentación RAG

smithery badge

Una implementación de servidor MCP que proporciona herramientas para recuperar y procesar documentación mediante búsqueda vectorial, permitiendo a los asistentes de IA enriquecer sus respuestas con contexto relevante de documentación.

Tabla de Contenidos

Características

Herramientas

  1. search_documentation

    • Busca en la documentación mediante búsqueda vectorial
    • Devuelve fragmentos relevantes de documentación con información de la fuente

  2. list_sources

    • Lista todas las fuentes de documentación disponibles
    • Proporciona metadatos sobre cada fuente

  3. extract_urls

    • Extrae URLs del texto y verifica si ya están en la documentación
    • Útil para prevenir documentación duplicada

  4. remove_documentation

    • Elimina documentación de una fuente específica
    • Limpia documentación desactualizada o irrelevante

  5. list_queue

    • Lista todos los elementos en la cola de procesamiento
    • Muestra el estado del procesamiento de documentación pendiente

  6. run_queue

    • Procesa todos los elementos de la cola
    • Agrega automáticamente nueva documentación al almacén vectorial

  7. clear_queue

    • Limpia todos los elementos de la cola de procesamiento
    • Útil para restablecer el sistema

  8. add_documentation

    • Agrega nueva documentación directamente al sistema proporcionando una URL
    • Obtiene, procesa e indexa automáticamente el contenido
    • Soporta varios formatos de páginas web y extrae contenido relevante
    • Divide el contenido inteligentemente para una recuperación óptima
    • Parámetro requerido: url (debe incluir el protocolo, por ejemplo, https://)

  9. add_repository

    • Indexa un repositorio de código local para documentación
    • Configura patrones de inclusión/exclusión para archivos y directorios
    • Soporta diferentes estrategias de división según el tipo de archivo
    • Utiliza procesamiento asíncrono para evitar tiempos de espera de MCP con repositorios grandes
    • Proporciona registro detallado de progreso (heartbeat) a stderr durante la indexación
    • Parámetro requerido: path (ruta absoluta al repositorio)

  10. list_repositories

    • Lista todos los repositorios indexados con sus configuraciones
    • Muestra patrones de inclusión/exclusión y estado de vigilancia

  11. update_repository

    • Re-indexa un repositorio con configuración actualizada
    • Puede modificar patrones de inclusión/exclusión y otras configuraciones
    • Proporciona registro detallado de progreso (heartbeat) a stderr durante la re-indexación
    • Parámetro requerido: name (nombre del repositorio)

  12. remove_repository

    • Elimina un repositorio del índice
    • Borra todos los documentos asociados de la base de datos vectorial
    • Parámetro requerido: name (nombre del repositorio)

  13. watch_repository

    • Inicia o detiene la vigilancia de un repositorio para detectar cambios
    • Actualiza automáticamente el índice cuando los archivos cambian
    • Parámetros requeridos: name (nombre del repositorio) y action ("start" o "stop")

  14. get_indexing_status

    • Obtiene el estado actual de las operaciones de indexación de repositorios
    • Proporciona información detallada sobre procesos de indexación en curso o completados
    • Muestra porcentaje de progreso, conteos de archivos e información de tiempo
    • Parámetro opcional: name (nombre del repositorio) - si no se proporciona, devuelve el estado de todos los repositorios

Inicio Rápido

La herramienta de Documentación RAG está diseñada para:

  • Mejorar las respuestas de IA con documentación relevante
  • Construir asistentes de IA conscientes de la documentación
  • Crear herramientas contextuales para desarrolladores
  • Implementar búsqueda semántica de documentación
  • Aumentar las bases de conocimiento existentes

Configuración con Docker Compose

El proyecto incluye un archivo docker-compose.yml para un despliegue contenerizado fácil. Para iniciar los servicios:

docker-compose up -d

Para detener los servicios:

docker-compose down

Interfaz Web

El sistema incluye una interfaz web que se puede acceder después de iniciar los servicios de Docker Compose:

  1. Abra su navegador y navegue a: http://localhost:3030
  2. La interfaz proporciona:
    • Monitoreo de cola en tiempo real
    • Gestión de fuentes de documentación
    • Interfaz de búsqueda para probar consultas
    • Estado del sistema y verificaciones de salud

Configuración

Configuración de Embeddings

El sistema utiliza Ollama como proveedor de embeddings predeterminado para la generación local de embeddings, con OpenAI disponible como opción de respaldo. Esta configuración prioriza el procesamiento local mientras mantiene la confiabilidad mediante respaldo en la nube.

Variables de Entorno

  • EMBEDDING_PROVIDER: Elija el proveedor de embeddings principal ('ollama' o 'openai', predeterminado: 'ollama')
  • EMBEDDING_MODEL: Especifique el modelo a utilizar (opcional)
    • Para OpenAI: predeterminado a 'text-embedding-3-small'
    • Para Ollama: predeterminado a 'nomic-embed-text'
  • OPENAI_API_KEY: Requerido cuando se usa OpenAI como proveedor
  • FALLBACK_PROVIDER: Proveedor de respaldo opcional ('ollama' o 'openai')
  • FALLBACK_MODEL: Modelo opcional para el proveedor de respaldo

Configuración de Cline

Agregue esto a su cline_mcp_settings.json:

{
  "mcpServers": {
    "rag-docs": {
      "command": "node",
      "args": ["/path/to/your/mcp-ragdocs/build/index.js"],
      "env": {
        "EMBEDDING_PROVIDER": "ollama", // default
        "EMBEDDING_MODEL": "nomic-embed-text", // optional
        "OPENAI_API_KEY": "your-api-key-here", // required for fallback
        "FALLBACK_PROVIDER": "openai", // recommended for reliability
        "FALLBACK_MODEL": "nomic-embed-text", // optional
        "QDRANT_URL": "http://localhost:6333"
      },
      "disabled": false,
      "autoApprove": [
        "search_documentation",
        "list_sources",
        "extract_urls",
        "remove_documentation",
        "list_queue",
        "run_queue",
        "clear_queue",
        "add_documentation",
        "add_repository",
        "list_repositories",
        "update_repository",
        "remove_repository",
        "watch_repository",
        "get_indexing_status"
      ]
    }
  }
}

Configuración de Claude Desktop

Agregue esto a su claude_desktop_config.json:

{
  "mcpServers": {
    "rag-docs": {
      "command": "node",
      "args": ["/path/to/your/mcp-ragdocs/build/index.js"],
      "env": {
        "EMBEDDING_PROVIDER": "ollama", // default
        "EMBEDDING_MODEL": "nomic-embed-text", // optional
        "OPENAI_API_KEY": "your-api-key-here", // required for fallback
        "FALLBACK_PROVIDER": "openai", // recommended for reliability
        "FALLBACK_MODEL": "nomic-embed-text", // optional
        "QDRANT_URL": "http://localhost:6333"
      },
      "autoApprove": [
        "search_documentation",
        "list_sources",
        "extract_urls",
        "remove_documentation",
        "list_queue",
        "run_queue",
        "clear_queue",
        "add_documentation",
        "add_repository",
        "list_repositories",
        "update_repository",
        "remove_repository",
        "watch_repository",
        "get_indexing_status"
      ]
    }
  }
}

Configuración Predeterminada

El sistema utiliza Ollama por defecto para una generación eficiente de embeddings locales. Para una confiabilidad óptima:

  1. Instale y ejecute Ollama localmente
  2. Configure OpenAI como respaldo (recomendado): 
    {
  // Ollama is used by default, no need to specify EMBEDDING_PROVIDER
  "EMBEDDING_MODEL": "nomic-embed-text", // optional
  "FALLBACK_PROVIDER": "openai",
  "FALLBACK_MODEL": "text-embedding-3-small",
  "OPENAI_API_KEY": "your-api-key-here"
}

Esta configuración garantiza:

  • Generación rápida de embeddings locales con Ollama
  • Respaldo automático a OpenAI si Ollama falla
  • Sin llamadas API externas a menos que sea necesario

Nota: El sistema utilizará automáticamente las dimensiones vectoriales apropiadas según el proveedor:

  • Ollama (nomic-embed-text): 768 dimensiones
  • OpenAI (text-embedding-3-small): 1536 dimensiones

Gestión de Documentación

Adición Directa vs. Basada en Cola de Documentación

El sistema proporciona dos enfoques complementarios para agregar documentación:

  1. Adición Directa (herramienta add_documentation)

    • Procesa e indexa inmediatamente la documentación desde una URL
    • Mejor para agregar fuentes de documentación individuales
    • Proporciona retroalimentación inmediata sobre el éxito/fracaso del procesamiento
    • Ejemplo de uso: add_documentation con url: "https://example.com/docs"

  2. Procesamiento Basado en Cola

    • Agregue URLs a una cola de procesamiento (extract_urls con add_to_queue: true)
    • Procese múltiples URLs en lote más tarde (run_queue)
    • Mejor para la ingesta de documentación a gran escala
    • Permite el procesamiento programado de muchas fuentes de documentación
    • Proporciona resiliencia a través del sistema de cola

Elija el enfoque que mejor se adapte a sus necesidades de gestión de documentación. Para un número pequeño de documentos importantes, la adición directa proporciona resultados inmediatos. Para conjuntos de documentación grandes o rastreo recursivo, el enfoque basado en cola ofrece mejor escalabilidad.

Indexación de Repositorios Locales

El sistema soporta la indexación de repositorios de código locales, haciendo su contenido buscable junto con la documentación web:

  1. Configuración del Repositorio

    • Defina qué archivos incluir/excluir usando patrones glob
    • Configure estrategias de división por tipo de archivo
    • Configure la detección automática de cambios con modo de vigilancia

  2. Procesamiento de Archivos

    • Los archivos se procesan según su tipo y lenguaje
    • El código se divide inteligentemente para preservar el contexto
    • Se preservan metadatos como la ruta del archivo y el lenguaje

  3. Procesamiento Asíncrono

    • Los repositorios grandes se procesan asincrónicamente para evitar tiempos de espera de MCP
    • La indexación continúa en segundo plano después de la respuesta inicial
    • El progreso se puede monitorear usando la herramienta get_indexing_status
    • Tamaños de lote más pequeños (50 fragmentos por lote) mejoran la capacidad de respuesta

  4. Detección de Cambios

    • Los repositorios pueden ser vigilados para detectar cambios
    • Los archivos modificados se re-indexan automáticamente
    • Los archivos eliminados se eliminan del índice

Ejemplo de uso:

add_repository with {
  "path": "/path/to/your/repo",
  "name": "my-project",
  "include": ["**/*.js", "**/*.ts", "**/*.md"],
  "exclude": ["**/node_modules/**", "**/dist/**"],
  "watchMode": true
}

Después de iniciar el proceso de indexación, puede verificar su estado:

get_indexing_status with {
  "name": "my-project"
}

Esto devolverá información detallada sobre el progreso de la indexación:

Repository: my-project
Status: 🔄 Processing
Progress: 45%
Started: 5/11/2025, 2:45:30 PM
Duration: 3m 15s
Files: 120 processed, 15 skipped (of 250)
Chunks: 1500 indexed (of 3300)
Batch: 15 of 33

Archivo de Configuración del Repositorio

El sistema soporta un archivo de configuración repositories.json que le permite definir repositorios para ser indexados automáticamente al inicio:

{
  "repositories": [
    {
      "path": "/path/to/your/repo",

El archivo de configuración se actualiza automáticamente cuando se agregan, actualizan o eliminan repositorios usando las herramientas de gestión de repositorios. También puede editar manualmente el archivo para configurar repositorios antes de iniciar el servidor. Las rutas dentro del archivo de configuración, como el path para cada repositorio y la ubicación implícita de repositories.json en sí, se resuelven relativas al directorio raíz del proyecto donde se ejecuta el servidor.

Opciones de Configuración:

  • repositories: Matriz de configuraciones de repositorios
    • path: Ruta absoluta al directorio del repositorio "name": "my-project", "include": ["/*.js", "/.ts", "**/.md"], "exclude": ["/node_modules/", "/.git/"], "watchMode": true, "watchInterval": 60000, "chunkSize": 1000, "fileTypeConfig": { ".js": { "include": true, "chunkStrategy": "semantic" }, ".ts": { "include": true, "chunkStrategy": "semantic" }, ".md": { "include": true, "chunkStrategy": "semantic" } } } ], "autoWatch": true }

The configuration file is automatically updated when repositories are added, updated, or removed using the repository management tools. You can also manually edit the file to configure repositories before starting the server.

**Configuration Options:**

- `repositories`: Array of repository configurations
  - `path`: Absolute path to the repository directory
  - `name`: Unique name for the repository
  - `include`: Array of glob patterns to include
  - `exclude`: Array of glob patterns to exclude
  - `watchMode`: Whether to watch for changes
  - `watchInterval`: Polling interval in milliseconds
  - `chunkSize`: Default chunk size for files
  - `fileTypeConfig`: Configuration for specific file types
    - `include`: Whether to include this file type
    - `chunkStrategy`: Chunking strategy ("semantic", "line", or "character")
    - `chunkSize`: Optional override for chunk size

- `autoWatch`: Whether to automatically start watching repositories with `watchMode: true` at startup

## Acknowledgments

This project is a fork of [qpd-v/mcp-ragdocs](https://github.com/qpd-v/mcp-ragdocs), originally developed by qpd-v. The original project provided the foundation for this implementation.

Special thanks to the original creator, qpd-v, for their innovative work on the initial version of this MCP server. This fork has been enhanced with additional features and improvements by Rahul Retnan.

## Troubleshooting

### Server Not Starting (Port Conflict)

If the MCP server fails to start due to a port conflict, follow these steps:

1. Identify and kill the process using port 3030:

```bash
npx kill-port 3030

  1. Reinicie el servidor MCP

  2. Si el problema persiste, verifique otros procesos que usen el puerto:

lsof -i :3030
  1. También puede cambiar el puerto predeterminado en la configuración si es necesario

Herramientas Faltantes en Claude Desktop

Si ciertas herramientas (como add_documentation) no aparecen en Claude Desktop:

  1. Verifique que la herramienta esté correctamente registrada en el archivo handler-registry.ts del servidor
  2. Asegúrese de que la herramienta esté incluida en la respuesta del manejador ListToolsRequestSchema
  3. Verifique que su configuración de Claude Desktop incluya la herramienta en el array autoApprove
  4. Reinicie la aplicación Claude Desktop y el servidor MCP
  5. Verifique los registros del servidor para detectar errores relacionados con el registro de herramientas

La causa más común de herramientas faltantes es que están registradas como manejadores pero no están incluidas en el array tools devuelto por el manejador ListToolsRequestSchema.

Problemas de Tiempo de Espera con Repositorios Grandes

Si encuentra errores de tiempo de espera al indexar repositorios grandes:

  1. El sistema ahora utiliza procesamiento asíncrono para evitar tiempos de espera de MCP
  2. Al agregar un repositorio con add_repository, la indexación continuará en segundo plano
  3. Use la herramienta get_indexing_status para monitorear el progreso
  4. Si aún experimenta problemas, pruebe estas soluciones:
    • Reduzca el alcance de la indexación con patrones de inclusión/exclusión más específicos
    • Divida repositorios muy grandes en unidades lógicas más pequeñas
    • Aumente el tamaño del lote en el código si su sistema tiene más recursos disponibles
    • Verifique los recursos del sistema (memoria, CPU) durante la indexación para identificar cuellos de botella