woods 1.1.0 → 1.3.0

data/lib/woods/console/eval_guard.rb

@@ -0,0 +1,319 @@
+# frozen_string_literal: true
+
+require_relative '../ast/parser'
+
+# @see Woods
+module Woods
+  class Error < StandardError; end unless defined?(Woods::Error)
+
+  module Console
+    # Raised when EvalGuard rejects a `console_eval` payload.
+    class ForbiddenExpressionError < Woods::Error; end
+
+    # Parse-time refusal layer for `console_eval`.
+    #
+    # ## Reachability (v0.2)
+    #
+    # EvalGuard is the first of five controls on the embedded `console_eval`
+    # opt-in path. `EmbeddedExecutor#handle_eval` calls `check!` before
+    # anything else — ahead of the Confirmation prompt, the SafeContext
+    # rollback, the timeout, and the audit log. When the opt-in is off
+    # (the default), `refusal_for('eval')` still short-circuits with the
+    # `eval_disabled` payload and this guard is not reached. See
+    # docs/CONSOLE_MCP_SETUP.md "console_eval opt-in" and backlog B-053.
+    #
+    # Bridge-process mode (in development) will call the same guard before
+    # shipping the payload to the remote Rails worker.
+    #
+    # ## Behaviour
+    #
+    # Walks the normalized {Woods::Ast::Parser} tree of the proposed Ruby
+    # snippet and refuses any expression that reaches a known credential or
+    # reflection escape — so an LLM-generated `Rails.application.credentials
+    # .stripe.secret_key` or a reflection escape is rejected before the bridge
+    # ever sees it.
+    #
+    # This is defense in depth, not the only line: the bridge process must
+    # re-enforce the same rules at execution time. The gem-side check exists
+    # so the LLM sees a fast, visible refusal instead of relying on the host
+    # app's bridge configuration.
+    #
+    # @example
+    #   EvalGuard.check!('User.count')                                # => true
+    #   EvalGuard.check!('Rails.application.credentials.stripe.key')  # raises
+    #
+    class EvalGuard # rubocop:disable Metrics/ClassLength
+      # Receivers/calls whose presence in the AST is always a refusal.
+      # Each entry is matched against the dotted source text of every send
+      # node's receiver (and qualified call name) — so a denial of
+      # `Rails.application.credentials` catches every chained access through it
+      # (e.g. `Rails.application.credentials.dig(:stripe)`).
+      DENIED_CALL_CHAINS = %w[
+        Rails.application.credentials
+        Rails.application.secrets
+        Rails::Secrets
+        Devise.secret_key
+      ].freeze
+
+      # Constants whose bare reference (or use as a receiver) is denied.
+      #
+      # - `ENV` — reads host secrets as a string-keyed hash.
+      # - Threading: `Thread`, `Fiber`, `Ractor`, `Process` — concurrent
+      #   execution escapes the rolled-back transaction (the spawned block
+      #   leases its own connection outside SafeContext's tx).
+      # - Deserialization: `Marshal`, `YAML`, `Psych` — unsafe load paths
+      #   can execute arbitrary code during object instantiation.
+      # - Network: `Net`, `Socket`, `TCPSocket`, `UDPSocket`, `URI`,
+      #   `OpenURI`, `Resolv`, `Faraday`, `HTTP` — every HTTP/network egress
+      #   point available in a standard Rails install.
+      # - File I/O: `File`, `FileUtils`, `IO`, `Dir`, `Pathname`,
+      #   `Tempfile`, `StringIO`, `BasicObject` — broad filesystem access.
+      # - Kernel-ish: `Kernel`, `Object`, `ObjectSpace`, `GC`,
+      #   `RubyVM`, `TracePoint`, `Gem`, `Bundler`.
+      # File/IO/Pathname are intentionally NOT in this list — legitimate
+      # non-credential file reads are a core use case. Credential-path
+      # access is handled by CREDENTIAL_FILE_READERS below, and shell-exec
+      # attempts (`Kernel.open("|cmd")`, backticks, `%x{}`) are caught by
+      # the backtick textual check in #check! and the DENIED_REFLECTION
+      # entries for `system`/`exec`/`popen`/etc.
+      DENIED_CONSTANTS = %w[
+        ENV
+        Thread Fiber Ractor Process Mutex ConditionVariable Queue SizedQueue
+        Marshal YAML Psych
+        Net Socket TCPSocket UDPSocket UNIXSocket URI OpenURI Resolv Faraday HTTP
+        ObjectSpace GC RubyVM TracePoint
+        Gem Bundler
+      ].freeze
+
+      # Method names that escape the AST sandbox regardless of receiver.
+      #
+      # Covers, in order:
+      # - Eval family: the classic `eval`/`instance_eval`/`class_eval`/
+      #   `module_eval` plus `binding` (which enables reconstructing an eval
+      #   in the caller's scope).
+      # - Dynamic dispatch: `send` / `public_send` / `__send__` / `method` /
+      #   `public_method` (returns a callable, indirect dispatch) and the
+      #   `const_get` / `const_set` / `remove_const` / `define_method` /
+      #   `define_singleton_method` / `alias_method` / `undef_method` /
+      #   `remove_method` / `method_defined?` / `prepend` / `include_module`
+      #   reflection family.
+      # - State mutation: `instance_variable_set` / `instance_variable_get`,
+      #   `class_variable_set` / `class_variable_get` / `freeze` / `taint`.
+      # - Object-space escapes: `_id2ref`, `each_object`, `const_source_location`.
+      # - System / process: `system`, `exec`, `spawn`, `fork`, `popen`, `%x{}`
+      #   (AST method name `backtick` / xstr) so they can't be invoked
+      #   implicitly.
+      # - File / IO: `open` (bare Kernel#open — the File-specific reader is
+      #   handled separately via CREDENTIAL_FILE_READERS, but the bare
+      #   `Kernel.open("|shell-command")` form is how most shellshock-style
+      #   escapes slip through).
+      # - Network: `URI.open` (when called as `open` on URI, the AST method
+      #   name is `open` so the string match above catches it). HTTP / Socket
+      #   constants are denied separately via DENIED_CONSTANTS.
+      # - Loader: `load`, `require`, `require_relative`, `autoload`.
+      # - Unsafe deserialization: `unsafe_load` / `_load` (Marshal.load and
+      #   YAML.load are denied via DENIED_CONSTANTS + method gate below).
+      # - Threading escapes from SafeContext's rollback: `new` on Thread /
+      #   Fiber / Process is denied via DENIED_CONSTANTS so the
+      #   {Kernel.fork, Thread.new} pair can't slip past.
+      DENIED_REFLECTION = %w[
+        eval instance_eval class_eval module_eval binding
+        instance_exec class_exec module_exec
+        send public_send __send__ method public_method
+        const_get const_set remove_const define_method define_singleton_method
+        alias_method undef_method remove_method method_defined? singleton_method
+        instance_variable_get instance_variable_set
+        class_variable_get class_variable_set
+        _id2ref each_object const_source_location instance_variables
+        prepend include_module
+        system exec spawn fork popen popen2 popen2e popen3 backtick
+        require require_relative autoload
+        unsafe_load _load
+        taint untaint
+      ].freeze
+
+      # Receivers + method-name pairs that read credential files from disk.
+      # Triggers when the receiver matches AND any literal argument source
+      # contains a known credential path fragment. `Pathname.new(...)` is
+      # included so `Pathname.new(...).read` chains are caught at construction.
+      #
+      # `open` is included for File and IO to catch chained patterns like
+      # `File.open("config/master.key").read` — the inner `File.open(path)`
+      # node is visited by `scan_send_nodes` and refused here before the
+      # outer `.read` call is even examined (PR #34 review medium #3).
+      CREDENTIAL_FILE_READERS = {
+        'File' => %w[read binread readlines open],
+        'IO' => %w[read binread readlines open],
+        'Pathname' => %w[read binread new open]
+      }.freeze
+      CREDENTIAL_PATH_HINTS = %w[
+        master.key credentials.yml.enc credentials/
+        secrets.yml secrets.yml.enc
+      ].freeze
+
+      class << self
+        # @param code [String] Ruby source proposed for `console_eval`.
+        # @raise [ForbiddenExpressionError] on any denial or parse failure.
+        def check!(code)
+          new.check!(code)
+        end
+      end
+
+      def initialize(parser: Woods::Ast::Parser.new)
+        @parser = parser
+      end
+
+      # Textual token for class-variable (`@@foo`) and global-variable
+      # (`$foo`) writes. {Woods::Ast::Parser} doesn't normalize cvasgn /
+      # gvasgn to a dedicated node type, so we catch them at the source
+      # level the same way shell-execution literals are caught. Instance-
+      # variable writes (`@foo`) ARE normalized to `:ivasgn` and are
+      # refused via the AST walk — see {#scan_assignment_nodes}.
+      #
+      # Covers plain assignment (`=`) AND op-assign forms (`+=`, `-=`,
+      # `*=`, `/=`, `%=`, `**=`, `<<=`, `>>=`, `|=`, `&=`, `^=`, `||=`,
+      # `&&=`) — all of which are writes. Excludes the non-assignment
+      # `==`, `=~`, `=>` forms via the trailing negative lookahead.
+      OP_ASSIGN_SUFFIX = %r{(?:\|\|?|&&?|<<|>>|\*\*?|[-+/%^])?=(?![=~>])}
+      private_constant :OP_ASSIGN_SUFFIX
+
+      CLASS_OR_GLOBAL_VAR_ASSIGNMENT = /
+        (?:^|[^\w])         # not mid-identifier
+        (@@\w+|\$\w+)       # @@cvar or $gvar
+        \s*
+        #{OP_ASSIGN_SUFFIX.source}
+      /x
+      private_constant :CLASS_OR_GLOBAL_VAR_ASSIGNMENT
+
+      # @param code [String]
+      # @raise [ForbiddenExpressionError]
+      def check!(code)
+        raise ForbiddenExpressionError, 'payload is empty' if code.nil? || code.strip.empty?
+
+        # Fail-safe textual check for backtick literals (` `cmd` ` and
+        # `%x{cmd}`) — the AST flavor of these is `:xstr`/`:xstr_heredoc`,
+        # which {Woods::Ast::Parser} may normalize differently across
+        # Prism/parser-gem backends. A source-level refusal is both cheap
+        # and impossible to evade via AST normalization.
+        if code.include?('`') || code =~ /%x[{<|!@#(\[]/
+          raise ForbiddenExpressionError, 'payload contains a shell-execution literal (backtick or %x)'
+        end
+
+        refuse_class_or_global_var_assignment!(code)
+
+        tree = parse_or_refuse(code)
+        scan_send_nodes(tree)
+        scan_const_nodes(tree)
+        scan_assignment_nodes(tree)
+      end
+
+      private
+
+      def parse_or_refuse(code)
+        @parser.parse(code)
+      rescue Woods::ExtractionError => e
+        raise ForbiddenExpressionError, "payload could not be parsed safely: #{e.message}"
+      end
+
+      def scan_send_nodes(tree)
+        tree.find_all(:send).each do |node|
+          refuse_reflection!(node)
+          refuse_denied_constant_receiver!(node)
+          refuse_denied_constant_in_args!(node)
+          refuse_denied_call_chain!(node)
+          refuse_credential_file_read!(node)
+        end
+      end
+
+      def scan_const_nodes(tree)
+        tree.find_all(:const).each do |node|
+          if DENIED_CONSTANTS.include?(node.method_name.to_s)
+            raise ForbiddenExpressionError,
+                  "payload references denied constant #{node.method_name}"
+          end
+        end
+      end
+
+      # Refuse `@ivar = …` writes. The embedded `console_eval` path runs
+      # inside a throwaway receiver, so a payload setting `@audit_logger
+      # = nil` would only affect the throwaway — but we deny the syntactic
+      # form anyway as defense-in-depth for any future caller that might
+      # hand EvalGuard a payload evaluated in a non-isolated binding.
+      def scan_assignment_nodes(tree)
+        node = tree.find_all(:ivasgn).first
+        return unless node
+
+        raise ForbiddenExpressionError,
+              "payload writes to instance variable #{node.method_name}"
+      end
+
+      # Textual refusal for `@@cvar = …` / `$gvar = …`. The parser
+      # normalization doesn't distinguish cvasgn / gvasgn today; the
+      # source-level scan is the same shape as the backtick check above.
+      def refuse_class_or_global_var_assignment!(code)
+        return unless (match = CLASS_OR_GLOBAL_VAR_ASSIGNMENT.match(code))
+
+        raise ForbiddenExpressionError,
+              "payload writes to #{match[1]} (class/global variable assignment)"
+      end
+
+      def refuse_reflection!(node)
+        return unless DENIED_REFLECTION.include?(node.method_name.to_s)
+
+        raise ForbiddenExpressionError,
+              "payload calls reflection method `#{node.method_name}`"
+      end
+
+      def refuse_denied_constant_receiver!(node)
+        return unless node.receiver && DENIED_CONSTANTS.include?(node.receiver.to_s)
+
+        raise ForbiddenExpressionError,
+              "payload references denied constant #{node.receiver}"
+      end
+
+      # Catches `puts ENV` — Prism flattens method-call argument nodes into
+      # source-text strings, so a bare ENV passed as an argument never appears
+      # as its own :const node. Match it as a whole-word token in arg text.
+      def refuse_denied_constant_in_args!(node)
+        DENIED_CONSTANTS.each do |const|
+          pattern = /\b#{Regexp.escape(const)}\b/
+          next unless Array(node.arguments).any? { |arg| arg.to_s.match?(pattern) }
+
+          raise ForbiddenExpressionError,
+                "payload references denied constant #{const}"
+        end
+      end
+
+      def refuse_denied_call_chain!(node)
+        qualified = qualified_call(node)
+        DENIED_CALL_CHAINS.each do |chain|
+          next unless qualified.include?(chain)
+
+          raise ForbiddenExpressionError,
+                "payload references denied call chain `#{chain}`"
+        end
+      end
+
+      def refuse_credential_file_read!(node)
+        receiver = node.receiver.to_s
+        return unless CREDENTIAL_FILE_READERS.key?(receiver)
+        return unless CREDENTIAL_FILE_READERS.fetch(receiver).include?(node.method_name.to_s)
+        return unless Array(node.arguments).any? { |arg| credential_path?(arg) }
+
+        raise ForbiddenExpressionError,
+              "payload reads credential file via `#{receiver}.#{node.method_name}`"
+      end
+
+      def qualified_call(node)
+        return node.method_name.to_s unless node.receiver
+
+        "#{node.receiver}.#{node.method_name}"
+      end
+
+      def credential_path?(arg_text)
+        text = arg_text.to_s
+        CREDENTIAL_PATH_HINTS.any? { |hint| text.include?(hint) }
+      end
+    end
+  end
+end

data/lib/woods/console/model_validator.rb

@@ -54,11 +54,9 @@ module Woods
       #
       # @param model_name [String]
       # @param column_names [Array<String>]
-      # @return [true]
       # @raise [ValidationError] if any column is unknown
-      def validate_columns!(model_name, column_names) # rubocop:disable Naming/PredicateMethod
+      def validate_columns!(model_name, column_names)
         column_names.each { |col| validate_column!(model_name, col) }
-        true
       end
 
       # List all known model names.

data/lib/woods/console/rack_middleware.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'json'
+require 'woods/observability/structured_logger'
 
 module Woods
   module Console
@@ -10,78 +11,233 @@ module Woods
     # and all models are loaded. Uses ActiveRecord connection pool for thread
     # safety under Puma.
     #
-    # @example In config/application.rb or an initializer:
+    # == Basic setup (Tier 1 tools only)
+    #
+    # Add to config/application.rb or an initializer:
+    #
     #   config.middleware.use Woods::Console::RackMiddleware, path: '/mcp/console'
     #
+    # This mounts 31 console tools at /mcp/console. By default, console_sql and
+    # console_query are blocked in embedded mode and return an "unsupported" error
+    # pointing users to enable the flag.
+    #
+    # == Enabling the feature
+    #
+    # The Console MCP is disabled by default. Enable it in your Woods initializer:
+    #
+    #   Woods.configure do |config|
+    #     config.console_mcp_enabled = true
+    #     config.console_blocked_tables = %w[authorizations credentials]
+    #     config.console_redacted_columns = %w[api_token password_digest]
+    #   end
+    #
+    # With the flag off, requests to the mounted path return 410 Gone so
+    # operators can see the endpoint exists but is gated. See
+    # docs/CONSOLE_MCP_SETUP.md for the full security posture (blocked tables,
+    # credential scanner, column/EAV redaction, SafeContext rollback).
+    #
+    # == Enabling read tools (console_sql + console_query)
+    #
+    # Set embedded_read_tools: true to unlock the sql and query tools:
+    #
+    #   # config/initializers/woods_console.rb
+    #   Rails.application.config.middleware.use \
+    #     Woods::Console::RackMiddleware,
+    #     path: '/mcp/console',
+    #     embedded_read_tools: true
+    #
+    # Security posture with embedded_read_tools: true:
+    #
+    # 1. SqlValidator denylist — console_sql rejects INSERT/UPDATE/DELETE/DROP/TRUNCATE/
+    #    ALTER/CREATE/REPLACE and similar DML/DDL at the string level before any database
+    #    interaction. Only SELECT and WITH...SELECT are allowed.
+    #
+    # 2. SafeContext rollback — every request (including console_query) runs inside
+    #    a database transaction that is always rolled back on completion. Even if a
+    #    query somehow mutated state (e.g. a function with side effects), the rollback
+    #    ensures nothing persists.
+    #
+    # 3. Per-request connection pooling — each HTTP request draws a connection from
+    #    ActiveRecord::Base's pool and returns it after the response. No shared
+    #    mutable state leaks between requests.
+    #
+    # These three layers make embedded_read_tools: true safe for read-only workloads.
+    # If your threat model requires stricter isolation, use the bridge mode instead
+    # (docs/CONSOLE_MCP_SETUP.md) which runs the executor in a separate process.
+    #
     class RackMiddleware
       # @param app [#call] The next Rack app in the middleware stack
       # @param path [String] URL path to mount the MCP endpoint (default: '/mcp/console')
       # @param embedded_read_tools [Boolean] Enable sql/query tools in embedded mode (default: false)
-      def initialize(app, path: '/mcp/console', embedded_read_tools: false)
+      # @param unsafe_eval_confirmation [Confirmation, nil] Approval callback for the
+      #   `console_eval` opt-in. Required when `WOODS_CONSOLE_UNSAFE_EVAL=true` (or
+      #   `config.console_unsafe_eval_enabled = true`); the server refuses to boot
+      #   without it. Takes precedence over `config.console_unsafe_eval_confirmation`.
+      # @param unsafe_eval_audit_log_path [String, Pathname, nil] JSONL audit log
+      #   path for every `console_eval` run. Required on the opt-in path. Takes
+      #   precedence over `config.console_unsafe_eval_audit_log_path`.
+      def initialize(app, path: '/mcp/console', embedded_read_tools: false,
+                     unsafe_eval_confirmation: nil, unsafe_eval_audit_log_path: nil)
         @app = app
         @path = path
         @embedded_read_tools = embedded_read_tools
+        @unsafe_eval_confirmation = unsafe_eval_confirmation
+        @unsafe_eval_audit_log_path = unsafe_eval_audit_log_path
         @mutex = Mutex.new
         @transport = nil
       end
 
+      DISABLED_BODY = JSON.generate(
+        error: 'woods_console_disabled',
+        message: 'Woods Console MCP is disabled. Set ' \
+                 'Woods.configuration.console_mcp_enabled = true to enable. ' \
+                 'See docs/CONSOLE_MCP_SETUP.md for the full security posture.'
+      ).freeze
+
       # Rack interface — intercepts requests at the configured path.
       #
+      # Returns 410 Gone when Woods.configuration.console_mcp_enabled is false
+      # (the default). This keeps the middleware inert on hosts that have
+      # mounted it but not yet opted into the feature. All other requests at
+      # non-matching paths pass through to the wrapped app unchanged.
+      #
       # @param env [Hash] Rack environment
       # @return [Array] Rack response triple
       def call(env)
         return @app.call(env) unless env['PATH_INFO'].start_with?(@path)
+        return [410, { 'content-type' => 'application/json' }, [DISABLED_BODY]] unless enabled?
 
-        transport = ensure_transport
-        request = Rack::Request.new(env)
-        transport.handle_request(request)
+        ensure_transport.handle_request(Rack::Request.new(env))
       end
 
       private
 
+      def enabled?
+        Woods.configuration.console_mcp_enabled
+      end
+
       # Thread-safe lazy initialization of the MCP server and transport.
       #
-      # @return [MCP::Server::Transports::StreamableHTTPTransport]
-      def ensure_transport # rubocop:disable Metrics/MethodLength
+      # @return [::MCP::Server::Transports::StreamableHTTPTransport]
+      def ensure_transport
         return @transport if @transport
 
         @mutex.synchronize do
           return @transport if @transport
 
-          require 'woods/console/server'
+          check_blocked_tables_config!
 
+          require 'woods/console/server'
           Rails.application.eager_load!
 
-          registry = ActiveRecord::Base.descendants.each_with_object({}) do |model, hash|
-            next if model.abstract_class?
-            next unless model.table_exists?
+          server = build_embedded_server
+          @transport = ::MCP::Server::Transports::StreamableHTTPTransport.new(server)
+          server.transport = @transport
+          @transport
+        end
+      end
+
+      # Emit a prominent warning (or raise in production) when the Console MCP
+      # is enabled but no tables are blocked. An empty block list means Layer 1
+      # of the defense stack is fully inactive — every table in the database is
+      # reachable via console_sql, console_query, and the model tools.
+      #
+      # Remediation:
+      #   Woods.configure { |c| c.console_blocked_tables =
+      #     Woods::DEFAULT_CONSOLE_BLOCKED_TABLES + %w[your_sensitive_table] }
+      #
+      # @raise [Woods::ConfigurationError] in production environments
+      def check_blocked_tables_config!
+        return unless Woods.configuration.console_blocked_tables.empty?
 
-            hash[model.name] = model.column_names
-          rescue StandardError
-            next
-          end
+        message =
+          '[Woods Console] console_blocked_tables is empty — Layer 1 (table gate) is INACTIVE. ' \
+          'All tables are reachable via the Console MCP. ' \
+          'Set console_blocked_tables in your Woods initializer to restrict access. ' \
+          'Example: Woods.configure { |c| c.console_blocked_tables = ' \
+          'Woods::DEFAULT_CONSOLE_BLOCKED_TABLES + %w[your_table] }'
 
-          validator = ModelValidator.new(registry: registry)
+        raise Woods::ConfigurationError, message if defined?(Rails) && Rails.env.production?
 
-          config = Woods.configuration
-          redacted = Array(config.console_redacted_columns)
+        warn message
+      end
 
-          # Each HTTP request gets its own connection from the pool.
-          # SafeContext wraps that connection in a rolled-back transaction.
-          safe_context = SafeContext.new(connection: ActiveRecord::Base.connection)
+      # Build the embedded MCP server. SafeContext is given the writing
+      # connection pool (not a connection) so each request leases a fresh
+      # connection via `pool.with_connection { ... }` and returns it to the
+      # pool when the rolled-back transaction completes. Capturing a
+      # connection at build time would leak it out of its lease and pin it
+      # for the lifetime of the process.
+      #
+      # Multi-DB / sharded hosts are still served from the writing pool
+      # only — extending SafeContext to route per role/shard is tracked as
+      # `WOODS-CONSOLE-PERREQ-CONN`.
+      def build_embedded_server
+        config = Woods.configuration
+        introspection = build_model_introspection
+        Server.build_embedded(
+          model_validator: ModelValidator.new(registry: introspection[:registry]),
+          safe_context: SafeContext.new(pool: ActiveRecord::Base.connection_pool),
+          redacted_columns: Array(config&.console_redacted_columns),
+          redacted_key_values: Array(config&.console_redacted_key_values),
+          read_tools_enabled: @embedded_read_tools,
+          model_tables: introspection[:tables],
+          model_reflections: introspection[:reflections],
+          unsafe_eval_confirmation: @unsafe_eval_confirmation,
+          unsafe_eval_audit_log_path: @unsafe_eval_audit_log_path
+        )
+      end
 
-          server = Server.build_embedded(
-            model_validator: validator,
-            safe_context: safe_context,
-            redacted_columns: redacted,
-            read_tools_enabled: @embedded_read_tools
+      # Walk ActiveRecord::Base.descendants once and collect the registry,
+      # table map, and reflection map in a single pass. Models that raise
+      # during introspection are silently skipped — same semantics as the
+      # three separate methods this replaces.
+      #
+      # Map every model to its association-name → target-table registry so
+      # TableGate can resolve `joins:` / `association:` arguments before the
+      # executor loads data. Polymorphic associations and anything that
+      # raises during reflection are skipped gracefully.
+      #
+      # @return [Hash] frozen hash with keys :registry, :tables, :reflections
+      def build_model_introspection
+        registry = {}
+        tables = {}
+        reflections = {}
+
+        ActiveRecord::Base.descendants.each do |model|
+          next if model.abstract_class?
+          next unless model.table_exists?
+
+          registry[model.name] = model.column_names
+          tables[model.name] = model.table_name
+          reflections[model.name] = reflections_for(model)
+        rescue StandardError => e
+          structured_logger.debug(
+            'console.model_introspection.skipped',
+            model: model.name,
+            error_class: e.class.name,
+            error_message: e.message
           )
+          next
+        end
 
-          @transport = MCP::Server::Transports::StreamableHTTPTransport.new(server)
-          server.transport = @transport
-          @transport
+        { registry: registry, tables: tables, reflections: reflections }.freeze
+      end
+
+      def reflections_for(model)
+        model.reflect_on_all_associations.each_with_object({}) do |reflection, assoc_map|
+          next if reflection.polymorphic?
+
+          klass = reflection.klass
+          assoc_map[reflection.name.to_s] = klass.table_name if klass.respond_to?(:table_name)
+        rescue StandardError
+          next
         end
       end
+
+      def structured_logger
+        @structured_logger ||= Woods::Observability::StructuredLogger.new
+      end
     end
   end
 end