AI导哈

语义搜索工具

HexDocs MCP 是一个为Hex包文档提供语义搜索能力的项目，专为AI应用设计。

  • by bradleygolden
  • Elixir
  • 本地部署
  • 70 星标
  • 更新于
在 GitHub 查看 bradleygolden/hexdocs-mcp

使用说明

HexDocs MCP

HexDocs MCP是一个为Hex包文档提供语义搜索功能的项目，专为AI应用程序设计。它由两个主要部分组成：

  1. 从Hex包文档下载、处理和生成嵌入的Elixir二进制文件
  2. 一个实现模型上下文协议（MCP）的TypeScript服务器，它调用Elixir二进制文件来获取和搜索文档

[！小心] 此文档反映了主分支的当前开发状态。 有关最新稳定版本的文档，请参阅 最新发布页面 和那个 最新版本分支.

安装

MCP客户端配置

TypeScript MCP服务器实现了 模型上下文协议（MCP） 并且设计用于MCP兼容客户端，如Cursor、Claude Desktop App、Continue等。服务器提供了对Hex文档进行语义搜索的工具。有关MCP兼容客户端的完整列表，请参阅 MCP客户文件.

将此添加到客户端的MCP json配置中：

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

此命令将自动将长生不老药二进制文件下载到fetch_docs和搜索文档中。虽然服务器处理二进制文件的下载，但您仍然需要在系统上安装Elixir和Mix，以便HexDocs获取功能正常工作。

史密瑟里

或者，您可以使用 史密瑟里 自动将MCP服务器添加到您的客户端配置中。

例如，对于Cursor，可以使用以下命令：

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

Elixir套装

或者，如果您不想使用mcp服务器，可以将hexdocs_mcp包添加到您的项目中。

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

如果你使用floki或任何其他标记为仅在中可用的依赖项 在另一个环境中，将其更新为可用 :dev 环境也是。

例如，floki通常用于 :test:

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

但您可以将其更新为在：dev环境中可用：

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

需求

  • 奥拉马 -生成嵌入所需
    • 跑 ollama pull mxbai-embed-large 下载推荐的嵌入模型
    • 在使用嵌入功能之前，确保Olama正在运行
  • Elixir 1.16+和Erlang/OTP 26+
    • 在CI环境中自动安装
    • 当地发展所需
  • Mix-Elixir构建工具（附带Elixir安装）
  • Node.js 22或更高版本（适用于MCP服务器）

突破性变化：模型迁移（v0.6.0+）

⚠️ 重要：版本0.6.0引入了默认嵌入模型的突破性更改。

发生了什么变化:

  • 默认模型已更改 nomic-embed-text （384个维度）至 mxbai-embed-large （1024个维度）
  • 现有嵌入不兼容，将在升级期间清除

升级:

  1. 拉动新模型：

    ollama pull mxbai-embed-large

  2. 当您首次运行任何命令时，您现有的嵌入将被自动清除

  3. 为您的包重新生成嵌入：

    mix hex.docs.mcp fetch_docs phoenix

为什么会发生这种变化: mxbai-embed-large 在所有平台（Windows/MOSC/Linux）上提供了明显更好的语义搜索质量和一致的维度。

配置

环境变量

以下环境变量可用于配置该工具：

变量 描述 默认值
HEXDOCS_MCP_PATH 数据存储路径 ~/.hexdocs_mcp
HEXDOCS_MCP_MIX_PROJECT_PATHS 以逗号分隔的mix.exs文件路径列表 （无）

示例：

# 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服务器配置

您还可以在服务器的MCP配置中配置环境变量：

{
  "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"
      }
    }
  }
}

用法

AI工具

MCP服务器可供任何与MCP兼容的AI工具使用。服务器将在需要时自动获取文档并将其存储在配置的数据目录中。

请注意，大型软件包的下载和处理需要时间。

Elixir套装

用于矢量存储和检索的SQLite数据库是在需要时自动创建的。

获取文档、处理并生成包的嵌入：

mix hex.docs.mcp fetch_docs phoenix

获取特定版本的文档：

mix hex.docs.mcp fetch_docs phoenix 1.5.9

使用项目中的版本获取包的文档：

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

配置项目路径以避免每次都指定它们：

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

在现有嵌入中搜索：

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

检查包是否存在嵌入：

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

致谢

发展

此项目使用 布置 （前身为rtx）来管理开发工具和任务。Mise在整个项目中提供一致的工具版本和任务自动化。

设置开发环境

  1. 安装mise（如果您还没有）：

    # macOS with Homebrew
brew install mise

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

  2. 克隆存储库并设置开发环境：

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

  3. 安装依赖关系：

    mise build

开发任务

Mise定义了几个有用的开发任务：

  • mise build -构建Elixir和TypeScript组件
  • mise test -运行所有测试
  • mise mcp_inspect -启动MCP检查器以测试服务器
  • mise start_mcp_server -启动MCP服务器（主要用于调试）

没有Mise

如果你不想使用mise，你需要：

  • 灵丹妙药1.18.x
  • Node.js 22.x

然后，您可以直接运行这些命令：

# 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助手集成

该项目包括人工智能助手的自定义说明，以帮助您在使用Hex文档时优化工作流程。

自定义说明示例

您可以在存储库中找到示例自定义说明：

建议内容

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

发布指南

在准备新版本时，请遵循以下准则以确保一致性：

版本管理

  1. SemVer合规性：关注 语义版本控制 严格来说：

    • 主要：不兼容的API更改
    • MINOR：向后兼容功能
    • 补丁：向后兼容的错误修复

  2. 版本同步:

    • 十六进制包版本（in mix.exs)和npm包版本（in package.json)必须相同
    • 更改版本时更新两个文件

代码的风格

  1. 格式和注释:
    • 遵循.formatter.exs中定义的Elixir格式化程序规则
    • 除非上下文有绝对必要，否则不要在代码中添加注释
    • 首选具有清晰函数名的自文档代码
    • 使用模块和函数文档（@moduledoc和@doc）而不是内联注释

变更日志管理

  1. 更新CHANGELOG.md:

    • 在适当的标题下记录所有更改（添加、更改、固定等）
    • 包括新版本号和日期
    • 保留[未发布]部分以跟踪当前更改
    • 跟随 保存变更日志 格式

  2. 输入格式:

    • 使用现在时态、祈使式风格（例如，“添加特征”而不是“添加的特征”）
    • 在适用的情况下，包括问题/PR编号
    • 集团相关变更

发布过程

  1. 发布前:

    • 跑 mix test 确保所有测试通过
    • 跑 mix format 确保代码格式正确
    • 验证CHANGELOG.md是否已更新

  2. 发布承诺:

    • 创建一个版本碰撞提交，更新：
      • mix.exs
      • package.json
      • CHANGELOG.md（将[未发布]移动到新版本）
    • 用版本号标记提交（v0.1.0格式）

  3. 释放后:

    • 在CHANGELOG.md中添加一个新的[未发布]部分
    • 更新CHANGELOG.md底部的版本链接

这些指南适用于参与此项目的人类贡献者和人工智能助理。

贡献

欢迎投稿！请随时提交拉取请求。对于重大更改，请先打开一个问题来讨论您想要更改的内容。

该项目在麻省理工学院获得许可-请参阅 许可证 文件以获取详细信息。

相关 MCP