rails-hyperdrive 0.3.0

data/lib/rails/hyperdrive/mcp_server.rb

@@ -0,0 +1,80 @@
+require "mcp"
+require "mcp/server/transports/streamable_http_transport"
+require_relative "safety/rack_middleware"
+require_relative "tools/describe_app"
+require_relative "tools/run_ruby"
+require_relative "tools/run_sql"
+require_relative "tools/tail_logs"
+require_relative "tools/list_models"
+require_relative "tools/locate_source"
+require_relative "tools/lookup_doc"
+require_relative "tools/list_routes"
+require_relative "resources/stack_profile"
+require_relative "resources/skill"
+
+module Rails
+  module Hyperdrive
+    module McpServer
+      TOOLS = [
+        Tools::DescribeApp,
+        Tools::RunRuby,
+        Tools::RunSql,
+        Tools::TailLogs,
+        Tools::ListModels,
+        Tools::LocateSource,
+        Tools::LookupDoc,
+        Tools::ListRoutes
+      ].freeze
+
+      module_function
+
+      def server
+        @server ||= build_server
+      end
+
+      def rack_app(allowed_hosts: Safety::RackMiddleware::DEFAULT_ALLOWED_HOSTS)
+        # The transport's own DNS-rebinding check requires same-origin (host:port);
+        # it is disabled because Safety::RackMiddleware enforces the localhost
+        # Origin allowlist, which accepts any port.
+        @rack_app ||= Safety::RackMiddleware.new(
+          ::MCP::Server::Transports::StreamableHTTPTransport.new(
+            server, stateless: true, enable_json_response: true, dns_rebinding_protection: false
+          ),
+          allowed_hosts: allowed_hosts
+        )
+      end
+
+      def reset!
+        @server = nil
+        @rack_app = nil
+      end
+
+      def build_server
+        srv = ::MCP::Server.new(
+          name: "hyperdrive",
+          title: "Rails Hyperdrive",
+          version: Rails::Hyperdrive::VERSION,
+          instructions: "Rails Hyperdrive MCP server. Prefer locate_source/list_models before guessing.",
+          tools: TOOLS,
+          resources: [Resources::StackProfile.resource, *Resources::Skill.installed_resources],
+          resource_templates: [Resources::Skill.template]
+        )
+
+        srv.resources_read_handler do |params|
+          uri = params[:uri] || params["uri"]
+          if uri == Resources::StackProfile::URI
+            Resources::StackProfile.read(params)
+          elsif uri.to_s.start_with?(Resources::Skill::URI_PREFIX)
+            Resources::Skill.read(params)
+          else
+            raise ::MCP::Server::RequestHandlerError.new(
+              "Resource not found: #{uri}", params, error_type: :invalid_params
+            )
+          end
+        end
+
+        srv
+      end
+    end
+  end
+end

data/lib/rails/hyperdrive/resources/skill.rb

@@ -0,0 +1,63 @@
+require "mcp"
+require "rails/hyperdrive/install_layout"
+
+module Rails
+  module Hyperdrive
+    module Resources
+      module Skill
+        URI_TEMPLATE = "hyperdrive://skills/{name}"
+        URI_PREFIX = "hyperdrive://skills/"
+        # Skill names follow the SKILL.md/.claude convention: lowercase letters,
+        # digits, hyphens. Anything else is rejected to prevent path traversal
+        # via `hyperdrive://skills/../../etc/passwd`.
+        NAME_PATTERN = /\A[a-z0-9][a-z0-9_\-]*\z/.freeze
+
+        module_function
+
+        def template
+          ::MCP::ResourceTemplate.new(
+            uri_template: URI_TEMPLATE,
+            name: "Installed skill",
+            description: "Markdown body of an installed #{InstallLayout::SKILLS_DIR}/<name>/SKILL.md",
+            mime_type: "text/markdown"
+          )
+        end
+
+        # Enumerated once at server build time, so skills installed by a fresh
+        # `hyperdrive:init` only appear after a dev-server restart.
+        def installed_resources
+          return [] unless defined?(::Rails) && ::Rails.respond_to?(:root) && ::Rails.root
+          skills_root = ::Rails.root.join(InstallLayout::SKILLS_DIR)
+          return [] unless Dir.exist?(skills_root)
+          Dir.glob(::Rails.root.join(InstallLayout.dest_for(:skill, "*")).to_s).sort.map do |path|
+            name = InstallLayout.installed_name(:skill, path)
+            next unless name.match?(NAME_PATTERN)
+            ::MCP::Resource.new(
+              uri: "#{URI_PREFIX}#{name}",
+              name: name,
+              description: "Skill: #{name}",
+              mime_type: "text/markdown"
+            )
+          end.compact
+        end
+
+        def read(params)
+          uri = params[:uri] || params["uri"]
+          name = uri.to_s.sub(URI_PREFIX, "")
+          unless name.match?(NAME_PATTERN)
+            raise ::MCP::Server::RequestHandlerError.new(
+              "Resource not found: #{uri}", params, error_type: :invalid_params
+            )
+          end
+          path = ::Rails.root.join(InstallLayout.dest_for(:skill, name))
+          unless File.exist?(path)
+            raise ::MCP::Server::RequestHandlerError.new(
+              "Resource not found: #{uri}", params, error_type: :invalid_params
+            )
+          end
+          [{ uri: uri, mimeType: "text/markdown", text: File.read(path) }]
+        end
+      end
+    end
+  end
+end

data/lib/rails/hyperdrive/resources/stack_profile.rb

@@ -0,0 +1,32 @@
+require "mcp"
+require "json"
+require_relative "../stack_profile"
+
+module Rails
+  module Hyperdrive
+    module Resources
+      module StackProfile
+        URI = "hyperdrive://stack-profile"
+
+        module_function
+
+        def resource
+          ::MCP::Resource.new(
+            uri: URI,
+            name: "Stack Profile",
+            description: "Parsed Gemfile.lock + categorization (rails, ruby, database, test, jobs, frontend, auth, authz, db_gems, gem_skills).",
+            mime_type: "application/json"
+          )
+        end
+
+        def read(_params)
+          [{
+            uri: URI,
+            mimeType: "application/json",
+            text: JSON.pretty_generate(Rails::Hyperdrive::StackProfile.current.to_h)
+          }]
+        end
+      end
+    end
+  end
+end

data/lib/rails/hyperdrive/safety/rack_middleware.rb

@@ -0,0 +1,54 @@
+require "rack"
+require "uri"
+require "json"
+
+module Rails
+  module Hyperdrive
+    module Safety
+      # Defense-in-depth gate for every request that hits the MCP transport.
+      class RackMiddleware
+        DEFAULT_ALLOWED_HOSTS = %w[localhost 127.0.0.1 [::1]].freeze
+
+        def initialize(app, allowed_hosts: DEFAULT_ALLOWED_HOSTS)
+          @app = app
+          @allowed_hosts = allowed_hosts
+        end
+
+        def call(env)
+          unless dev?
+            return forbid("hyperdrive is dev-only (Rails.env=#{rails_env})")
+          end
+
+          origin = env["HTTP_ORIGIN"]
+          if origin && !origin_allowed?(origin)
+            return forbid("origin not allowed: #{origin}")
+          end
+
+          @app.call(env)
+        end
+
+        private
+
+        def dev?
+          Rails::Hyperdrive.dev_mode?
+        end
+
+        def rails_env
+          defined?(::Rails) && ::Rails.respond_to?(:env) ? ::Rails.env : "unknown"
+        end
+
+        def origin_allowed?(origin)
+          host = URI.parse(origin).host
+          @allowed_hosts.include?(host)
+        rescue URI::InvalidURIError
+          false
+        end
+
+        def forbid(reason)
+          body = { error: "forbidden", reason: reason }.to_json
+          [403, { "content-type" => "application/json" }, [body]]
+        end
+      end
+    end
+  end
+end

data/lib/rails/hyperdrive/skill_template.rb

@@ -0,0 +1,52 @@
+require "erb"
+
+module Rails
+  module Hyperdrive
+    # Renders a skill's *.md.erb sources against the app's resolved bundle.
+    # The template binding is sealed: exactly three helpers over the resolved
+    # {gem name => Gem::Version} map, no app context, no arbitrary lookup.
+    module SkillTemplate
+      class Context
+        def initialize(resolved)
+          @resolved = resolved
+        end
+
+        def gem?(name, requirement = nil)
+          version = @resolved[name.to_s]
+          return false unless version
+          requirement.nil? || SkillTemplate.version_matches?(requirement, version)
+        end
+
+        def any_gem?(*names)
+          names.any? { |n| @resolved.key?(n.to_s) }
+        end
+
+        def gem_version(name)
+          version = @resolved[name.to_s]
+          version&.to_s
+        end
+
+        def template_binding
+          binding
+        end
+      end
+
+      module_function
+
+      # Errors (ERB SyntaxError included) propagate; the caller decides how to
+      # skip and warn.
+      def render(source, resolved:)
+        ERB.new(source, trim_mode: "-").result(Context.new(resolved).template_binding)
+      end
+
+      # Gem::Requirement.new does not parse a single comma-separated string, so
+      # such strings are split into separate constraints first.
+      def version_matches?(requirement_str, version)
+        parts = Array(requirement_str).flat_map { |s| s.is_a?(String) ? s.split(",").map(&:strip) : s }
+        Gem::Requirement.new(*parts).satisfied_by?(Gem::Version.new(version.to_s))
+      rescue ArgumentError
+        false
+      end
+    end
+  end
+end

data/lib/rails/hyperdrive/sql_safety.rb

@@ -0,0 +1,28 @@
+module Rails
+  module Hyperdrive
+    # Guardrail (not a sandbox) against an AI accidentally mutating the dev
+    # database. Rejects anything other than read-only statements at the regex
+    # level. A determined caller with `run_ruby` can trivially bypass it.
+    module SqlSafety
+      ALLOWED_LEADERS = /\A\s*(WITH\b.*?\bSELECT\b|SELECT\b|EXPLAIN\b|SHOW\b|PRAGMA\b)/im
+      FORBIDDEN_TOKEN = /\b(INSERT|UPDATE|DELETE|DROP|ALTER|TRUNCATE|CREATE|GRANT|REVOKE|REPLACE|MERGE|RENAME|VACUUM|ATTACH|DETACH)\b/i
+
+      class Error < StandardError; end
+
+      module_function
+
+      def assert_read_only!(sql)
+        raise Error, "empty SQL" if sql.nil? || sql.strip.empty?
+        unless sql =~ ALLOWED_LEADERS
+          raise Error, "only SELECT / WITH...SELECT / EXPLAIN / SHOW / PRAGMA are allowed"
+        end
+        # Second pass catches a mutation smuggled inside a CTE body
+        # (e.g. `WITH x AS (DELETE ...) SELECT ...`).
+        if sql =~ FORBIDDEN_TOKEN
+          raise Error, "forbidden token detected: #{Regexp.last_match(1)}"
+        end
+        true
+      end
+    end
+  end
+end

data/lib/rails/hyperdrive/stack_profile.rb

@@ -0,0 +1,176 @@
+require "bundler"
+require "yaml"
+require "digest"
+
+module Rails
+  module Hyperdrive
+    class StackProfile
+      CATEGORIES_PATH = File.expand_path("data/gem_categories.yml", __dir__)
+
+      class << self
+        def categories
+          @categories ||= YAML.load_file(CATEGORIES_PATH).each_with_object({}) do |(cat, gems), acc|
+            gems.each { |g| acc[g] = cat.to_sym }
+          end
+        end
+
+        def current
+          @current ||= from_lockfile(default_lockfile_path)
+        end
+
+        def reset!
+          @current = nil
+        end
+
+        def from_lockfile(path, app_root: nil)
+          new(path: path, app_root: app_root).tap(&:parse!)
+        end
+
+        def default_lockfile_path
+          if defined?(::Rails) && ::Rails.respond_to?(:root) && ::Rails.root
+            ::Rails.root.join("Gemfile.lock").to_s
+          else
+            File.expand_path("Gemfile.lock", Dir.pwd)
+          end
+        end
+      end
+
+      attr_reader :path, :data
+
+      def initialize(path:, app_root: nil)
+        @path = path
+        @app_root = app_root
+        @data = empty_profile
+      end
+
+      def parse!
+        unless File.exist?(@path)
+          @data = empty_profile.merge(error: "Gemfile.lock not found at #{@path}")
+          return self
+        end
+
+        contents = File.read(@path)
+        parser   = ::Bundler::LockfileParser.new(contents)
+        specs    = parser.specs.each_with_object({}) { |s, h| h[s.name] = s.version.to_s }
+
+        @data = {
+          rails:      rails_info(specs),
+          ruby:       ruby_info(parser),
+          database:   database_info(specs),
+          test:       bucket(specs, :test),
+          jobs:       bucket(specs, :jobs),
+          frontend:   frontend_info(specs),
+          auth:       bucket(specs, :auth),
+          authz:      bucket(specs, :authz),
+          db_gems:    bucket(specs, :db),
+          gem_skills: gem_skills_info
+        }
+        self
+      end
+
+      def to_h
+        @data
+      end
+
+      private
+
+      def empty_profile
+        {
+          rails: {}, ruby: {}, database: {},
+          test: [], jobs: [], frontend: [],
+          auth: [], authz: [], db_gems: [], gem_skills: []
+        }
+      end
+
+      def rails_info(specs)
+        version = specs["rails"] || specs["railties"]
+        return {} unless version
+        { version: version, major: version.to_s.split(".").first.to_i }
+      end
+
+      def ruby_info(parser)
+        version = parser.ruby_version || (RUBY_VERSION if defined?(RUBY_VERSION))
+        version ? { version: version.to_s.sub(/^ruby /, "") } : {}
+      end
+
+      # database.yml takes precedence: a Rails app can ship `pg` for a
+      # secondary store while running on sqlite3, and the declared adapter is
+      # what we want to report.
+      def database_info(specs)
+        if (yml_adapter = adapter_from_database_yml)
+          return { adapter: yml_adapter }
+        end
+        adapter = if specs["pg"] then "postgresql"
+        elsif specs["mysql2"] then "mysql2"
+        elsif specs["trilogy"] then "trilogy"
+        elsif specs["sqlite3"] then "sqlite3"
+        end
+        adapter ? { adapter: adapter } : {}
+      end
+
+      def adapter_from_database_yml
+        yml_path = database_yml_path
+        return nil unless yml_path && File.exist?(yml_path)
+        # ERB-rendered config is common; permissive parse keeps us out of the
+        # business of evaluating user code at generator time.
+        raw = File.read(yml_path)
+        raw = raw.gsub(/<%.*?%>/m, '""')
+        parsed = YAML.safe_load(raw, aliases: true) || {}
+        env = (defined?(::Rails) && ::Rails.respond_to?(:env) && ::Rails.env.to_s) || "development"
+        section = parsed[env] || parsed["development"]
+        return nil unless section.is_a?(Hash)
+        adapter = section["adapter"] || section.values.grep(Hash).map { |h| h["adapter"] }.compact.first
+        adapter&.to_s
+      rescue StandardError
+        nil
+      end
+
+      # An explicit app_root keeps the adapter resolvable with no Rails booted.
+      def database_yml_path
+        return File.join(@app_root.to_s, "config", "database.yml") if @app_root
+        return nil unless defined?(::Rails) && ::Rails.respond_to?(:root) && ::Rails.root
+        ::Rails.root.join("config", "database.yml").to_s
+      end
+
+      def bucket(specs, category)
+        gem_names = self.class.categories.select { |_, c| c == category }.keys
+        gem_names.filter_map do |name|
+          version = specs[name]
+          next unless version
+          { key: name.to_sym, version: version }
+        end
+      end
+
+      # Frontend gets a special shape because Hotwire is actually two gems.
+      def frontend_info(specs)
+        bucket(specs, :frontend).map do |entry|
+          if entry[:key] == :"turbo-rails" || entry[:key] == :"stimulus-rails"
+            turbo = specs["turbo-rails"]
+            stim  = specs["stimulus-rails"]
+            { key: :hotwire, versions: { turbo: turbo, stimulus: stim }.compact }
+          else
+            entry
+          end
+        end.uniq
+      end
+
+      # Loaded lazily and rescued broadly so StackProfile stays usable where
+      # Bundler is absent or refuses to resolve.
+      def gem_skills_info
+        require "rails/hyperdrive/bundler_artifact_discovery"
+        ::Rails::Hyperdrive::BundlerArtifactDiscovery.discover.select(&:skill?).map do |skill|
+          {
+            name: skill.name,
+            gem: skill.target_gem,
+            source: skill.source_gem,
+            version: skill.spec_version,
+            path: skill.path,
+            sha256: Digest::SHA256.hexdigest(skill.body.to_s)
+          }
+        end
+      rescue StandardError
+        []
+      end
+    end
+  end
+end

data/lib/rails/hyperdrive/tools/base.rb

@@ -0,0 +1,39 @@
+require "mcp"
+require "json"
+
+module Rails
+  module Hyperdrive
+    module Tools
+      class Base < ::MCP::Tool
+        class << self
+          def respond_text(text)
+            ::MCP::Tool::Response.new([{ type: "text", text: text.to_s }])
+          end
+
+          def respond_json(object)
+            respond_text(JSON.pretty_generate(object))
+          end
+
+          def respond_error(message)
+            ::MCP::Tool::Response.new(
+              [{ type: "text", text: message.to_s }],
+              error: true
+            )
+          end
+
+          # Defense in depth: the Rack middleware already gates the HTTP
+          # transport; this catches direct in-process invocations (specs, rake
+          # tasks) that bypass it.
+          def with_dev_guard
+            unless Rails::Hyperdrive.dev_mode?
+              return respond_error("hyperdrive tools are disabled outside Rails.env.development?")
+            end
+            yield
+          rescue => e
+            respond_error("#{e.class}: #{e.message}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rails/hyperdrive/tools/describe_app.rb

@@ -0,0 +1,21 @@
+require_relative "base"
+require_relative "../stack_profile"
+
+module Rails
+  module Hyperdrive
+    module Tools
+      class DescribeApp < Base
+        tool_name "describe_app"
+        description "Snapshot of Rails/Ruby/DB versions plus the full StackProfile (test, jobs, frontend, auth, authz, db_gems, gem_skills)."
+
+        input_schema(properties: {})
+
+        def self.call(server_context: nil)
+          with_dev_guard do
+            respond_json(Rails::Hyperdrive::StackProfile.current.to_h)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rails/hyperdrive/tools/list_models.rb

@@ -0,0 +1,76 @@
+require_relative "base"
+
+module Rails
+  module Hyperdrive
+    module Tools
+      class ListModels < Base
+        tool_name "list_models"
+        description "List Active Record model classes with their columns, validations, and associations. Eager-loads the app first."
+
+        input_schema(properties: {})
+
+        def self.call(server_context: nil)
+          with_dev_guard do
+            ::Rails.application.eager_load!
+            models = ActiveRecord::Base.descendants.reject(&:abstract_class?).sort_by(&:name)
+            described = models.map do |m|
+              describe(m)
+            rescue StandardError => e
+              # Collect per-model failures so one broken class doesn't blank out
+              # the whole listing.
+              { class: m.name, errors: ["#{e.class}: #{e.message}"] }
+            end
+            respond_json(described)
+          end
+        end
+
+        def self.describe(model)
+          {
+            class: model.name,
+            table: safe(model, :table_name),
+            columns: safe_columns(model),
+            validators: safe_validators(model),
+            associations: safe_associations(model)
+          }
+        end
+
+        def self.safe(model, method)
+          model.public_send(method)
+        rescue => e
+          "<error: #{e.class}: #{e.message}>"
+        end
+
+        def self.safe_columns(model)
+          return [] unless model.connected? || ActiveRecord::Base.connected?
+          model.columns.map { |c| { name: c.name, type: c.type.to_s, null: c.null, default: c.default } }
+        rescue => e
+          [{ error: "#{e.class}: #{e.message}" }]
+        end
+
+        def self.safe_validators(model)
+          model.validators.flat_map do |v|
+            v.attributes.map do |attr|
+              { attribute: attr.to_s, kind: v.kind.to_s, options: v.options.transform_values(&:to_s) }
+            end
+          end
+        rescue
+          []
+        end
+
+        def self.safe_associations(model)
+          model.reflect_on_all_associations.map do |a|
+            { name: a.name.to_s, macro: a.macro.to_s, class_name: safe_class_name(a) }
+          end
+        rescue
+          []
+        end
+
+        def self.safe_class_name(association)
+          association.class_name
+        rescue
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/rails/hyperdrive/tools/list_routes.rb

@@ -0,0 +1,33 @@
+require_relative "base"
+
+module Rails
+  module Hyperdrive
+    module Tools
+      class ListRoutes < Base
+        tool_name "list_routes"
+        description "List all routes: {verb, path, controller_action, name}."
+
+        input_schema(properties: {})
+
+        def self.call(server_context: nil)
+          with_dev_guard do
+            list = ::Rails.application.routes.routes.map do |r|
+              reqs = r.requirements
+              controller = reqs[:controller]
+              action     = reqs[:action]
+              # Engine mounts have no controller/action, so the pair is nil.
+              controller_action = (controller && action) ? "#{controller}##{action}" : nil
+              {
+                verb: r.verb.to_s,
+                path: r.path.spec.to_s.sub(/\(\.:format\)\z/, ""),
+                controller_action: controller_action,
+                name: r.name
+              }
+            end
+            respond_json(list)
+          end
+        end
+      end
+    end
+  end
+end