{"id":27028315,"url":"https://github.com/bradleygolden/hexdocs-mcp","last_synced_at":"2025-10-25T09:01:56.716Z","repository":{"id":285837339,"uuid":"959052039","full_name":"bradleygolden/hexdocs-mcp","owner":"bradleygolden","description":"Semantic search for Hex documentation, right in your editor ✨","archived":false,"fork":false,"pushed_at":"2025-06-18T05:37:20.000Z","size":358,"stargazers_count":58,"open_issues_count":1,"forks_count":3,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-10-14T09:15:37.394Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://hexdocs.pm/hexdocs_mcp/readme.html","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bradleygolden.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-02T07:31:55.000Z","updated_at":"2025-09-26T07:52:49.000Z","dependencies_parsed_at":"2025-06-16T23:23:59.942Z","dependency_job_id":"8114de40-be81-4fb3-b0aa-55a6913a69fb","html_url":"https://github.com/bradleygolden/hexdocs-mcp","commit_stats":null,"previous_names":["bradleygolden/hexdocs-mcp"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/bradleygolden/hexdocs-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bradleygolden%2Fhexdocs-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bradleygolden%2Fhexdocs-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bradleygolden%2Fhexdocs-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bradleygolden%2Fhexdocs-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bradleygolden","download_url":"https://codeload.github.com/bradleygolden/hexdocs-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bradleygolden%2Fhexdocs-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280583899,"owners_count":26355257,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-23T02:00:06.710Z","response_time":142,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-04-05T00:27:39.122Z","updated_at":"2025-10-25T09:01:56.703Z","avatar_url":"https://github.com/bradleygolden.png","language":"Elixir","funding_links":[],"categories":["Resources","Data Analytics","Generative AI"],"sub_categories":["Model Context Protocol (MCP)","Development Tools"],"readme":"# HexDocs MCP\n\nHexDocs MCP is a project that provides semantic search capabilities for Hex package documentation, designed specifically for AI applications. It consists of two main components:\n\n1. An Elixir binary that downloads, processes, and generates embeddings from Hex package documentation\n2. A TypeScript server implementing the Model Context Protocol (MCP) that calls the Elixir binary to fetch and search documentation\n\n\u003e [!CAUTION]\n\u003e **This documentation reflects the current development state on the main branch.**\n\u003e 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).\n\n## Installation\n\n### MCP Client Configuration\n\nThe 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).\n\nAdd this to your client's MCP json config:\n\n```json\n{\n  \"mcpServers\": {\n    \"hexdocs-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"hexdocs-mcp@0.5.0\"\n      ]\n    }\n  }\n}\n```\n\nThis 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.\n\n#### Smithery\n\nAlternatively, you can use [Smithery](https://smithery.ai/server/@bradleygolden/hexdocs-mcp) to automatically add the MCP server to your client config.\n\nFor example, for Cursor, you can use the following command:\n\n```bash\nnpx -y @smithery/cli@latest install @bradleygolden/hexdocs-mcp --client cursor\n```\n\n### Elixir Package\n\nAlternatively, you can add the hexdocs_mcp package to your project if you don't want to use the MCP server.\n\n```elixir\n{:hexdocs_mcp, \"~\u003e 0.5.0\", only: :dev, runtime: false}\n```\n\nAnd if you use floki or any other dependencies that are marked as only available in\nanother environment, update them to be available in the `:dev` environment as well.\n\nFor example floki is commonly used in `:test`:\n\n```elixir\n{:floki, \"\u003e= 0.30.0\", only: :test}\n```\n\nBut you can update it to be available in the :dev environment:\n\n```elixir\n{:floki, \"\u003e= 0.30.0\", only: [:dev, :test]}\n```\n\n### Requirements\n\n- [Ollama](https://ollama.ai) - Required for generating embeddings\n  - Run `ollama pull mxbai-embed-large` to download the recommended embedding model\n  - Ensure Ollama is running before using the embedding features\n- Elixir 1.16+ and Erlang/OTP 26+ \n  - Installed automatically in CI environments\n  - Required locally for development\n- Mix - The Elixir build tool (comes with Elixir installation)\n- Node.js 22 or later (for the MCP server)\n\n### Breaking Change: Model Migration (v0.6.0+)\n\n**⚠️ IMPORTANT**: Version 0.6.0 introduces a breaking change with the default embedding model.\n\n**What changed**: \n- Default model changed from `nomic-embed-text` (384 dimensions) to `mxbai-embed-large` (1024 dimensions)\n- Existing embeddings are incompatible and will be cleared during upgrade\n\n**To upgrade**:\n1. Pull the new model:\n   ```bash\n   ollama pull mxbai-embed-large\n   ```\n\n2. Your existing embeddings will be automatically cleared when you first run any command\n\n3. Regenerate embeddings for your packages:\n   ```bash\n   mix hex.docs.mcp fetch_docs phoenix\n   ```\n\n**Why this change**: `mxbai-embed-large` provides significantly better semantic search quality and consistent dimensions across all platforms (Windows/macOS/Linux).\n\n## Configuration\n\n### Environment Variables\n\nThe following environment variables can be used to configure the tool:\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `HEXDOCS_MCP_PATH` | Path where data will be stored | `~/.hexdocs_mcp` |\n| `HEXDOCS_MCP_MIX_PROJECT_PATHS` | Comma-separated list of paths to mix.exs files | (none) |\n\n#### Examples:\n\n```bash\n# Set custom storage location\nexport HEXDOCS_MCP_PATH=/path/to/custom/directory\n\n# Configure common project paths to avoid specifying --project flag each time\nexport HEXDOCS_MCP_MIX_PROJECT_PATHS=\"/path/to/project1/mix.exs,/path/to/project2/mix.exs\"\n```\n\n### MCP Server Configuration\n\nYou can also configure environment variables in the MCP configuration for the server:\n\n```json\n{\n  \"mcpServers\": {\n    \"hexdocs-mcp\": {\n      \"command\": \"...\",\n      \"args\": [\n        \"...\"\n      ],\n      \"env\": {\n        \"HEXDOCS_MCP_PATH\": \"/path/to/custom/directory\",\n        \"HEXDOCS_MCP_MIX_PROJECT_PATHS\": \"/path/to/project1/mix.exs,/path/to/project2/mix.exs\"\n      }\n    }\n  }\n}\n```\n\n## Usage\n\n### AI Tooling\n\nThe 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.\n\nNote that large packages make take time to download and process.\n\n### Elixir Package\n\nThe SQLite database for vector storage and retrieval is created automatically when needed.\n\nFetch documentation, process, and generate embeddings for a package:\n\n```bash\nmix hex.docs.mcp fetch_docs phoenix\n```\n\nFetch documentation for a specific version:\n\n```bash\nmix hex.docs.mcp fetch_docs phoenix 1.5.9\n```\n\nFetch documentation for a package using the version from your project:\n\n```bash\nmix hex.docs.mcp fetch_docs phoenix --project path/to/mix.exs\n```\n\nConfigure project paths to avoid specifying them every time:\n\n```bash\nexport HEXDOCS_MCP_MIX_PROJECT_PATHS=\"/path/to/project1/mix.exs,/path/to/project2/mix.exs\"\nmix hex.docs.mcp fetch_docs phoenix  # Will use the first path from HEXDOCS_MCP_MIX_PROJECT_PATHS\n```\n\nSearch in the existing embeddings:\n\n```bash\nmix hex.docs.mcp semantic_search phoenix --query \"channels\"\n```\n\nCheck if embeddings exist for a package:\n\n```bash\nmix hex.docs.mcp check_embeddings phoenix\nmix hex.docs.mcp check_embeddings phoenix 1.7.0\n```\n\n## Acknowledgements\n\n- [hex2text](https://github.com/mjrusso/hex2txt) - For the initial idea and as a reference\n\n## Development\n\nThis 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.\n\n### Setting Up Development Environment\n\n1. Install mise (if you don't have it already):\n   ```bash\n   # macOS with Homebrew\n   brew install mise\n   \n   # Using the installer script\n   curl https://mise.run | sh\n   ```\n\n2. Clone the repository and setup the development environment:\n   ```bash\n   git clone https://github.com/bradleygolden/hexdocs-mcp.git\n   cd hexdocs-mcp\n   mise install # Installs the right versions of Elixir and Node.js\n   ```\n\n3. Setup dependencies:\n   ```bash\n   mise build\n   ```\n\n### Development Tasks\n\nMise defines several useful development tasks:\n\n- `mise build` - Build both Elixir and TypeScript components\n- `mise test` - Run all tests\n- `mise mcp_inspect` - Start the MCP inspector for testing the server\n- `mise start_mcp_server` - Start the MCP server (primarily for debugging)\n\n### Without Mise\n\nIf you prefer not to use mise, you'll need:\n\n- Elixir 1.18.x\n- Node.js 22.x\n\nThen, you can run these commands directly:\n\n```bash\n# Instead of mise run setup_elixir\nmix setup\n\n# Instead of mise run setup_ts\nnpm install\n\n# Instead of mise run build\nmix compile --no-optional-deps --warnings-as-errors\nnpm run build\n\n# Instead of mise run test\nmix test\nmix format --check-formatted\nmix deps --check-unused\nmix deps.unlock --all\nmix deps.get\nmix test\n\n# Instead of mise run mcp_inspect\nMCP_INSPECTOR=true npx @modelcontextprotocol/inspector node dist/index.js\n```\n\n## AI Assistant Integration\n\nThis project includes custom instructions for AI assistants to help optimize your workflow when working with Hex documentation.\n\n### Example Custom Instructions\n\nYou can find sample custom instructions in the repository:\n- [Cursor rules](.cursor/rules/hexdocs-mcp.mdc) - Custom rules for Cursor editor\n- [GitHub Copilot](.github/copilot/instructions.md) - Custom instructions for GitHub Copilot\n\n### Suggested Content\n\n```\nWhen working with Elixir projects that use Hex packages:\n\n## HexDocs MCP Workflow\n\n1. Use `search` to find relevant documentation\n2. Use `fetch` to fetch documentation for a package\n```\n\n## Release Guidelines\n\nWhen preparing a new release, please follow these guidelines to ensure consistency:\n\n### Version Management\n\n1. **SemVer Compliance**: Follow [Semantic Versioning](https://semver.org/) strictly:\n   - MAJOR: incompatible API changes\n   - MINOR: backward-compatible functionality\n   - PATCH: backward-compatible bug fixes\n\n2. **Version Synchronization**:\n   - Hex package version (in `mix.exs`) and npm package version (in `package.json`) MUST be identical\n   - Update both files when changing the version\n\n### Code Style\n\n1. **Formatting and Comments**:\n   - Follow the Elixir formatter rules defined in .formatter.exs\n   - Do not add comments to code unless strictly necessary for context\n   - Self-documenting code with clear function names is preferred\n   - Use module and function documentation (@moduledoc and @doc) instead of inline comments\n\n### Changelog Management\n\n1. **Update CHANGELOG.md**:\n   - Document all changes under the appropriate heading (Added, Changed, Fixed, etc.)\n   - Include the new version number and date\n   - Keep an [Unreleased] section for tracking current changes\n   - Follow the [Keep a Changelog](https://keepachangelog.com/) format\n\n2. **Entry Format**:\n   - Use present tense, imperative style (e.g., \"Add feature\" not \"Added feature\")\n   - Include issue/PR numbers where applicable\n   - Group related changes\n\n### Release Process\n\n1. **Before Release**:\n   - Run `mix test` to ensure all tests pass\n   - Run `mix format` to ensure code is properly formatted\n   - Verify CHANGELOG.md is updated\n\n2. **Release Commits**:\n   - Create a version bump commit that updates:\n     - mix.exs\n     - package.json\n     - CHANGELOG.md (move [Unreleased] to new version)\n   - Tag the commit with the version number (v0.1.0 format)\n\n3. **After Release**:\n   - Add a new [Unreleased] section to CHANGELOG.md\n   - Update version links at the bottom of CHANGELOG.md\n\nThese guidelines apply to both human contributors and AI assistants working on this project.\n\n## Contributing\n\nContributions 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.\n\nThis project is licensed under MIT - see the [LICENSE](https://github.com/bradleygolden/hexdocs-mcp/blob/main/LICENSE) file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbradleygolden%2Fhexdocs-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbradleygolden%2Fhexdocs-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbradleygolden%2Fhexdocs-mcp/lists"}