DocsetMCP

DocsetMCP

Accede a tu documentación local de Dash directamente desde asistentes de IA 🚀

DocsetMCP es un servidor de Model Context Protocol (MCP) que integra sin problemas tus docsets locales de Dash con asistentes de IA como Claude, permitiendo acceso instantáneo a documentación sin conexión sin salir de tu conversación.

📋 Tabla de Contenidos

• ¿Por qué DocsetMCP?
• Inicio Rápido
• Características
• Requisitos Previos
• Instalación
• Configuración
• Ejemplos de Uso
• Herramientas Disponibles
• Solución de Problemas
• Desarrollo
• Contribuciones
• Licencia

¿Por qué DocsetMCP?

• 📚 Documentación Instantánea: Sin cambios de ventana, sin búsquedas web. Ve directamente a la documentación en tu conversación con IA
• 🔒 Local y Privado: Trabaja con archivos de docset en tu máquina
• ⚡ Rápidísimo: Caché optimizada y consultas directas a la base de datos
• 🎯 Resultados Precisos: Obtén exactamente lo que necesitas con filtrado inteligente

Inicio Rápido

{
  "mcpServers": {
    "docsetmcp": {
      "command": "uvx",
      "args": ["docsetmcp"]
    }
  }
}

Añádelo a tu configuración de MCP y reinicia tu cliente MCP. Luego intenta preguntar algo como "Encuéntrame la documentación de AppIntent"

✨ Características

Búsqueda de Documentación

• Soporte Multi-Docset: Busca en más de 165 docsets compatibles, incluyendo Apple, NodeJS, Python y más
• Filtrado por Lenguaje: Apunta a lenguajes de programación específicos dentro de los docsets
• Búsqueda por Nombre: Solo devuelve entradas donde los términos de búsqueda coinciden con los nombres de los elementos para resultados precisos
• Clasificación Inteligente: Resultados ordenados por tipo de coincidencia (exacta > prefijo > subcadena) y orden dinámico por tipo
• Guía de Contenedores: Las entradas de frameworks y clases muestran notas de exploración para profundizar en sus miembros

Acceso a Cheatsheets

• Referencia Rápida: Acceso instantáneo a Git, Vim, Docker y más de 40 otros cheatsheets
• Coincidencia Difusa: Encuentra cheatsheets incluso con nombres parciales
• Navegación por Categorías: Explora comandos por categoría dentro de cada cheatsheet
• Búsqueda Interna: Consulta comandos específicos dentro de cualquier cheatsheet

Rendimiento e Integración

• Caché Eficiente: Caché en memoria para consultas repetidas
• Acceso Directo a la Base de Datos: Sin servidores intermedios ni APIs
• Universal: Funciona con Claude Desktop, Cursor, VS Code y cualquier cliente compatible con MCP
• Descubrimiento de Frameworks: Lista todos los frameworks/tipos disponibles en cualquier docset
• Guía de Contenedores: Notas automáticas de exploración para frameworks y clases con miembros

📦 Docsets Compatibles

DocsetMCP soporta más de 165 docsets, incluyendo:

Usa list_available_docsets para ver todos los docsets instalados en tu sistema.

Requisitos Previos

• macOS (Dash es solo para Mac)
• Dash con los docsets deseados descargados
• Python 3.10 o superior
• Gestor de paquetes UV (Cómo Instalar)
• Un asistente de IA que soporte MCP (Claude Desktop, Claude Code CLI, Cursor IDE, etc.)

Configuración

Ubicaciones Personalizadas de Docsets

Por defecto, DocsetMCP busca docsets en los directorios estándar de Dash:

• Docsets: ~/Library/Application Support/Dash/DocSets
• Cheatsheets: ~/Library/Application Support/Dash/Cheat Sheets

Puedes personalizar estas ubicaciones usando:

Variables de Entorno

# Set custom docset directory
export DOCSET_PATH="/path/to/your/docsets"

# Set custom cheatsheet directory  
export CHEATSHEET_PATH="/path/to/your/cheatsheets"

# Run with custom paths
docsetmcp

Argumentos de Línea de Comandos

# Test with custom docset path
docsetmcp --docset-path "/path/to/your/docsets" --list-docsets

# Test with custom cheatsheet path
docsetmcp --cheatsheet-path "/path/to/your/cheatsheets" --test-connection

# Use both custom paths
docsetmcp --docset-path "/custom/docsets" --cheatsheet-path "/custom/cheatsheets"

# Use additional search paths (searches multiple locations)
docsetmcp --additional-docset-paths "/extra/docsets" "/more/docsets"
docsetmcp --additional-cheatsheet-paths "/extra/cheatsheets" "/more/cheatsheets"

Orden de Prioridad:

1. Argumentos de CLI (mayor prioridad)
2. Variables de entorno
3. Ubicaciones predeterminadas de Dash (menor prioridad)

Rutas de Búsqueda Adicionales:

Las opciones --additional-docset-paths y --additional-cheatsheet-paths permiten a DocsetMCP buscar en múltiples ubicaciones más allá de la ruta principal. Esto es útil cuando:

• Tienes docsets en múltiples directorios
• Quieres incluir docsets de terceros o personalizados
• Estás compartiendo docsets entre diferentes herramientas

DocsetMCP descubrirá y configurará automáticamente los docsets encontrados en estas rutas adicionales.

Configuración del Cliente MCP

Elige tu cliente MCP a continuación para instrucciones de configuración específicas:

{
  "mcpServers": {
    "docsetmcp": {
      "command": "uvx",
      "args": ["docsetmcp"]
    }
  }
}

{
  "mcpServers": {
    "docsetmcp": {
      "command": "uvx",
      "args": ["docsetmcp"],
      "env": {
        "DOCSET_PATH": "/path/to/your/docsets",
        "CHEATSHEET_PATH": "/path/to/your/cheatsheets"
      }
    }
  }
}

# For current project
claude mcp add docsetmcp "uvx docsetmcp"

# For all projects
claude mcp add --scope user docsetmcp "uvx docsetmcp"

{
  "mcpServers": {
    "docsetmcp": {
      "command": "uvx",
      "args": ["docsetmcp"]
    }
  }
}

Instalación

Sin Instalación Requerida (Recomendado)

Si tu cliente MCP soporta uvx, ¡no se necesita instalación! El paquete se descargará y ejecutará automáticamente cuando sea necesario. Consulta las secciones de Inicio Rápido o Configuración.

Instalación Manual

Si prefieres instalar localmente o tu cliente MCP no soporta uvx:

pip install docsetmcp

Luego usa docsetmcp en lugar de uvx docsetmcp en tu configuración.

Instalación para Desarrollo

1. Clona e instala:

   git clone https://github.com/codybrom/docsetmcp.git
   cd docsetmcp
   pip install -e .
   

2. Ejecuta las pruebas (opcional):

   # Install test dependencies
   pip install pytest pytest-cov pytest-xdist
   
   # Run basic tests
   pytest tests/test_docsets.py::TestDocsets::test_yaml_structure -v
   
   # Run quick tests (structure + existence checks)
   pytest tests/ -k "yaml_structure or test_docset_exists" -v
   
   # Run full test suite (all docsets)
   pytest tests/ -v
   
   # Run with coverage
   pytest tests/ --cov=docsetmcp --cov-report=html -v
   
   # Validate all local cheatsheets work (integration test)
   python scripts/validate_cheatsheets.py
   

Ejemplos de Uso

Una vez configurado, puedes pedirle a tu asistente de IA que busque documentación de forma natural:

🍎 Desarrollo iOS/macOS

"Search for URLSession documentation"
"Show me how to use AppIntent in SwiftUI"
"Find CarPlay framework documentation"  # Returns framework + related entries with drilldown notes
"Search for CPListTemplate class"       # Returns specific CarPlay class
"Find NSPredicate examples"

🌐 Desarrollo Web

"Look up Express.js middleware documentation"
"Search React hooks in the React docset"
"Find CSS flexbox properties"

🛠️ DevOps y Terminal

"Search git rebase commands in the Git cheatsheet"
"Show Docker compose syntax from the cheatsheet"
"Find bash array manipulation commands"

📊 Ciencia de Datos

"Search pandas DataFrame methods"
"Look up NumPy array broadcasting"
"Find matplotlib pyplot functions"

Uso Avanzado

# Search specific docset with language filter
"Use search_docs for 'URLSession' in the apple_api_reference docset with Swift language"

# Explore framework members using drilldown guidance
"Search for 'SwiftData' then follow the drilldown note to see all members"

# List all available tools
"What frameworks are available in the nodejs docset?"

# Browse cheatsheet categories
"Show all categories in the vim cheatsheet"

Flujo de Descubrimiento

DocsetMCP está diseñado para búsquedas por nombre, no por palabras clave. Sigue este flujo:

1. Comienza con Herramientas de Descubrimiento

# Find what languages are available
"List all available programming languages"

# Find docsets for your language
"Show me all Python docsets"

# See what types are available in a docset
"List all types in the apple_api_reference docset for Swift"

# Browse entries by type with letter filters
"Show me all Classes starting with 'UI' in apple_api_reference for Swift"

2. Luego Busca por Nombres Exactos

# Once you know exact names, search for them
"Search for UIViewController in apple_api_reference with Swift"
"Find readFile documentation in nodejs docset"
"Show me the CarPlay framework documentation"

3. Usa las Notas de Exploración

Cuando encuentres tipos contenedores (frameworks, clases), sigue la guía de exploración:

# Container entry will show: "contains 42 additional members - use search_docs('ContainerName', max_results=50)"
"Search for SwiftData in apple_api_reference with max_results=50"

Cómo Funciona

1. Soporte Multi-Formato: Maneja tanto el formato de caché de Apple como la compresión tarix
2. Acceso Directo a la Base de Datos: Consulta las bases de datos SQLite de Dash para búsquedas rápidas
3. Coincidencia por Nombre: Solo devuelve entradas donde los términos de búsqueda coinciden con los nombres de los elementos (sin falsos positivos)
4. Clasificación Inteligente: Prioriza coincidencias exactas, luego prefijos, luego subcadenas
5. Orden Dinámico por Tipo: Usa archivos de configuración del docset para priorización inteligente de resultados
6. Detección de Contenedores: Detecta automáticamente frameworks/clases con miembros y proporciona guía de exploración
7. Extracción Inteligente: Descomprime el JSON de DocC de Apple o extrae HTML de archivos tarix
8. Formato Markdown: Convierte la documentación a Markdown legible

Herramientas Disponibles

DocsetMCP proporciona once potentes herramientas para acceder a tu documentación:

🔍 search_docs

Busca y extrae documentación de cualquier docset.

📋 search_cheatsheet

Busca en cheatsheets de Dash para referencia rápida de comandos.

📚 list_available_docsets

Lista todos los docsets de Dash instalados con sus lenguajes compatibles.

📝 list_available_cheatsheets

Lista todos los cheatsheets de Dash disponibles que se pueden buscar.

🏗️ list_frameworks

Lista frameworks/tipos dentro de un docset específico.

🌍 list_languages

Descubre todos los lenguajes de programación con documentación disponible.

📖 list_docsets_by_language

Encuentra todos los docsets que soportan un lenguaje de programación específico.

🏷️ list_types

Lista todos los tipos disponibles (Class, Protocol, Function, etc.) en un docset/lenguaje.

📋 list_entries

Lista entradas filtradas por tipo y prefijo de nombre opcional.

📂 list_cheatsheet_categories

Lista todas las categorías dentro de un cheatsheet específico.

📄 fetch_cheatsheet

Obtiene el contenido completo del cheatsheet (recomendado para acceso integral).

Solución de Problemas

Desarrollo

Compilación desde el Código Fuente

# Clone the repository
git clone https://github.com/codybrom/docsetmcp.git
cd docsetmcp

# Install in development mode
pip install -e .

# Install all development dependencies
pip install -r requirements.txt

# Set up pre-commit hooks
pre-commit install

Pruebas

# Run basic structure tests
pytest tests/test_docsets.py::TestDocsets::test_yaml_structure -v

# Run quick tests (structure + existence)
pytest tests/ -k "yaml_structure or test_docset_exists" -v

# Run full test suite (all docsets)
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=docsetmcp --cov-report=html -v

# Run tests in parallel
pytest tests/ -n auto -v

# Validate cheatsheets
python scripts/validate_cheatsheets.py

Calidad del Código

# Format Python code with Black
black docsetmcp/

# Format YAML files with yamlfix
yamlfix docsetmcp/docsets/*.yaml

# Run all pre-commit hooks
pre-commit run --all-files

# Run specific hook
pre-commit run yamlfix --all-files

# Run spell check (cspell installed automatically during setup)
npm run spell

Comandos CLI

# Test version
docsetmcp --version

# List available docsets
docsetmcp --list-docsets

# Test server startup
docsetmcp --test-connection

# Test with custom paths
docsetmcp --docset-path "/custom/path" --list-docsets

Compilación de Distribución

# Build package
python setup.py sdist bdist_wheel

# Install from source
pip install .

Arquitectura

Componentes Principales

• docsetmcp/server.py: Implementación principal del servidor MCP usando FastMCP. Contiene la clase DashExtractor que maneja:

  • Formato de caché de Apple (basado en UUID SHA-1 con compresión brotli)
  • Formato Tarix (archivos tar.gz)
  • Consultas a la base de datos SQLite para búsqueda de documentación
  • Conversión de HTML a Markdown

• docsetmcp/config_loader.py: Sistema de configuración que carga configuraciones YAML para más de 165 docsets compatibles. Proporciona valores predeterminados inteligentes y maneja formatos de configuración tanto simples como complejos.

• docsetmcp/docsets/: Archivos de configuración YAML para cada docset compatible, que definen:

  • Rutas y formatos de docsets
  • Variantes de idioma y filtros
  • Prioridades de tipo para resultados de búsqueda

Detalles Clave de Implementación

1. Soporte Multi-Formato: El servidor detecta y maneja tanto el formato de caché moderno de Apple (usando UUIDs basados en SHA-1) como el formato de compresión tarix más antiguo automáticamente según la configuración del docset.

2. Estrategia de Caché: La documentación extraída se almacena en caché en memoria (_fs_cache para formato Apple, _html_cache para tarix) para mejorar el rendimiento en consultas repetidas.

3. Algoritmo de Búsqueda: Utiliza consultas SQLite LIKE sin distinción de mayúsculas y minúsculas en la base de datos optimizedIndex.dsidx. Los resultados se clasifican por tipo de coincidencia (exacta > prefijo > subcadena) y luego por orden dinámico de tipos desde los archivos de configuración del docset. Solo devuelve entradas donde el término de búsqueda coincide con el nombre del elemento.

4. Carga de Configuración: El ConfigLoader aplica valores predeterminados inteligentes, permitiendo configuraciones YAML mínimas mientras soporta anulaciones complejas cuando sea necesario.

5. Detección de Tipo de Contenedor: Las entradas de framework, clase y módulo incluyen automáticamente notas de profundización cuando contienen miembros adicionales, guiando a los usuarios a buscar contenido más específico.

Contribuciones

¡Damos la bienvenida a las contribuciones! Así es como puedes ayudar:

Agregar Soporte para Nuevos Docsets

1. Crea una configuración YAML en docsetmcp/docsets/:

   # docsetmcp/docsets/my_docset.yaml
   name: My Docset
   description: Brief description of the docset
   docset_path: My_Docset/My_Docset.docset
   languages:
     - python
     - javascript
   

2. Prueba tu configuración:

   pytest tests/test_docsets.py -k "my_docset" -v
   

3. Envía una solicitud de extracción

Reportar Problemas

• 🐛 Reportes de Errores
• 💡 Solicitudes de Funciones
• 📚 Problemas de Documentación

Pautas de Desarrollo

• Sigue las pautas de estilo PEP 8
• Agrega pruebas para nuevas funciones
• Actualiza la documentación según sea necesario
• Mantén los commits enfocados y descriptivos

Arquitectura Técnica

DocsetMCP aprovecha la estructura interna de Dash para un acceso eficiente a la documentación:

• Soporte de Formatos: Maneja tanto el formato de caché moderno de Apple (basado en UUID SHA-1 con compresión brotli) como los archivos tarix tradicionales
• Estrategia de Caché: Caché en memoria para consultas repetidas
• Acceso a Base de Datos: Consultas SQLite directas a los índices optimizados de Dash
• Extracción de Contenido: Extracción inteligente con estrategias de respaldo
• Sistema de Tipos: Anotaciones de tipo completas para mejor soporte de IDE

Licencia

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

Agradecimientos

• Gracias a Kapeli por crear Dash
• Construido sobre el estándar Model Context Protocol
• Inspirado por la comunidad y el ecosistema MCP