bundler_mcp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6e512b7990ccd597566b67a7fa65d6ee92347c670d394cec2fa913c243542353
+  data.tar.gz: 3b1a3d045f42f34a05264d22497cd8e0d588deb58a332227bb68f714bba81ed8
+SHA512:
+  metadata.gz: 3417bfa815a0b37472355fda7f4ebe8d6d575efabb73c2bf5be107c367dcfb289997d5495f61f037f2d2cd9140698610226e2d1d44716e4098cd375df98f660e
+  data.tar.gz: 7fcd767de09ad6691f3fe14c2be1de4b3fa50420dfa34d0af5a9908d310cefa58d1f79a81cdb6a8e5377f80ec11d44434ef7ca47c6aa49dc4239089685a099bc

data/.ruby-version

@@ -0,0 +1 @@
+3.4.2

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-05-18
+
+- Initial release
+- Add `list_project_gems` tool
+- Add `get_gem_details` tool

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Mike Subelsky
+
+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,128 @@
+# BundlerMCP
+
+A Model Context Protocol (MCP) server enabling AI agents to query information about gems in a Ruby project's Gemfile, including source code and metadata. Built with [fast-mcp](https://github.com/yjacquin/fast-mcp).
+
+[![CI](https://github.com/subelsky/bundler_mcp/actions/workflows/main.yml/badge.svg)](https://github.com/subelsky/bundler_mcp/actions/workflows/main.yml)
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add bundler_mcp --group=development
+```
+
+## Usage
+
+1) Generate the binstub:
+
+```bash
+bundle binstubs bundler_mcp
+```
+
+2) Configure your client to execute the binstub. Here are examples that work for Claude and Cursor:
+
+### Basic Example (mcp.json)
+
+```json
+{
+  "mcpServers": {
+    "bundler-mcp": {
+      "command": "/Users/mike/my_project/bin/bundler_mcp"
+    }
+  }
+}
+```
+
+### Example with logging and explicit Gemfile
+
+```json
+{
+  "mcpServers": {
+    "bundler-mcp": {
+      "command": "/Users/mike/my_project/bin/bundler_mcp",
+
+      "env": {
+        "BUNDLER_MCP_LOG_FILE": "/Users/mike/my_project/log/mcp.log",
+        "BUNDLE_GEMFILE": "/Users/mike/my_project/subdir/Gemfile"
+      }
+    }
+  }
+}
+```
+
+### Available Tools
+
+The server provides two tools for AI agents:
+
+#### list_project_gems
+
+Lists all bundled Ruby gems with their:
+
+- Versions
+- Descriptions
+- Installation paths
+- Top-level documentation locations (e.g. `README` and `CHANGELOG`)
+
+![list_project_gems tool](/docs/list_project_gems.png)
+
+#### get_gem_details
+
+Retrieves detailed information about a specific gem, including:
+
+- Version
+- Description
+- Installation path
+- Top-level documentation locations
+- Source code file locations
+
+![get_gem_details tool](/docs/get_gem_details.png)
+
+## Environment Variables
+
+- `BUNDLE_GEMFILE`: Used by Bundler to locate your Gemfile. If you use the binstub method described in the [Usage](#usage) section, this is usually not needed.
+- `BUNDLER_MCP_LOG_FILE`: Path to log file. Useful for troubleshooting (defaults to no logging)
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies and `bundle exec rspec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+### Testing with the MCP Inspector
+
+You can test the server directly using the [MCP inspector](https://modelcontextprotocol.io/docs/tools/inspector):
+
+```bash
+# Basic usage
+npx @modelcontextprotocol/inspector ./bin/bundler_mcp
+
+# With logging enabled
+BUNDLER_MCP_LOG_FILE=/tmp/log/mcp.log npx @modelcontextprotocol/inspector ./bin/bundler_mcp
+
+# With custom Gemfile
+BUNDLE_GEMFILE=./other/Gemfile npx @modelcontextprotocol/inspector ./bin/bundler_mcp
+```
+
+### Release Process
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version:
+
+1. Update the version number in `version.rb`
+2. Run `bundle exec rake release`
+
+This will:
+
+- Create a git tag for the version
+- Push git commits and the created tag
+- Push the `.gem` file to [rubygems.org](https://rubygems.org)
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/subelsky/bundler_mcp.
+
+## License
+
+Open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Author
+
+[Mike Subelsky](https://subelsky.com)

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/exe/bundler_mcp

@@ -0,0 +1,14 @@
+#! /usr/bin/env ruby
+
+require "bundler/setup"
+require "logger"
+require_relative "../lib/bundler_mcp/server"
+
+# Set this up by running `bundle binstubs bundler_mcp`;
+# your client will then able to run `bin/bundler_mcp`
+# in the correct Bundler environment
+
+logfile_path = ENV.fetch("BUNDLER_MCP_LOGFILE", nil)
+logger = Logger.new(logfile_path || File::NULL)
+
+BundlerMCP::Server.run(logger:)

data/lib/bundler_mcp/environment_checker.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "bundler"
+require "bundler_mcp"
+
+module BundlerMCP
+  # Responsible for checking the environment to make sure Bundler can find gems
+  class EnvironmentChecker
+    # Check for a Gemfile and raise an error if not found
+    # @return [Pathname] The path to the Gemfile
+    # @raise [GemfileNotFound]
+    #   If Bundler cannot find a Gemfile; can be avoided by setting BUNDLE_GEMFILE
+    def self.check!
+      raise GemfileNotFound unless Bundler.default_gemfile.exist?
+
+      Bundler.default_gemfile
+    end
+  end
+end

data/lib/bundler_mcp/gem_resource.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+module BundlerMCP
+  # Represents a Ruby gem and its associated data
+  # @see https://docs.ruby-lang.org/en/2.5.0/Gem/Specification.html
+  class GemResource
+    extend Forwardable
+
+    def_delegators :gem, :name, :description, :full_gem_path
+
+    # @param gem [Gem::Specification]
+    def initialize(gem)
+      @gem = gem
+
+      @version = gem.version.to_s
+      @base_path = Pathname(@gem.full_gem_path)
+      @doc_paths = @base_path.glob("{README,CHANGELOG}*").map!(&:to_s)
+      @lib_path = @base_path.join("lib").to_s
+    end
+
+    # @return [Hash] A hash containing the gem's details
+    def to_h(include_source_files: false)
+      base_hash = { name:,
+                    version:,
+                    description:,
+                    full_gem_path:,
+                    lib_path:,
+                    top_level_documentation_paths: doc_paths }
+
+      base_hash[:source_files] = @base_path.glob("**/*.{rb,c,rake}").map!(&:to_s) if include_source_files
+
+      base_hash
+    end
+
+    private
+
+    attr_reader :gem, :version, :base_path, :doc_paths, :lib_path
+  end
+end

data/lib/bundler_mcp/resource_collection.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "gem_resource"
+require "singleton"
+
+module BundlerMCP
+  # Represents a collection of GemResource objects defining all currently bundled gems
+  # @see GemResource
+  class ResourceCollection
+    include Singleton
+    include Enumerable
+
+    def initialize
+      @resources = []
+
+      Gem.loaded_specs.each_value do |spec|
+        # Returns most gems as Bundler::StubSpecification, which does not expose
+        # many gem details, so we convert to Gem::Specification
+        spec = Gem::Specification.find_by_name(spec.name)
+        resources << GemResource.new(spec)
+      end
+    end
+
+    # Iterate over all GemResource objects in the collection
+    # @yield [GemResource] each GemResource object in the collection
+    def each(&)
+      resources.each(&)
+    end
+
+    private
+
+    attr_reader :resources
+  end
+end

data/lib/bundler_mcp/server.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "bundler"
+require "fast_mcp"
+require "json"
+require "pathname"
+require "logger"
+require_relative "version"
+require_relative "resource_collection"
+require_relative "tool_collection"
+require_relative "environment_checker"
+
+module BundlerMCP
+  # Main server class for BundlerMCP
+  # @see https://github.com/yjacquin/fast-mcp/blob/main/examples/server_with_stdio_transport.rb
+  class Server
+    # Convenience method to start the server
+    # @return [void]
+    def self.run(**args)
+      new(**args).run
+    end
+
+    # Initialize the server
+    # @return [void]
+    def initialize(logger: Logger.new(File::NULL))
+      @logger = logger
+
+      @server = FastMcp::Server.new(
+        name: "bundler-gem-documentation",
+        version: VERSION
+      )
+    end
+
+    # Start the MCP server
+    # @return [void]
+    def run
+      gemfile_path = EnvironmentChecker.check!
+      logger.info "Starting BundlerMCP server with Gemfile: #{gemfile_path}"
+
+      ToolCollection.each do |tool|
+        server.register_tool(tool)
+      end
+
+      server.start
+    rescue StandardError => e
+      logger.error e.message
+      raise e
+    end
+
+    private
+
+    attr_reader :logger, :server
+  end
+end

data/lib/bundler_mcp/tool_collection.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+Pathname(__dir__).glob("tools/*.rb").each do |tool|
+  require tool
+end
+
+module BundlerMCP
+  # Contains all tools that can be used by the caller
+  class ToolCollection
+    # @yield [Tool] each MCP tool
+    # @yieldparam tool [Tool] a tool in the collection
+    def self.each(&)
+      TOOLS.each(&)
+    end
+
+    TOOLS = BundlerMCP::Tools.constants.map { |c| BundlerMCP::Tools.const_get(c) }
+    private_constant :TOOLS
+  end
+end

data/lib/bundler_mcp/tools/get_gem_details.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "fast_mcp"
+
+module BundlerMCP
+  module Tools
+    # Retrieve details about a specific bundled Ruby gem
+    # @see ResourceCollection
+    class GetGemDetails < FastMcp::Tool
+      description <<~DESC
+        Returns detailed information about one **Ruby Gem** that is installed in the current project.
+
+        ‣ Use this tool when you need to know the version, summary, or source code location for a gem that is installed in the current project.
+        ‣ Do **not** use it for gems that are *not* part of this project.
+
+        The data comes directly from Gemfile.lock and the local installation, so it is always up-to-date and requires **no Internet access**.
+      DESC
+
+      arguments do
+        required(:name).filled(:string).description("The name of the gem to fetch")
+      end
+
+      # @return [String] Tool name exposed by FastMCP to clients
+      def self.name = "get_gem_details"
+
+      # @param collection [ResourceCollection] contains installed gems
+      def initialize(collection = ResourceCollection.instance)
+        @resource_collection = collection
+        super()
+      end
+
+      # @param name [String] The name of the gem to fetch
+      # @return [Hash] Contains the gem's details, or an error message if the gem is not found
+      def call(name:)
+        name = name.to_s.strip
+        gem_resource = resource_collection.find { |r| r.name == name }
+
+        data = if gem_resource
+                 gem_resource.to_h(include_source_files: true)
+               else
+                 { error: "We could not find '#{name}' among the project's bundled gems" }
+               end
+
+        JSON.generate(data)
+      end
+
+      private
+
+      attr_reader :resource_collection
+    end
+  end
+end

data/lib/bundler_mcp/tools/list_project_gems.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "mcp/tool"
+
+module BundlerMCP
+  module Tools
+    # Informs the client of all bundled Ruby gems with their versions, descriptions, installation paths,
+    # documentation, and (optionally) source code locations
+    # @see https://github.com/yjacquin/fast-mcp/blob/main/docs/tools.md
+    class ListProjectGems < FastMcp::Tool
+      description <<~DESC
+        Lists **all** Ruby Gems declared in this project's Gemfile/Gemfile.lock, returning for each gem:
+        name, version, short description, install path, and top-level docs path.
+
+        ‣ Use this tool whenever you need to know about the project's gem dependencies and how they work.
+        ‣ This tool reads local files only, so the data is authoritative for the current workspace
+          and never relies on the Internet.
+      DESC
+
+      # @return [String] Tool name exposed by FastMCP to clients
+      def self.name
+        "list_project_gems"
+      end
+
+      # @param collection [ResourceCollection] contains installed gems
+      def initialize(collection = ResourceCollection.instance)
+        @resource_collection = collection
+        super()
+      end
+
+      # Invoke the tool to list all installed gems
+      # @return [Array<Hash>] An array of hashes containing gem details
+      def call
+        data = resource_collection.map(&:to_h)
+        JSON.generate(data)
+      end
+
+      private
+
+      attr_reader :resource_collection
+    end
+  end
+end

data/lib/bundler_mcp/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module BundlerMCP
+  VERSION = "0.1.0"
+end

data/lib/bundler_mcp.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "bundler_mcp/version"
+
+# Namespace for BundlerMCP code
+module BundlerMCP
+  # Base error class for BundlerMCP
+  Error = Class.new(StandardError)
+
+  # Raised when Bundler cannot find a Gemfile
+  class GemfileNotFound < Error
+    def initialize(msg = DEFAULT_MESSAGE)
+      super
+    end
+
+    DEFAULT_MESSAGE = "Bundler cannot find a Gemfile; try setting BUNDLE_GEMFILE"
+  end
+end

metadata

@@ -0,0 +1,94 @@
+--- !ruby/object:Gem::Specification
+name: bundler_mcp
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Mike Subelsky
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+- !ruby/object:Gem::Dependency
+  name: fast-mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+description: |
+  A Model Context Protocol (MCP) server that enables AI agents to query information
+  about gems in a Ruby project's Gemfile, including source code and metadata.
+email:
+- 12020+subelsky@users.noreply.github.com
+executables:
+- bundler_mcp
+extensions: []
+extra_rdoc_files: []
+files:
+- ".ruby-version"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- docs/get_gem_details.png
+- docs/list_project_gems.png
+- exe/bundler_mcp
+- lib/bundler_mcp.rb
+- lib/bundler_mcp/environment_checker.rb
+- lib/bundler_mcp/gem_resource.rb
+- lib/bundler_mcp/resource_collection.rb
+- lib/bundler_mcp/server.rb
+- lib/bundler_mcp/tool_collection.rb
+- lib/bundler_mcp/tools/get_gem_details.rb
+- lib/bundler_mcp/tools/list_project_gems.rb
+- lib/bundler_mcp/version.rb
+homepage: https://github.com/subelsky/bundler_mcp
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/subelsky/bundler_mcp
+  source_code_uri: https://github.com/subelsky/bundler_mcp
+  changelog_uri: https://github.com/subelsky/bundler_mcp/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+  keywords: mcp gems bundler
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.8
+specification_version: 4
+summary: MCP server for searching Ruby bundled gem documentation and metadata
+test_files: []