六边文档-MCP

Name: 六边文档-MCP
Author: bradleygolden

作者：bradleygolden61 星标更新：2025-06-18

安装使用来源：spider==github.com

项目介绍

HexDocs MCP

HexDocs MCP 是一个项目，它为 Hex 包文档提供了语义搜索功能，特别针对AI应用设计。该项目由两个主要组件构成：

一个Elixir二进制文件，用于下载、处理并生成来自Hex包文档的嵌入式数据。
一个实现模型上下文协议（MCP）的TypeScript服务器，该服务器调用Elixir二进制文件来获取和搜索文档。

[!CAUTION] 本文档反映了主分支上的当前开发状态。 如需查看最新稳定版本的文档，请参阅最新发布页面和最新发布分支。

安装

MCP客户端配置

TypeScript MCP服务器实现了模型上下文协议（MCP），旨在被兼容MCP的客户端如Cursor、Claude桌面应用、Continue等使用。服务器提供工具以进行Hex文档的语义搜索。对于完整的MCP兼容客户端列表，请参阅MCP客户端文档。

在您的客户端MCP json配置中添加以下内容：

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

此命令会自动下载Elixir二进制文件以获取文档并进行搜索。虽然服务器负责下载二进制文件，但您仍需要在系统上安装Elixir和Mix，以便HexDocs抓取功能正常工作。

Smithery

或者，您可以使用Smithery自动将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 - 生成嵌入式数据所需
- 运行ollama pull mxbai-embed-large以下载推荐的嵌入式模型
- 在使用嵌入式功能之前确保Ollama正在运行
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维）
现有嵌入式数据不兼容，并将在升级过程中清除

如何升级：

拉取新模型：
```
ollama pull mxbai-embed-large
```
您现有的嵌入式数据将在首次运行任何命令时自动清除
重新生成您的包的嵌入式数据：
```
mix hex.docs.mcp fetch_docs phoenix
```

为什么做出这个改变：mxbai-embed-large提供了显著更好的语义搜索质量，并且在所有平台（Windows/macOS/Linux）上具有一致的维度。

配置

环境变量

可以使用以下环境变量来配置工具：

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

示例：

# 设置自定义存储位置
export HEXDOCS_MCP_PATH=/path/to/custom/directory

# 配置常见项目路径以避免每次指定--project标志
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  # 将使用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

致谢

hex2text - 初始想法和参考

开发

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

设置开发环境

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

# macOS使用Homebrew
brew install mise

# 使用安装脚本
curl https://mise.run | sh

克隆仓库并设置开发环境：

git clone https://github.com/bradleygolden/hexdocs-mcp.git
cd hexdocs-mcp
mise install # 安装正确的Elixir和Node.js版本

设置依赖项：
```
mise build
```

开发任务

Mise定义了一些有用的开发任务：

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

不使用Mise

如果您不希望使用mise，您需要：

Elixir 1.18.x
Node.js 22.x

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

# 代替mise run setup_elixir
mix setup

# 代替mise run setup_ts
npm install

# 代替mise run build
mix compile --no-optional-deps --warnings-as-errors
npm run build

# 代替mise run test
mix test
mix format --check-formatted
mix deps --check-unused
mix deps.unlock --all
mix deps.get
mix test

# 代替mise run mcp_inspect
MCP_INSPECTOR=true npx @modelcontextprotocol/inspector node dist/index.js

AI助手集成

此项目包括自定义指令，以帮助优化与Hex文档一起工作的流程。

示例自定义指令

您可以在仓库中找到示例自定义指令：

Cursor规则 - 适用于Cursor编辑器的自定义规则
GitHub Copilot - 适用于GitHub Copilot的自定义指令

建议的内容

当使用使用Hex包的Elixir项目时：

## HexDocs MCP工作流

1. 使用`search`查找相关文档
2. 使用`fetch`获取包的文档

发布指南

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

版本管理

语义化版本控制：严格遵守语义化版本控制：
- 主要版本：不兼容的API更改
- 次要版本：向后兼容的功能
- 补丁版本：向后兼容的错误修复
版本同步：
- Hex包版本（在mix.exs中）和npm包版本（在package.json中）必须相同
- 更改版本时更新这两个文件

代码风格

格式化和注释：
- 遵循.formatter.exs中定义的Elixir格式化规则
- 除非严格必要，否则不要在代码中添加注释
- 优先使用清晰函数名的自文档代码
- 使用模块和函数文档（@moduledoc和@doc），而不是内联注释

更新CHANGELOG.md

更新CHANGELOG.md：
- 在适当的标题下记录所有更改（新增、更改、修复等）
- 包括新的版本号和日期
- 保留一个[未发布]部分以跟踪当前更改
- 遵循维护CHANGELOG格式
条目格式：
- 使用现在时态，命令式风格（例如，“添加功能”而不是“已添加功能”）
- 适用时包含问题/PR编号
- 分组相关的更改

发布过程

发布前：
- 运行mix test以确保所有测试通过
- 运行mix format以确保代码正确格式化
- 验证CHANGELOG.md已更新
发布提交：
- 创建一个版本提升提交，更新：
  - mix.exs
  - package.json
  - CHANGELOG.md（将[未发布]移动到新版本）
- 使用版本号标记提交（v0.1.0格式）
发布后：
- 在CHANGELOG.md中添加一个新的[未发布]部分
- 更新CHANGELOG.md底部的版本链接

这些指南适用于参与此项目的人员和AI助手。

贡献

欢迎贡献！请随时提交Pull Request。对于重大更改，请先打开一个问题以讨论您想要更改的内容。

此项目根据MIT许可发布 - 详情请参阅LICENSE文件。