open_gemdocs 0.2.4 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dd7cbbce2ee27525094486dde7d4b75c04075ca23f9c70e94fd5967b4e61075b
-  data.tar.gz: 660ee427703e51eda2215c6f04e83b6ed919097cde4c48a736c8b7b366f40e94
+  metadata.gz: 9bbe6e98bfab5caa95c6324956c9a45c44460d78851aeec0187d2a2718a0009a
+  data.tar.gz: 5f63e28eb06fc99aa6302784266315f9db0c7564a97319a12db88ad6b1faf917
 SHA512:
-  metadata.gz: fcc5a0e61f086ef4381b272b0cb9d47a49ae3046a9f33516279cd481ceae0bec09ea70b988cf981759d64961ca9d8917866b26d06a8a2e1422667078db86da9c
-  data.tar.gz: 6dea5832d8b8ffcbc941d77100a84c5873dcc351441780883c45950e1cc64c26d4a75cdb565b1d500433d600d352589792616edd7ebd83390f470145d759c406
+  metadata.gz: f8ac2030c49a4a20960eaee3d183ffb00794678db396897f14c969088355c734fa57d9ea62613946553a7400dfcbd344613eddeb74734acf0bdad35964f0e474
+  data.tar.gz: bc42203b67b70b9839844febce219fa5d7b9732c609120eeac8f39d32b86de423794ace83d1c208a069eff4df9ca14f5958d57ce3a36a611e1c6d61cabb7a66b

data/.rubocop.yml

@@ -1,8 +1,45 @@
 AllCops:
   TargetRubyVersion: 3.1
+  NewCops: enable
+  SuggestExtensions: false
 
 Style/StringLiterals:
   EnforcedStyle: double_quotes
 
 Style/StringLiteralsInInterpolation:
   EnforcedStyle: double_quotes
+
+Style/Documentation:
+  Enabled: false
+
+Metrics/MethodLength:
+  Max: 30
+  Exclude:
+    - 'lib/open_gemdocs/mcp/tools.rb'
+
+Metrics/ClassLength:
+  Max: 350
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+    - '*.gemspec'
+
+Metrics/AbcSize:
+  Max: 35
+
+Metrics/CyclomaticComplexity:
+  Max: 15
+
+Metrics/PerceivedComplexity:
+  Max: 15
+
+Layout/LineLength:
+  Max: 200
+
+Naming/AccessorMethodName:
+  Exclude:
+    - 'lib/open_gemdocs/mcp/tools.rb'
+
+Style/MultilineBlockChain:
+  Enabled: false

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [Unreleased]
 
+## [0.3.0] - 2025-04-27
+### Added
+- Added a MCP server that can serve local yard documentation for all installed gems. This allows AI agents to access gem documentation without needing to run a local server manually.
+
 ## [0.2.1] - 2025-04-26
 ### Changed
 - Fixed a bug where the `--local` option was not working correctly when a specific gem was specified. The command now correctly serves the documentation for the specified gem from the local server.

data/CLAUDE.md

@@ -0,0 +1,136 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Repository Overview
+
+Open_gemdocs is a Ruby gem that provides a command-line tool for opening Ruby gem documentation. It supports both local documentation (via Yard server) and online documentation (via gemdocs.org).
+
+## Common Commands
+
+### Development Setup
+```bash
+# Install dependencies
+bundle install
+
+# Setup development environment
+bin/setup
+
+# Open IRB console with gem loaded
+bin/console
+```
+
+### Testing
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run specific test file
+bundle exec rspec spec/open_gemdocs_spec.rb
+
+# Run tests via Rake
+bundle exec rake spec
+```
+
+### Linting & Code Quality
+```bash
+# Run RuboCop for code linting
+bundle exec rubocop
+
+# Auto-fix RuboCop violations
+bundle exec rubocop -a
+
+# Run all checks (tests + linting)
+bundle exec rake
+```
+
+### Building & Installation
+```bash
+# Build the gem
+gem build open_gemdocs.gemspec
+
+# Install locally for testing
+gem install ./open_gemdocs-*.gem
+
+# Build via Rake
+bundle exec rake build
+
+# Release new version (requires gem push permissions)
+bundle exec rake release
+```
+
+### Local Testing of CLI
+```bash
+# Test the main executable
+bundle exec exe/open-gem-docs rails
+
+# Test with local documentation
+bundle exec exe/open-gem-docs --local rails
+
+# Test the local-only wrapper
+bundle exec exe/open-local-docs rails
+```
+
+### MCP Server
+```bash
+# Start MCP server on default port (6789)
+bundle exec exe/open-gem-docs-mcp
+
+# Start MCP server on custom port
+bundle exec exe/open-gem-docs-mcp --port 8080
+
+# Start MCP server in stdio mode (for Claude Desktop integration)
+bundle exec exe/open-gem-docs-mcp-stdio
+
+# View MCP server help and available tools
+bundle exec exe/open-gem-docs-mcp --help
+```
+
+## Architecture
+
+The gem follows a simple, focused architecture with core documentation components and MCP server integration:
+
+### Core Module Structure
+- **`lib/open_gemdocs.rb`**: Main module that orchestrates between Browser and Yard classes based on user options
+- **`lib/open_gemdocs/browser.rb`**: Handles opening online documentation from gemdocs.org, includes Gemfile.lock parsing for version detection
+- **`lib/open_gemdocs/yard.rb`**: Manages local Yard server lifecycle (starting, stopping, checking status) and opens local documentation
+
+### MCP (Model Context Protocol) Integration
+The gem includes MCP server capabilities for AI assistant integration:
+
+- **`lib/open_gemdocs/mcp/server.rb`**: MCP server implementation supporting both TCP and stdio modes
+- **`lib/open_gemdocs/mcp/handlers.rb`**: JSON-RPC request handling for MCP protocol
+- **`lib/open_gemdocs/mcp/tools.rb`**: MCP tool implementations providing programmatic access to gem documentation
+
+Available MCP tools:
+- `search_gems`: Search for installed Ruby gems by name
+- `get_gem_info`: Get detailed metadata about a specific gem
+- `start_yard_server`: Start the Yard documentation server
+- `stop_yard_server`: Stop the Yard documentation server
+- `get_yard_server_status`: Check if Yard server is running and where
+- `get_gem_documentation_url`: Get the local documentation URL for a gem
+- `fetch_gem_docs`: Fetch documentation content from Yard server
+
+### Key Implementation Details
+
+1. **Version Detection**: The Browser class automatically detects gem versions from Gemfile.lock when no version is specified
+2. **Server Management**: The Yard class manages a background Yard server process, checking if it's running and starting it if needed
+3. **Platform Dependency**: Uses macOS `open` command - platform-specific implementation would be needed for Linux/Windows support
+4. **Error Handling**: Custom `OpenGemdocs::Error` class for consistent error reporting
+
+### CLI Entry Points
+- **`exe/open-gem-docs`**: Full-featured CLI with option parsing (--local, --version, etc.)
+- **`exe/open-local-docs`**: Convenience wrapper that always uses local documentation
+- **`exe/open-gem-docs-mcp`**: MCP server for TCP connections (default port 6789)
+- **`exe/open-gem-docs-mcp-stdio`**: MCP server for stdio mode (Claude Desktop integration)
+
+## Important Considerations
+
+- The gem is signed with a certificate in `certs/mrinterweb.pem` - ensure this is present when building releases
+- Requires Ruby >= 3.1.0
+- The test suite needs expansion - currently only has placeholder tests
+- When modifying CLI behavior, update all relevant executables if needed
+- The Yard server runs on port 8808 by default
+- MCP server runs on port 6789 by default (configurable via --port)
+- MCP stdio mode is designed for Claude Desktop integration via the MCP protocol
+- The MCP server automatically manages the Yard server lifecycle as needed

data/README.md

@@ -1,6 +1,8 @@
 # OpenGemdocs
 
-This is ruby gem that provides a simple command line tool that helps open gem documentation. There are two documentation sources this gem supports.
+This gem makes accessing ruby gem documentation easy for users with a CLI tool and AI agents with a MCP server.
+
+There are two documentation sources this gem supports.
 
 1. local gems served with the yard gem via `yard server --gems` or `yard server --gemfile` accessible at http://localhost:8808.
 2. [https://gemdocs.org](https://gemdocs.org) - a good ruby gem documentation host
@@ -24,7 +26,7 @@ If bundler is not being used to manage dependencies, install the gem by executin
 gem install open_gemdocs
 ```
 
-## Usage
+## CLI Usage
 
 Currently, this only works on Macs because of the `open` command. It opens the documentation for a gem in your default web browser.
 
@@ -69,6 +71,55 @@ Example using the `open-local-docs` command:
 open-local-docs rspec
 ```
 
+## MCP Server
+
+The gem includes an MCP (Model Context Protocol) server that allows AI assistants to programmatically access Ruby gem documentation. The MCP server manages a local Yard documentation server and provides tools for searching and retrieving gem documentation.
+
+### Starting the MCP Server
+
+```bash
+open-gem-docs-mcp
+```
+
+By default, the server runs on port 6789. You can specify a different port:
+
+```bash
+open-gem-docs-mcp --port 8080
+```
+
+### Available MCP Tools
+
+The MCP server provides the following tools:
+
+- **search_gems** - Search for installed Ruby gems by name
+- **get_gem_info** - Get detailed information about a specific gem
+- **start_yard_server** - Start the Yard documentation server
+- **stop_yard_server** - Stop the Yard documentation server
+- **get_yard_server_status** - Check if the Yard server is running
+- **get_gem_documentation_url** - Get the local documentation URL for a gem
+- **fetch_gem_docs** - Fetch documentation content from the Yard server
+
+### Using with Claude Code
+
+```
+claude mcp add open-gem-docs -- open-gem-docs-mcp-stdio
+```
+
+### Using with Claude Desktop
+
+To use the MCP server with Claude Desktop, add the following to your Claude Desktop configuration:
+
+```json
+{
+  "mcpServers": {
+    "open_gemdocs": {
+      "command": "open-gem-docs-mcp",
+      "args": ["--port", "6789"]
+    }
+  }
+}
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/checksums/open_gemdocs-0.3.1.gem.sha512

@@ -0,0 +1 @@
+32e9cdcb7c3c463dbff38e38fb53e0a51eb2cf8e80250420e40129d32911b9fce015ef3cc0266f1773f0cf39ff644a16c662068860c43d4f0d210688df4dd8f8

data/exe/document-bundle

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+
+system(%q{
+bundle list | awk '/ \* / {gsub(/[()]/, "", $3); print $2, $3}' | while read gem version; do
+  echo "Processing docs for: $gem $version"
+  yard gems "$gem" "$version"
+done
+})

data/exe/open-gem-docs

@@ -1,34 +1,34 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require 'uri'
-require 'net/http'
-require 'json'
-require 'optparse'
-require_relative File.join('..', 'lib', 'open_gemdocs')
+require "uri"
+require "net/http"
+require "json"
+require "optparse"
+require_relative File.join("..", "lib", "open_gemdocs")
 
 options = {}
 
 OptionParser.new do |opts|
-  opts.banner = 'Usage: open-gem-docs [options] <gem_name>'
+  opts.banner = "Usage: open-gem-docs [options] <gem_name>"
 
-  opts.on('--local', 'Use local documentation') do
+  opts.on("--local", "Use local documentation") do
     options[:local] = true
   end
-  opts.on('-v', '--version VERSION', 'Specify the version') do |version|
+  opts.on("-v", "--version VERSION", "Specify the version") do |version|
     options[:version] = version
   end
 
-  opts.on('--latest', 'Use the latest version') do
+  opts.on("--latest", "Use the latest version") do
     options[:latest] = true
   end
 
-  opts.on('-h', '--help', 'Display this help message') do
+  opts.on("-h", "--help", "Display this help message") do
     puts opts
     exit
   end
 
-  opts.on('-s', '--stop', 'stops the yard server') do
+  opts.on("-s", "--stop", "stops the yard server") do
     OpenGemdocs::Yard.stop_server
     exit
   end

data/exe/open-gem-docs-mcp

@@ -0,0 +1,52 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "../lib/open_gemdocs/version"
+require_relative "../lib/open_gemdocs/mcp/server"
+require_relative "../lib/open_gemdocs/mcp/handlers"
+require_relative "../lib/open_gemdocs/mcp/tools"
+
+options = { port: 6789 }
+
+OptionParser.new do |opts|
+  opts.banner = "Usage: open-gem-docs-mcp [options]"
+
+  opts.on("-p", "--port PORT", Integer, "Port to run MCP server on (default: 6789)") do |p|
+    options[:port] = p
+  end
+
+  opts.on("-v", "--version", "Show version") do
+    puts "open_gemdocs MCP server v#{OpenGemdocs::VERSION}"
+    exit
+  end
+
+  opts.on("-h", "--help", "Show this help message") do
+    puts opts
+    puts
+    puts "This MCP server provides tools for accessing Ruby gem documentation."
+    puts "It integrates with the Yard documentation server to provide local docs."
+    puts
+    puts "Available MCP tools:"
+    puts "  - search_gems: Search for installed Ruby gems"
+    puts "  - get_gem_info: Get detailed information about a gem"
+    puts "  - start_yard_server: Start the Yard documentation server"
+    puts "  - stop_yard_server: Stop the Yard documentation server"
+    puts "  - get_yard_server_status: Check Yard server status"
+    puts "  - get_gem_documentation_url: Get the documentation URL for a gem"
+    puts "  - fetch_gem_docs: Fetch documentation content from Yard server"
+    exit
+  end
+end.parse!
+
+begin
+  server = OpenGemdocs::MCP::Server.new(port: options[:port])
+  server.start
+rescue Interrupt
+  puts "\nShutting down..."
+  exit 0
+rescue StandardError => e
+  warn "Error: #{e.message}"
+  warn e.backtrace if ENV["DEBUG"]
+  exit 1
+end

data/exe/open-gem-docs-mcp-stdio

@@ -0,0 +1,76 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "json"
+require_relative "../lib/open_gemdocs/version"
+require_relative "../lib/open_gemdocs/mcp/handlers"
+require_relative "../lib/open_gemdocs/mcp/tools"
+
+# MCP stdio server for Claude Desktop
+class MCPStdioServer
+  def initialize
+    @handlers = OpenGemdocs::MCP::Handlers.new
+    STDERR.puts "open_gemdocs MCP server v#{OpenGemdocs::VERSION} (stdio mode)"
+  end
+
+  def run
+    STDERR.puts "MCP server started in stdio mode"
+    
+    loop do
+      begin
+        # Read line from stdin
+        line = STDIN.gets
+        break if line.nil? # EOF
+        
+        next if line.strip.empty?
+        
+        # Parse JSON-RPC request
+        request = JSON.parse(line.strip)
+        
+        # Handle the request
+        response = @handlers.handle(request)
+        
+        # Write response to stdout if there is one
+        if response
+          STDOUT.puts JSON.generate(response)
+          STDOUT.flush
+        end
+      rescue JSON::ParserError => e
+        error_response = {
+          jsonrpc: "2.0",
+          error: {
+            code: -32700,
+            message: "Parse error",
+            data: e.message
+          }
+        }
+        STDOUT.puts JSON.generate(error_response)
+        STDOUT.flush
+      rescue StandardError => e
+        STDERR.puts "Error: #{e.message}"
+        STDERR.puts e.backtrace if ENV["DEBUG"]
+        
+        error_response = {
+          jsonrpc: "2.0",
+          error: {
+            code: -32603,
+            message: "Internal error",
+            data: e.message
+          }
+        }
+        STDOUT.puts JSON.generate(error_response)
+        STDOUT.flush
+      end
+    end
+    
+    STDERR.puts "MCP server shutting down"
+  rescue Interrupt
+    STDERR.puts "\nShutting down MCP server..."
+    OpenGemdocs::Yard.stop_server
+    exit 0
+  end
+end
+
+# Run the server
+server = MCPStdioServer.new
+server.run

data/lib/open_gemdocs/browser.rb

@@ -6,7 +6,7 @@ module OpenGemdocs
 
     def initialize(gem_name:, version: nil, use_latest: false)
       @gem_name = gem_name
-      raise ArgumentError, 'Gem name is required' if gem_name.nil? || gem_name.empty?
+      raise ArgumentError, "Gem name is required" if gem_name.nil? || gem_name.empty?
 
       @version = version
       @use_latest = use_latest
@@ -15,7 +15,7 @@ module OpenGemdocs
     def resolve_version
       return version if version
 
-      if !use_latest && File.exist?('Gemfile.lock')
+      if !use_latest && File.exist?("Gemfile.lock")
         @version = check_bundle_version
         if @version
           puts "Using version from Gemfile.lock: #{version}"
@@ -25,27 +25,27 @@ module OpenGemdocs
 
       @use_latest = true
 
-      puts 'No version specified, using latest version'
+      puts "No version specified, using latest version"
     end
 
     def open_browser
       resolve_version
-      raise Error, 'No version URL found' unless version_url
+      raise Error, "No version URL found" unless version_url
 
-      version_str = version ? "@v#{version}" : ''
-      latest_str = use_latest ? ' (latest)' : ''
+      version_str = version ? "@v#{version}" : ""
+      latest_str = use_latest ? " (latest)" : ""
       puts "Fetching gem documentation for #{gem_name}#{version_str}#{latest_str}..."
       # open is a macOS command to open a URL in the default browser
-      raise Error, 'Could not resolve URL' if version_url.nil?
+      raise Error, "Could not resolve URL" if version_url.nil?
 
-      `open "#{version_url.sub('production.', '')}"`
+      `open "#{version_url.sub("production.", "")}"`
     end
 
     def version_url
       if use_latest
-        version_data.last['url']
+        version_data.last["url"]
       else
-        version_data.detect { |row| row['version'] == version }&.fetch('url')
+        version_data.detect { |row| row["version"] == version }&.fetch("url")
       end
     end
 
@@ -57,11 +57,9 @@ module OpenGemdocs
       @version_data ||= begin
         uri = URI("https://gemdocs.org/gems/#{ARGV[0]}/versions.json")
         res = Net::HTTP.get_response(uri)
-        unless res.is_a?(Net::HTTPSuccess)
-          raise Error, "HTTP request failed to uri: #{uri} -- #{res.code} #{res.message}"
-        end
+        raise Error, "HTTP request failed to uri: #{uri} -- #{res.code} #{res.message}" unless res.is_a?(Net::HTTPSuccess)
 
-        JSON.parse(res.body)['versions']
+        JSON.parse(res.body)["versions"]
       end
     end
   end

data/lib/open_gemdocs/mcp/handlers.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require_relative "tools"
+
+module OpenGemdocs
+  module MCP
+    class Handlers
+      def initialize
+        @tools = Tools.new
+      end
+
+      def handle(request)
+        method = request["method"]
+        id = request["id"]
+
+        case method
+        when "initialize"
+          handle_initialize(id)
+        when "initialized"
+          # Client notification, no response needed
+          nil
+        when "tools/list"
+          handle_tools_list(id)
+        when "tools/call"
+          handle_tool_call(id, request["params"])
+        when "ping"
+          { "jsonrpc" => "2.0", "id" => id, "result" => {} }
+        else
+          error_response(id, -32_601, "Method not found: #{method}")
+        end
+      end
+
+      private
+
+      def handle_initialize(id)
+        {
+          "jsonrpc" => "2.0",
+          "id" => id,
+          "result" => {
+            "protocolVersion" => "2024-11-05",
+            "capabilities" => {
+              "tools" => {},
+              "resources" => {}
+            },
+            "serverInfo" => {
+              "name" => "open_gemdocs_mcp",
+              "version" => OpenGemdocs::VERSION
+            }
+          }
+        }
+      end
+
+      def handle_tools_list(id)
+        {
+          "jsonrpc" => "2.0",
+          "id" => id,
+          "result" => {
+            "tools" => @tools.list
+          }
+        }
+      end
+
+      def handle_tool_call(id, params)
+        tool_name = params["name"]
+        arguments = params["arguments"] || {}
+
+        begin
+          result = @tools.call(tool_name, arguments)
+
+          {
+            "jsonrpc" => "2.0",
+            "id" => id,
+            "result" => result
+          }
+        rescue StandardError => e
+          error_response(id, -32_603, "Tool execution error: #{e.message}")
+        end
+      end
+
+      def error_response(id, code, message)
+        {
+          "jsonrpc" => "2.0",
+          "id" => id,
+          "error" => {
+            "code" => code,
+            "message" => message
+          }
+        }
+      end
+    end
+  end
+end