girb-mcp 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52b798eb530b44561b3c7c15e3949e9d4c9376d719f212be7bc2aece5e1a15f4
-  data.tar.gz: d83af060aa7dd5feb7199ffcd5902957b01db11a89daa56b268f0a9925fda888
+  metadata.gz: 8213f3c4f1d7f389034a135870ac3ae68cb452420d8f383d4317539899c31a81
+  data.tar.gz: 785eb0939caf7fa4f78947790ca2833c9bd2362b26ad00a2e64ab20f252cc9d1
 SHA512:
-  metadata.gz: 030243a382e114faba8479096f334803124f2124f3b2111bec437a63cc7f7532b6b4688b3646900d2e20f86fb50cb3b6ec4d5354e12597e28887ed7e0dbfd68b
-  data.tar.gz: e3d558db66f789691d84b8e52437fce620b3581a0c2aebc12f0e12d898589a2d9504432529a096fc1df529603d26fd1319e633d7f0e2e739232add675f97f903
+  metadata.gz: fa5704c2861680cf78b9b7d5df6a8444141c7c100529f49d9d601ed6699b2feea1ff0e7332d8c7a1fdd3b2c90ecd98413960e755e55d4f5b5e4a972ff4c8714d
+  data.tar.gz: f8b84758a7ce6d9fa1ba52c9d11b9e369f4a5dd18e8a2822a19dec6e0bff7cf1e58f0d2b46c310e2d0e40587019e3eb6acb9b1d8fd8bdcb9fd46a72a717f8698

data/README.md

@@ -1,351 +1,39 @@
-# girb-mcp
+# girb-mcp (DEPRECATED — renamed to debug-mcp)
 
-[日本語版 (Japanese)](README.ja.md)
+> **This gem has been renamed to [`debug-mcp`](https://rubygems.org/gems/debug-mcp).**
+> Recent `girb-mcp` releases on RubyGems are a deprecation shim that depends on `debug-mcp`
+> and forwards all executables to it. It will receive no further updates.
 
-MCP (Model Context Protocol) server that gives LLM agents access to the runtime context of executing Ruby processes.
+## Migration
 
-LLM agents like Claude Code can connect to a paused Ruby process, inspect variables, evaluate code, set breakpoints, and control execution — all through MCP tool calls.
-
-## What it does
-
-Existing Ruby/Rails MCP servers only provide static analysis or application-level APIs. girb-mcp goes further: it connects to **running Ruby processes** via the debug gem and exposes their runtime state to LLM agents.
-
-```
-Claude Code → connect(host: "localhost", port: 12345)
-Claude Code → get_context()
-  → local variables, instance variables, call stack
-Claude Code → evaluate_code(code: "user.valid?")
-  → false
-Claude Code → evaluate_code(code: "user.errors.full_messages")
-  → ["Email can't be blank"]
-Claude Code → continue_execution()
-```
-
-## Installation
+Replace `girb-mcp` with `debug-mcp` in your `Gemfile`:
 
 ```ruby
-gem "girb-mcp"
-```
-
-Or install directly:
-
-```
-gem install girb-mcp
+gem "debug-mcp"  # was: gem "girb-mcp"
 ```
 
-Requires Ruby >= 3.2.0.
-
-## Quick Start
-
-### 1. Start a Ruby process with the debugger
-
-```bash
-# Script
-rdbg --open --port=12345 my_script.rb
-
-# Or with environment variables
-RUBY_DEBUG_OPEN=true RUBY_DEBUG_PORT=12345 ruby my_script.rb
-
-# Or add `debugger` / `binding.break` in your code and run with rdbg
-rdbg --open my_script.rb
-```
-
-### 2. Configure Claude Code
-
-Add to your `~/.claude/settings.json` (or project `.claude/settings.json`):
+And in your MCP client config:
 
 ```json
 {
   "mcpServers": {
-    "girb-mcp": {
-      "command": "girb-mcp",
+    "debug-mcp": {                // was: "girb-mcp"
+      "command": "debug-mcp",     // was: "girb-mcp"
       "args": []
     }
   }
 }
 ```
 
-If using Bundler:
-
-```json
-{
-  "mcpServers": {
-    "girb-mcp": {
-      "command": "bundle",
-      "args": ["exec", "girb-mcp"]
-    }
-  }
-}
-```
-
-### 3. Debug with Claude Code
-
-Ask Claude Code to connect and debug:
-
-> "Connect to the debug session on port 12345 and show me the current state"
-
-> "Set a breakpoint at app/models/user.rb line 42 and send a GET request to /users/1"
-
-## Usage
-
-```
-Usage: girb-mcp [options]
-    -t, --transport TRANSPORT        Transport type: stdio (default) or http
-    -p, --port PORT                  HTTP port (default: 6029, only for http transport)
-        --host HOST                  HTTP host (default: 127.0.0.1, only for http transport)
-        --session-timeout SECONDS    Session timeout in seconds (default: 1800)
-    -v, --version                    Show version
-    -h, --help                       Show this help
-```
-
-### STDIO transport (default)
-
-Standard transport for Claude Code and other MCP clients. No additional configuration needed.
-
-```bash
-girb-mcp
-```
-
-### HTTP transport (Streamable HTTP)
-
-For browser-based clients or other HTTP-compatible MCP clients.
-
-```bash
-girb-mcp --transport http --port 8080
-```
-
-The MCP endpoint will be available at `http://127.0.0.1:8080/mcp`.
-
-### Session timeout
-
-Debug sessions are automatically cleaned up after 30 minutes of inactivity. Adjust with:
-
-```bash
-girb-mcp --session-timeout 3600  # 1 hour
-```
-
-The session manager also detects and cleans up sessions whose target process has exited.
-
-## Tools
-
-### Discovery & Connection
-
-| Tool | Description |
-|------|-------------|
-| `list_debug_sessions` | List available debug sessions (Unix sockets) |
-| `connect` | Connect to a debug session via socket path or TCP |
-| `list_paused_sessions` | List currently connected sessions |
-
-### Investigation
-
-| Tool | Description |
-|------|-------------|
-| `evaluate_code` | Execute Ruby code in the stopped binding |
-| `inspect_object` | Get class, value, and instance variables of an object |
-| `get_context` | Local variables, instance variables, call stack, breakpoints |
-| `get_source` | Source code of a method or class |
-| `read_file` | Read source files with optional line range |
-| `list_files` | List files in a directory, with optional glob pattern |
-
-### Execution Control
-
-| Tool | Description |
-|------|-------------|
-| `set_breakpoint` | Set a breakpoint: line (file + line), method (`User#save`), or exception class |
-| `remove_breakpoint` | Remove a breakpoint by file + line, method name, exception class, or number |
-| `continue_execution` | Resume execution until next breakpoint or exit |
-| `step` | Step into the next method call |
-| `next` | Step over to the next line |
-| `finish` | Run until the current method/block returns |
-| `run_debug_command` | Execute any raw debugger command |
-| `disconnect` | Disconnect from the session and terminate the process |
-
-### Entry Points
-
-| Tool | Description |
-|------|-------------|
-| `run_script` | Start a Ruby script under rdbg and connect to it |
-| `trigger_request` | Send an HTTP request to a Rails app under debug |
-
-### Rails Tools (auto-detected)
-
-These tools are automatically registered when a Rails process is detected.
-
-| Tool | Description |
-|------|-------------|
-| `rails_info` | Show app name, Rails/Ruby versions, environment, root path |
-| `rails_routes` | Show routes (verb, path, controller#action), filterable by controller or path |
-| `rails_model` | Show model structure: columns, associations, validations, enums, scopes |
-
-## Workflows
-
-### Debug a Ruby script
+The executable `girb-rails` was likewise renamed to `debug-rails`.
 
-```
-Agent: run_script(file: "my_script.rb")
-Agent: get_context()
-Agent: evaluate_code(code: "result")
-Agent: next()
-Agent: evaluate_code(code: "result")
-Agent: continue_execution()
-```
-
-### Method breakpoints
-
-```
-Agent: run_script(file: "my_script.rb", breakpoints: ["DataPipeline#validate"])
-  → Script starts and pauses at DataPipeline#validate
-Agent: evaluate_code(code: "records")
-Agent: continue_execution()
-```
-
-### Catch and debug exceptions
-
-```
-Agent: run_script(file: "my_script.rb")
-Agent: set_breakpoint(exception_class: "NoMethodError")
-Agent: continue_execution()
-  → Execution pauses BEFORE the exception propagates
-Agent: get_context()
-Agent: evaluate_code(code: "$!.message")
-```
-
-### Restart after a crash
-
-```
-  → Program crashed with NoMethodError
-Agent: run_script(file: "my_script.rb", restore_breakpoints: true)
-  → Same breakpoints restored automatically
-Agent: set_breakpoint(exception_class: "NoMethodError")
-Agent: continue_execution()
-  → Catches the exception before it crashes
-```
-
-### Debug a Rails request
-
-Start your Rails server with debug enabled using `girb-rails`:
-
-```bash
-girb-rails                # equivalent to RUBY_DEBUG_OPEN=true bin/rails server
-girb-rails s -p 4000      # specify port
-girb-rails --debug-port 3333  # use specific TCP debug port (useful in Docker)
-```
-
-Then ask the agent to debug:
-
-```
-Agent: connect()
-Agent: set_breakpoint(file: "app/controllers/users_controller.rb", line: 15)
-Agent: trigger_request(method: "GET", url: "http://localhost:3000/users/1")
-Agent: get_context()
-Agent: evaluate_code(code: "@user.attributes")
-Agent: continue_execution()
-```
-
-### Debug a Dockerized Rails app
-
-> **Security note:** The debug gem has no authentication. Anyone who can reach the debug port can execute arbitrary code inside the container. Always restrict access as shown below.
-
-#### Option A: Localhost-only TCP (simple)
-
-Expose the debug port bound to `127.0.0.1` so only local processes can connect:
-
-```yaml
-services:
-  web:
-    build: .
-    ports:
-      - "3000:3000"
-      - "127.0.0.1:12345:12345"  # localhost only
-    environment:
-      - RUBY_DEBUG_OPEN=true
-      - RUBY_DEBUG_HOST=0.0.0.0
-      - RUBY_DEBUG_PORT=12345
-```
-
-```
-Agent: connect(port: 12345)
-```
-
-The agent can read source files inside the container — no local copy of the source code is needed.
-
-#### Option B: Unix socket volume mount (recommended)
-
-Mount a shared directory for the debug socket. No port exposure needed:
-
-```yaml
-services:
-  web:
-    build: .
-    ports:
-      - "3000:3000"
-    environment:
-      - RUBY_DEBUG_OPEN=true
-      - RUBY_DEBUG_SOCK_PATH=/debug/rdbg.sock
-    volumes:
-      - debug_sock:/debug
-
-volumes:
-  debug_sock:
-```
-
-```
-Agent: connect(path: "/path/to/debug_sock/rdbg.sock")
-```
-
-### Connect to an existing breakpoint
-
-```bash
-# Terminal: your app hits a `debugger` statement
-rdbg --open my_app.rb
-```
-
-```
-Agent: list_debug_sessions()
-Agent: connect(path: "/tmp/rdbg-1000/rdbg-12345")
-Agent: get_context()
-```
-
-## How it works
-
-```
-┌─────────────┐  STDIO or Streamable HTTP ┌───────────┐    TCP/Unix Socket    ┌──────────────┐
-│ Claude Code  │ ◄──────────────────────► │ girb-mcp  │ ◄──────────────────► │ Ruby process │
-│ (MCP Client) │       (JSON-RPC)         │(MCP Server)│    debug gem proto   │  (rdbg)      │
-└─────────────┘                           └───────────┘                      └──────────────┘
-```
-
-1. girb-mcp runs as an MCP server communicating via STDIO (default) or Streamable HTTP
-2. The debug gem (`rdbg --open`) exposes a socket on the target Ruby process
-3. girb-mcp connects to that socket using the debug gem's wire protocol
-4. MCP tool calls are translated to debugger commands and results are returned
-5. Idle sessions are automatically cleaned up after a configurable timeout
-
-## Security
-
-girb-mcp is a debugging tool that intentionally provides deep runtime access. Here's what you should know:
-
-**Structured tools minimize arbitrary code execution.** Most debugging tasks — viewing variables, reading source code, inspecting model structure — are handled by dedicated tools that don't run arbitrary code. `evaluate_code` is available for runtime inspection, and a built-in safety checker warns about dangerous operations.
-
-**The debug gem has no authentication.** Anyone who can reach the debug socket can execute arbitrary code in the target process. Always bind to localhost (`127.0.0.1`) or use Unix sockets. See the [Docker section](#debug-a-dockerized-rails-app) for configuration examples.
-
-## Part of the girb family
-
-girb-mcp is part of the [girb](https://github.com/rira100000000/girb) family:
-
-- **girb** — AI-powered IRB assistant (interactive, for humans)
-- **girb-mcp** — MCP server for LLM agents (programmatic, for agents)
-- **girb-ruby_llm** — LLM provider for girb via ruby_llm
-- **girb-gemini** — LLM provider for girb via Gemini API
-
-## Development
-
-```bash
-git clone https://github.com/rira100000000/girb-mcp.git
-cd girb-mcp
-bundle install
-```
+The `girb-mcp` deprecation shim still works as a transitional step (it `exec`s
+`debug-mcp` / `debug-rails` after printing a deprecation warning), but please
+migrate to `debug-mcp` directly.
 
-## License
+## Why the rename?
 
-MIT
+The new name better reflects what this gem does: an MCP server for Ruby's
+[`debug` gem](https://github.com/ruby/debug). See the
+[debug-mcp repository](https://github.com/rira100000000/debug-mcp) for the
+current source and changelog.

data/exe/girb-mcp

@@ -1,39 +1,10 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require "girb_mcp"
-require "optparse"
+$stderr.puts "[DEPRECATION] girb-mcp has been renamed to debug-mcp."
+$stderr.puts "  Replace 'girb-mcp' with 'debug-mcp' in your MCP client config."
+$stderr.puts "  See: https://github.com/rira100000000/debug-mcp"
+$stderr.puts "  This shim forwards to 'debug-mcp' for now, but will not receive updates."
 
-options = {}
-
-OptionParser.new do |opts|
-  opts.banner = "Usage: girb-mcp [options]"
-
-  opts.on("-t", "--transport TRANSPORT", %w[stdio http], "Transport type: stdio (default) or http") do |t|
-    options[:transport] = t
-  end
-
-  opts.on("-p", "--port PORT", Integer, "HTTP port (default: 6029, only for http transport)") do |p|
-    options[:port] = p
-  end
-
-  opts.on("--host HOST", "HTTP host (default: 127.0.0.1, only for http transport)") do |h|
-    options[:host] = h
-  end
-
-  opts.on("--session-timeout SECONDS", Integer, "Session timeout in seconds (default: 1800)") do |t|
-    options[:session_timeout] = t
-  end
-
-  opts.on("-v", "--version", "Show version") do
-    puts "girb-mcp #{GirbMcp::VERSION}"
-    exit
-  end
-
-  opts.on("-h", "--help", "Show this help") do
-    puts opts
-    exit
-  end
-end.parse!
-
-GirbMcp::Server.new(**options).start
+require "rubygems"
+exec(Gem.bin_path("debug-mcp", "debug-mcp"), *ARGV)

data/exe/girb-rails

@@ -1,127 +1,10 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-class GirbRails
-  DEFAULT_DEBUG_PORT = 12321
+$stderr.puts "[DEPRECATION] girb-rails has been renamed to debug-rails."
+$stderr.puts "  Replace 'girb-rails' with 'debug-rails' in your scripts/configs."
+$stderr.puts "  See: https://github.com/rira100000000/debug-mcp"
+$stderr.puts "  This shim forwards to 'debug-rails' for now, but will not receive updates."
 
-  def self.parse_args(argv)
-    debug_port = nil
-    show_help = false
-
-    i = 0
-    while i < argv.length
-      case argv[i]
-      when "--debug-port"
-        i += 1
-        raise ArgumentError, "--debug-port requires a port number" if i >= argv.length
-        debug_port = parse_port(argv[i])
-        i += 1
-      when /\A--debug-port=(.+)\z/
-        debug_port = parse_port($1)
-        i += 1
-      when "-h", "--help"
-        show_help = true
-        i += 1
-      else
-        break
-      end
-    end
-
-    rails_args = argv[i..] || []
-
-    if rails_args.empty? || rails_args.first.start_with?("-")
-      rails_args.unshift("server")
-    end
-
-    { debug_port: debug_port, rails_args: rails_args, show_help: show_help }
-  end
-
-  def self.parse_port(value)
-    port = Integer(value)
-    raise ArgumentError unless port.positive?
-    port
-  rescue ArgumentError, TypeError
-    raise ArgumentError, "--debug-port requires a valid port number, got: #{value.inspect}"
-  end
-
-  def self.build_env(debug_port:, docker:)
-    if docker
-      {
-        "RUBY_DEBUG_HOST" => "0.0.0.0",
-        "RUBY_DEBUG_PORT" => (debug_port || DEFAULT_DEBUG_PORT).to_s,
-      }
-    else
-      env = { "RUBY_DEBUG_OPEN" => "true" }
-      env["RUBY_DEBUG_PORT"] = debug_port.to_s if debug_port
-      env
-    end
-  end
-
-  def self.docker?
-    File.exist?("/.dockerenv")
-  end
-
-  def self.print_help(io = $stdout)
-    io.puts <<~HELP
-      Usage: girb-rails [options] [rails-command] [rails-options]
-
-      Launch a Rails server with Ruby debug gem enabled for girb-mcp debugging.
-
-      Options:
-        --debug-port PORT  Debug port for TCP connection (default: #{DEFAULT_DEBUG_PORT} in Docker)
-        -h, --help         Show this help
-
-      Examples:
-        girb-rails                          # rails server with debug enabled
-        girb-rails s -p 4000                # rails server on port 4000
-        girb-rails --debug-port 3333        # use TCP debug port 3333
-        girb-rails console                  # rails console with debug enabled
-
-      Environment:
-        Outside Docker: Sets RUBY_DEBUG_OPEN=true
-        Inside Docker:  Sets RUBY_DEBUG_HOST=0.0.0.0, RUBY_DEBUG_PORT=PORT
-    HELP
-  end
-
-  def self.run(argv = ARGV)
-    parsed = parse_args(argv)
-
-    if parsed[:show_help]
-      print_help
-      exit 0
-    end
-
-    unless File.exist?("bin/rails")
-      $stderr.puts "Error: bin/rails not found in current directory."
-      $stderr.puts "Run this command from your Rails application root."
-      exit 1
-    end
-
-    env = build_env(debug_port: parsed[:debug_port], docker: docker?)
-    pid = spawn(env, "bin/rails", *parsed[:rails_args])
-
-    force_quit_deadline = nil
-
-    Signal.trap("INT") do
-      if force_quit_deadline && Time.now < force_quit_deadline
-        Process.kill("KILL", pid)
-      else
-        Process.kill("TERM", pid)
-        $stderr.write "\nStopping... Press Ctrl+C again within 3s to force quit\n"
-        force_quit_deadline = Time.now + 3
-      end
-    end
-
-    Signal.trap("TERM") do
-      Process.kill("TERM", pid)
-    end
-
-    _, status = Process.waitpid2(pid)
-    exit(status.exitstatus || 1)
-  rescue ArgumentError => e
-    $stderr.puts "Error: #{e.message}"
-    exit 1
-  end
-end
-
-GirbRails.run unless defined?(RSpec)
+require "rubygems"
+exec(Gem.bin_path("debug-mcp", "debug-rails"), *ARGV)

data/lib/girb_mcp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module GirbMcp
-  VERSION = "0.1.1"
+  VERSION = "0.1.3"
 end

data/lib/girb_mcp.rb

@@ -1,40 +1,11 @@
 # frozen_string_literal: true
 
 require_relative "girb_mcp/version"
-require_relative "girb_mcp/debug_client"
-require_relative "girb_mcp/session_manager"
-require_relative "girb_mcp/exit_message_builder"
-require_relative "girb_mcp/stop_event_annotator"
-require_relative "girb_mcp/tcp_session_discovery"
-require_relative "girb_mcp/server"
 
-module GirbMcp
-  class Error < StandardError; end
+warn "[DEPRECATION] girb-mcp has been renamed to debug-mcp. " \
+     "Update your Gemfile to use 'debug-mcp' instead, and update any MCP " \
+     "client config that references the 'girb-mcp' / 'girb-rails' commands " \
+     "to 'debug-mcp' / 'debug-rails'. " \
+     "See https://github.com/rira100000000/debug-mcp for migration details."
 
-  class ConnectionError < Error
-    attr_reader :final_output
-
-    def initialize(message = nil, final_output: nil)
-      super(message)
-      @final_output = final_output
-    end
-  end
-
-  class SessionError < Error
-    attr_reader :final_output
-
-    def initialize(message = nil, final_output: nil)
-      super(message)
-      @final_output = final_output
-    end
-  end
-
-  class TimeoutError < Error
-    attr_reader :final_output
-
-    def initialize(message = nil, final_output: nil)
-      super(message)
-      @final_output = final_output
-    end
-  end
-end
+require "debug_mcp"