hexpm-mcp: Instructions file for Claude Code

hexpm-mcp

MCP server for querying hex.pm and hexdocs.pm. Deployed on Fly.io and published to Hex. The current version is in .release-please-manifest.json (0.3.8 at the time of writing).

Built with snodo in Elixir. The Rust/tower-mcp version is archived on the master branch; main is the default branch.

snodo is published on Hex (snodo and snodo_jsv) and resolved through the snodo_dep/3 helper in mix.exs. Setting SNODO_PATH points both packages at one local checkout. The MCP layer moved from anubis_mcp to snodo in #81.

Architecture

lib/
  hexpm_mcp.ex             -- Public API (25 functions returning structured maps)
  hexpm_mcp/
    application.ex         -- OTP app: resolves CLI config, starts cache + transport,
                              or runs init and halts
    client.ex              -- HTTP client for hex.pm API (Req)
    hexdocs.ex             -- HexDocs client: sidebar_items parsing, HTML-to-markdown
    osv.ex                 -- OSV.dev client for vulnerability auditing
    toolbox.ex             -- Elixir Toolbox client: curated discovery (groups, trending, search)
    cache.ex               -- ETS-based response cache with TTL + sweeper
    types.ex               -- Response structs (Package, Release, Owner)
    formatter.ex           -- Markdown formatting (one function per API call)
    cli.ex                 -- Cheer command tree; argv -> server config or init
    cli/init.ex            -- the init subcommand's options
    init.ex                -- hexpm_mcp init: writes the local marketplace and
                              registers it through the claude and codex CLIs

    mcp/
      server.ex            -- Snodo.Server definition (24 tools, 5 resources, 6 prompts)
      stdio_lifecycle.ex   -- stdio task: runs Snodo.Transport.Stdio.serve/2,
                              halts 0 at EOF and 1 on transport failure
      package_completion.ex -- package-name completion for resource and prompt
                              arguments (one cached hex.pm search page)

    mcp/tools/             -- Thin wrappers: call HexpmMcp API -> Formatter -> Snodo.Result
      search.ex, info.ex, versions.ex, release.ex, features.ex,
      dependencies.ex, downloads.ex, owners.ex, readme.ex,
      compare.ex, health.ex, audit.ex, alternatives.ex, dep_tree.ex,
      docs.ex, doc_item.ex, search_docs.ex,
      audit_mix_deps.ex, upgrade_check.ex,
      toolbox_groups.ex, toolbox_group.ex, toolbox_category.ex,
      toolbox_trending.ex, toolbox_search.ex

    mcp/resources/         -- URI resources: hex://{name}/info, /readme, /docs;
                              toolbox://groups, toolbox://{group}/{category}
    mcp/prompts/           -- Guided analysis prompts (6): analyze_package,
                              compare_packages, evaluate_dependencies,
                              recommend_packages, migration_guide, package_review

priv/plugin/hexpm/         -- Claude Code and Codex plugin, embedded by init.ex
  .claude-plugin/plugin.json, .codex-plugin/plugin.json -- no version; init adds it
  skills/hexpm/SKILL.md    -- dependency workflow skill
  hooks/hooks.json, hooks/mix-deps.sh -- PostToolUse hook on mix.exs / mix.lock edits

test/
  test_helper.exs
  hexpm_mcp_test.exs       -- API-level tests (Bypass mocks)
  hexpm_mcp/
    client_test.exs        -- Client HTTP tests (Bypass)
    cache_test.exs         -- Cache TTL/fetch tests
    cli_test.exs           -- argv parsing and config/1
    formatter_test.exs     -- Markdown formatter tests
    hexdocs_test.exs       -- HTML-to-markdown tests
    init_test.exs          -- init planning, written files, host steps (fake runner)
    plugin_test.exs        -- manifests, skill names only served tools, hook script
    toolbox_test.exs       -- Elixir Toolbox client tests (Bypass)
    mcp/
      server_test.exs                 -- discovery, catalogs, argument validation,
                                         HTTP listener per protocol version
      application_acceptance_test.exs -- tools and resources over direct, stdio, and HTTP
      discovery_workflow_test.exs     -- completions, list caching and cursors,
                                         package_review elicitation
      stdio_lifecycle_test.exs        -- the real app over stdio: EOF, drain,
                                         initialize-era negotiation, failure exits
  fixtures/
    mcp_tool_catalog.json  -- expected tools/list catalog (server_test.exs)
  support/
    fixtures.ex            -- Shared test data builders