HexDocs MCP

Pesquisa semântica para documentação de pacotes Hex. Requer instalação local de Elixir e Mix.

GitHub
70
Experimente este MCPPatrocinado

Documentação

HexDocs MCP

HexDocs MCP é um projeto que fornece recursos de busca semântica para documentação de pacotes Hex, projetado especificamente para aplicações de IA. Ele consiste em dois componentes principais:

  1. Um binário Elixir que baixa, processa e gera embeddings a partir da documentação de pacotes Hex
  2. Um servidor TypeScript que implementa o Model Context Protocol (MCP) e chama o binário Elixir para buscar e pesquisar documentação

[!CAUTION] Esta documentação reflete o estado atual de desenvolvimento no branch main. Para documentação sobre a versão estável mais recente, consulte a página da versão mais recente e o branch da versão mais recente.

Instalação

Configuração do Cliente MCP

O servidor MCP TypeScript implementa o Model Context Protocol (MCP) e é projetado para ser usado por clientes compatíveis com MCP, como Cursor, Claude Desktop App, Continue e outros. O servidor fornece ferramentas para busca semântica da documentação Hex. Para uma lista completa de clientes compatíveis com MCP, consulte a documentação de Clientes MCP.

Adicione isto à configuração JSON do MCP do seu cliente:

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

Este comando baixará automaticamente os binários Elixir para buscar e pesquisar documentação. Embora o servidor gerencie o download dos binários, você ainda precisa ter Elixir e Mix instalados no seu sistema para que a funcionalidade de busca do HexDocs funcione corretamente.

Smithery

Alternativamente, você pode usar o Smithery para adicionar automaticamente o servidor MCP à configuração do seu cliente.

Por exemplo, para o Cursor, você pode usar o seguinte comando:

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

Pacote Elixir

Alternativamente, você pode adicionar o pacote hexdocs_mcp ao seu projeto se não quiser usar o servidor MCP.

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

E se você usar floki ou outras dependências marcadas como disponíveis apenas em outro ambiente, atualize-as para que fiquem disponíveis também no ambiente :dev.

Por exemplo, floki é comumente usado em :test:

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

Mas você pode atualizá-lo para que fique disponível no ambiente :dev:

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

Requisitos

  • Ollama - Necessário para gerar embeddings
    • Execute ollama pull mxbai-embed-large para baixar o modelo de embedding recomendado
    • Certifique-se de que o Ollama esteja em execução antes de usar os recursos de embedding
  • Elixir 1.16+ e Erlang/OTP 26+
    • Instalados automaticamente em ambientes CI
    • Necessários localmente para desenvolvimento
  • Mix - A ferramenta de build do Elixir (incluída na instalação do Elixir)
  • Node.js 22 ou posterior (para o servidor MCP)

Mudança Importante: Migração de Modelo (v0.6.0+)

⚠️ IMPORTANTE: A versão 0.6.0 introduz uma mudança importante no modelo de embedding padrão.

O que mudou:

  • O modelo padrão mudou de nomic-embed-text (384 dimensões) para mxbai-embed-large (1024 dimensões)
  • Os embeddings existentes são incompatíveis e serão limpos durante a atualização

Para atualizar:

  1. Baixe o novo modelo:

    ollama pull mxbai-embed-large

  2. Seus embeddings existentes serão limpos automaticamente na primeira execução de qualquer comando

  3. Regere os embeddings para seus pacotes:

    mix hex.docs.mcp fetch_docs phoenix

Por que esta mudança: mxbai-embed-large fornece qualidade de busca semântica significativamente melhor e dimensões consistentes em todas as plataformas (Windows/macOS/Linux).

Configuração

Variáveis de Ambiente

As seguintes variáveis de ambiente podem ser usadas para configurar a ferramenta:

VariávelDescriçãoPadrão
HEXDOCS_MCP_PATHCaminho onde os dados serão armazenados~/.hexdocs_mcp
HEXDOCS_MCP_MIX_PROJECT_PATHSLista separada por vírgulas de caminhos para arquivos mix.exs(nenhum)

Exemplos:

# 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"

Configuração do Servidor MCP

Você também pode configurar variáveis de ambiente na configuração do MCP para o 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

Ferramentas de IA

O servidor MCP pode ser usado por qualquer ferramenta de IA compatível com MCP. O servidor buscará automaticamente a documentação quando necessário e a armazenará no diretório de dados configurado.

Observe que pacotes grandes podem levar tempo para baixar e processar.

Pacote Elixir

O banco de dados SQLite para armazenamento e recuperação de vetores é criado automaticamente quando necessário.

Busque documentação, processe e gere embeddings para um pacote:

mix hex.docs.mcp fetch_docs phoenix

Busque documentação para uma versão específica:

mix hex.docs.mcp fetch_docs phoenix 1.5.9

Busque documentação para um pacote usando a versão do seu projeto:

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

Configure caminhos de projeto para evitar especificá-los toda 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

Pesquise nos embeddings existentes:

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

Verifique se existem embeddings para um pacote:

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

Agradecimentos

  • hex2text - Pela ideia inicial e como referência

Desenvolvimento

Este projeto usa mise (anteriormente rtx) para gerenciar ferramentas de desenvolvimento e tarefas. O Mise fornece versões consistentes de ferramentas e automação de tarefas em todo o projeto.

Configurando o Ambiente de Desenvolvimento

  1. Instale o mise (se ainda não o tiver):

    # macOS with Homebrew
brew install mise

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

  2. Clone o repositório e configure o ambiente de desenvolvimento:

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

  3. Configure as dependências:

    mise build

Tarefas de Desenvolvimento

O Mise define várias tarefas de desenvolvimento úteis:

  • mise build - Compila os componentes Elixir e TypeScript
  • mise test - Executa todos os testes
  • mise mcp_inspect - Inicia o inspetor MCP para testar o servidor
  • mise start_mcp_server - Inicia o servidor MCP (principalmente para depuração)

Sem Mise

Se você preferir não usar o mise, precisará de:

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

Então, você pode executar estes comandos diretamente:

# 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

Integração com Assistente de IA

Este projeto inclui instruções personalizadas para assistentes de IA para ajudar a otimizar seu fluxo de trabalho ao trabalhar com documentação Hex.

Exemplo de Instruções Personalizadas

Você pode encontrar exemplos de instruções personalizadas no repositório:

Conteúdo 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

Diretrizes de Lançamento

Ao preparar um novo lançamento, siga estas diretrizes para garantir consistência:

Gerenciamento de Versão

  1. Conformidade com SemVer: Siga o Versionamento Semântico estritamente:

    • MAJOR: mudanças incompatíveis na API
    • MINOR: funcionalidade compatível com versões anteriores
    • PATCH: correções de bugs compatíveis com versões anteriores

  2. Sincronização de Versão:

    • A versão do pacote Hex (em mix.exs) e a versão do pacote npm (em package.json) DEVEM ser idênticas
    • Atualize ambos os arquivos ao alterar a versão

Estilo de Código

  1. Formatação e Comentários:
    • Siga as regras do formatador Elixir definidas em .formatter.exs
    • Não adicione comentários ao código, a menos que estritamente necessário para contexto
    • Código autodocumentado com nomes de funções claros é preferido
    • Use documentação de módulo e função (@moduledoc e @doc) em vez de comentários inline

Gerenciamento de Changelog

  1. Atualize o CHANGELOG.md:

    • Documente todas as mudanças sob o título apropriado (Adicionado, Alterado, Corrigido, etc.)
    • Inclua o número da nova versão e a data
    • Mantenha uma seção [Não Lançado] para rastrear mudanças atuais
    • Siga o formato Keep a Changelog

  2. Formato de Entrada:

    • Use tempo presente, estilo imperativo (por exemplo, "Adicionar recurso" não "Recurso adicionado")
    • Inclua números de issue/PR quando aplicável
    • Agrupe mudanças relacionadas

Processo de Lançamento

  1. Antes do Lançamento:

    • Execute mix test para garantir que todos os testes passem
    • Execute mix format para garantir que o código esteja formatado corretamente
    • Verifique se o CHANGELOG.md está atualizado

  2. Commits de Lançamento:

    • Crie um commit de incremento de versão que atualize:
      • mix.exs
      • package.json
      • CHANGELOG.md (mova [Não Lançado] para a nova versão)
    • Marque o commit com o número da versão (formato v0.1.0)

  3. Após o Lançamento:

    • Adicione uma nova seção [Não Lançado] ao CHANGELOG.md
    • Atualize os links de versão no final do CHANGELOG.md

Estas diretrizes se aplicam tanto a contribuidores humanos quanto a assistentes de IA que trabalham neste projeto.

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request. Para mudanças importantes, abra uma issue primeiro para discutir o que você gostaria de alterar.

Este projeto é licenciado sob MIT - consulte o arquivo LICENSE para detalhes.