# 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.4.1).

## 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.4.1"
      ]
    }
  }
}
```

This command will automatically download the elixir binaries to both fetch 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.4.1", 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 nomic-embed-text` 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)

## 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_DEFAULT_EMBEDDING_MODEL` | Default model to use for embeddings | `nomic-embed-text` |
| `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

# Use a different default embedding model
export HEXDOCS_MCP_DEFAULT_EMBEDDING_MODEL=all-minilm

# 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_DEFAULT_EMBEDDING_MODEL": "all-minilm",
        "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 phoenix
```

Fetch documentation for a specific version:

```bash
mix hex.docs.mcp fetch phoenix 1.5.9
```

Use a specific embedding model when fetching:

```bash
mix hex.docs.mcp fetch phoenix --model all-minilm
```

Fetch documentation for a package using the version from your project:

```bash
mix hex.docs.mcp fetch 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 phoenix  # Will use the first path from HEXDOCS_MCP_MIX_PROJECT_PATHS
```

Search in the existing embeddings:

```bash
mix hex.docs.mcp search phoenix --query "channels"
```

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