RubyGems - debug-mcp - Versions diffs - 0.1.2 - Mend

debug-mcp 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (122) hide show

checksums.yaml +7 -0
data/.rspec +3 -0
data/CHANGELOG.md +83 -0
data/LICENSE +21 -0
data/README.ja.md +383 -0
data/README.md +384 -0
data/examples/01_simple_bug.rb +43 -0
data/examples/02_data_pipeline.rb +93 -0
data/examples/03_recursion.rb +96 -0
data/examples/RAILS_SCENARIOS.md +350 -0
data/examples/SCENARIOS.md +142 -0
data/examples/rails_test_app/setup.sh +428 -0
data/examples/rails_test_app/testapp/.dockerignore +10 -0
data/examples/rails_test_app/testapp/.ruby-version +1 -0
data/examples/rails_test_app/testapp/Dockerfile +23 -0
data/examples/rails_test_app/testapp/Gemfile +17 -0
data/examples/rails_test_app/testapp/README.md +65 -0
data/examples/rails_test_app/testapp/Rakefile +6 -0
data/examples/rails_test_app/testapp/app/assets/images/.keep +0 -0
data/examples/rails_test_app/testapp/app/assets/stylesheets/application.css +1 -0
data/examples/rails_test_app/testapp/app/controllers/application_controller.rb +4 -0
data/examples/rails_test_app/testapp/app/controllers/concerns/.keep +0 -0
data/examples/rails_test_app/testapp/app/controllers/dashboard_controller.rb +38 -0
data/examples/rails_test_app/testapp/app/controllers/health_controller.rb +11 -0
data/examples/rails_test_app/testapp/app/controllers/orders_controller.rb +100 -0
data/examples/rails_test_app/testapp/app/controllers/posts_controller.rb +82 -0
data/examples/rails_test_app/testapp/app/controllers/sessions_controller.rb +25 -0
data/examples/rails_test_app/testapp/app/controllers/users_controller.rb +44 -0
data/examples/rails_test_app/testapp/app/helpers/application_helper.rb +2 -0
data/examples/rails_test_app/testapp/app/models/application_record.rb +3 -0
data/examples/rails_test_app/testapp/app/models/comment.rb +8 -0
data/examples/rails_test_app/testapp/app/models/concerns/.keep +0 -0
data/examples/rails_test_app/testapp/app/models/order.rb +56 -0
data/examples/rails_test_app/testapp/app/models/order_item.rb +16 -0
data/examples/rails_test_app/testapp/app/models/post.rb +29 -0
data/examples/rails_test_app/testapp/app/models/user.rb +34 -0
data/examples/rails_test_app/testapp/app/services/order_report_service.rb +40 -0
data/examples/rails_test_app/testapp/app/views/layouts/application.html.erb +28 -0
data/examples/rails_test_app/testapp/app/views/pwa/manifest.json.erb +22 -0
data/examples/rails_test_app/testapp/app/views/pwa/service-worker.js +26 -0
data/examples/rails_test_app/testapp/bin/ci +6 -0
data/examples/rails_test_app/testapp/bin/dev +2 -0
data/examples/rails_test_app/testapp/bin/rails +4 -0
data/examples/rails_test_app/testapp/bin/rake +4 -0
data/examples/rails_test_app/testapp/bin/setup +35 -0
data/examples/rails_test_app/testapp/config/application.rb +42 -0
data/examples/rails_test_app/testapp/config/boot.rb +3 -0
data/examples/rails_test_app/testapp/config/ci.rb +14 -0
data/examples/rails_test_app/testapp/config/database.yml +32 -0
data/examples/rails_test_app/testapp/config/environment.rb +5 -0
data/examples/rails_test_app/testapp/config/environments/development.rb +54 -0
data/examples/rails_test_app/testapp/config/environments/production.rb +67 -0
data/examples/rails_test_app/testapp/config/environments/test.rb +42 -0
data/examples/rails_test_app/testapp/config/initializers/content_security_policy.rb +29 -0
data/examples/rails_test_app/testapp/config/initializers/filter_parameter_logging.rb +8 -0
data/examples/rails_test_app/testapp/config/initializers/inflections.rb +16 -0
data/examples/rails_test_app/testapp/config/locales/en.yml +31 -0
data/examples/rails_test_app/testapp/config/puma.rb +39 -0
data/examples/rails_test_app/testapp/config/routes.rb +34 -0
data/examples/rails_test_app/testapp/config.ru +6 -0
data/examples/rails_test_app/testapp/db/migrate/20260216002916_create_users.rb +12 -0
data/examples/rails_test_app/testapp/db/migrate/20260216002919_create_posts.rb +13 -0
data/examples/rails_test_app/testapp/db/migrate/20260216002922_create_comments.rb +11 -0
data/examples/rails_test_app/testapp/db/migrate/20260222000001_create_orders.rb +14 -0
data/examples/rails_test_app/testapp/db/migrate/20260222000002_create_order_items.rb +13 -0
data/examples/rails_test_app/testapp/db/schema.rb +71 -0
data/examples/rails_test_app/testapp/db/seeds.rb +85 -0
data/examples/rails_test_app/testapp/docker-compose.yml +21 -0
data/examples/rails_test_app/testapp/docker-entrypoint.sh +10 -0
data/examples/rails_test_app/testapp/lib/tasks/.keep +0 -0
data/examples/rails_test_app/testapp/log/.keep +0 -0
data/examples/rails_test_app/testapp/public/400.html +135 -0
data/examples/rails_test_app/testapp/public/404.html +135 -0
data/examples/rails_test_app/testapp/public/406-unsupported-browser.html +135 -0
data/examples/rails_test_app/testapp/public/422.html +135 -0
data/examples/rails_test_app/testapp/public/500.html +135 -0
data/examples/rails_test_app/testapp/public/icon.png +0 -0
data/examples/rails_test_app/testapp/public/icon.svg +3 -0
data/examples/rails_test_app/testapp/public/robots.txt +1 -0
data/examples/rails_test_app/testapp/script/.keep +0 -0
data/examples/rails_test_app/testapp/storage/.keep +0 -0
data/examples/rails_test_app/testapp/tmp/.keep +0 -0
data/examples/rails_test_app/testapp/tmp/pids/.keep +0 -0
data/examples/rails_test_app/testapp/tmp/storage/.keep +0 -0
data/examples/rails_test_app/testapp/vendor/.keep +0 -0
data/exe/debug-mcp +39 -0
data/exe/debug-rails +127 -0
data/lib/debug_mcp/client_cleanup.rb +102 -0
data/lib/debug_mcp/code_safety_analyzer.rb +124 -0
data/lib/debug_mcp/debug_client.rb +1143 -0
data/lib/debug_mcp/exit_message_builder.rb +112 -0
data/lib/debug_mcp/pending_http_helper.rb +25 -0
data/lib/debug_mcp/rails_helper.rb +155 -0
data/lib/debug_mcp/server.rb +364 -0
data/lib/debug_mcp/session_manager.rb +436 -0
data/lib/debug_mcp/stop_event_annotator.rb +152 -0
data/lib/debug_mcp/tcp_session_discovery.rb +226 -0
data/lib/debug_mcp/tools/connect.rb +669 -0
data/lib/debug_mcp/tools/continue_execution.rb +161 -0
data/lib/debug_mcp/tools/disconnect.rb +169 -0
data/lib/debug_mcp/tools/evaluate_code.rb +354 -0
data/lib/debug_mcp/tools/finish.rb +84 -0
data/lib/debug_mcp/tools/get_context.rb +217 -0
data/lib/debug_mcp/tools/get_source.rb +193 -0
data/lib/debug_mcp/tools/inspect_object.rb +107 -0
data/lib/debug_mcp/tools/list_debug_sessions.rb +60 -0
data/lib/debug_mcp/tools/list_files.rb +189 -0
data/lib/debug_mcp/tools/list_paused_sessions.rb +108 -0
data/lib/debug_mcp/tools/next.rb +70 -0
data/lib/debug_mcp/tools/rails_info.rb +200 -0
data/lib/debug_mcp/tools/rails_model.rb +362 -0
data/lib/debug_mcp/tools/rails_routes.rb +186 -0
data/lib/debug_mcp/tools/read_file.rb +214 -0
data/lib/debug_mcp/tools/remove_breakpoint.rb +173 -0
data/lib/debug_mcp/tools/run_debug_command.rb +55 -0
data/lib/debug_mcp/tools/run_script.rb +293 -0
data/lib/debug_mcp/tools/set_breakpoint.rb +206 -0
data/lib/debug_mcp/tools/step.rb +67 -0
data/lib/debug_mcp/tools/trigger_request.rb +515 -0
data/lib/debug_mcp/version.rb +5 -0
data/lib/debug_mcp.rb +40 -0
metadata +251 -0

data/examples/rails_test_app/testapp/public/500.html ADDED Viewed

@@ -0,0 +1,135 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <title>We're sorry, but something went wrong (500 Internal Server Error)</title>
+    <meta charset="utf-8">
+    <meta name="viewport" content="initial-scale=1, width=device-width">
+    <meta name="robots" content="noindex, nofollow">
+    <style>
+      *, *::before, *::after {
+        box-sizing: border-box;
+      }
+      * {
+        margin: 0;
+      }
+      html {
+        font-size: 16px;
+      }
+      body {
+        background: #FFF;
+        color: #261B23;
+        display: grid;
+        font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Aptos, Roboto, "Segoe UI", "Helvetica Neue", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
+        font-size: clamp(1rem, 2.5vw, 2rem);
+        -webkit-font-smoothing: antialiased;
+        font-style: normal;
+        font-weight: 400;
+        letter-spacing: -0.0025em;
+        line-height: 1.4;
+        min-height: 100dvh;
+        place-items: center;
+        text-rendering: optimizeLegibility;
+        -webkit-text-size-adjust: 100%;
+      }
+      #error-description {
+        fill: #d30001;
+      }
+      #error-id {
+        fill: #f0eff0;
+      }
+      @media (prefers-color-scheme: dark) {
+        body {
+          background: #101010;
+          color: #e0e0e0;
+        }
+        #error-description {
+          fill: #FF6161;
+        }
+        #error-id {
+          fill: #2c2c2c;
+        }
+      }
+      a {
+        color: inherit;
+        font-weight: 700;
+        text-decoration: underline;
+        text-underline-offset: 0.0925em;
+      }
+      b, strong {
+        font-weight: 700;
+      }
+      i, em {
+        font-style: italic;
+      }
+      main {
+        display: grid;
+        gap: 1em;
+        padding: 2em;
+        place-items: center;
+        text-align: center;
+      }
+      main header {
+        width: min(100%, 12em);
+      }
+      main header svg {
+        height: auto;
+        max-width: 100%;
+        width: 100%;
+      }
+      main article {
+        width: min(100%, 30em);
+      }
+      main article p {
+        font-size: 75%;
+      }
+      main article br {
+        display: none;
+        @media(min-width: 48em) {
+          display: inline;
+        }
+      }
+    </style>
+  </head>
+  <body>
+    <!-- This file lives in public/500.html -->
+    <main>
+      <header>
+        <svg height="172" viewBox="0 0 480 172" width="480" xmlns="http://www.w3.org/2000/svg"><path d="m101.23 93.8427c-8.1103 0-15.4098 3.7849-19.7354 8.3813h-36.2269v-99.21891h103.8143v37.03791h-68.3984v24.8722c5.1366-2.7035 15.1396-5.9477 24.6014-5.9477 35.146 0 56.233 22.7094 56.233 55.4215 0 34.605-23.791 57.315-60.558 57.315-37.8492 0-61.64-22.169-63.8028-55.963h42.9857c1.0814 10.814 9.1919 19.195 21.6281 19.195 11.355 0 19.465-8.381 19.465-20.547 0-11.625-7.299-20.5463-20.006-20.5463zm138.833 77.8613c-40.822 0-64.884-35.146-64.884-85.7015 0-50.5554 24.062-85.700907 64.884-85.700907 40.823 0 64.884 35.145507 64.884 85.700907 0 50.5555-24.061 85.7015-64.884 85.7015zm0-133.2831c-17.572 0-22.709 21.8984-22.709 47.5816 0 25.6835 5.137 47.5815 22.709 47.5815 17.303 0 22.71-21.898 22.71-47.5815 0-25.6832-5.407-47.5816-22.71-47.5816zm140.456 133.2831c-40.823 0-64.884-35.146-64.884-85.7015 0-50.5554 24.061-85.700907 64.884-85.700907 40.822 0 64.884 35.145507 64.884 85.700907 0 50.5555-24.062 85.7015-64.884 85.7015zm0-133.2831c-17.573 0-22.71 21.8984-22.71 47.5816 0 25.6835 5.137 47.5815 22.71 47.5815 17.302 0 22.709-21.898 22.709-47.5815 0-25.6832-5.407-47.5816-22.709-47.5816z" id="error-id"/><path d="m23.1377 68.9967v34.0033h-8.9162v-34.0033zm4.3157 34.0033v-24.921h8.6947v2.1598c1.3845-1.5506 3.8212-2.7136 6.701-2.7136 5.538 0 8.8054 3.5997 8.8054 9.1377v16.3371h-8.6393v-14.2327c0-2.049-1.0522-3.5443-3.2674-3.5443-1.7168 0-3.1567.9969-3.5997 2.7136v15.0634zm29.9913-8.5839v-9.5807h-3.655v-6.7564h3.655v-6.8671h8.5839v6.8671h5.2058v6.7564h-5.2058v8.307c0 1.9383.9415 2.769 2.6583 2.769.9414 0 1.9937-.2216 2.769-.5538v7.3654c-.9969.443-2.8798.775-4.8181.775-5.8703 0-9.1931-2.769-9.1931-9.0819zm32.3666-.1108h8.0301c-.8861 5.7597-5.2057 9.2487-11.6852 9.2487-7.6424 0-12.682-5.2613-12.682-13.0145 0-7.6978 5.3165-13.0143 12.5159-13.0143 7.6424 0 11.9621 5.095 11.9621 12.5159v2.1598h-16.1156c.2769 2.9905 1.8275 4.5965 4.3196 4.5965 1.7722 0 3.1567-.7753 3.6551-2.4921zm-3.8212-10.0237c-2.0491 0-3.4336 1.2737-3.9874 3.5997h7.5317c-.1107-2.0491-1.3845-3.5997-3.5443-3.5997zm31.4299-6.3134v8.3624c-1.052-.5538-2.215-.7753-3.599-.7753-2.382 0-3.988 1.0522-4.431 2.8244v14.6203h-8.694v-24.921h8.694v2.2152c1.219-1.6614 3.157-2.769 5.649-2.769 1.108 0 1.994.2215 2.381.443zm2.949 25.0318v-24.921h8.694v2.1598c1.385-1.5506 3.821-2.7136 6.701-2.7136 5.538 0 8.806 3.5997 8.806 9.1377v16.3371h-8.64v-14.2327c0-2.049-1.052-3.5443-3.267-3.5443-1.717 0-3.157.9969-3.6 2.7136v15.0634zm50.371 0h-8.363v-1.274c-.83.831-3.323 1.717-5.981 1.717-4.929 0-9.082-2.769-9.082-8.0301 0-4.818 4.153-7.9193 9.581-7.9193 2.049 0 4.485.6646 5.482 1.3845v-1.606c0-1.606-.941-2.9905-3.046-2.9905-1.606 0-2.547.7199-2.935 1.8275h-8.196c.72-4.8181 4.984-8.6393 11.408-8.6393 7.089 0 11.132 3.7659 11.132 10.2453zm-8.363-6.9779v-1.4399c-.554-1.0522-2.049-1.7167-3.655-1.7167-1.717 0-3.433.7199-3.433 2.3813 0 1.7168 1.716 2.4367 3.433 2.4367 1.606 0 3.101-.6645 3.655-1.6614zm20.742-29.0191v35.997h-8.694v-35.997zm13.036 25.9178h9.248c.72 2.326 2.714 3.489 5.483 3.489 2.713 0 4.596-1.163 4.596-3.2674 0-1.6061-1.052-2.326-3.212-2.8244l-6.534-1.3845c-4.985-1.1076-8.751-3.7105-8.751-9.47 0-6.6456 5.538-11.0206 13.07-11.0206 8.307 0 13.014 4.5411 13.956 10.4114h-8.695c-.72-1.8829-2.27-3.3228-5.205-3.3228-2.548 0-4.265 1.1076-4.265 2.9905 0 1.4953 1.052 2.326 2.825 2.7137l6.645 1.5506c5.815 1.3845 9.027 4.5412 9.027 9.8023 0 6.9778-5.87 10.9654-13.291 10.9654-8.141 0-13.679-3.9322-14.897-10.6332zm46.509 1.3845h8.031c-.887 5.7597-5.206 9.2487-11.686 9.2487-7.642 0-12.682-5.2613-12.682-13.0145 0-7.6978 5.317-13.0143 12.516-13.0143 7.643 0 11.962 5.095 11.962 12.5159v2.1598h-16.115c.277 2.9905 1.827 4.5965 4.319 4.5965 1.773 0 3.157-.7753 3.655-2.4921zm-3.821-10.0237c-2.049 0-3.433 1.2737-3.987 3.5997h7.532c-.111-2.0491-1.385-3.5997-3.545-3.5997zm31.431-6.3134v8.3624c-1.053-.5538-2.216-.7753-3.6-.7753-2.381 0-3.988 1.0522-4.431 2.8244v14.6203h-8.694v-24.921h8.694v2.2152c1.219-1.6614 3.157-2.769 5.649-2.769 1.108 0 1.994.2215 2.382.443zm18.288 25.0318h-7.809l-9.47-24.921h8.861l4.763 14.288 4.652-14.288h8.528zm25.614-8.6947h8.03c-.886 5.7597-5.206 9.2487-11.685 9.2487-7.642 0-12.682-5.2613-12.682-13.0145 0-7.6978 5.316-13.0143 12.516-13.0143 7.642 0 11.962 5.095 11.962 12.5159v2.1598h-16.116c.277 2.9905 1.828 4.5965 4.32 4.5965 1.772 0 3.157-.7753 3.655-2.4921zm-3.821-10.0237c-2.049 0-3.434 1.2737-3.988 3.5997h7.532c-.111-2.0491-1.384-3.5997-3.544-3.5997zm31.43-6.3134v8.3624c-1.052-.5538-2.215-.7753-3.6-.7753-2.381 0-3.987 1.0522-4.43 2.8244v14.6203h-8.695v-24.921h8.695v2.2152c1.218-1.6614 3.157-2.769 5.649-2.769 1.107 0 1.993.2215 2.381.443zm13.703-8.9715h24.312v7.6424h-15.562v5.3165h14.232v7.4763h-14.232v5.8703h15.562v7.6978h-24.312zm44.667 8.9715v8.3624c-1.052-.5538-2.215-.7753-3.6-.7753-2.381 0-3.987 1.0522-4.43 2.8244v14.6203h-8.695v-24.921h8.695v2.2152c1.218-1.6614 3.156-2.769 5.648-2.769 1.108 0 1.994.2215 2.382.443zm19.673 0v8.3624c-1.053-.5538-2.216-.7753-3.6-.7753-2.381 0-3.987 1.0522-4.43 2.8244v14.6203h-8.695v-24.921h8.695v2.2152c1.218-1.6614 3.156-2.769 5.648-2.769 1.108 0 1.994.2215 2.382.443zm26.769 12.5713c0 7.6978-5.15 13.0145-12.737 13.0145-7.532 0-12.738-5.3167-12.738-13.0145s5.206-13.0143 12.738-13.0143c7.587 0 12.737 5.3165 12.737 13.0143zm-8.529 0c0-3.4336-1.495-5.8703-4.208-5.8703-2.659 0-4.154 2.4367-4.154 5.8703s1.495 5.8149 4.154 5.8149c2.713 0 4.208-2.3813 4.208-5.8149zm28.082-12.5713v8.3624c-1.052-.5538-2.215-.7753-3.6-.7753-2.381 0-3.987 1.0522-4.43 2.8244v14.6203h-8.695v-24.921h8.695v2.2152c1.218-1.6614 3.157-2.769 5.649-2.769 1.107 0 1.993.2215 2.381.443z" id="error-description"/></svg>
+      </header>
+      <article>
+        <p><strong>We're sorry, but something went wrong.</strong><br> If you're the application owner check the logs for more information.</p>
+      </article>
+    </main>
+  </body>
+</html>

data/examples/rails_test_app/testapp/public/icon.png ADDED Viewed

Binary file

data/examples/rails_test_app/testapp/public/icon.svg ADDED Viewed

@@ -0,0 +1,3 @@
+<svg width="512" height="512" xmlns="http://www.w3.org/2000/svg">
+  <circle cx="256" cy="256" r="256" fill="red"/>
+</svg>

data/examples/rails_test_app/testapp/public/robots.txt ADDED Viewed

	@@ -0,0 +1 @@
1	+ # See https://www.robotstxt.org/robotstxt.html for documentation on how to use the robots.txt file

data/examples/rails_test_app/testapp/script/.keep ADDED Viewed

File without changes

data/examples/rails_test_app/testapp/storage/.keep ADDED Viewed

File without changes

data/examples/rails_test_app/testapp/tmp/.keep ADDED Viewed

File without changes

data/examples/rails_test_app/testapp/tmp/pids/.keep ADDED Viewed

File without changes

data/examples/rails_test_app/testapp/tmp/storage/.keep ADDED Viewed

File without changes

data/examples/rails_test_app/testapp/vendor/.keep ADDED Viewed

File without changes

data/exe/debug-mcp ADDED Viewed

@@ -0,0 +1,39 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+require "debug_mcp"
+require "optparse"
+options = {}
+OptionParser.new do |opts|
+  opts.banner = "Usage: debug-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 "debug-mcp #{DebugMcp::VERSION}"
+    exit
+  end
+  opts.on("-h", "--help", "Show this help") do
+    puts opts
+    exit
+  end
+end.parse!
+DebugMcp::Server.new(**options).start

data/exe/debug-rails ADDED Viewed

@@ -0,0 +1,127 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+class DebugRails
+  DEFAULT_DEBUG_PORT = 12321
+  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: debug-rails [options] [rails-command] [rails-options]
+      Launch a Rails server with Ruby debug gem enabled for debug-mcp debugging.
+      Options:
+        --debug-port PORT  Debug port for TCP connection (default: #{DEFAULT_DEBUG_PORT} in Docker)
+        -h, --help         Show this help
+      Examples:
+        debug-rails                          # rails server with debug enabled
+        debug-rails s -p 4000                # rails server on port 4000
+        debug-rails --debug-port 3333        # use TCP debug port 3333
+        debug-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
+DebugRails.run unless defined?(RSpec)

data/lib/debug_mcp/client_cleanup.rb ADDED Viewed

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+module DebugMcp
+  # Shared cleanup logic for graceful disconnect.
+  # Used by Disconnect tool and SessionManager reaper to avoid ~100 lines of duplication.
+  # Performs: stdout restore, breakpoint deletion, SIGINT handler restore,
+  # process resume, and stale pause defense.
+  module ClientCleanup
+    # Perform best-effort cleanup and resume a paused debug client.
+    # The client MUST be paused before calling this method.
+    # @param client [DebugClient] the client to clean up
+    # @param deadline [Time] hard deadline for all cleanup operations
+    # @param max_stale_retries [Integer] max retries for stale pause defense
+    def self.cleanup_and_resume(client, deadline:, max_stale_retries: 2)
+      # Restore $stdout if evaluate_code left it redirected (its ensure block
+      # fails when send_command timeout sets @paused=false).
+      remaining = deadline - Time.now
+      if remaining > 0
+        begin
+          client.send_command(
+            '$stdout = STDOUT if $stdout != STDOUT',
+            timeout: [remaining, 1].min,
+          )
+        rescue DebugMcp::Error
+          # Best-effort
+        end
+      end
+      # Delete all breakpoints FIRST — this is the most critical step.
+      # If breakpoints remain and the process resumes without a client,
+      # it will hit a breakpoint and become stuck with no way to continue.
+      delete_all_breakpoints(client, deadline)
+      # Restore original SIGINT handler
+      remaining = deadline - Time.now
+      if remaining > 0
+        begin
+          client.send_command(
+            "p $_debug_mcp_orig_int ? (trap('INT',$_debug_mcp_orig_int);$_debug_mcp_orig_int=nil;:ok) : nil",
+            timeout: [remaining, 2].min,
+          )
+        rescue DebugMcp::Error
+          # Best-effort
+        end
+      end
+      # Resume the process. If a cleanup command timed out (setting
+      # @paused=false even though the process is actually still paused),
+      # use force: true to bypass the @paused check.
+      client.send_command_no_wait("c", force: true)
+      # Wait for the debug gem to settle after 'c'. After SIGINT recovery,
+      # the main thread needs to finish the interrupted eval and re-enter
+      # the command loop (sending `input PID`). If we close the socket
+      # before this completes, the debug gem's cleanup_reader closes @q_msg
+      # while the main thread is still pushing results, leaving it stuck
+      # on a futex. Draining here gives the debug gem time to settle.
+      client.ensure_paused(timeout: 2)
+      # Stale pause defense: after 'c' → ensure_paused, the process might
+      # have been re-paused by a stale `pause` message left in the debug
+      # gem's socket buffer. If still paused, delete remaining BPs and
+      # send 'c' again (bounded retries to prevent infinite loop).
+      stale_retries = 0
+      while client.paused && stale_retries < max_stale_retries
+        stale_retries += 1
+        remaining = deadline - Time.now
+        break if remaining <= 0
+        delete_all_breakpoints(client, deadline)
+        remaining = deadline - Time.now
+        break if remaining <= 0
+        client.send_command_no_wait("c", force: true)
+        client.ensure_paused(timeout: [remaining, 1].min)
+      end
+    end
+    # Delete all breakpoints from the debug session.
+    # @param client [DebugClient] the client
+    # @param deadline [Time] hard deadline
+    def self.delete_all_breakpoints(client, deadline)
+      remaining = deadline - Time.now
+      return if remaining <= 0
+      bp_output = client.send_command("info breakpoints", timeout: [remaining, 2].min)
+      return if bp_output.strip.empty?
+      bp_output.each_line do |line|
+        remaining = deadline - Time.now
+        break if remaining <= 0
+        if (match = line.match(/#(\d+)/))
+          client.send_command("delete #{match[1]}", timeout: [remaining, 2].min) rescue nil
+        end
+      end
+    rescue DebugMcp::Error
+      # Best-effort
+    end
+  end
+end

data/lib/debug_mcp/code_safety_analyzer.rb ADDED Viewed

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+module DebugMcp
+  module CodeSafetyAnalyzer
+    DANGEROUS_PATTERNS = {
+      file_operations: [
+        [/\bFile\s*\.\s*(write|delete|unlink|rename|chmod|chown)\b/, "File.write/delete/unlink/rename"],
+        [/\bFileUtils\b/, "FileUtils"],
+        [/\bIO\s*\.\s*(write|binwrite)\b/, "IO.write"],
+        [/\bDir\s*\.\s*(mkdir|rmdir|delete|unlink)\b/, "Dir.mkdir/rmdir"],
+      ],
+      system_commands: [
+        [/\bsystem\s*\(/, "system()"],
+        [/\bexec\s*\(/, "exec()"],
+        [/\bspawn\s*\(/, "spawn()"],
+        [/`[^`]+`/, "backtick command"],
+        [/%x\{/, "%x{}"],
+        [/%x\[/, "%x[]"],
+        [/%x\(/, "%x()"],
+        [/\bOpen3\b/, "Open3"],
+        [/\bIO\s*\.\s*popen\b/, "IO.popen"],
+      ],
+      process_manipulation: [
+        [/\bProcess\s*\.\s*(kill|fork|exit)\b/, "Process.kill/fork/exit"],
+        [/\bfork\s*[\s({]/, "fork"],
+        [/\bexit!/, "exit!"],
+        [/\babort\b/, "abort"],
+      ],
+      network_operations: [
+        [/\bNet::HTTP\b/, "Net::HTTP"],
+        [/\bTCPSocket\b/, "TCPSocket"],
+        [/\bUDPSocket\b/, "UDPSocket"],
+        [/\bFaraday\b/, "Faraday"],
+        [/\bHTTParty\b/, "HTTParty"],
+        [/\bopen-uri\b/, "open-uri"],
+        [/\bURI\s*\.\s*open\b/, "URI.open"],
+        [/\bRestClient\b/, "RestClient"],
+      ],
+      destructive_data: [
+        [/\.destroy_all\b/, ".destroy_all"],
+        [/\.delete_all\b/, ".delete_all"],
+        [/\.update_all\b/, ".update_all"],
+        [/\b(DROP|TRUNCATE)\s+(TABLE|DATABASE)\b/i, "DROP/TRUNCATE SQL"],
+      ],
+      mutation_operations: [
+        [/\.save!/, ".save!"],
+        [/\.save\b(?![!?])/, ".save"],
+        [/\.update![\s(]/, ".update!"],
+        [/\.update[\s(]/, ".update"],
+        [/\.create![\s(]/, ".create!"],
+        [/\.create[\s(]/, ".create"],
+        [/\.destroy!/, ".destroy!"],
+        [/\.destroy\b(?![_!])/, ".destroy"],
+        [/\.touch\b/, ".touch"],
+        [/\.increment!/, ".increment!"],
+        [/\.decrement!/, ".decrement!"],
+        [/\.toggle!/, ".toggle!"],
+      ],
+    }.freeze
+    # Filter out warnings whose categories have been acknowledged.
+    def self.filter_acknowledged(warnings, acknowledged_categories)
+      return warnings if acknowledged_categories.nil? || acknowledged_categories.empty?
+      warnings.reject { |w| acknowledged_categories.include?(w[:category]) }
+    end
+    # Analyze code for dangerous patterns.
+    # Returns an array of warnings: [{ category:, label:, matches: }]
+    def self.analyze(code)
+      warnings = []
+      DANGEROUS_PATTERNS.each do |category, patterns|
+        matches = []
+        patterns.each do |regexp, label|
+          matches << label if code.match?(regexp)
+        end
+        next if matches.empty?
+        warnings << { category: category, matches: matches }
+      end
+      warnings
+    end
+    CATEGORY_LABELS = {
+      file_operations: "File system operations",
+      system_commands: "System command execution",
+      process_manipulation: "Process manipulation",
+      network_operations: "Network operations",
+      destructive_data: "Destructive data operations",
+      mutation_operations: "Data mutation (modifies database records)",
+    }.freeze
+    # Format warnings into human-readable text.
+    # Returns nil if no warnings.
+    # Uses a compact "Note:" format when only mutation_operations are present,
+    # and a verbose "WARNING:" format when other categories are involved.
+    def self.format_warnings(warnings)
+      return nil if warnings.empty?
+      # Compact format for mutation-only warnings
+      if warnings.all? { |w| w[:category] == :mutation_operations }
+        matches = warnings.flat_map { |w| w[:matches] }
+        return "Note: Data mutation detected (#{matches.join(", ")}). " \
+               "Use acknowledge_mutations to suppress this notice."
+      end
+      # Verbose format for dangerous operations
+      lines = []
+      lines << "WARNING: Potentially dangerous operations detected in code."
+      lines << "evaluate_code should only be used for investigating runtime state."
+      lines << "Use the agent's own tools for file/system/network operations."
+      lines << ""
+      warnings.each do |w|
+        label = CATEGORY_LABELS[w[:category]] || w[:category].to_s
+        lines << "  #{label}: #{w[:matches].join(", ")}"
+      end
+      lines.join("\n")
+    end
+  end
+end