HexDocs MCP

Add this to your client's MCP json config:

For example, for Cursor, you can use the following command:

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

Alternatively, you can add the hexdocs_mcp package to your project if you don't want to use the MCP server.

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

And if you use floki or any other dependencies that are marked as only available in another environment, update them to be available in the:devenvironment as well.

For example floki is commonly used in:test:

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

But you can update it to be available in the :dev environment:

- Runollama pull mxbai-embed-largeto download the recommended embedding model
- Ensure Ollama is running before using the embedding features

- Installed automatically in CI environments
- Required locally for development

Breaking Change: Model Migration (v0.6.0+)

⚠️ IMPORTANT: Version 0.6.0 introduces a breaking change with the default embedding model.

- Default model changed fromnomic-embed-text(384 dimensions) tomxbai-embed-large(1024 dimensions)
- Existing embeddings are incompatible and will be cleared during upgrade

Your existing embeddings will be automatically cleared when you first run any command

Regenerate embeddings for your packages:

Why this change:mxbai-embed-largeprovides significantly better semantic search quality and consistent dimensions across all platforms (Windows/macOS/Linux).

The following environment variables can be used to configure the tool:

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

You can also configure environment variables in the MCP configuration for the server:

Install mise (if you don't have it already):

# macOS with Homebrew brew install mise # Using the installer script curl https://mise.run | sh

Clone the repository and setup the development environment:

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

Mise defines several useful development tasks:

- mise build- Build both Elixir and TypeScript components
- mise test- Run all tests
- mise mcp_inspect- Start the MCP inspector for testing the server
- mise start_mcp_server- Start the MCP server (primarily for debugging)

If you prefer not to use mise, you'll need:

Then, you can run these commands directly:

# 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

This project includes custom instructions for AI assistants to help optimize your workflow when working with Hex documentation.

You can find sample custom instructions in the repository:

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

When preparing a new release, please follow these guidelines to ensure consistency:
-

- MAJOR: incompatible API changes
- MINOR: backward-compatible functionality
- PATCH: backward-compatible bug fixes

- Hex package version (inmix.exs) and npm package version (inpackage.json) MUST be identical
- Update both files when changing the version
- Formatting and Comments:

- Follow the Elixir formatter rules defined in .formatter.exs
- Do not add comments to code unless strictly necessary for context
- Self-documenting code with clear function names is preferred
- Use module and function documentation (@moduledoc and @doc) instead of inline comments

- Use present tense, imperative style (e.g., "Add feature" not "Added feature")
- Include issue/PR numbers where applicable
- Group related changes

- Runmix testto ensure all tests pass
- Runmix formatto ensure code is properly formatted
- Verify CHANGELOG.md is updated

- Create a version bump commit that updates:

Search global news using natural language. Webz.io News Search API returns the most relevant articles and content, with filters for source, country, language, date, sentiment, and category.

Retrieve and process documentation using vector search to provide context for AI assistants.

Retrieve and process documentation using vector search to provide relevant context for AI assistants.

Search and query Teleport's documentation using embeddings stored in a local Chroma vector database.