gemcp

MCP tools for RubyGems package intelligence. Ask about gems, versions, dependencies, and ownership. Get structured, provenance-tagged answers an agent can trust.

gemcp reads from installed gemspecs first, a persistent disk cache second, and the RubyGems.org API only when neither has what you need.

Tools

Tool Purpose
search_gems Search installed gems first, then RubyGems.org
get_gem Current gem metadata, preferring an installed gemspec
list_gem_versions Installed versions first, registry versions otherwise
get_gem_version Exact local version/platform first, API v2 otherwise
get_gem_owners Public owner/maintainer data from RubyGems.org
get_dependency_graph Bounded exploratory graph with constraints on edges
get_gem_context Aggregated context: metadata + recent versions + owners
check_compatibility Detect dependency conflicts between two gem versions
get_releases_between List all releases between two versions of a gem
reverse_dependencies Find gems that depend on a given gem
compare_versions Diff dependency requirements between two versions

Example questions

These are the kinds of questions gemcp helps an agent answer with authoritative data:

  • "Is sidekiq still actively maintained? Who owns it on RubyGems?"
  • "What Ruby version does nokogiri 1.18.8 require?"
  • "Can authlogic 3.6 coexist with Rails 8?"
  • "What changed in authlogic's dependencies between version 3.6.1 and 6.6.0?"
  • "What gems depend on rack?"
  • "Show me every release of rails between 7.0.0 and 8.0.0"
  • "Compare puma and unicorn — versions, owners, dependency counts"
  • "What are the runtime dependencies of rails 8.1?"
  • "Build me a dependency graph for sidekiq at depth 2"
  • "Find me gems for background job processing"

Quick start

bundle install
bundle exec bin/gemcp

Add to your MCP client config:

{
  "mcpServers": {
    "gemcp": {
      "command": "bundle",
      "args": ["exec", "/absolute/path/bin/gemcp"]
    }
  }
}

Or run over HTTP:

bundle exec rackup -p 9292

How it resolves data

installed gemspecs
      ↓ miss
fresh disk cache
      ↓ stale/miss
conditional RubyGems.org request (ETag / If-Modified-Since)
      ↓
refresh cache

Local results include metadata_source: "local". On network failure with a stale cache entry, the stale data is served rather than raising.

Search is conservative: when installed gems satisfy a query, no network call is made.

Configuration

Environment variable Default Meaning
GEMCP_LOCAL_FIRST true Prefer installed gemspecs before network
GEMCP_CACHE_DIR ~/.cache/gemcp Persistent JSON response cache
GEMCP_CACHE_TTL 3600 Cache freshness lifetime in seconds
GEMCP_REQUESTS_PER_SECOND 2 Outbound request rate limit
RUBYGEMS_API_BASE_URL https://rubygems.org API origin (useful for tests or mirrors)

Architecture

Tools receive a Client via constructor injection. Each tool wraps its operation in dry-monads (Success/Failure) and renders the result to MCP response format. No global state.

Tool.new(client:) → with_errors { client.do_thing } → Success(data) / Failure(error:, message:) → render → MCP response

The cache uses atomic temp-file + rename writes. The rate limiter uses a Mutex to serialize sleeps between outbound requests.

Dependency graph limitations

get_dependency_graph is exploratory, not authoritative. It follows declared dependencies using the latest release of each, preserving requirement constraints on edges. It does not consider lockfiles, Ruby versions, platforms, or source configuration. It is not a substitute for Bundler.

Compatibility checking limitations

check_compatibility tests whether two gems' declared dependency constraints overlap by sampling candidate versions against both Gem::Requirement objects. It catches common conflicts (e.g., < 5.0 vs = 8.0.0) but is not a full constraint solver. It does not resolve transitive dependencies.

Trust model

Registry facts (versions, checksums, dependencies, ownership, yanked state) are structured and authoritative. README, changelog, and documentation content is untrusted prose and never overrides registry facts.

Dependencies

  • fast-mcp — MCP server framework (instance-based tools, Rack transport)
  • dry-monads — Success/Failure result types for tool error handling
  • rack — HTTP transport

Test

bundle exec rake

License

MIT