Docs MCP Server

Grounded Docs: El experto en documentación actualizada para tu IA

Docs MCP Server resuelve el problema de las alucinaciones de IA y el conocimiento desactualizado al proporcionar un índice de documentación personal y siempre actualizado para tu asistente de codificación con IA. Obtiene documentación oficial de sitios web, GitHub, npm, PyPI y archivos locales, permitiendo que tu IA consulte la versión exacta que estás utilizando.

✨ ¿Por qué Grounded Docs MCP Server?

La alternativa de código abierto a Context7, Nia y Ref.Tools.

• ✅ Contexto actualizado: Obtiene documentación directamente de fuentes oficiales bajo demanda.
• 🎯 Específico por versión: Las consultas apuntan a las versiones exactas de las bibliotecas en tu proyecto.
• 💡 Reduce alucinaciones: Fundamenta los LLM en documentación real.
• 🔒 Privado y local: Se ejecuta completamente en tu máquina; tu código nunca sale de tu red.
• 🧩 Amplia compatibilidad: Funciona con cualquier cliente compatible con MCP (Claude, Cline, etc.).
• 📁 Múltiples fuentes: Indexa sitios web, repositorios de GitHub, carpetas locales y archivos zip.
• 📄 Soporte de archivos enriquecidos: Procesa HTML, Markdown, PDF, documentos de Office (Word, Excel, PowerPoint), OpenDocument, RTF, EPUB, Jupyter Notebooks y más de 90 lenguajes de código fuente.

📄 Formatos admitidos

Consulta Formatos admitidos para la referencia completa, incluidos los tipos MIME y los detalles de procesamiento.

🚀 Inicio rápido

CLI primero

Para agentes y scripts, la CLI suele ser la forma más sencilla de usar Grounded Docs.

1. Indexa la documentación (requiere Node.js 22+):

npx @arabold/docs-mcp-server@latest scrape react https://react.dev/reference/react

Para sitios de documentación SPA con enrutamiento por hash, habilita la preservación de hash explícitamente:

npx @arabold/docs-mcp-server@latest scrape my-spa https://docs.example.com/#/guide --preserve-hashes

2. Consulta el índice:

npx @arabold/docs-mcp-server@latest search react "useEffect cleanup" --output yaml

3. Obtén una página individual como Markdown:

npx @arabold/docs-mcp-server@latest fetch-url https://react.dev/reference/react/useEffect

Comportamiento de salida

• Los comandos estructurados usan JSON limpio en stdout por defecto en ejecuciones no interactivas.
• Usa --output json|yaml|toon para elegir un formato estructurado.
• Los comandos de texto plano como fetch-url mantienen su carga útil de texto en stdout.
• Los diagnósticos pasan por el registrador compartido y se mantienen fuera de stdout en ejecuciones no interactivas.
• Usa --quiet para suprimir diagnósticos que no sean errores o --verbose para habilitar la salida de depuración.

Habilidades del agente

El directorio skills/ contiene Habilidades del agente que enseñan a los asistentes de codificación con IA cómo usar la CLI, cubriendo búsqueda de documentación, gestión de índices y obtención de URL.

Servidor MCP

Si deseas un endpoint MCP de larga duración para Claude, Cline, Copilot, Gemini CLI u otros clientes MCP:

1. Inicia el servidor:

npx @arabold/docs-mcp-server@latest

2. Abre la interfaz web en http://localhost:6280 para agregar documentación.

3. Conecta tu cliente de IA agregando esto a tu configuración de MCP (por ejemplo, claude_desktop_config.json):

{
  "mcpServers": {
    "docs-mcp-server": {
      "type": "sse",
      "url": "http://localhost:6280/sse"
    }
  }
}

Consulta Conexión de clientes para VS Code (Cline, Roo) y otras opciones de configuración.

scrape_docs también acepta preserveHashes: true para sitios de documentación que usan enrutamiento del lado del cliente basado en hash. Úsalo solo para SPA con enrutamiento por hash; los sitios normales suelen usar fragmentos de hash para anclas dentro de la página.

docker run --rm \
  -v docs-mcp-data:/data \
  -v docs-mcp-config:/config \
  -p 6280:6280 \
  ghcr.io/arabold/docs-mcp-server:latest \
  --protocol http --host 0.0.0.0 --port 6280

🧠 Configurar modelo de incrustación (recomendado)

Usar un modelo de incrustación es opcional, pero mejora drásticamente la calidad de búsqueda al habilitar la búsqueda semántica por vectores.

Ejemplo: Habilitar incrustaciones de OpenAI

OPENAI_API_KEY="sk-proj-..." npx @arabold/docs-mcp-server@latest

Consulta Modelos de incrustación para configurar Ollama, Gemini, Azure y otros.

📚 Documentación

Primeros pasos

• Instalación: Guías de configuración detalladas para Docker, Node.js (npx) y modo integrado.
• Conexión de clientes: Cómo conectar Claude, VS Code (Cline/Roo) y otros clientes MCP.
• Uso básico: Uso de la interfaz web, la CLI y el raspado de archivos locales.
• Configuración: Referencia completa de archivos de configuración y variables de entorno.
• Formatos admitidos: Referencia completa de formatos de archivo y tipos MIME.
• Modelos de incrustación: Configura OpenAI, Ollama, Gemini y otros proveedores.
• Benchmark de calidad de búsqueda: Mide la calidad de recuperación con métricas de IR + puntuaciones evaluadas por LLM; requisitos previos, cómo ejecutarlo, cómo interpretar los resultados.

SPA con enrutamiento por hash

• Usa --preserve-hashes, MCP preserveHashes o la casilla "Preservar rutas hash" de la interfaz web solo para sitios de documentación que enrutan con URLs como #/guide.
• Cuando se habilita con scrapeMode=fetch, el raspador actualiza automáticamente el trabajo a Playwright porque la obtención simple no puede evaluar rutas hash del lado del cliente.
• La actualización reutiliza la configuración almacenada de preserveHashes por defecto, y los puntos de entrada de actualización de CLI/Web pueden anularla explícitamente.

Raspado web optimizado para Markdown

• Los raspados y actualizaciones web prueban automáticamente llms.txt en la subruta de documentación y en la raíz del sitio antes del rastreo normal. Cuando se encuentra, los enlaces seleccionados se convierten en semillas de rastreo adicionales, y las páginas descubiertas de esta manera prefieren variantes de URL .md como /guide/index.html.md o /page.html.md antes de recurrir a la página original.
• Las solicitudes web envían Accept: text/markdown, text/html;q=0.9, */*;q=0.8 por defecto. Los servidores que admiten negociación de contenido Markdown, incluido Cloudflare Markdown for Agents, pueden devolver Markdown directamente para que el raspador omita la conversión de HTML a Markdown y obtenga una salida más limpia.
• Este comportamiento es automático y no requiere configuración. Los encabezados personalizados Accept se conservan cuando se proporcionan.

Conceptos clave y arquitectura

• Modos de implementación: Independiente vs. distribuido (Docker Compose).
• Autenticación: Asegura tu servidor con OAuth2/OIDC.
• Seguridad: Límites de confianza, endurecimiento de la implementación y controles de acceso saliente.
• Telemetría: Recopilación de datos de uso centrada en la privacidad.
• Arquitectura: Análisis profundo del diseño del sistema.

🤝 Contribuciones

¡Agradecemos las contribuciones! Consulta CONTRIBUTING.md para obtener pautas de desarrollo e instrucciones de configuración.

Licencia

Este proyecto está licenciado bajo la Licencia MIT. Consulta LICENSE para más detalles.