Hex.pm MCP

hexpm-mcp

用于查询 hex.pm 和 hexdocs.pm 的 MCP 服务——Elixir/Erlang 软件包注册表和文档托管平台。

基于 snodo 构建。它通过 stdio 和 Streamable HTTP 支持 MCP 2026-07-28、2025-11-25 和 2025-06-18。 关于较早版本缺少哪些功能，请参阅协议兼容性。

它提供 24 个工具、六个提示词和软件包资源。工具参数会根据其 JSON Schema 进行验证；每个列表都带有缓存提示，并且可在单页内显示；提示词和资源参数会补全软件包名称。package_review 提示词会在省略参数且客户端支持引导提问时，询问其 focus（质量、安全性或升级）。否则，评审会涵盖这三个方面。

快速开始

一个公共实例正在 https://hexpm-mcp.fly.dev/mcp 上运行。将其添加到 MCP 客户端配置中（Claude Desktop、Claude Code 或任何 MCP 客户端）：

{
  "mcpServers": {
    "hexpm": {
      "type": "http",
      "url": "https://hexpm-mcp.fly.dev/mcp"
    }
  }
}

协议兼容性

MCP 版本	stdio	Streamable HTTP
2026-07-28	是	是
2025-11-25	是	是
2025-06-18	是	是
2025-03-26、2024-11-05	否	否

如果客户端提议的版本不在此表中，服务将提供 2025-11-25。

在 2025-11-25 和 2025-06-18 版本中：

• 服务不会向客户端发送请求，因此，不带 focus 的 package_review 会返回涵盖全部三个方面的评审，而不是发起询问。
• HTTP 为无状态。initialize 不会签发 Mcp-Session-Id，后续每个请求都需要 MCP-Protocol-Version 标头，并且对 /mcp 的 GET 和 DELETE 请求会返回 405。

从 0.3.7 升级。 0.3.7 及更早版本基于 anubis_mcp 构建。它们 还支持 2025-03-26 和 2024-11-05，并通过 GET 事件流维持 HTTP 会话。依赖这些版本的客户端将无法再连接。

于 2026-09-26 通过 stdio 检查：Codex 0.157.1 协商使用 2025-06-18，Claude Code 2.1.283 使用 2026-07-28。

安装

有三种安装方式，可根据使用需求选择。

独立二进制文件（推荐）

适用于 macOS、Linux 和 Windows 的自包含二进制文件。它捆绑了 Erlang 运行时，因此无需 Elixir 工具链。

curl -fsSL https://raw.githubusercontent.com/joshrotenberg/hexpm-mcp/main/scripts/install.sh | sh

安装程序会解析最新版本，选择适用于你操作系统和架构的资源，验证其 sha256，并安装到 ~/.local/bin。如果该目录不在你的 PATH 中，它会告知你。

要选择其他目录或固定版本，请通过 sh 传递标志：

curl -fsSL https://raw.githubusercontent.com/joshrotenberg/hexpm-mcp/main/scripts/install.sh | sh -s -- --install-dir /usr/local/bin
curl -fsSL https://raw.githubusercontent.com/joshrotenberg/hexpm-mcp/main/scripts/install.sh | sh -s -- --version v0.3.6

Windows 使用对应的 PowerShell 命令：

iex (irm https://raw.githubusercontent.com/joshrotenberg/hexpm-mcp/main/scripts/install.ps1)

每个发布版本还会附带归档文件和合并后的 checksums-sha256.txt，方便你选择手动安装。

验证是否运行正常：

hexpm_mcp --version

有关 MCP 客户端配置，请参阅用法；如果 Gatekeeper 阻止了通过浏览器下载的副本，请参阅 macOS：“Apple 无法验证 hexpm_mcp”。

作为 Elixir 库使用

如果要通过 iex 或自己的代码使用公共 API，而不运行 MCP 服务：

def deps do
  [{:hexpm_mcp, "~> 0.3"}]
end

从源代码构建

git clone https://github.com/joshrotenberg/hexpm-mcp.git
cd hexpm-mcp
mix deps.get

功能

• 提供 24 个工具，用于搜索、检查、比较、审计和发现 hex.pm 软件包
• 提供 5 个资源，用于访问结构化的软件包和发现数据
• 提供 5 个引导式分析提示词
• 浏览 HexDocs（模块列表、文档搜索、完整模块文档）
• 通过 Elixir Toolbox 精选发现软件包（分组、趋势、增强搜索）
• 检查 OSV.dev 漏洞
• 审计 Mix.exs 依赖项并检查升级
• 基于 ETS 的响应缓存，支持配置 TTL
• 双传输方式：stdio（Claude Code/Desktop）和 StreamableHTTP（远程）
• 可直接通过 iex 使用的公开 Elixir API

工具

软件包信息

工具	描述
search	按名称或关键词搜索软件包，支持排序和分页
info	软件包元数据、描述、链接、下载统计
versions	版本历史及弃用状态
release	发布详情、发布者、依赖项、构建工具
features	可选依赖项和额外元数据
dependencies	指定版本的依赖项列表
downloads	下载统计（全部时间、近期、每周、每日）
owners	软件包维护者
readme	Markdown 格式的 README 内容

文档浏览

工具	描述
docs	来自 hexdocs.pm 的模块列表（目录）
doc_item	特定模块的完整文档
search_docs	在软件包文档中搜索

分析

工具	描述
compare	并排比较 2–5 个软件包
health	评估维护情况、受欢迎程度、质量和风险
audit	依赖项风险审计（已弃用版本、陈旧程度、巴士系数、CVE）
alternatives	查找并比较类似软件包
dep_tree	递归依赖树（BFS，最大深度为 5）

Mix.exs 分析

工具	描述
audit_mix_deps	审计 deps 列表的陈旧程度、弃用状态、CVE 和巴士系数
upgrade_check	检查哪些依赖项有更新版本，并标记破坏性变更

发现（Elixir Toolbox）

通过 Elixir Toolbox API 精选发现内容。项目结果包含 GitHub/GitLab 统计数据、受欢迎程度评分和健康状况信号，这些信息无法通过原始 hex.pm API 获取。

工具	描述
toolbox_groups	浏览精选的分组和类别体系
toolbox_group	列出单个分组中的类别
toolbox_category	类别中的精选项目（可按名称或下载量排序）
toolbox_trending	趋势中的 Elixir 软件包
toolbox_search	搜索软件包，并显示受欢迎程度和健康状况信号

输出示例

健康检查

# Health Check: req

## Maintenance
- Age: 4 years ago
- Total versions: 52
- Status: **Active**
- Days since last release: 57

## Popularity
- All-time downloads: 11.5M
- Recent (90 days): 1.6M
- Weekly: 141.5K

## Quality
- Documentation: available
- Licenses: Apache-2.0
- Dependencies: 3 required, 4 optional
- Elixir requirement: ~> 1.14

## Risk
- Maintainers: 1 (single maintainer!)
- Retired versions: 0

软件包比较

# Package Comparison

| Metric          | req        | httpoison  | finch      |
| --------------- | ---------- | ---------- | ---------- |
| Downloads (all) | 11.5M      | 129.2M     | 54.1M      |
| Downloads (90d) | 1.6M       | 1.6M       | 2.4M       |
| Latest version  | 0.5.17     | 2.3.0      | 0.21.0     |
| Last updated    | 2026-02-07 | 2025-11-14 | 2026-01-22 |
| License         | Apache-2.0 | MIT        | MIT        |
| Dependencies    | 7          | 1          | 5          |

依赖项审计

# Dependency Audit: phoenix v1.8.5

Checked 10 dependencies. 8 warning(s) across 7 package(s).

- **bandit**: 1 retired version(s)
- **jason**: single maintainer
- **plug**: 2 retired version(s); 3 known vulnerability(ies)
- **telemetry**: no issues

用法

独立二进制文件（stdio）

安装后：

{
  "mcpServers": {
    "hexpm": {
      "command": "hexpm_mcp",
      "args": ["--transport", "stdio"]
    }
  }
}

该二进制文件默认使用 stdio，因此可以省略 args。运行 hexpm_mcp --help 查看完整选项列表。

如需改用 HTTP 提供服务，请传入 --transport http。MCP 服务位于 /mcp：

hexpm_mcp --transport http --port 1234
# MCP endpoint: http://localhost:1234/mcp

macOS：“Apple 无法验证 hexpm_mcp”

这些二进制文件未经代码签名或公证。macOS 会为通过浏览器下载的任何文件添加隔离属性，并拒绝运行带有该属性的未签名可执行文件：

“hexpm_mcp”未打开。 Apple 无法验证“hexpm_mcp”不含可能损害你的 Mac 或泄露隐私的恶意软件。

选择完成，而不是“移到废纸篓”，然后清除该属性：

xattr -d com.apple.quarantine /path/to/hexpm_mcp

也可以通过系统设置操作：打开“隐私与安全性”，然后点击被阻止的二进制文件提示旁边的仍要打开。

上面的安装程序不受影响，因为 curl 不会设置隔离属性。只有通过浏览器下载时才会设置，因此使用 curl 或 wget 安装即可完全避免此问题。如果你确实通过浏览器下载了 tarball，请在终端中使用 tar -xzf 解压，而不要双击，因为“归档实用工具”会将该属性传播到解压后的文件。

从源代码运行（stdio）

例如，开发时可从检出目录运行：

{
  "mcpServers": {
    "hexpm": {
      "command": "mix",
      "args": ["run", "--no-halt", "--", "--transport", "stdio"],
      "cwd": "/path/to/hexpm-mcp"
    }
  }
}

iex

无需 MCP 服务即可直接从 iex 使用公共 API，可以通过 Hex 依赖项调用，也可以直接从检出目录调用：

$ MIX_ENV=test iex -S mix

iex> HexpmMcp.get_info("phoenix")
{:ok, %{
  name: "phoenix",
  description: "Peace of mind from prototype to production",
  downloads: %{all: 148_100_000, recent: 2_600_000, week: 223_000, day: 13_000},
  licenses: ["MIT"],
  latest_stable_version: "1.8.5",
  ...
}}

iex> HexpmMcp.health_check("req")
{:ok, %{
  name: "req",
  maintenance: %{status: "Active", age: "4 years ago", days_since_release: 57},
  popularity: %{all: 11_500_000, recent: 1_600_000, week: 141_000},
  quality: %{has_docs: true, licenses: ["Apache-2.0"], required_deps: 3, optional_deps: 4},
  risk: %{owner_count: 1, retired_count: 0},
  ...
}}

iex> HexpmMcp.compare_packages(["plug", "bandit"])
{:ok, [
  %{name: "plug", downloads_all: 156_000_000, dep_count: 3, ...},
  %{name: "bandit", downloads_all: 9_900_000, dep_count: 5, ...}
]}

iex> HexpmMcp.audit_mix_deps(~s({:phoenix, "~> 1.7"}, {:jason, "~> 1.0"}))
{:ok, %{total_checked: 2, total_warnings: 1, results: [...]}}

API 参考

每个函数都会返回 {:ok, structured_map} 或 {:error, reason}。

# Search and lookup
HexpmMcp.search(query, opts \\ [])
HexpmMcp.get_info(name)
HexpmMcp.get_downloads(name)
HexpmMcp.get_owners(name)
HexpmMcp.get_versions(name)

# Version-specific (pass nil for latest)
HexpmMcp.get_release(name, version \\ nil)
HexpmMcp.get_dependencies(name, version \\ nil)
HexpmMcp.get_features(name, version \\ nil)

# Composite analysis
HexpmMcp.compare_packages(names)
HexpmMcp.health_check(name)
HexpmMcp.audit_dependencies(name, version \\ nil)
HexpmMcp.find_alternatives(name)
HexpmMcp.dependency_tree(name, version \\ nil, opts \\ [])

# Mix.exs analysis
HexpmMcp.audit_mix_deps(deps_string)
HexpmMcp.upgrade_check(deps_string)

# HexDocs browsing
HexpmMcp.get_readme(name, version \\ nil)
HexpmMcp.get_docs(name, version \\ nil)
HexpmMcp.get_doc_item(name, module, version \\ nil)
HexpmMcp.search_docs(name, query, version \\ nil)

# Elixir Toolbox (curated discovery)
HexpmMcp.toolbox_groups()
HexpmMcp.toolbox_group(group)
HexpmMcp.toolbox_category(group, category, opts \\ [])
HexpmMcp.toolbox_trending(opts \\ [])
HexpmMcp.toolbox_search(query)

架构

iex / Elixir code                 MCP clients
        |                              |
   HexpmMcp (public API)         MCP Tools (thin wrappers)
   returns {:ok, map}                  |
        |                         calls HexpmMcp API
   Client / HexDocs / OSV /      then Formatter -> markdown
   Toolbox (internal clients)    then Snodo.Result.text()

• HexpmMcp —— 25 个返回结构化映射的公共函数，可从 iex 使用
• HexpmMcp.Formatter —— 用于 MCP 工具输出的 Markdown 格式化
• HexpmMcp.Client —— 基于 Req 的 hex.pm API 客户端，带有速率限制
• HexpmMcp.HexDocs —— hexdocs.pm 浏览功能（侧边栏数据解析、HTML 转 Markdown）
• HexpmMcp.OSV —— OSV.dev 漏洞数据库客户端
• HexpmMcp.Toolbox —— Elixir Toolbox 客户端，用于发现精选软件包
• HexpmMcp.Cache —— 基于 ETS 的响应缓存，带有 TTL 和定期清理功能
• HexpmMcp.CLI —— Cheer 命令树；将 argv 转换为服务的配置
• HexpmMcp.MCP.StdioLifecycle —— 管理 stdio 服务任务，在 EOF 时处理完请求，正常断开时以状态码 0 退出，传输失败时以状态码 1 退出并报告错误
• MCP 工具、资源和提示词 —— 以 JSON 为结构的轻量级协议组件，注册到 Snodo.Server

开发

snodo 和 snodo_jsv 来自 Hex。要基于本地 snodo 检出目录构建，请设置 SNODO_PATH，例如 SNODO_PATH=../snodo mix deps.get。

test/fixtures/mcp_tool_catalog.json 保存工具目录，测试会根据该目录检查工具定义。验收测试会准备领域数据，并通过直接分派、stdio 和 HTTP 测试资源、工具失败情况及参数验证。

snodo 对官方 TypeScript 客户端的检查也会使用预置的领域响应，通过 stdio 和 HTTP 对此服务运行。该检查需要位于 ../snodo 的 snodo 检出目录。在 snodo/interop/official_client 中运行一次 npm ci --ignore-scripts，安装其锁定版本的 Node 依赖项，然后：

MIX_ENV=test mix compile --warnings-as-errors
cd ../snodo
HEXPM_MCP_BUILD_PATH=../hexpm-mcp/_build/test node interop/official_client/check_hexpm.mjs

# Install dependencies
mix deps.get

# Run tests
mix test

# Full CI check
mix format --check-formatted
mix compile --warnings-as-errors
mix credo --strict
mix dialyzer

# Run locally (HTTP on port 8765)
mix run --no-halt

# Run locally (stdio for MCP clients)
mix run --no-halt -- --transport stdio

许可证

MIT