Content
# HexDocs MCP
HexDocs MCP is a project that provides semantic search capabilities for Hex package documentation, designed specifically for AI applications. It consists of two main components:
1. An Elixir binary that downloads, processes, and generates embeddings from Hex package documentation
2. A TypeScript server implementing the Model Context Protocol (MCP) that calls the Elixir binary to fetch and search documentation
> [!CAUTION]
> **This documentation reflects the current development state on the main branch.**
> For documentation on the latest stable release, please see the [latest release page](https://github.com/bradleygolden/hexdocs-mcp/releases/latest) and the [latest release branch](https://github.com/bradleygolden/hexdocs-mcp/tree/v0.5.0).
## Installation
### MCP Client Configuration
The TypeScript MCP server implements the [Model Context Protocol (MCP)](https://modelcontextprotocol.io) and is designed to be used by MCP-compatible clients such as Cursor, Claude Desktop App, Continue, and others. The server provides tools for semantic search of Hex documentation. For a complete list of MCP-compatible clients, see the [MCP Clients documentation](https://modelcontextprotocol.io/clients).
Add this to your client's MCP json config:
```json
{
"mcpServers": {
"hexdocs-mcp": {
"command": "npx",
"args": [
"-y",
"hexdocs-mcp@0.5.0"
]
}
}
}
```
This command will automatically download the elixir binaries to both fetch_docs and search documentation. While the server handles downloading the binaries, you still need Elixir and Mix installed on your system for the HexDocs fetching functionality to work properly.
#### Smithery
Alternatively, you can use [Smithery](https://smithery.ai/server/@bradleygolden/hexdocs-mcp) to automatically add the MCP server to your client config.
For example, for Cursor, you can use the following command:
```bash
npx -y @smithery/cli@latest install @bradleygolden/hexdocs-mcp --client cursor
```
### Elixir Package
Alternatively, you can add the hexdocs_mcp package to your project if you don't want to use the MCP server.
```elixir
{: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 `:dev` environment as well.
For example floki is commonly used in `:test`:
```elixir
{:floki, ">= 0.30.0", only: :test}
```
But you can update it to be available in the :dev environment:
```elixir
{:floki, ">= 0.30.0", only: [:dev, :test]}
```
### Requirements
- [Ollama](https://ollama.ai) - Required for generating embeddings
- Run `ollama pull mxbai-embed-large` to download the recommended embedding model
- Ensure Ollama is running before using the embedding features
- Elixir 1.16+ and Erlang/OTP 26+
- Installed automatically in CI environments
- Required locally for development
- Mix - The Elixir build tool (comes with Elixir installation)
- Node.js 22 or later (for the MCP server)
### Breaking Change: Model Migration (v0.6.0+)
**⚠️ IMPORTANT**: Version 0.6.0 introduces a breaking change with the default embedding model.
**What changed**:
- Default model changed from `nomic-embed-text` (384 dimensions) to `mxbai-embed-large` (1024 dimensions)
- Existing embeddings are incompatible and will be cleared during upgrade
**To upgrade**:
1. Pull the new model:
```bash
ollama pull mxbai-embed-large
```
2. Your existing embeddings will be automatically cleared when you first run any command
3. Regenerate embeddings for your packages:
```bash
mix hex.docs.mcp fetch_docs phoenix
```
**Why this change**: `mxbai-embed-large` provides significantly better semantic search quality and consistent dimensions across all platforms (Windows/macOS/Linux).
## Configuration
### Environment Variables
The following environment variables can be used to configure the tool:
| Variable | Description | Default |
|----------|-------------|---------|
| `HEXDOCS_MCP_PATH` | Path where data will be stored | `~/.hexdocs_mcp` |
| `HEXDOCS_MCP_MIX_PROJECT_PATHS` | Comma-separated list of paths to mix.exs files | (none) |
#### Examples:
```bash
# 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"
```
### MCP Server Configuration
You can also configure environment variables in the MCP configuration for the server:
```json
{
"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"
}
}
}
}
```
## Usage
### AI Tooling
The MCP server can be used by any MCP-compatible AI tooling. The server will automatically fetch documentation when needed and store it in the configured data directory.
Note that large packages make take time to download and process.
### Elixir Package
The SQLite database for vector storage and retrieval is created automatically when needed.
Fetch documentation, process, and generate embeddings for a package:
```bash
mix hex.docs.mcp fetch_docs phoenix
```
Fetch documentation for a specific version:
```bash
mix hex.docs.mcp fetch_docs phoenix 1.5.9
```
Fetch documentation for a package using the version from your project:
```bash
mix hex.docs.mcp fetch_docs phoenix --project path/to/mix.exs
```
Configure project paths to avoid specifying them every time:
```bash
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
```
Search in the existing embeddings:
```bash
mix hex.docs.mcp semantic_search phoenix --query "channels"
```
Check if embeddings exist for a package:
```bash
mix hex.docs.mcp check_embeddings phoenix
mix hex.docs.mcp check_embeddings phoenix 1.7.0
```
## Acknowledgements
- [hex2text](https://github.com/mjrusso/hex2txt) - For the initial idea and as a reference
## Development
This project uses [mise](https://mise.jdx.dev/) (formerly rtx) to manage development tools and tasks. Mise provides consistent tool versions and task automation across the project.
### Setting Up Development Environment
1. Install mise (if you don't have it already):
```bash
# macOS with Homebrew
brew install mise
# Using the installer script
curl https://mise.run | sh
```
2. Clone the repository and setup the development environment:
```bash
git clone https://github.com/bradleygolden/hexdocs-mcp.git
cd hexdocs-mcp
mise install # Installs the right versions of Elixir and Node.js
```
3. Setup dependencies:
```bash
mise build
```
### Development Tasks
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)
### Without Mise
If you prefer not to use mise, you'll need:
- Elixir 1.18.x
- Node.js 22.x
Then, you can run these commands directly:
```bash
# 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
```
## AI Assistant Integration
This project includes custom instructions for AI assistants to help optimize your workflow when working with Hex documentation.
### Example Custom Instructions
You can find sample custom instructions in the repository:
- [Cursor rules](.cursor/rules/hexdocs-mcp.mdc) - Custom rules for Cursor editor
- [GitHub Copilot](.github/copilot/instructions.md) - Custom instructions for GitHub Copilot
### Suggested Content
```
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
```
## Release Guidelines
When preparing a new release, please follow these guidelines to ensure consistency:
### Version Management
1. **SemVer Compliance**: Follow [Semantic Versioning](https://semver.org/) strictly:
- MAJOR: incompatible API changes
- MINOR: backward-compatible functionality
- PATCH: backward-compatible bug fixes
2. **Version Synchronization**:
- Hex package version (in `mix.exs`) and npm package version (in `package.json`) MUST be identical
- Update both files when changing the version
### Code Style
1. **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
### Changelog Management
1. **Update CHANGELOG.md**:
- Document all changes under the appropriate heading (Added, Changed, Fixed, etc.)
- Include the new version number and date
- Keep an [Unreleased] section for tracking current changes
- Follow the [Keep a Changelog](https://keepachangelog.com/) format
2. **Entry Format**:
- Use present tense, imperative style (e.g., "Add feature" not "Added feature")
- Include issue/PR numbers where applicable
- Group related changes
### Release Process
1. **Before Release**:
- Run `mix test` to ensure all tests pass
- Run `mix format` to ensure code is properly formatted
- Verify CHANGELOG.md is updated
2. **Release Commits**:
- Create a version bump commit that updates:
- mix.exs
- package.json
- CHANGELOG.md (move [Unreleased] to new version)
- Tag the commit with the version number (v0.1.0 format)
3. **After Release**:
- Add a new [Unreleased] section to CHANGELOG.md
- Update version links at the bottom of CHANGELOG.md
These guidelines apply to both human contributors and AI assistants working on this project.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
This project is licensed under MIT - see the [LICENSE](https://github.com/bradleygolden/hexdocs-mcp/blob/main/LICENSE) file for details.
