gemcp 0.0.1

data/lib/gemcp/local_repository.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "rubygems"
+
+module GemCP
+  # Reads gem metadata from installed gemspecs on the local system.
+  # All methods return nil or empty arrays when nothing matches —
+  # never raises for missing gems.
+  class LocalRepository
+    # Find the latest installed version of a gem by name.
+    #
+    # @param name [String] gem name
+    # @return [Hash, nil] serialized gem metadata, or nil if not installed
+    def gem(name)
+      spec = Gem::Specification.find_all_by_name(name).max_by(&:version)
+      spec && serialize(spec, source: "local")
+    end
+
+    # Find a specific installed version, optionally filtered by platform.
+    #
+    # @param name [String] gem name
+    # @param number [String] exact version number
+    # @param platform [String, nil] platform string (e.g. "ruby", "x86_64-linux")
+    # @return [Hash, nil] serialized version metadata, or nil if not installed
+    def version(name, number, platform: nil)
+      specs = Gem::Specification.find_all_by_name(name, Gem::Requirement.new("=#{number}"))
+      spec = if platform
+        specs.find { |candidate| candidate.platform.to_s == platform }
+      else
+        specs.first
+      end
+      spec && serialize(spec, source: "local")
+    end
+
+    # List all installed versions of a gem, newest first.
+    #
+    # @param name [String] gem name
+    # @return [Array<Hash>] version metadata hashes (empty if not installed)
+    def versions(name)
+      Gem::Specification.find_all_by_name(name)
+        .sort_by(&:version)
+        .reverse
+        .map { |spec| serialize_version(spec) }
+    end
+
+    # Search installed gems by name or summary substring match.
+    #
+    # @param query [String] case-insensitive search text
+    # @return [Array<Hash>] matching gem metadata (latest version per gem)
+    def search(query)
+      needle = query.downcase
+      Gem::Specification.each
+        .select { |spec| spec.name.downcase.include?(needle) || spec.summary.to_s.downcase.include?(needle) }
+        .group_by(&:name)
+        .values
+        .map { |specs| serialize(specs.max_by(&:version), source: "local") }
+    end
+
+    private
+
+    # @param spec [Gem::Specification]
+    # @param source [String] provenance tag
+    # @return [Hash]
+    def serialize(spec, source:)
+      {
+        "name" => spec.name,
+        "version" => spec.version.to_s,
+        "platform" => spec.platform.to_s,
+        "authors" => Array(spec.authors).join(", "),
+        "info" => spec.description || spec.summary,
+        "summary" => spec.summary,
+        "licenses" => Array(spec.licenses),
+        "homepage_uri" => spec.homepage,
+        "source_code_uri" => spec.metadata["source_code_uri"],
+        "documentation_uri" => spec.metadata["documentation_uri"],
+        "required_ruby_version" => spec.required_ruby_version.to_s,
+        "required_rubygems_version" => spec.required_rubygems_version.to_s,
+        "dependencies" => {
+          "runtime" => spec.runtime_dependencies.map { |dep| serialize_dependency(dep) },
+          "development" => spec.development_dependencies.map { |dep| serialize_dependency(dep) }
+        },
+        "metadata_source" => source,
+        "full_gem_path" => spec.full_gem_path
+      }.compact
+    end
+
+    # @param spec [Gem::Specification]
+    # @return [Hash]
+    def serialize_version(spec)
+      {
+        "number" => spec.version.to_s,
+        "platform" => spec.platform.to_s,
+        "ruby_version" => spec.required_ruby_version.to_s,
+        "rubygems_version" => spec.required_rubygems_version.to_s,
+        "metadata_source" => "local"
+      }
+    end
+
+    # @param dep [Gem::Dependency]
+    # @return [Hash]
+    def serialize_dependency(dep)
+      { "name" => dep.name, "requirements" => dep.requirement.to_s }
+    end
+  end
+end

data/lib/gemcp/rate_limiter.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module GemCP
+  # Thread-safe rate limiter that enforces a minimum interval between calls.
+  # Uses a Mutex to prevent interleaving during the sleep gap.
+  class RateLimiter
+    # @param requests_per_second [Float] maximum request rate (0 disables throttling)
+    def initialize(requests_per_second:)
+      @minimum_interval = requests_per_second.positive? ? 1.0 / requests_per_second : 0.0
+      @last_request_at = nil
+      @mutex = Mutex.new
+    end
+
+    # Blocks until enough time has elapsed since the last call.
+    # Safe to call from multiple threads.
+    #
+    # @return [void]
+    def wait
+      @mutex.synchronize do
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        if @last_request_at
+          sleep_for = @minimum_interval - (now - @last_request_at)
+          sleep(sleep_for) if sleep_for.positive?
+        end
+
+        @last_request_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/gemcp/server.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "fast_mcp"
+require "time"
+require_relative "tools/base"
+require_relative "tools/search_gems"
+require_relative "tools/get_gem"
+require_relative "tools/list_versions"
+require_relative "tools/get_version"
+require_relative "tools/get_owners"
+require_relative "tools/dependency_graph"
+require_relative "tools/get_context"
+require_relative "tools/check_compatibility"
+require_relative "tools/get_releases_between"
+require_relative "tools/reverse_dependencies"
+require_relative "tools/compare_versions"
+
+module GemCP
+  # Builds and configures the MCP server with all registered tools.
+  module Server
+    TOOLS = [
+      Tools::SearchGems,
+      Tools::GetGem,
+      Tools::ListVersions,
+      Tools::GetVersion,
+      Tools::GetOwners,
+      Tools::DependencyGraph,
+      Tools::GetContext,
+      Tools::CheckCompatibility,
+      Tools::GetReleasesBetween,
+      Tools::ReverseDependencies,
+      Tools::CompareVersions
+    ].freeze
+
+    module_function
+
+    # Build a FastMcp::Server with all GemCP tools registered.
+    #
+    # @return [FastMcp::Server]
+    def build
+      server = FastMcp::Server.new(name: "gemcp", version: VERSION)
+      TOOLS.each { |tool| server.register_tool(tool) }
+      server
+    end
+  end
+end

data/lib/gemcp/tools/base.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "dry/monads"
+require "fast_mcp"
+
+module GemCP
+  module Tools
+    # Base class for all MCP tools. Provides client injection, error handling
+    # via dry-monads, and rendering to MCP response format.
+    class Base < FastMcp::Tool
+      include Dry::Monads[:result]
+
+      annotations(
+        read_only_hint: true,
+        destructive_hint: false,
+        idempotent_hint: true,
+        open_world_hint: true
+      )
+
+      # @param client [Client, nil] injected client (defaults to a new Client)
+      def initialize(client: nil)
+        super()
+        @client = client || Client.new
+      end
+
+      private
+
+      attr_reader :client
+
+      # Execute a block, wrapping the return value in Success or capturing
+      # errors as Failure. Handles both GemCP errors and unexpected exceptions.
+      #
+      # @yield the operation to execute
+      # @return [Dry::Monads::Result]
+      def with_errors
+        Success(yield)
+      rescue GemCP::Error => e
+        Failure(error: e.error_type, message: e.message)
+      rescue StandardError => e
+        Failure(error: "InternalError", message: "#{e.class}: #{e.message}")
+      end
+
+      # Convert a dry-monads Result into an MCP tool response hash.
+      #
+      # @param result [Dry::Monads::Result]
+      # @return [Hash] MCP response with :content and :isError keys
+      def render(result)
+        case result
+        in Dry::Monads::Success(data)
+          { content: [{ type: "text", text: JSON.pretty_generate(data) }], isError: false }
+        in Dry::Monads::Failure(data)
+          { content: [{ type: "text", text: JSON.generate(data) }], isError: true }
+        end
+      end
+    end
+  end
+end

data/lib/gemcp/tools/check_compatibility.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module GemCP
+  module Tools
+    # Check if two gems can coexist by comparing their dependency constraints.
+    # Detects hard conflicts where declared requirements are mutually exclusive.
+    class CheckCompatibility < Base
+      tool_name "check_compatibility"
+      description \
+        "Check if two gems' dependency constraints conflict. Compares their runtime dependency " \
+        "requirements to find shared dependencies with incompatible version ranges."
+
+      arguments do
+        required(:gem_a).filled(:string).description("First gem name")
+        required(:version_a).filled(:string).description("First gem version")
+        required(:gem_b).filled(:string).description("Second gem name")
+        required(:version_b).filled(:string).description("Second gem version")
+      end
+
+      # @param gem_a [String] first gem name
+      # @param version_a [String] first gem version
+      # @param gem_b [String] second gem name
+      # @param version_b [String] second gem version
+      # @return [Hash] MCP response
+      def call(gem_a:, version_a:, gem_b:, version_b:)
+        result = with_errors do
+          meta_a = client.version(gem_a, version_a)
+          meta_b = client.version(gem_b, version_b)
+
+          deps_a = normalize_deps(meta_a)
+          deps_b = normalize_deps(meta_b)
+
+          shared_deps = deps_a.keys & deps_b.keys
+          conflicts = find_conflicts(shared_deps, deps_a, deps_b)
+
+          {
+            gem_a: { name: gem_a, version: version_a },
+            gem_b: { name: gem_b, version: version_b },
+            compatible: conflicts.empty?,
+            shared_dependencies: shared_deps.length,
+            conflicts: conflicts
+          }
+        end
+        render(result)
+      end
+
+      private
+
+      def normalize_deps(metadata)
+        Array(metadata.dig("dependencies", "runtime")).each_with_object({}) do |dep, hash|
+          hash[dep["name"]] = dep["requirements"]
+        end
+      end
+
+      def find_conflicts(shared_deps, deps_a, deps_b)
+        shared_deps.filter_map do |dep_name|
+          req_a = Gem::Requirement.new(deps_a[dep_name].split(",").map(&:strip))
+          req_b = Gem::Requirement.new(deps_b[dep_name].split(",").map(&:strip))
+
+          next if requirements_overlap?(req_a, req_b)
+
+          {
+            dependency: dep_name,
+            requirement_a: deps_a[dep_name],
+            requirement_b: deps_b[dep_name]
+          }
+        end
+      end
+
+      def requirements_overlap?(req_a, req_b)
+        # Test a range of versions to see if any satisfy both requirements.
+        # This is a heuristic — not a full SAT solver — but covers common cases.
+        test_versions.any? { |v| req_a.satisfied_by?(v) && req_b.satisfied_by?(v) }
+      end
+
+      def test_versions
+        @test_versions ||= begin
+          majors = (0..30)
+          majors.flat_map do |major|
+            [0, 1, 2, 5, 10, 15, 20].map { |minor| Gem::Version.new("#{major}.#{minor}.0") }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/gemcp/tools/compare_versions.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module GemCP
+  module Tools
+    # Compare dependency requirements between two versions of the same gem.
+    # Shows added, removed, and changed dependencies.
+    class CompareVersions < Base
+      tool_name "compare_versions"
+      description \
+        "Diff the dependency requirements between two versions of a gem. " \
+        "Shows added, removed, and changed runtime dependencies."
+
+      arguments do
+        required(:name).filled(:string).description("Gem name")
+        required(:old_version).filled(:string).description("Older version to compare from")
+        required(:new_version).filled(:string).description("Newer version to compare to")
+      end
+
+      # @param name [String] gem name
+      # @param old_version [String] older version
+      # @param new_version [String] newer version
+      # @return [Hash] MCP response
+      def call(name:, old_version:, new_version:)
+        result = with_errors do
+          old_meta = client.version(name, old_version)
+          new_meta = client.version(name, new_version)
+
+          old_deps = normalize_deps(old_meta)
+          new_deps = normalize_deps(new_meta)
+
+          added = (new_deps.keys - old_deps.keys).map { |n| { name: n, requirements: new_deps[n] } }
+          removed = (old_deps.keys - new_deps.keys).map { |n| { name: n, requirements: old_deps[n] } }
+          changed = (old_deps.keys & new_deps.keys).filter_map do |n|
+            next if old_deps[n] == new_deps[n]
+            { name: n, old_requirements: old_deps[n], new_requirements: new_deps[n] }
+          end
+
+          {
+            name: name,
+            old_version: old_version,
+            new_version: new_version,
+            old_ruby_version: old_meta["ruby_version"],
+            new_ruby_version: new_meta["ruby_version"],
+            dependencies: {
+              added: added,
+              removed: removed,
+              changed: changed,
+              unchanged: (old_deps.keys & new_deps.keys).count - changed.length
+            }
+          }
+        end
+        render(result)
+      end
+
+      private
+
+      def normalize_deps(metadata)
+        Array(metadata.dig("dependencies", "runtime")).each_with_object({}) do |dep, hash|
+          hash[dep["name"]] = dep["requirements"]
+        end
+      end
+    end
+  end
+end

data/lib/gemcp/tools/dependency_graph.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module GemCP
+  module Tools
+    # Build an exploratory dependency graph from RubyGems metadata.
+    class DependencyGraph < Base
+      tool_name "get_dependency_graph"
+      description \
+        "Build a bounded exploratory dependency graph from RubyGems metadata. Constraints are preserved on edges, " \
+        "but transitive nodes use each dependency's latest release; this is not a Bundler lockfile resolution."
+
+      arguments do
+        required(:name).filled(:string).description("Root gem name")
+        optional(:version).filled(:string).description("Defaults to the latest version")
+        optional(:platform).filled(:string).description("Platform filter")
+        optional(:depth).filled(:integer).description("Traversal depth (0-4)")
+        optional(:include_development).filled(:bool).description("Include development dependencies")
+      end
+
+      # @param name [String] root gem name
+      # @param version [String, nil] root version (nil = latest)
+      # @param platform [String, nil] platform filter
+      # @param depth [Integer] traversal depth
+      # @param include_development [Boolean] whether to include dev dependencies
+      # @return [Hash] MCP response
+      def call(name:, version: nil, platform: nil, depth: 1, include_development: false)
+        result = with_errors do
+          GemCP::DependencyGraph.new(client: client).build(
+            name: name,
+            version: version,
+            platform: platform,
+            depth: depth,
+            include_development: include_development
+          )
+        end
+        render(result)
+      end
+    end
+  end
+end

data/lib/gemcp/tools/get_context.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module GemCP
+  module Tools
+    # Aggregate gem metadata, recent versions, and owners into a single response
+    # with provenance metadata for AI agent consumption.
+    class GetContext < Base
+      tool_name "get_gem_context"
+      description "Aggregate registry facts useful for grounded AI answers: gem metadata, recent releases, and owners."
+
+      arguments do
+        required(:name).filled(:string).description("Gem name")
+        optional(:recent_versions).filled(:integer).description("Number of recent versions (1-20)")
+      end
+
+      # @param name [String] gem name
+      # @param recent_versions [Integer] how many recent versions to include
+      # @return [Hash] MCP response
+      def call(name:, recent_versions: 5)
+        result = with_errors do
+          {
+            gem: client.gem(name),
+            versions: client.versions(name).first(recent_versions),
+            owners: client.owners(name),
+            provenance: {
+              source: "RubyGems.org public API",
+              retrieved_at: Time.now.utc.iso8601,
+              authoritative_fields: [
+                "versions", "dependencies", "downloads", "owners", "checksums", "compatibility", "URIs"
+              ],
+              untrusted_documentation_included: false
+            }
+          }
+        end
+        render(result)
+      end
+    end
+  end
+end

data/lib/gemcp/tools/get_gem.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module GemCP
+  module Tools
+    # Fetch metadata for the latest version of a gem.
+    class GetGem < Base
+      tool_name "get_gem"
+      description "Get current RubyGems.org metadata for a gem, including latest version, downloads, URIs, and dependencies."
+
+      arguments do
+        required(:name).filled(:string).description("Gem name")
+      end
+
+      # @param name [String] gem name
+      # @return [Hash] MCP response
+      def call(name:)
+        render(with_errors { client.gem(name) })
+      end
+    end
+  end
+end

data/lib/gemcp/tools/get_owners.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module GemCP
+  module Tools
+    # Fetch public owner/maintainer data for a gem.
+    class GetOwners < Base
+      tool_name "get_gem_owners"
+      description "List the public owners and maintainers returned by RubyGems.org for a gem."
+
+      arguments do
+        required(:name).filled(:string).description("Gem name")
+      end
+
+      # @param name [String] gem name
+      # @return [Hash] MCP response
+      def call(name:)
+        render(with_errors { { name: name, owners: client.owners(name) } })
+      end
+    end
+  end
+end

data/lib/gemcp/tools/get_releases_between.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module GemCP
+  module Tools
+    # List all releases between two versions of a gem, including changelog links.
+    class GetReleasesBetween < Base
+      tool_name "get_releases_between"
+      description \
+        "List all versions released between two versions of a gem, including release dates " \
+        "and changelog URIs. Useful for understanding the upgrade path between versions."
+
+      arguments do
+        required(:name).filled(:string).description("Gem name")
+        required(:from_version).filled(:string).description("Starting version (exclusive)")
+        required(:to_version).filled(:string).description("Ending version (inclusive)")
+      end
+
+      # @param name [String] gem name
+      # @param from_version [String] starting version (exclusive lower bound)
+      # @param to_version [String] ending version (inclusive upper bound)
+      # @return [Hash] MCP response
+      def call(name:, from_version:, to_version:)
+        result = with_errors do
+          all_versions = client.versions(name)
+
+          from = Gem::Version.new(from_version)
+          to = Gem::Version.new(to_version)
+
+          between = all_versions.select do |v|
+            version = Gem::Version.new(v["number"])
+            version > from && version <= to
+          end
+
+          between.sort_by! { |v| Gem::Version.new(v["number"]) }
+
+          {
+            name: name,
+            from_version: from_version,
+            to_version: to_version,
+            count: between.length,
+            releases: between.map { |v| summarize_release(v) }
+          }
+        end
+        render(result)
+      end
+
+      private
+
+      def summarize_release(version_data)
+        {
+          number: version_data["number"],
+          platform: version_data["platform"],
+          released_at: version_data["created_at"],
+          prerelease: version_data["prerelease"],
+          changelog_uri: version_data.dig("metadata", "changelog_uri"),
+          yanked: version_data["yanked"]
+        }.compact
+      end
+    end
+  end
+end

data/lib/gemcp/tools/get_version.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module GemCP
+  module Tools
+    # Fetch metadata for a specific gem version and optional platform.
+    class GetVersion < Base
+      tool_name "get_gem_version"
+      description "Get authoritative metadata for one gem version and optional platform using the RubyGems.org v2 API."
+
+      arguments do
+        required(:name).filled(:string).description("Gem name")
+        required(:version).filled(:string).description("Version number")
+        optional(:platform).filled(:string).description("Platform, such as ruby or x86_64-linux")
+      end
+
+      # @param name [String] gem name
+      # @param version [String] version number
+      # @param platform [String, nil] platform filter
+      # @return [Hash] MCP response
+      def call(name:, version:, platform: nil)
+        render(with_errors { client.version(name, version, platform: platform) })
+      end
+    end
+  end
+end

data/lib/gemcp/tools/list_versions.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module GemCP
+  module Tools
+    # List published versions of a gem with optional prerelease filtering.
+    class ListVersions < Base
+      tool_name "list_gem_versions"
+      description "List published versions and compatibility metadata for a gem."
+
+      arguments do
+        required(:name).filled(:string).description("Gem name")
+        optional(:include_prerelease).filled(:bool).description("Include prerelease versions")
+        optional(:limit).filled(:integer).description("Maximum versions to return (1-200)")
+      end
+
+      # @param name [String] gem name
+      # @param include_prerelease [Boolean] whether to include pre-release versions
+      # @param limit [Integer] maximum versions to return
+      # @return [Hash] MCP response
+      def call(name:, include_prerelease: false, limit: 50)
+        result = with_errors do
+          versions = client.versions(name)
+          versions = versions.reject { |item| item["prerelease"] } unless include_prerelease
+          limited = versions.first(limit)
+          { name: name, count: limited.length, versions: limited }
+        end
+        render(result)
+      end
+    end
+  end
+end

data/lib/gemcp/tools/reverse_dependencies.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module GemCP
+  module Tools
+    # Find gems that depend on a given gem (reverse dependencies).
+    class ReverseDependencies < Base
+      tool_name "reverse_dependencies"
+      description \
+        "List gems that declare a runtime dependency on this gem. " \
+        "Useful for understanding a gem's ecosystem impact and finding potential conflicts."
+
+      arguments do
+        required(:name).filled(:string).description("Gem name")
+        optional(:limit).filled(:integer).description("Maximum results to return (1-100)")
+      end
+
+      # @param name [String] gem name
+      # @param limit [Integer] maximum results
+      # @return [Hash] MCP response
+      def call(name:, limit: 50)
+        result = with_errors do
+          dependents = client.reverse_dependencies(name)
+          limited = Array(dependents).first(limit)
+
+          {
+            name: name,
+            total_dependents: Array(dependents).length,
+            count: limited.length,
+            dependents: limited
+          }
+        end
+        render(result)
+      end
+    end
+  end
+end