HexDocs MCP

Búsqueda semántica para la documentación de paquetes Hex. Requiere instalación local de Elixir y Mix.

GitHub
70
Prueba este MCPPatrocinado

Documentación

HexDocs MCP

HexDocs MCP es un proyecto que proporciona capacidades de búsqueda semántica para la documentación de paquetes Hex, diseñado específicamente para aplicaciones de IA. Consta de dos componentes principales:

  1. Un binario de Elixir que descarga, procesa y genera embeddings a partir de la documentación de paquetes Hex
  2. Un servidor TypeScript que implementa el Model Context Protocol (MCP) que llama al binario de Elixir para obtener y buscar documentación

[!CAUTION] Esta documentación refleja el estado actual de desarrollo en la rama principal. Para la documentación de la última versión estable, consulte la página de la última versión y la rama de la última versión.

Instalación

Configuración del Cliente MCP

El servidor MCP TypeScript implementa el Model Context Protocol (MCP) y está diseñado para ser utilizado por clientes compatibles con MCP como Cursor, Claude Desktop App, Continue y otros. El servidor proporciona herramientas para la búsqueda semántica de documentación de Hex. Para una lista completa de clientes compatibles con MCP, consulte la documentación de clientes MCP.

Añade esto a la configuración JSON de MCP de tu cliente:

{
  "mcpServers": {
    "hexdocs-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "hexdocs-mcp@0.5.0"
      ]
    }
  }
}

Este comando descargará automáticamente los binarios de Elixir tanto para fetch_docs como para buscar documentación. Aunque el servidor se encarga de descargar los binarios, aún necesitas tener Elixir y Mix instalados en tu sistema para que la funcionalidad de obtención de HexDocs funcione correctamente.

Smithery

Alternativamente, puedes usar Smithery para añadir automáticamente el servidor MCP a la configuración de tu cliente.

Por ejemplo, para Cursor, puedes usar el siguiente comando:

npx -y @smithery/cli@latest install @bradleygolden/hexdocs-mcp --client cursor

Paquete de Elixir

Alternativamente, puedes añadir el paquete hexdocs_mcp a tu proyecto si no quieres usar el servidor MCP.

{:hexdocs_mcp, "~> 0.5.0", only: :dev, runtime: false}

Y si usas floki o cualquier otra dependencia que esté marcada como disponible solo en otro entorno, actualízalas para que también estén disponibles en el entorno :dev.

Por ejemplo, floki se usa comúnmente en :test:

{:floki, ">= 0.30.0", only: :test}

Pero puedes actualizarlo para que esté disponible en el entorno :dev:

{:floki, ">= 0.30.0", only: [:dev, :test]}

Requisitos

  • Ollama - Requerido para generar embeddings
    • Ejecuta ollama pull mxbai-embed-large para descargar el modelo de embeddings recomendado
    • Asegúrate de que Ollama esté en ejecución antes de usar las funciones de embeddings
  • Elixir 1.16+ y Erlang/OTP 26+
    • Instalado automáticamente en entornos CI
    • Requerido localmente para desarrollo
  • Mix - La herramienta de compilación de Elixir (viene con la instalación de Elixir)
  • Node.js 22 o posterior (para el servidor MCP)

Cambio Importante: Migración del Modelo (v0.6.0+)

⚠️ IMPORTANTE: La versión 0.6.0 introduce un cambio importante con el modelo de embeddings predeterminado.

Qué cambió:

  • El modelo predeterminado cambió de nomic-embed-text (384 dimensiones) a mxbai-embed-large (1024 dimensiones)
  • Los embeddings existentes son incompatibles y se borrarán durante la actualización

Para actualizar:

  1. Descarga el nuevo modelo:

    ollama pull mxbai-embed-large

  2. Tus embeddings existentes se borrarán automáticamente la primera vez que ejecutes cualquier comando

  3. Regenera los embeddings para tus paquetes:

    mix hex.docs.mcp fetch_docs phoenix

Por qué este cambio: mxbai-embed-large proporciona una calidad de búsqueda semántica significativamente mejor y dimensiones consistentes en todas las plataformas (Windows/macOS/Linux).

Configuración

Variables de Entorno

Las siguientes variables de entorno se pueden usar para configurar la herramienta:

VariableDescripciónPredeterminado
HEXDOCS_MCP_PATHRuta donde se almacenarán los datos~/.hexdocs_mcp
HEXDOCS_MCP_MIX_PROJECT_PATHSLista separada por comas de rutas a archivos mix.exs(ninguno)

Ejemplos:

# Set custom storage location
export HEXDOCS_MCP_PATH=/path/to/custom/directory

# Configure common project paths to avoid specifying --project flag each time
export HEXDOCS_MCP_MIX_PROJECT_PATHS="/path/to/project1/mix.exs,/path/to/project2/mix.exs"

Configuración del Servidor MCP

También puedes configurar variables de entorno en la configuración MCP del servidor:

{
  "mcpServers": {
    "hexdocs-mcp": {
      "command": "...",
      "args": [
        "..."
      ],
      "env": {
        "HEXDOCS_MCP_PATH": "/path/to/custom/directory",
        "HEXDOCS_MCP_MIX_PROJECT_PATHS": "/path/to/project1/mix.exs,/path/to/project2/mix.exs"
      }
    }
  }
}

Uso

Herramientas de IA

El servidor MCP puede ser utilizado por cualquier herramienta de IA compatible con MCP. El servidor obtendrá automáticamente la documentación cuando sea necesario y la almacenará en el directorio de datos configurado.

Ten en cuenta que los paquetes grandes pueden tardar en descargarse y procesarse.

Paquete de Elixir

La base de datos SQLite para el almacenamiento y recuperación de vectores se crea automáticamente cuando es necesario.

Obtén la documentación, procesa y genera embeddings para un paquete:

mix hex.docs.mcp fetch_docs phoenix

Obtén la documentación para una versión específica:

mix hex.docs.mcp fetch_docs phoenix 1.5.9

Obtén la documentación de un paquete usando la versión de tu proyecto:

mix hex.docs.mcp fetch_docs phoenix --project path/to/mix.exs

Configura las rutas del proyecto para evitar especificarlas cada vez:

export HEXDOCS_MCP_MIX_PROJECT_PATHS="/path/to/project1/mix.exs,/path/to/project2/mix.exs"
mix hex.docs.mcp fetch_docs phoenix  # Will use the first path from HEXDOCS_MCP_MIX_PROJECT_PATHS

Busca en los embeddings existentes:

mix hex.docs.mcp semantic_search phoenix --query "channels"

Comprueba si existen embeddings para un paquete:

mix hex.docs.mcp check_embeddings phoenix
mix hex.docs.mcp check_embeddings phoenix 1.7.0

Agradecimientos

  • hex2text - Por la idea inicial y como referencia

Desarrollo

Este proyecto utiliza mise (anteriormente rtx) para gestionar herramientas y tareas de desarrollo. Mise proporciona versiones de herramientas consistentes y automatización de tareas en todo el proyecto.

Configuración del Entorno de Desarrollo

  1. Instala mise (si aún no lo tienes):

    # macOS with Homebrew
brew install mise

# Using the installer script
curl https://mise.run | sh

  2. Clona el repositorio y configura el entorno de desarrollo:

    git clone https://github.com/bradleygolden/hexdocs-mcp.git
cd hexdocs-mcp
mise install # Installs the right versions of Elixir and Node.js

  3. Configura las dependencias:

    mise build

Tareas de Desarrollo

Mise define varias tareas de desarrollo útiles:

  • mise build - Compila los componentes de Elixir y TypeScript
  • mise test - Ejecuta todas las pruebas
  • mise mcp_inspect - Inicia el inspector MCP para probar el servidor
  • mise start_mcp_server - Inicia el servidor MCP (principalmente para depuración)

Sin Mise

Si prefieres no usar mise, necesitarás:

  • Elixir 1.18.x
  • Node.js 22.x

Luego, puedes ejecutar estos comandos directamente:

# Instead of mise run setup_elixir
mix setup

# Instead of mise run setup_ts
npm install

# Instead of mise run build
mix compile --no-optional-deps --warnings-as-errors
npm run build

# Instead of mise run test
mix test
mix format --check-formatted
mix deps --check-unused
mix deps.unlock --all
mix deps.get
mix test

# Instead of mise run mcp_inspect
MCP_INSPECTOR=true npx @modelcontextprotocol/inspector node dist/index.js

Integración con Asistentes de IA

Este proyecto incluye instrucciones personalizadas para asistentes de IA que ayudan a optimizar tu flujo de trabajo al trabajar con documentación de Hex.

Ejemplo de Instrucciones Personalizadas

Puedes encontrar ejemplos de instrucciones personalizadas en el repositorio:

Contenido Sugerido

When working with Elixir projects that use Hex packages:

## HexDocs MCP Workflow

1. Use `search` to find relevant documentation
2. Use `fetch` to fetch documentation for a package

Directrices de Publicación

Al preparar una nueva publicación, sigue estas directrices para garantizar la coherencia:

Gestión de Versiones

  1. Cumplimiento de SemVer: Sigue Versionado Semántico estrictamente:

    • MAJOR: cambios incompatibles en la API
    • MINOR: funcionalidad compatible con versiones anteriores
    • PATCH: correcciones de errores compatibles con versiones anteriores

  2. Sincronización de Versiones:

    • La versión del paquete Hex (en mix.exs) y la versión del paquete npm (en package.json) DEBEN ser idénticas
    • Actualiza ambos archivos al cambiar la versión

Estilo de Código

  1. Formato y Comentarios:
    • Sigue las reglas del formateador de Elixir definidas en .formatter.exs
    • No añadas comentarios al código a menos que sean estrictamente necesarios para el contexto
    • Se prefiere código autodocumentado con nombres de funciones claros
    • Usa documentación de módulos y funciones (@moduledoc y @doc) en lugar de comentarios en línea

Gestión del Changelog

  1. Actualiza CHANGELOG.md:

    • Documenta todos los cambios bajo el encabezado apropiado (Added, Changed, Fixed, etc.)
    • Incluye el número de versión y la fecha
    • Mantén una sección [Unreleased] para rastrear los cambios actuales
    • Sigue el formato Keep a Changelog

  2. Formato de Entrada:

    • Usa tiempo presente, estilo imperativo (por ejemplo, "Añadir función" no "Función añadida")
    • Incluye números de issue/PR cuando corresponda
    • Agrupa cambios relacionados

Proceso de Publicación

  1. Antes de la Publicación:

    • Ejecuta mix test para asegurarte de que todas las pruebas pasen
    • Ejecuta mix format para asegurarte de que el código esté correctamente formateado
    • Verifica que CHANGELOG.md esté actualizado

  2. Commits de Publicación:

    • Crea un commit de incremento de versión que actualice:
      • mix.exs
      • package.json
      • CHANGELOG.md (mueve [Unreleased] a la nueva versión)
    • Etiqueta el commit con el número de versión (formato v0.1.0)

  3. Después de la Publicación:

    • Añade una nueva sección [Unreleased] a CHANGELOG.md
    • Actualiza los enlaces de versión al final de CHANGELOG.md

Estas directrices se aplican tanto a contribuyentes humanos como a asistentes de IA que trabajan en este proyecto.

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar un Pull Request. Para cambios importantes, abre primero un issue para discutir lo que te gustaría cambiar.

Este proyecto está licenciado bajo MIT - consulta el archivo LICENSE para más detalles.