docs-mcp-server Servidor MCP

Un servidor MCP para obtener y buscar documentación de paquetes de terceros.

✨ Características principales

• 🌐 Scraping versátil: obtenga documentación de diversas fuentes, como sitios web, GitHub, npm, PyPI o archivos locales.
• 🧠 Procesamiento inteligente: divide automáticamente el contenido semánticamente y genera incrustaciones utilizando los modelos que elijas (OpenAI, Google Gemini, Azure OpenAI, AWS Bedrock, Ollama y más).
• 💾 Almacenamiento optimizado: aproveche SQLite con sqlite-vec para un almacenamiento vectorial eficiente y FTS5 para una búsqueda sólida de texto completo.
• 🔍 Búsqueda híbrida potente: combine la similitud vectorial y la búsqueda de texto completo en diferentes versiones de la biblioteca para obtener resultados altamente relevantes.
• ⚙️ Manejo de trabajos asincrónicos: administre las tareas de raspado e indexación de manera eficiente con una cola de trabajos en segundo plano y herramientas MCP/CLI.
• 🐳 Implementación sencilla: póngase en funcionamiento rápidamente usando Docker o npx.

Descripción general

Este proyecto proporciona un servidor de Protocolo de Contexto de Modelo (MCP) diseñado para extraer, procesar, indexar y buscar documentación de diversas bibliotecas y paquetes de software. Obtiene contenido de URLs específicas, lo divide en fragmentos significativos mediante técnicas de división semántica, genera incrustaciones vectoriales con OpenAI y almacena los datos en una base de datos SQLite. El servidor utiliza sqlite-vec para una búsqueda eficiente por similitud vectorial y FTS5 para la búsqueda de texto completo, combinándolos para obtener resultados de búsqueda híbridos. Admite control de versiones, lo que permite almacenar y consultar la documentación de diferentes versiones de la biblioteca (incluido el contenido sin versionar) de forma independiente.

El servidor expone herramientas MCP para:

• Iniciar un trabajo de raspado ( scrape_docs ): devuelve un jobId inmediatamente.
• Comprobación del estado del trabajo ( get_job_status ): recupera el estado actual y el progreso de un trabajo específico.
• Listado de trabajos activos/completados ( list_jobs ): muestra trabajos recientes y en curso.
• Cancelar un trabajo ( cancel_job ): intenta detener un trabajo en ejecución o en cola.
• Buscando documentación ( search_docs ).
• Listado de bibliotecas indexadas ( list_libraries ).
• Encontrar versiones apropiadas ( find_version ).
• Eliminar documentos indexados ( remove_docs ).
• Obtención de URL individuales ( fetch_url ): obtiene una URL y devuelve su contenido como Markdown.

Configuración

Se admiten las siguientes variables de entorno para configurar el comportamiento del modelo de incrustación:

Configuración del modelo de incrustación

• DOCS_MCP_EMBEDDING_MODEL : Opcional. Formato: provider:model_name o simplemente model_name (el valor predeterminado es text-embedding-3-small ). Proveedores compatibles y sus variables de entorno requeridas:
  • openai (predeterminado): utiliza los modelos de incrustación de OpenAI
    • OPENAI_API_KEY : Obligatorio. Su clave de API de OpenAI.
    • OPENAI_ORG_ID : Opcional. Su ID de organización de OpenAI.
    • OPENAI_API_BASE : Opcional. URL base personalizada para API compatibles con OpenAI (p. ej., Ollama, Azure OpenAI).
  • vertex : utiliza incrustaciones de inteligencia artificial de Google Cloud Vertex
    • GOOGLE_APPLICATION_CREDENTIALS : Obligatorio. Ruta al archivo de clave JSON de la cuenta de servicio.
  • gemini : utiliza incrustaciones de Google Generative AI (Gemini)
    • GOOGLE_API_KEY : Obligatorio. Tu clave API de Google.
  • aws : utiliza incrustaciones de AWS Bedrock
    • AWS_ACCESS_KEY_ID : Obligatorio. Clave de acceso de AWS.
    • AWS_SECRET_ACCESS_KEY : Obligatorio. Clave secreta de AWS.
    • AWS_REGION o BEDROCK_AWS_REGION : Obligatorio. Región de AWS para Bedrock.
  • microsoft : utiliza incrustaciones de Azure OpenAI
    • AZURE_OPENAI_API_KEY : Obligatorio. Clave de API de Azure OpenAI.
    • AZURE_OPENAI_API_INSTANCE_NAME : Obligatorio. Nombre de la instancia de Azure.
    • AZURE_OPENAI_API_DEPLOYMENT_NAME : Obligatorio. Nombre de la implementación de Azure.
    • AZURE_OPENAI_API_VERSION : Obligatorio. Versión de la API de Azure.

Dimensiones vectoriales

El esquema de la base de datos utiliza una dimensión fija de 1536 para la incrustación de vectores. Solo se admiten los modelos que generan vectores con una dimensión ≤ 1536, excepto ciertos proveedores (como Gemini) que admiten la reducción de dimensión.

Para las API compatibles con OpenAI (como Ollama), utilice el proveedor openai con OPENAI_API_BASE apuntando a su punto final.

Estas variables se pueden configurar independientemente de cómo ejecute el servidor (Docker, npx o desde la fuente).

Ejecución del servidor MCP

Hay dos formas de ejecutar docs-mcp-server:

Opción 1: Usar Docker (recomendado)

Este es el enfoque recomendado para la mayoría de los usuarios. Es fácil, sencillo y no requiere la instalación de Node.js.

1. Asegúrese de que Docker esté instalado y en ejecución.
2. Configure los ajustes de su MCP:Ejemplo de configuración de Claude/Cline/Roo: agregue el siguiente bloque de configuración a su archivo de configuración de MCP (ajuste la ruta según sea necesario):
   { "mcpServers": { "docs-mcp-server": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "OPENAI_API_KEY", "-v", "docs-mcp-data:/data", "ghcr.io/arabold/docs-mcp-server:latest" ], "env": { "OPENAI_API_KEY": "sk-proj-..." // Required: Replace with your key }, "disabled": false, "autoApprove": [] } } }
   Recuerde reemplazar "sk-proj-..." con su clave API de OpenAI real y reiniciar la aplicación.
3. ¡Listo! El servidor ya estará disponible para tu asistente de IA.

Configuración del contenedor Docker:

• -i : Mantener abierto STDIN, crucial para la comunicación MCP a través de stdio.
• --rm : elimina automáticamente el contenedor cuando sale.
• -e OPENAI_API_KEY : Obligatorio. Establezca su clave de API de OpenAI.
• -v docs-mcp-data:/data : Obligatorio para la persistencia. Monta un Docker llamado volumen docs-mcp-data para almacenar la base de datos. Puede reemplazarlo con una ruta de host específica si lo prefiere (p. ej., -v /path/on/host:/data ).

Cualquier variable de entorno de configuración (ver Configuración más arriba) se puede pasar al contenedor mediante el indicador -e . Por ejemplo:

Opción 2: Usar npx

Este enfoque se recomienda cuando se necesita acceso a archivos locales (por ejemplo, para indexar documentación desde el sistema de archivos local). Si bien esto también se puede lograr montando rutas en un contenedor Docker, usar npx es más sencillo, pero requiere la instalación de Node.js.

1. Asegúrese de que Node.js esté instalado.
2. Configure los ajustes de su MCP:Ejemplo de configuración de Claude/Cline/Roo: agregue el siguiente bloque de configuración a su archivo de configuración de MCP:
   { "mcpServers": { "docs-mcp-server": { "command": "npx", "args": ["-y", "--package=@arabold/docs-mcp-server", "docs-server"], "env": { "OPENAI_API_KEY": "sk-proj-..." // Required: Replace with your key }, "disabled": false, "autoApprove": [] } } }
   Recuerde reemplazar "sk-proj-..." con su clave API de OpenAI real y reiniciar la aplicación.
3. ¡Listo! El servidor ya estará disponible para tu asistente de IA.

Usando la CLI

Puede usar la CLI para gestionar la documentación directamente, ya sea mediante Docker o npx. Importante: Use el mismo método (Docker o npx) tanto para el servidor como para la CLI para garantizar el acceso a la misma documentación indexada.

Uso de Docker CLI

Si está ejecutando el servidor con Docker, utilice Docker también para la CLI:

Asegúrese de usar el mismo nombre de volumen ( docs-mcp-data en este ejemplo) que para el servidor. Cualquier variable de entorno de configuración (consulte "Configuración" más arriba) se puede pasar mediante el parámetro -e , al igual que con el servidor.

Uso de la CLI de npx

Si está ejecutando el servidor con npx, utilice npx también para la CLI:

El enfoque npx utilizará el directorio de datos predeterminado de su sistema (normalmente en su directorio de inicio), lo que garantiza la coherencia entre el servidor y la CLI.

(Consulte “Referencia de comandos CLI” a continuación para conocer los comandos y opciones disponibles).

Referencia de comandos CLI

La línea de docs-cli proporciona comandos para gestionar el índice de documentación. Se puede acceder a ella mediante Docker ( docker run -v docs-mcp-data:/data ghcr.io/arabold/docs-mcp-server:latest docs-cli ... ) o npx ( npx -y --package=@arabold/docs-mcp-server docs-cli ... ).

Ayuda general:

Ayuda específica del comando: (reemplace docs-cli con el comando npx... si no está instalado globalmente)

Obtención de URL individuales ( fetch-url )

Obtiene una URL y convierte su contenido a Markdown. A diferencia de scrape , este comando no rastrea enlaces ni almacena el contenido.

Opciones:

• --no-follow-redirects : deshabilita las siguientes redirecciones HTTP (predeterminado: seguir redirecciones)

Ejemplos:

Documentación de scraping ( scrape )

Extrae e indexa la documentación de una URL determinada para una biblioteca específica.

Opciones:

• -v, --version <string> : La versión específica que se asociará con los documentos raspados.
  • Acepta versiones completas ( 1.2.3 ), versiones preliminares ( 1.2.3-beta.1 ) o versiones parciales ( 1 , 1.2 que se han ampliado a 1.0.0 , 1.2.0 ).
  • Si se omite, la documentación se indexa como sin versión .
• -p, --max-pages <number> : Máximo de páginas a raspar (predeterminado: 1000).
• -d, --max-depth <number> : Profundidad máxima de navegación (predeterminado: 3).
• -c, --max-concurrency <number> : Máximo de solicitudes simultáneas (predeterminado: 3).
• --ignore-errors : ignora los errores durante el raspado (predeterminado: verdadero).

Ejemplos:

Búsqueda de documentación ( search )

Busca la documentación indexada de una biblioteca, filtrando opcionalmente por versión.

Opciones:

• -v, --version <string> : La versión o rango de destino dentro del cual buscar.
  • Admite versiones exactas ( 18.0.0 ), versiones parciales ( 18 ) o rangos ( 18.x ).
  • Si se omite, busca la última versión indexada disponible.
  • Si una versión/rango específico no coincide, se recurre a la última versión indexada que sea más antigua que el objetivo.
  • Para buscar solo documentos sin versionar , pase explícitamente una cadena vacía: --version "" . (Nota: Si omite --version , buscará la versión más reciente, que podría estar sin versionar si no existen otras versiones).
• -l, --limit <number> : Número máximo de resultados (predeterminado: 5).
• -e, --exact-match : Solo coincide con la versión exacta especificada (desactiva la coincidencia de rango y de respaldo) (valor predeterminado: falso).

Ejemplos:

Encontrar versiones disponibles ( find-version )

Comprueba el índice para encontrar la mejor versión coincidente para una biblioteca en función de un objetivo e indica si existen documentos sin versión.

Opciones:

• -v, --version <string> : La versión o rango de destino. Si se omite, busca la última versión disponible.

Ejemplos:

Listado de bibliotecas ( list )

Enumera todas las bibliotecas indexadas actualmente en la tienda.

Eliminar documentación ( remove )

Elimina documentos indexados para una biblioteca y versión específicas.

Opciones:

• -v, --version <string> : La versión específica que se eliminará. Si se omite, elimina los documentos no versionados de la biblioteca.

Ejemplos:

Resumen del manejo de versiones

• Scraping: Requiere una versión válida ( XYZ , XYZ-pre , XY , X ) o ninguna versión (para documentos sin versionar). Los rangos ( Xx ) no son válidos para el scraping.
• Búsqueda: Acepta versiones, parciales o rangos específicos ( XYZ , XY , X , Xx ). Recurre a la versión anterior más reciente si el destino no coincide. Omitir la versión se basa en la última versión disponible. La búsqueda explícita --version "" se basa en documentos sin versionar.
• Documentación sin versión: Las bibliotecas pueden tener documentación almacenada sin una versión específica (omitiendo --version durante el scraping). Esta documentación se puede buscar explícitamente usando --version "" . El comando find-version también informará si existe documentación sin versión junto con cualquier coincidencia de semver.

Desarrollo y configuración avanzada

Esta sección explica cómo ejecutar el servidor/CLI directamente desde el código fuente para fines de desarrollo. El método principal de uso ahora es a través de la imagen pública de Docker, como se describe en el "Método 2".

Ejecutar desde la fuente (desarrollo)

Esto proporciona un entorno aislado y expone el servidor a través de puntos finales HTTP.

1. Clonar el repositorio:
   git clone https://github.com/arabold/docs-mcp-server.git # Replace with actual URL if different cd docs-mcp-server
2. Cree un archivo .env : copie el ejemplo y agregue su clave OpenAI (consulte “Configuración del entorno” a continuación).
   cp .env.example .env # Edit .env and add your OPENAI_API_KEY
3. Construya la imagen de Docker:
   docker build -t docs-mcp-server .
4. Ejecute el contenedor Docker:
   # Option 1: Using a named volume (recommended) # Docker automatically creates the volume 'docs-mcp-data' if it doesn't exist on first run. docker run -i --env-file .env -v docs-mcp-data:/data --name docs-mcp-server docs-mcp-server # Option 2: Mapping to a host directory # docker run -i --env-file .env -v /path/on/your/host:/data --name docs-mcp-server docs-mcp-server
   • -i : Mantener STDIN abierto incluso si no está conectado. Esto es crucial para interactuar con el servidor a través de stdio.
   • --env-file .env : carga variables de entorno (como OPENAI_API_KEY ) desde su archivo .env local.
   • -v docs-mcp-data:/data o -v /path/on/your/host:/data : Es crucial para la persistencia. Esto monta un volumen Docker con nombre (Docker crea docs-mcp-data automáticamente si es necesario) o un directorio de host en el directorio /data dentro del contenedor. El directorio /data es donde el servidor almacena su archivo documents.db (según la configuración de DOCS_MCP_STORE_PATH en el Dockerfile). Esto garantiza que la documentación indexada persista incluso si el contenedor se detiene o se elimina.
   • --name docs-mcp-server : asigna un nombre conveniente al contenedor.

   El servidor dentro del contenedor ahora se ejecuta directamente usando Node.js y se comunica a través de stdio .

Este método es útil para contribuir al proyecto o ejecutar versiones no publicadas.

1. Clonar el repositorio:
   git clone https://github.com/arabold/docs-mcp-server.git # Replace with actual URL if different cd docs-mcp-server
2. Instalar dependencias:
   npm install
3. Construir el proyecto: Esto compila TypeScript a JavaScript en el directorio dist/ .
   npm run build
4. Configuración del entorno: Cree y configure su archivo .env como se describe en "Configuración del entorno" a continuación. Esto es crucial para proporcionar la OPENAI_API_KEY .
5. Correr:
   • Servidor (modo de desarrollo): npm run dev:server (compila, supervisa y reinicia)
   • Servidor (modo de producción): npm run start (ejecuta código prediseñado)
   • CLI: npm run cli -- <command> [options] o node dist/cli.js <command> [options]

Configuración del entorno (para Source/Docker)

Nota: Esta configuración del archivo .env es necesaria principalmente al ejecutar el servidor desde el código fuente o al usar el método Docker. Al usar el método de integración npx , OPENAI_API_KEY se configura directamente en el archivo de configuración de MCP.

1. Cree un archivo .env basado en .env.example :
   cp .env.example .env
2. Actualice su clave API de OpenAI en .env :
   # Required: Your OpenAI API key for generating embeddings. OPENAI_API_KEY=your-api-key-here # Optional: Your OpenAI Organization ID (handled automatically by LangChain if set) OPENAI_ORG_ID= # Optional: Custom base URL for OpenAI API (e.g., for Azure OpenAI or compatible APIs) OPENAI_API_BASE= # Optional: Embedding model name (defaults to "text-embedding-3-small") # Examples: text-embedding-3-large, text-embedding-ada-002 DOCS_MCP_EMBEDDING_MODEL= # Optional: Specify a custom directory to store the SQLite database file (documents.db). # If set, this path takes precedence over the default locations. # Default behavior (if unset): # 1. Uses './.store/' in the project root if it exists (legacy). # 2. Falls back to OS-specific data directory (e.g., ~/Library/Application Support/docs-mcp-server on macOS). # DOCS_MCP_STORE_PATH=/path/to/your/desired/storage/directory

Depuración (desde la fuente)

Dado que los servidores MCP se comunican a través de stdio cuando se ejecutan directamente desde Node.js, la depuración puede ser complicada. Recomendamos usar el Inspector MCP , disponible como script de paquete después de la compilación:

El Inspector proporcionará una URL para acceder a las herramientas de depuración en su navegador.

Liberando

Este proyecto utiliza lanzamiento semántico y confirmaciones convencionales para automatizar el proceso de lanzamiento.

Cómo funciona:

1. Mensajes de confirmación: todas las confirmaciones fusionadas en la rama maindeben seguir la especificación de confirmaciones convencionales.
2. Activador manual: el flujo de trabajo de Acciones de GitHub "Lanzamiento" se puede activar manualmente desde la pestaña Acciones cuando esté listo para crear un nuevo lanzamiento.
3. Acciones de semantic-release : determina la versión, actualiza CHANGELOG.md y package.json , confirma, etiqueta, publica en npm y crea una versión de GitHub.

Lo que necesitas hacer:

• Utilice confirmaciones convencionales.
• Fusionar cambios en main .
• Active un lanzamiento manualmente cuando esté listo desde la pestaña Acciones en GitHub.

La automatización maneja: registro de cambios, actualizaciones de versiones, etiquetas, npm publish, lanzamientos de GitHub.

Arquitectura

Para obtener detalles sobre la arquitectura del proyecto y los principios de diseño, consulte ARCHITECTURE.md .

Cabe destacar que la gran mayoría del código de este proyecto fue generado por el asistente de inteligencia artificial Cline, aprovechando las capacidades de este mismo servidor MCP.