使用说明

项目简介

HexDocs MCP 是一个 MCP (Model Context Protocol) 服务器，专注于为 Elixir Hex 包文档提供语义搜索能力。它通过预处理 Hex 包文档，生成向量嵌入，并提供工具接口，使得 AI 客户端能够通过语义搜索快速找到相关的文档内容。该项目包含 Elixir 文档处理工具和 TypeScript MCP 服务器两部分。

主要功能点

文档语义搜索: 通过向量搜索技术，基于自然语言查询在 Elixir Hex 包文档中查找相关信息。
Hex 包文档管理: 支持下载、处理和存储 Hex 包文档，并生成用于语义搜索的向量嵌入。
MCP 工具接口: 提供 'list_packages' 和 'vector_search' 两个 MCP 工具，方便 AI 客户端调用。
- 'list_packages': 列出服务器中已加载文档的 Hex 包列表。
- 'vector_search': 根据用户查询，在指定 Hex 包的文档中进行语义搜索，返回相关文档片段。

安装步骤

克隆仓库

git clone https://github.com/bradleygolden/hexdocs-mcp.git
cd hexdocs-mcp

安装 Elixir 包依赖 (开发环境)

mise install # 如果您安装了 mise
# 或者
mix deps.get # 如果您没有安装 mise，并确保您已安装 Elixir 1.16+

安装 Node.js 依赖并构建 TypeScript 服务器

mise install # 如果您安装了 mise，这将同时安装 Node.js 22+
# 或者
npm install # 如果您没有安装 mise，并确保您已安装 Node.js 22+
npm run build

安装并运行 Ollama
- 访问 Ollama 官网下载并安装 Ollama。
- 拉取 'nomic-embed-text' 嵌入模型：
```
ollama pull nomic-embed-text
```
- 确保 Ollama 服务在后台运行。

服务器配置

MCP 客户端需要配置 'mcpServers' 来连接 HexDocs MCP 服务器。以下是一个示例配置，您需要根据实际路径进行调整：

{
  "mcpServers": {
    "hexdocs-mcp": {
      "command": "node",
      "args": [
        "/path/to/hexdocs-mcp/dist/index.js"  //  请替换为您的 hexdocs-mcp 仓库 dist/index.js 文件的绝对路径
      ],
      "env": {
        "HEXDOCS_MCP_PATH": "/path/to/custom/directory" // 可选：自定义数据库和文档存储路径
      }
    }
  }
}

配置参数说明:

'command': 运行 MCP 服务器的命令，这里是 'node'。
'args': 传递给 'node' 命令的参数，指向编译后的 'index.js' 文件路径。请务必替换 '/path/to/hexdocs-mcp/dist/index.js' 为您本地仓库 'dist/index.js' 文件的绝对路径。
'env': (可选) 环境变量配置。
- 'HEXDOCS_MCP_PATH': 用于自定义 HexDocs MCP 存储数据（数据库、文档等）的路径。如果不设置，默认存储在用户家目录下的 '.hexdocs_mcp' 目录中。

基本使用方法

使用 Elixir 工具下载和处理 Hex 包文档 (在项目根目录执行)

下载并处理指定 Hex 包的最新版本文档 (例如 'phoenix'):

mix hex.docs.mcp fetch phoenix

下载并处理指定 Hex 包的特定版本文档 (例如 'phoenix' 1.5.9):

mix hex.docs.mcp fetch phoenix 1.5.9

使用特定的 embedding model (例如 'all-minilm'):

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

通过 MCP 客户端连接到 HexDocs MCP 服务器
- 确保 MCP 服务器已按照上述配置正确启动。
- 在 MCP 客户端 (如 Cursor, Claude Desktop App, Continue 等) 中配置 'mcpServers'，并选择 'hexdocs-mcp' 服务器。
在 MCP 客户端中使用工具
- 列出可用 Hex 包: 调用 'list_packages' 工具，查看服务器中已加载文档的 Hex 包列表。
- 语义搜索: 调用 'vector_search' 工具，输入 'query' (搜索关键词)、'packageName' (Hex 包名) 等参数，进行文档语义搜索。

示例 AI 助手指令 (Custom Instructions):

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

## HexDocs MCP 工作流

1. 使用 'list_packages' 查看可用的文档包。
2. 使用 'vector_search' 查找相关文档。
3. 对于数据库中没有的包，使用以下命令获取：
   - 'mix hex.docs.mcp fetch PACKAGE'
   - 对于特定版本: 'mix hex.docs.mcp fetch PACKAGE VERSION'

## 环境设置

- 需要运行 Ollama 并拉取 nomic-embed-text 模型
- 默认数据位置: '~/.hexdocs_mcp' (可通过 HEXDOCS_MCP_PATH 配置)
- SQLite 数据库在需要时自动创建

关键词