# Reported issues for Hex.pm MCP

Pod holds 16 of 20 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to [Hex.pm MCP](/mcp/hex-pm-mcp).

## Most discussed

### feat: CI, CLAUDE.md, and .arsenale.exs

## Summary

Project infrastructure for arsenale-driven development.

## Files

### .arsenale.exs
\`\`\`elixir
%{
  preamble_files: ["CLAUDE.md"],
  validation_commands: [
    "cargo fmt --all -- --check",
    "cargo clippy --all-targets --all-features -- -D warnings",
    "cargo test --all-features"
  ]
}
\`\`\`

### CLAUDE.md
- Project overview: hex.pm MCP server using tower-mcp
- Architecture: client, types, tools pattern from cratesio-mcp
- Reference: /Users/joshrotenberg/Code/active/cratesio

[Read the thread](https://github.com/joshrotenberg/hexpm-mcp/issues/6) · 2026-03-31 · closed · 1 comment

### ci: consolidate deploy into a reusable workflow and record GitHub Deployments

## Background

Deploy-on-release already works: `release-please.yml` has a `deploy` job gated on `release_created == 'true'` that runs `flyctl deploy` and verifies the MCP protocol. It deployed v0.3.3 successfully. Two problems remain.

### 1. Duplicated deploy logic

The `flyctl deploy` step and the ~40-line MCP verification script are copy-pasted verbatim into two files:

- `.github/workflows/deploy.yml` (manual, `workflow_dispatch`)
- `.github/workflows/release-please.yml` (the `deploy` job)

[Read the thread](https://github.com/joshrotenberg/hexpm-mcp/issues/62) · 2026-07-07 · closed · 0 comments

### feat: add Elixir Toolbox discovery tools

## Summary

Add a set of MCP tools backed by the [Elixir Toolbox API](https://elixir-toolbox.dev/api) (`https://elixir-toolbox.dev/api/v1`). Elixir Toolbox is a curated discovery layer over hex.pm: a human-maintained taxonomy (groups -> categories -> hand-picked projects), plus trending and search. The API is free, requires no auth, and has CORS enabled. OpenAPI spec: `https://elixir-toolbox.dev/api/openapi`.

## Motivation

The existing tools answer "tell me about *this* package" (`search`, `in

[Read the thread](https://github.com/joshrotenberg/hexpm-mcp/issues/58) · 2026-07-07 · closed · 0 comments

### fix: reverse_dependencies endpoint returns 404

The `reverse` tool always returns "Package not found" because the hex.pm API endpoint `GET /api/packages/{name}/reverse_dependencies` returns 404 for all packages.

This endpoint may have been removed or relocated in a recent hex.pm API update. Need to:

1. Check the current hex.pm API spec for the correct endpoint
2. Update `Client.get_reverse_dependencies/2` accordingly
3. If the feature was removed from the API, deprecate or remove the tool

Reproduction:
```bash
curl -s -H "User-Agent: hexpm

[Read the thread](https://github.com/joshrotenberg/hexpm-mcp/issues/39) · 2026-04-06 · closed · 0 comments

### Expand test coverage

Current tests cover the Client (Bypass-based) and Formatter (unit). Need to add:

- **API-level tests** (`test/hexpm_mcp_test.exs`) -- test `HexpmMcp` public functions with Bypass mocks
- **HexDocs tests** -- test sidebar_items parsing, html_to_markdown, URL construction
- **OSV tests** -- test vulnerability query parsing
- **Tool tests** -- verify each MCP tool returns proper Response structs
- **Cache tests** -- test TTL expiry, sweep, fetch-or-compute
- **Integration tests** (tagged, optional

[Read the thread](https://github.com/joshrotenberg/hexpm-mcp/issues/26) · 2026-04-05 · closed · 0 comments

### Add audit_mix_deps and upgrade_check tools

Two tools from the CLAUDE.md spec that aren't implemented yet:

### audit_mix_deps
Accept a mix.exs deps list (as text), parse out the package names/versions, and run the full audit pipeline (staleness, retirement, CVEs, bus factor) on all of them at once.

### upgrade_check
Accept a deps list, check which deps have newer versions available on hex.pm, and flag breaking changes (major version bumps, retired versions, changed requirements).

Both are composite tools that build on the existing `Hex

[Read the thread](https://github.com/joshrotenberg/hexpm-mcp/issues/25) · 2026-04-05 · closed · 0 comments

### Improve get_doc_item HTML-to-markdown conversion

The `HexDocs.html_to_markdown/1` converter currently picks up nav/search chrome along with the actual content. Needs:

- Better content selector (target `#content .content-inner` or `article.main` more precisely)
- Strip navigation elements, search bars, sidebar content
- Handle code blocks with language annotations
- Handle tables (currently dropped)
- Clean up redundant whitespace/newlines in output

The converter is in `lib/hexpm_mcp/hexdocs.ex` -- `html_to_markdown/1` and `node_to_markdown/1

[Read the thread](https://github.com/joshrotenberg/hexpm-mcp/issues/24) · 2026-04-05 · closed · 0 comments

### Add @moduledoc and @doc to public API functions

The `HexpmMcp` module has `@doc` on all public functions but they're minimal. Improve them with:

- Typespec (`@spec`) for every public function
- Example usage in `@doc` (iex examples that can serve as doctests)
- Document all options (e.g. `search/2` opts, `dependency_tree/3` opts)
- Add `@moduledoc` sections explaining the return value shapes

This also enables `mix docs` to produce useful hexdocs output for the library.

[Read the thread](https://github.com/joshrotenberg/hexpm-mcp/issues/23) · 2026-04-05 · closed · 0 comments

## Most recent

### Improve README with usage examples and remote server docs

The current README covers the basics but could be expanded:

- Add example output for key tools (search, health check, compare)
- Document the remote StreamableHTTP server for Claude Desktop / other MCP clients
- Add badges (CI, license, Fly.io status)
- Add a "How it works" section explaining the architecture (public API + MCP tools + formatter)
- Document the iex API more thoroughly with example return values

[Read the thread](https://github.com/joshrotenberg/hexpm-mcp/issues/22) · 2026-04-05 · closed · 0 comments

### test: integration tests for hex.pm API client

## Summary

Integration tests that hit the real hex.pm API (behind a feature flag).

Tests:
- Search for "phoenix" returns results
- Fetch phoenix package info
- Fetch a specific release
- Fetch owners
- Handle 404 for nonexistent package

Use #[ignore] or a feature flag so they don't run in CI by default.

## Depends on
- #12 (foundation)

[Read the thread](https://github.com/joshrotenberg/hexpm-mcp/issues/17) · 2026-03-31 · closed · 0 comments

### ci: release-plz setup for automated releases

## Summary

Set up release-plz for automated changelog generation and crate publishing.

- .github/workflows/release-plz.yml
- Conventional commit format
- Changelog generation
- Automated crates.io publish on release

## Reference
- cratesio-mcp uses release-plz, copy the workflow pattern

[Read the thread](https://github.com/joshrotenberg/hexpm-mcp/issues/16) · 2026-03-31 · closed · 0 comments

### docs: README with usage examples and tool reference

## Summary

README covering:
- What hexpm-mcp is
- Installation (cargo install or from source)
- Usage with Claude Code / other MCP clients
- Tool reference table (all tools with inputs/outputs)
- Configuration

## Depends on
- #12 (foundation — need to know what tools exist)

[Read the thread](https://github.com/joshrotenberg/hexpm-mcp/issues/15) · 2026-03-31 · closed · 0 comments

### feat: get_release, get_dependencies, get_owners tools

## Summary

Version detail and dependency tools.

### get_release
- Input: name, version
- GET /api/packages/{name}/releases/{version}
- Output: version details, requirements, publisher, retirement status

### get_dependencies
- Input: name, version (optional, defaults to latest)
- Extract requirements from release

### get_owners
- Input: name
- GET /api/packages/{name}/owners
- Output: maintainer list

## Depends on
- #12 (foundation)

[Read the thread](https://github.com/joshrotenberg/hexpm-mcp/issues/14) · 2026-03-31 · closed · 0 comments

### feat: search_packages and get_package_info tools

## Summary

First two MCP tools. Follow the cratesio-mcp tool pattern.

### search_packages
- Input: query (string), sort (optional: downloads/inserted_at/updated_at)
- GET /api/packages?search={query}&sort={sort}
- Output: formatted list with name, description, downloads, latest version

### get_package_info
- Input: name (string)
- GET /api/packages/{name}
- Output: full details — description, licenses, downloads, latest version, docs URL

## Depends on
- #12 (foundation)

[Read the thread](https://github.com/joshrotenberg/hexpm-mcp/issues/13) · 2026-03-31 · closed · 0 comments

### feat: project foundation — deps, types, client, MCP server

## Summary

Set up the full project foundation in one shot. Reference cratesio-mcp
at /Users/joshrotenberg/Code/active/cratesio-mcp for patterns.

1. Cargo.toml deps: tower-mcp (latest), reqwest, serde, serde_json, schemars, tokio, clap, tracing
2. src/client.rs: HexClient wrapping reqwest, base URL https://hex.pm/api, User-Agent header
3. src/types.rs: Package, Release, Owner, DownloadStats, Retirement structs with Deserialize
4. src/main.rs: MCP server with AppState, stdio transport, empty too

[Read the thread](https://github.com/joshrotenberg/hexpm-mcp/issues/12) · 2026-03-31 · closed · 0 comments

### feat: health check, audit, and find alternatives

## Summary

Higher-level analysis tools that combine multiple API calls.

## Tools

### package_health_check
- Input: name (string)
- Combines: package info + latest release + downloads + owners
- Output: comprehensive health report
  - Maintenance: last release date, release frequency
  - Popularity: download trends
  - Quality: has docs, license, multiple maintainers
  - Risk: any retirements, single owner

### audit_dependencies
- Input: name (string), version (optional)
- Fetch release requi

[Read the thread](https://github.com/joshrotenberg/hexpm-mcp/issues/5) · 2026-03-31 · closed · 0 comments

The remaining reports are on [the project's issue tracker](https://github.com/joshrotenberg/hexpm-mcp/issues).