gemcp 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b3fbb27e1ba6c5a3784a08a182ebf231f88ab2a4cefe032393c69f0629964e2e
+  data.tar.gz: 3a38ad87ee84faddd0422d9fe909ae8fd58ba0344842516d07f37df169a8a318
+SHA512:
+  metadata.gz: 37310c5845ad72a4124a148b6401b76b06fc8e3ee5475a724b4822a76a39af976afba151877f5bb532833b9b5cee0522a0b6c373f95668d3376a2bcc7105ac62
+  data.tar.gz: 2dbc82a8d0ba76f31e09a0569f0aada7a1a50fc6c0d2a59b3e5ae8c3691af6ab78aa129b60a6ed820d315986baf83765ad2b3494a1d3eb61d18c861a0f5234a5

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brandon Weaver
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,126 @@
+# 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
+
+```bash
+bundle install
+bundle exec bin/gemcp
+```
+
+Add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "gemcp": {
+      "command": "bundle",
+      "args": ["exec", "/absolute/path/bin/gemcp"]
+    }
+  }
+}
+```
+
+Or run over HTTP:
+
+```bash
+bundle exec rackup -p 9292
+```
+
+## How it resolves data
+
+```text
+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.
+
+```text
+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`](https://github.com/yjacquin/fast-mcp) — MCP server framework (instance-based tools, Rack transport)
+- [`dry-monads`](https://github.com/dry-rb/dry-monads) — `Success`/`Failure` result types for tool error handling
+- `rack` — HTTP transport
+
+## Test
+
+```bash
+bundle exec rake
+```
+
+## License
+
+MIT

data/bin/gemcp

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "gemcp"
+
+server = GemCP::Server.build
+server.start

data/lib/gemcp/cache.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "json"
+require "securerandom"
+
+module GemCP
+  # Persistent JSON file cache with conditional-request metadata (ETag, Last-Modified).
+  # Uses atomic temp+rename writes to prevent partial reads on POSIX systems.
+  class Cache
+    # A single cached response with freshness metadata.
+    Entry = Data.define(:body, :etag, :last_modified, :stored_at) do
+      # @param ttl [Integer] freshness lifetime in seconds
+      # @param now [Time] current time (injectable for testing)
+      # @return [Boolean] whether this entry is younger than ttl seconds
+      def fresh?(ttl:, now: Time.now)
+        now.to_i - stored_at.to_i < ttl
+      end
+    end
+
+    # @param directory [String] path to the cache directory (created if missing)
+    def initialize(directory:)
+      @directory = directory
+      FileUtils.mkdir_p(directory)
+    end
+
+    # @param key [String] cache key (typically a full URL)
+    # @return [Entry, nil] the cached entry, or nil if missing/corrupt
+    def read(key)
+      path = path_for(key)
+      return unless File.file?(path)
+
+      data = JSON.parse(File.read(path))
+      Entry.new(
+        body: data.fetch("body"),
+        etag: data["etag"],
+        last_modified: data["last_modified"],
+        stored_at: Time.at(data.fetch("stored_at"))
+      )
+    rescue JSON::ParserError, KeyError, Errno::ENOENT
+      nil
+    end
+
+    # @param key [String] cache key
+    # @param body [Hash, Array] parsed JSON response body
+    # @param etag [String, nil] ETag header from the response
+    # @param last_modified [String, nil] Last-Modified header from the response
+    # @return [Entry] the newly written entry
+    def write(key, body:, etag: nil, last_modified: nil)
+      path = path_for(key)
+      temp = "#{path}.#{SecureRandom.hex(8)}.tmp"
+      now = Time.now
+
+      payload = {
+        body: body,
+        etag: etag,
+        last_modified: last_modified,
+        stored_at: now.to_i
+      }
+
+      File.write(temp, JSON.generate(payload))
+      File.rename(temp, path)
+
+      Entry.new(body: body, etag: etag, last_modified: last_modified, stored_at: now)
+    ensure
+      File.delete(temp) if temp && File.exist?(temp)
+    end
+
+    # Re-writes an entry with a fresh timestamp, preserving body and headers.
+    #
+    # @param key [String] cache key
+    # @param entry [Entry] the stale entry to refresh
+    # @return [Entry] the refreshed entry
+    def touch(key, entry)
+      write(key, body: entry.body, etag: entry.etag, last_modified: entry.last_modified)
+    end
+
+    # Artificially age a cache entry by the given number of seconds.
+    # Intended for testing staleness without coupling to internal storage format.
+    #
+    # @param key [String] cache key
+    # @param seconds [Integer] number of seconds to subtract from stored_at
+    # @return [void]
+    def backdate(key, seconds:)
+      path = path_for(key)
+      return unless File.file?(path)
+
+      data = JSON.parse(File.read(path))
+      data["stored_at"] = data["stored_at"] - seconds
+      File.write(path, JSON.generate(data))
+    end
+
+    private
+
+    # @param key [String]
+    # @return [String] filesystem path for this cache key
+    def path_for(key)
+      File.join(@directory, "#{Digest::SHA256.hexdigest(key)}.json")
+    end
+  end
+end

data/lib/gemcp/client.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module GemCP
+  # HTTP client for the RubyGems.org API with local-first resolution,
+  # conditional caching (ETag/If-Modified-Since), and rate limiting.
+  class Client
+    DEFAULT_BASE_URL = "https://rubygems.org"
+    USER_AGENT = "gemcp/#{VERSION} (+https://github.com/baweaver/gemcp)"
+
+    # @param base_url [String] RubyGems API origin
+    # @param open_timeout [Integer] TCP connect timeout in seconds
+    # @param read_timeout [Integer] response read timeout in seconds
+    # @param config [Config, nil] configuration (built from env if nil)
+    # @param local_repository [LocalRepository, nil]
+    # @param cache [Cache, nil]
+    # @param rate_limiter [RateLimiter, nil]
+    def initialize(
+      base_url: ENV.fetch("RUBYGEMS_API_BASE_URL", DEFAULT_BASE_URL),
+      open_timeout: 3,
+      read_timeout: 10,
+      config: nil,
+      local_repository: nil,
+      cache: nil,
+      rate_limiter: nil
+    )
+      @config = config || Config.new
+      @local_repository = local_repository || LocalRepository.new
+      @cache = cache || Cache.new(directory: @config.cache_dir)
+      @rate_limiter = rate_limiter || RateLimiter.new(requests_per_second: @config.requests_per_second)
+      @base_url = base_url.delete_suffix("/")
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+    end
+
+    # Search for gems by name or description.
+    #
+    # @param query [String] search text
+    # @return [Array<Hash>] list of gem metadata hashes
+    def search(query)
+      local = @config.local_first ? @local_repository.search(query) : []
+      return local if local.any?
+
+      get_json("/api/v1/search.json", query: { query: query })
+    end
+
+    # Get metadata for the latest version of a gem.
+    #
+    # @param name [String] gem name
+    # @return [Hash] gem metadata including version, downloads, URIs, dependencies
+    # @raise [NotFound] if the gem does not exist
+    def gem(name)
+      local = @config.local_first ? @local_repository.gem(name) : nil
+      return local if local
+
+      get_json("/api/v1/gems/#{escape(name)}.json")
+    end
+
+    # List all published versions of a gem.
+    #
+    # @param name [String] gem name
+    # @return [Array<Hash>] version metadata ordered newest-first
+    # @raise [NotFound] if the gem does not exist
+    def versions(name)
+      local = @config.local_first ? @local_repository.versions(name) : []
+      return local if local.any?
+
+      get_json("/api/v1/versions/#{escape(name)}.json")
+    end
+
+    # Get the latest version number for a gem.
+    #
+    # @param name [String] gem name
+    # @return [Hash] hash with "version" key
+    # @raise [NotFound] if the gem does not exist
+    def latest_version(name)
+      local = @config.local_first ? @local_repository.gem(name) : nil
+      return { "version" => local.fetch("version"), "metadata_source" => "local" } if local
+
+      get_json("/api/v1/versions/#{escape(name)}/latest.json")
+    end
+
+    # Get metadata for a specific version and optional platform.
+    #
+    # @param name [String] gem name
+    # @param number [String] version number
+    # @param platform [String, nil] platform filter (e.g. "x86_64-linux")
+    # @return [Hash] version metadata
+    # @raise [NotFound] if the version does not exist
+    def version(name, number, platform: nil)
+      local = @config.local_first ? @local_repository.version(name, number, platform: platform) : nil
+      return local if local
+
+      query = platform ? { platform: platform } : nil
+      get_json("/api/v2/rubygems/#{escape(name)}/versions/#{escape(number)}.json", query: query)
+    end
+
+    # Get public owners/maintainers for a gem.
+    #
+    # @param name [String] gem name
+    # @return [Array<Hash>] owner records with id, handle, role
+    # @raise [NotFound] if the gem does not exist
+    def owners(name)
+      get_json("/api/v1/gems/#{escape(name)}/owners.json")
+    end
+
+    # Get gems that depend on this gem (reverse dependencies).
+    #
+    # @param name [String] gem name
+    # @return [Array<String>] names of gems that declare a runtime dependency on this gem
+    # @raise [NotFound] if the gem does not exist
+    def reverse_dependencies(name)
+      get_json("/api/v1/gems/#{escape(name)}/reverse_dependencies.json")
+    end
+
+    private
+
+    # Fetch JSON from the RubyGems API with caching and conditional requests.
+    #
+    # @param path [String] API path (e.g. "/api/v1/gems/rails.json")
+    # @param query [Hash, nil] query string parameters
+    # @return [Hash, Array] parsed JSON response
+    # @raise [NotFound, UpstreamError, InvalidResponse]
+    def get_json(path, query: nil)
+      uri = URI("#{@base_url}#{path}")
+      uri.query = URI.encode_www_form(query) if query
+      key = uri.to_s
+      cached = @cache.read(key)
+      return cached.body if cached&.fresh?(ttl: @config.cache_ttl)
+
+      request = Net::HTTP::Get.new(uri)
+      request["Accept"] = "application/json"
+      request["User-Agent"] = USER_AGENT
+      request["If-None-Match"] = cached.etag if cached&.etag
+      request["If-Modified-Since"] = cached.last_modified if cached&.last_modified
+
+      @rate_limiter.wait
+      response = Net::HTTP.start(
+        uri.host,
+        uri.port,
+        use_ssl: uri.scheme == "https",
+        open_timeout: @open_timeout,
+        read_timeout: @read_timeout
+      ) { |http| http.request(request) }
+
+      case response
+      when Net::HTTPNotModified
+        @cache.touch(key, cached).body
+      when Net::HTTPSuccess
+        body = JSON.parse(response.body)
+        @cache.write(
+          key,
+          body: body,
+          etag: response["ETag"],
+          last_modified: response["Last-Modified"]
+        ).body
+      when Net::HTTPTooManyRequests
+        raise UpstreamError, "RubyGems.org rate limited gemcp; retry later"
+      when Net::HTTPNotFound
+        raise NotFound, "RubyGems resource not found: #{uri.path}"
+      else
+        raise UpstreamError, "RubyGems.org returned HTTP #{response.code} for #{uri.path}"
+      end
+    rescue JSON::ParserError => e
+      raise InvalidResponse, "RubyGems.org returned invalid JSON: #{e.message}"
+    rescue Timeout::Error, SocketError, SystemCallError => e
+      return cached.body if cached
+      raise UpstreamError, "RubyGems.org request failed: #{e.class}: #{e.message}"
+    end
+
+    # @param value [String] value to URL-encode
+    # @return [String]
+    def escape(value)
+      URI.encode_www_form_component(value.to_s)
+    end
+  end
+end

data/lib/gemcp/config.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module GemCP
+  # Immutable configuration for a GemCP client. Reads from environment
+  # variables at construction time, with sensible defaults.
+  class Config
+    # @return [String] path to the persistent JSON cache directory
+    attr_reader :cache_dir
+
+    # @return [Integer] seconds before a cache entry is considered stale
+    attr_reader :cache_ttl
+
+    # @return [Float] maximum outbound requests per second
+    attr_reader :requests_per_second
+
+    # @return [Boolean] whether to prefer installed gemspecs over network
+    attr_reader :local_first
+
+    # @param cache_dir [String]
+    # @param cache_ttl [Integer]
+    # @param requests_per_second [Float]
+    # @param local_first [Boolean]
+    def initialize(
+      cache_dir: ENV.fetch("GEMCP_CACHE_DIR", File.join(Dir.home, ".cache", "gemcp")),
+      cache_ttl: Integer(ENV.fetch("GEMCP_CACHE_TTL", "3600")),
+      requests_per_second: Float(ENV.fetch("GEMCP_REQUESTS_PER_SECOND", "2")),
+      local_first: ENV.fetch("GEMCP_LOCAL_FIRST", "true") != "false"
+    )
+      @cache_dir = cache_dir
+      @cache_ttl = cache_ttl
+      @requests_per_second = requests_per_second
+      @local_first = local_first
+    end
+  end
+end

data/lib/gemcp/dependency_graph.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "set"
+
+module GemCP
+  # Builds a bounded exploratory dependency graph by traversing RubyGems metadata.
+  # This is NOT a lockfile resolver — it follows each dependency's latest release
+  # and preserves version constraints on edges for informational purposes only.
+  class DependencyGraph
+    MAX_DEPTH = 4
+    MAX_NODES = 100
+
+    # @param client [Client] the API client to fetch version metadata
+    def initialize(client:)
+      @client = client
+    end
+
+    # Build the dependency graph starting from a root gem.
+    #
+    # @param name [String] root gem name
+    # @param version [String, nil] root version (defaults to latest)
+    # @param platform [String, nil] platform filter for the root
+    # @param depth [Integer] traversal depth (clamped to 0..MAX_DEPTH)
+    # @param include_development [Boolean] whether to follow dev dependencies
+    # @return [Hash] graph with :root, :nodes, :edges, :truncated, :limits
+    def build(name:, version: nil, platform: nil, depth: 1, include_development: false)
+      depth = Integer(depth).clamp(0, MAX_DEPTH)
+      root_version = version || @client.latest_version(name).fetch("version")
+      state = { nodes: {}, edges: [], visited: Set.new, truncated: false }
+
+      visit(
+        name: name,
+        version: root_version,
+        platform: platform,
+        depth_remaining: depth,
+        include_development: include_development,
+        state: state
+      )
+
+      {
+        root: { name: name, version: root_version, platform: platform },
+        nodes: state[:nodes].values,
+        edges: state[:edges],
+        truncated: state[:truncated],
+        limits: { max_depth: MAX_DEPTH, max_nodes: MAX_NODES }
+      }
+    end
+
+    private
+
+    # @param name [String]
+    # @param version [String]
+    # @param platform [String, nil]
+    # @return [String] unique node identifier (e.g. "rails@8.0.0@ruby")
+    def node_key(name, version, platform)
+      [name, version, platform || "ruby"].join("@")
+    end
+
+    # Recursively visit a node and its dependencies.
+    #
+    # @param name [String] gem name
+    # @param version [String] version to fetch
+    # @param platform [String, nil] platform filter
+    # @param depth_remaining [Integer] remaining traversal depth
+    # @param include_development [Boolean]
+    # @param state [Hash] mutable accumulator for nodes, edges, visited set
+    # @return [void]
+    def visit(name:, version:, platform:, depth_remaining:, include_development:, state:)
+      key = node_key(name, version, platform)
+      return if state[:visited].include?(key)
+
+      if state[:nodes].length >= MAX_NODES
+        state[:truncated] = true
+        return
+      end
+
+      state[:visited] << key
+      metadata = @client.version(name, version, platform: platform)
+      state[:nodes][key] = summarize(metadata)
+      return if depth_remaining.zero?
+
+      dependency_groups = ["runtime"]
+      dependency_groups << "development" if include_development
+
+      dependency_groups.each do |kind|
+        Array(metadata.dig("dependencies", kind)).each do |dependency|
+          dep_name = dependency.fetch("name")
+          edge = {
+            from: key,
+            to: dep_name,
+            requirements: dependency["requirements"],
+            kind: kind
+          }
+          state[:edges] << edge
+
+          child_version = @client.latest_version(dep_name).fetch("version")
+          visit(
+            name: dep_name,
+            version: child_version,
+            platform: nil,
+            depth_remaining: depth_remaining - 1,
+            include_development: include_development,
+            state: state
+          )
+        rescue NotFound, UpstreamError => e
+          edge[:unresolved] = true
+          edge[:error] = e.message
+        end
+      end
+    end
+
+    # @param metadata [Hash] raw version metadata from the API
+    # @return [Hash] summarized node for the graph output
+    def summarize(metadata)
+      {
+        id: node_key(metadata["name"], metadata["version"], metadata["platform"]),
+        name: metadata["name"],
+        version: metadata["version"],
+        platform: metadata["platform"],
+        summary: metadata["summary"],
+        licenses: metadata["licenses"],
+        ruby_version: metadata["ruby_version"],
+        yanked: metadata["yanked"],
+        sha: metadata["sha"],
+        project_uri: metadata["project_uri"],
+        source_code_uri: metadata["source_code_uri"]
+      }
+    end
+  end
+end

data/lib/gemcp/errors.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module GemCP
+  # Base error class for all GemCP exceptions.
+  class Error < StandardError
+    # @return [String] machine-readable error type for structured responses
+    def error_type = raise NotImplementedError
+  end
+
+  # Raised when a gem, version, or resource is not found.
+  class NotFound < Error
+    def error_type = "NotFound"
+  end
+
+  # Raised when RubyGems.org returns an unexpected status or is unreachable.
+  class UpstreamError < Error
+    def error_type = "UpstreamError"
+  end
+
+  # Raised when RubyGems.org returns a body that cannot be parsed as JSON.
+  class InvalidResponse < Error
+    def error_type = "InvalidResponse"
+  end
+end