rails-ai-bridge 3.5.1 → 3.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 86847cb1d8613336bb1538fdde0c64461dcc69d2423b48939629695f40c99688
-  data.tar.gz: 65d9c1a4f11b3edc80a077e66c41e339ca845e4d10993d63cddef79be7ef9c5d
+  metadata.gz: 87f66a2c3254515e628ba04cac7fcda527bda86254df738f3384f28ccad5fcdf
+  data.tar.gz: 6bc9b66810b8c5bedd1526a3683b13530a46c1c5b61ba7db89288544d61bce20
 SHA512:
-  metadata.gz: c6ae4378aa2f3321b0753fb7e111a4d6777bd4de63e5ade3bcf38047affac48ce86630490dcacd33610021f299833bc5d7dd24f9dc238614f60786d8fac42ea4
-  data.tar.gz: 22caf59cc05827c7a5824f17c2dd1a5715b8ba62b70930ef300835bdbdc96506bdae1f2ec8590391272576c097363b45debb605f195e0e7c7b43c227f8a75289
+  metadata.gz: ae624883e2d08b61bd76d178b52d7067aefd611a1fc6e6f760b7f07361b7acbe877b2ce3f5984b2b6c9d0c74b7376c522cc8065fdf25a8cc8c78660a95583c18
+  data.tar.gz: 8cc300bb5f6e4d9669e8de9313eca2c4e5cd0c4a7ce336c2cec7bd5c69665df2580d3864536aef092cc22c16ca775909d26c40c372b5bc065577f567836dc149

data/CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.5.2]
+
+### Security
+
+- **HTTP MCP unauthenticated boot warning** (#60/#81) — the standalone HTTP MCP server now prints a one-time stderr warning when it boots in a non-production environment without an authentication strategy, making the default open behavior visible.
+- **Pluggable / distributed rate limiting** (#69/#80) — `config.mcp.rate_limiter` accepts any object implementing `allow?(ip)` or `call(ip)`, enabling shared backends such as Redis or `Rails.cache`. A built-in `Mcp::CacheRateLimiter` is provided for multi-process Puma deployments.
+- **Skill pack lockfile verification** (#65/#84) — `config/rails_ai_bridge/directory.lock` records the expected git commit SHA for every remote skill pack. `PackResolver` compares the cloned HEAD against the lockfile and fails closed on mismatch. Generate or update the lockfile with `rails ai:registry:lockfile`. Verification mode is configurable via `config.registry.lockfile_verification` (`:strict`, `:warn`, `:disabled`).
+- **Security documentation** (#61/#62/#82/#83) — added distributed rate-limiting guidance, a stdio transport threat model, and operational hardening recommendations.
+
+### Added
+
+- **CORS support for HTTP MCP** (#63/#76) — `config.mcp.cors_origins` controls `Access-Control-Allow-Origin` headers for the MCP HTTP endpoint; `['*']` or a list of exact origins is supported.
+- **JSON output for MCP tools** (#68/#77) — `rails_get_routes` and `rails_get_model_details` now accept `format: 'json'` for programmatic clients.
+- **`authorize` lambda logging** (#64/#75) — explicit denies and lambda exceptions on the HTTP MCP path are now logged and emitted through `Mcp::HttpStructuredLog`.
+- **`bundler-audit` CI job** (#74/#78) — the GitHub Actions workflow now runs `bundle-audit update && bundle-audit check` to catch known vulnerable dependencies.
+- **MCP tool result caching** (#71/#79) — opt-in TTL-based cache keyed by tool name + SHA256 fingerprint of arguments. Enable with `config.mcp.tool_result_cache_ttl` (default `0`).
+- **ActiveSupport::Notifications hooks** (#72/#85) — emits `rails_ai_bridge.tool.call`, `rails_ai_bridge.tool.result_cache_hit/miss`, `rails_ai_bridge.auth.success/failure`, and `rails_ai_bridge.rate_limit.hit` events.
+- **Rails 8.1+ introspection signals** (#73/#86) — `GemRegistry` now recognizes `mission_control-jobs`; `ConfigIntrospector` reports `queue_adapter` and `cable_adapter`; `AuthIntrospector` surfaces Rails 8 generator patterns (`authentication_concern`, `generates_token_for`, `normalizes`).
+
+### Changed
+
+- **Summary-first defaults** (#70/#87) — `rails_get_schema` and `rails_get_model_details` now default to `detail: 'summary'` when listing, reducing the chance of oversized tool responses. Callers can still opt into `standard` or `full` and use filters for specific tables/models.
+
+### Tests
+
+- **Total: 2157 examples, 0 failures, 94.34% line coverage**.
+
 ## [3.5.1]
 
 ### Security

data/SECURITY.md

@@ -85,6 +85,7 @@ see **[docs/mcp-security.md](docs/mcp-security.md)**.
 ## Operational Security Guidance
 
 - Prefer **stdio** transport for local development and AI-assisted editing.
+  See [docs/mcp-security.md](docs/mcp-security.md) for the stdio threat model.
 - If you enable HTTP transport, keep it bound to `127.0.0.1` unless you add your
   own network isolation and authentication controls.
 - Do **not** expose `auto_mount` on public or shared production surfaces without an explicit threat model review.

data/docs/mcp-security.md

@@ -10,10 +10,41 @@ A valid Bearer token (or JWT accepted by your decoder) grants access to read-onl
 
 By default, HTTP MCP allows anonymous access when no auth strategy is configured (backward compatible for local development). For servers reachable beyond localhost, set `config.mcp.require_http_auth = true` so unconfigured deployments return `401`, or configure `http_mcp_token`, `mcp_token_resolver`, or `mcp_jwt_decoder`. In production, also use `validate_http_mcp_server_in_production!` / `require_auth_in_production` as documented in the main README.
 
+In non-production environments, the standalone HTTP MCP server prints a one-time stderr warning when it starts without authentication to make the default behavior visible.
+
 ## Rate limiting and proxies
 
 Built-in rate limiting keys off the Rack request IP. Behind reverse proxies, configure Rails `trusted_proxies` so `request.ip` reflects the real client; otherwise limits may apply to the wrong address or be bypassed.
 
+### Single-process deployments
+
+The default in-memory limiter works for one Puma worker or a single-process server. Configure the ceiling and window via `config.mcp.rate_limit_max_requests` and `config.mcp.rate_limit_window_seconds`.
+
+### Multi-process or multi-host deployments
+
+The default in-memory limiter is not shared across Puma workers or hosts. For distributed deployments, plug in `RailsAiBridge::Mcp::CacheRateLimiter`, which uses `Rails.cache` (Redis, Memcached, etc.) as the shared counter backend:
+
+```ruby
+RailsAiBridge.configure do |config|
+  config.mcp.rate_limiter = RailsAiBridge::Mcp::CacheRateLimiter.new(
+    max_requests: 300,
+    window_seconds: 60,
+    cache: Rails.cache,
+    key_prefix: "rab:rl"
+  )
+end
+```
+
+Alternatively, use `Rack::Attack` in front of the MCP endpoint for centralized, proxy-aware throttling:
+
+```ruby
+class Rack::Attack
+  throttle("mcp/ip", limit: 300, period: 60) do |request|
+    request.ip if request.path == "/mcp"
+  end
+end
+```
+
 ## Optional authorization after auth
 
 `config.mcp.authorize` can return false to issue `403` for otherwise valid tokens (e.g. tenant or role checks).
@@ -22,6 +53,21 @@ Built-in rate limiting keys off the Rack request IP. Behind reverse proxies, con
 
 The stdio MCP server has no Bearer layer; anyone who can run the process can use the tools. Use isolated users or containers if multiple tenants share a host.
 
+### Threat model
+
+| Assumption | Implication |
+|------------|-------------|
+| The host operating system controls who can execute `rails ai:serve`. | Anyone with shell access to the Rails app can invoke every `rails_*` MCP tool and read the returned context. |
+| The stdio transport is local to the process. | Network attackers cannot reach stdio directly, but a compromised local account or shared development container bypasses this boundary. |
+| AI clients run with the same privileges as the user who launched them. | A malicious or misconfigured client can exfiltrate schema, routes, source code, and any file the user can read. |
+
+### Recommendations
+
+- Run MCP-enabled Rails processes under dedicated, least-privilege OS accounts.
+- In shared development containers or CI runners, avoid mixing users who should not see each other's application context.
+- Do not mount sensitive credentials files or SSH keys into containers that run the MCP server unless those tools genuinely need them.
+- Prefer HTTP MCP with authentication when multiple users or services share a host and need access controls beyond the OS.
+
 ## See also
 
 - [SECURITY.md](../SECURITY.md) — reporting vulnerabilities and design summary

data/docs/skill-registry-guide.md

@@ -154,6 +154,41 @@ When `ref` is set, rails-ai-bridge runs `git checkout <ref>` after cloning or pu
 
 ---
 
+## Lockfile verification
+
+A lockfile records the exact git commit SHA of every remote pack that was resolved the last time the registry was built. On subsequent loads, rails-ai-bridge compares the locked SHA against the actual HEAD of the cloned repository and fails closed on mismatch.
+
+This protects against:
+
+- A compromised pack repository pushing unexpected content
+- Accidental drift between environments (development vs. production)
+- Force-pushes or tag rewrites changing the content under a stable ref name
+
+### Generate the lockfile
+
+```bash
+rails ai:registry:lockfile
+```
+
+The file is written to `config/rails_ai_bridge/directory.lock` by default. Commit it alongside your manifest.
+
+### Configuration
+
+```ruby
+RailsAiBridge.configure do |config|
+  config.registry.lockfile_path = "config/rails_ai_bridge/directory.lock"
+  config.registry.lockfile_verification = :strict  # :strict (default), :warn, or :disabled
+end
+```
+
+- `:strict` — raise `ResolutionError` when the resolved commit does not match the lockfile.
+- `:warn` — log a stderr warning and continue loading.
+- `:disabled` — skip verification entirely.
+
+When no lockfile exists, verification is silently skipped so existing apps keep working.
+
+---
+
 ## The `directory.json` format
 
 Each skill pack repository should have a `directory.json` at its root. Here is an annotated example:
@@ -344,6 +379,7 @@ initializer changes take effect immediately.
 | Stale skills after pack update | Resolver cache is warm or pull TTL has not elapsed | Run `rails ai:skills:clear_cache` to force a re-clone on the next build |
 | Pack is not re-fetched even after `resolver_ttl` expired | Pack was cloned recently — `git_pull_ttl` (24 h) is still fresh | Run `rails ai:skills:clear_cache` or set `git_pull_ttl: 0` temporarily |
 | `git checkout <ref>` failed | Invalid ref or detached HEAD issue | Verify the `ref` value matches a branch, tag, or SHA in the remote repo |
+| `Lockfile mismatch for pack '…'` | Resolved pack commit differs from `directory.lock` | Run `rails ai:registry:lockfile` to update the lockfile after reviewing the pack changes |
 | Git operation hangs / server request times out | Slow or unreachable remote | Reduce `git_timeout` to fail faster; check network connectivity to the remote |
 | Warning: "Pack '…' depends on '…' which is not in the active pack set" | A loaded pack has an unsatisfied `depends_on` entry | Add the missing pack name to `always_loaded` or `skill_packs` in your manifest |
 
@@ -358,4 +394,5 @@ initializer changes take effect immediately.
 - **Timeout protection**: all git operations are bounded by `git_timeout` (default 30 s) so a slow remote cannot block the calling thread indefinitely.
 - **Cache key sanitization**: local cache directory names are derived from a sanitized source string plus a SHA256 hash suffix to prevent filesystem collisions.
 - **Stable local pack names**: local registry pack names use a SHA256 digest of the directory path, so reordering `local_registry_paths` cannot silently shift pack identities.
+- **Lockfile verification**: a `directory.lock` records the expected commit SHA for each remote pack. The resolver fails closed when the cloned commit does not match, preventing a compromised or unexpectedly modified pack from injecting instructions.
 - **Local path trust**: local paths are used directly without git operations. The path traversal guard in the Resolver still applies to file reads within a local pack.

data/lib/generators/rails_ai_bridge/install/install_generator.rb

@@ -185,9 +185,19 @@ module RailsAiBridge
             #      config.http_mcp_token = "generate-a-long-random-secret"
             #      # ENV["RAILS_AI_BRIDGE_MCP_TOKEN"] takes precedence when set
             #
+            # Require authentication on every HTTP MCP request. When true, requests
+            # return 401 unless one of the auth mechanisms above is configured.
+            # Default is false for backward compatibility with local development.
+            # config.mcp.require_http_auth = true
+            #
             # Timing-safe token comparison is built in, but add rate limiting too
             # (e.g. Rack::Attack throttle on config.http_path) to prevent brute-force.
             #
+            # CORS for browser-based AI clients connecting over SSE.
+            # Default is nil (no CORS headers). Set to ['*'] to allow any origin,
+            # or to a list of exact origins such as ['https://app.example.com'].
+            # config.mcp.cors_origins = ['https://app.example.com']
+            #
             # config.auto_mount = false
             # config.allow_auto_mount_in_production = false
             # config.http_path = "/mcp"

data/lib/rails_ai_bridge/config/mcp.rb

@@ -68,6 +68,30 @@ module RailsAiBridge
       # @return [Boolean]
       attr_accessor :require_http_auth
 
+      # Allowed origins for CORS on the HTTP MCP endpoint.
+      # +nil+ or empty array disables CORS headers (default). Pass +['*']+ to allow any origin,
+      # or a list of exact origins such as +['https://app.example.com']+.
+      # @return [Array<String>, nil]
+      attr_accessor :cors_origins
+
+      # TTL in seconds for MCP tool result caching by argument fingerprint.
+      # +0+ or negative disables caching. Default +0+ to keep existing behavior.
+      # @return [Integer]
+      attr_accessor :tool_result_cache_ttl
+
+      # Optional custom rate limiter for MCP HTTP requests.
+      #
+      # When set, it takes precedence over the in-memory {Mcp::HttpRateLimiter}.
+      # The object must respond to +allow?(ip)+ (preferred) or +call(ip)+ and return a truthy/falsey value.
+      # This enables distributed backends such as Redis, Rails.cache, or an external service.
+      #
+      # @return [#allow?, #call, nil]
+      attr_accessor :rate_limiter
+
+      # Key prefix used by the optional {Mcp::CacheRateLimiter} distributed rate limiter.
+      # @return [String]
+      attr_accessor :rate_limiter_key_prefix
+
       def initialize
         @mode                     = :hybrid
         @security_profile         = :balanced
@@ -77,6 +101,15 @@ module RailsAiBridge
         @authorize                = nil
         @require_auth_in_production = false
         @require_http_auth          = false
+        @cors_origins             = nil
+        @tool_result_cache_ttl    = 0
+        @rate_limiter             = nil
+        @rate_limiter_key_prefix  = 'rab:rl'
+      end
+
+      # @return [Boolean] whether tool call results should be cached
+      def tool_result_cache_enabled?
+        tool_result_cache_ttl.to_i.positive?
       end
 
       # Effective rate-limit ceiling for {HttpTransportApp} (+0+ means disabled).

data/lib/rails_ai_bridge/config/registry.rb

@@ -35,6 +35,13 @@ module RailsAiBridge
       #   Prevents a slow or unreachable remote from blocking the calling thread indefinitely.
       attr_reader :git_timeout
 
+      # @return [String, nil] path to the skill pack lockfile. nil disables lockfile verification.
+      attr_accessor :lockfile_path
+
+      # @return [Symbol] how to behave when the lockfile differs from the resolved pack:
+      #   :strict (default) raises, :warn logs but proceeds, :disabled skips verification.
+      attr_accessor :lockfile_verification
+
       # Sets the git pull TTL.
       #
       # Coerces the value to a non-negative integer; raises +ArgumentError+ for
@@ -93,6 +100,8 @@ module RailsAiBridge
         @resolver_ttl = 1800
         @git_pull_ttl = 86_400
         @git_timeout = 30
+        @lockfile_path = 'config/rails_ai_bridge/directory.lock'
+        @lockfile_verification = :strict
       end
     end
   end

data/lib/rails_ai_bridge/configuration.rb

@@ -114,7 +114,16 @@ module RailsAiBridge
                    :rate_limit_max_requests, :rate_limit_max_requests=,
                    :rate_limit_window_seconds, :rate_limit_window_seconds=,
                    :http_log_json, :http_log_json=,
-                   :require_http_auth, :require_http_auth=
+                   :require_http_auth, :require_http_auth=,
+                   :tool_result_cache_ttl, :tool_result_cache_ttl=,
+                   :tool_result_cache_enabled?,
+                   :rate_limiter, :rate_limiter=,
+                   :rate_limiter_key_prefix, :rate_limiter_key_prefix=
+
+    # -- Config::Registry -------------------------------------------------------
+    def_delegators :@registry,
+                   :lockfile_path, :lockfile_path=,
+                   :lockfile_verification, :lockfile_verification=
 
     # -- Config::Rubydex --------------------------------------------------------
     def_delegators :@rubydex,

data/lib/rails_ai_bridge/http_transport_app.rb

@@ -12,15 +12,17 @@ module RailsAiBridge
         mcp_cfg    = RailsAiBridge.configuration.mcp
         max_reqs   = mcp_cfg.effective_http_rate_limit_max_requests
         window_sec = mcp_cfg.effective_http_rate_limit_window_seconds
-        limiter    = if max_reqs.positive?
-                       Mcp::HttpRateLimiter.new(max_requests: max_reqs,
-                                                window_seconds: window_sec)
-                     end
+        limiter    = mcp_cfg.rate_limiter || build_default_rate_limiter(max_requests: max_reqs,
+                                                                        window_seconds: window_sec)
+        cors_origins = Array(mcp_cfg.cors_origins).reject(&:empty?)
 
         lambda do |env|
           return [404, { 'Content-Type' => 'application/json' }, ['{"error":"Not found"}']] unless [path, "#{path}/"].include?(env['PATH_INFO'])
 
           request = Rack::Request.new(env)
+          cors_headers = build_cors_headers(request.get_header('HTTP_ORIGIN'), cors_origins)
+
+          return [204, cors_headers, ['']] if request.request_method == 'OPTIONS' && cors_headers
 
           if mcp_cfg.require_http_auth && !Mcp::Authenticator.any_configured?
             Mcp::HttpStructuredLog.emit(request: request, event: :unauthorized, http_status: 401)
@@ -35,19 +37,23 @@ module RailsAiBridge
 
           authorize = RailsAiBridge.configuration.mcp.authorize
           if authorize
-            authorized = begin
-              authorize.call(auth_result.context, request)
+            begin
+              authorized = authorize.call(auth_result.context, request)
             rescue StandardError => error
-              Rails.logger.error("rails_ai_bridge: authorize lambda raised #{error.class}: #{error.message}") if defined?(Rails)
-              false
+              Rails.logger.error("rails_ai_bridge: authorize lambda raised #{error.class}: #{error.message}") if defined?(Rails) && Rails.logger
+              Mcp::HttpStructuredLog.emit(request: request, event: :forbidden, http_status: 403)
+              return [403, { 'Content-Type' => 'application/json' }, ['{"error":"Forbidden"}']]
             end
+
             unless authorized
+              Rails.logger.warn("rails_ai_bridge: authorize lambda denied access for #{request.ip} at #{request.path}") if defined?(Rails) && Rails.logger
               Mcp::HttpStructuredLog.emit(request: request, event: :forbidden, http_status: 403)
               return [403, { 'Content-Type' => 'application/json' }, ['{"error":"Forbidden"}']]
             end
           end
 
-          if limiter && !limiter.allow?(request.ip)
+          if limiter && !rate_limiter_allow?(limiter, request)
+            Instrumentation.instrument('rate_limit.hit', ip: request.ip, path: request.path)
             Mcp::HttpStructuredLog.emit(request: request, event: :rate_limited, http_status: 429)
             return [429, { 'Content-Type' => 'application/json', 'Retry-After' => window_sec.to_s },
                     ['{"error":"Too many requests"}']]
@@ -55,9 +61,51 @@ module RailsAiBridge
 
           response = transport.handle_request(request)
           Mcp::HttpStructuredLog.emit(request: request, event: :handled, http_status: response.first)
+          response[1].merge!(cors_headers) if cors_headers
           response
         end
       end
+
+      private
+
+      def build_default_rate_limiter(max_requests:, window_seconds:)
+        return nil unless max_requests.positive?
+
+        Mcp::HttpRateLimiter.new(max_requests: max_requests, window_seconds: window_seconds)
+      end
+
+      # Asks a configured rate limiter whether a request may proceed.
+      # Supports objects that expose +allow?(ip)+ (preferred) or +call(ip)+.
+      #
+      # @param limiter [#allow?, #call]
+      # @param request [Rack::Request]
+      # @return [Boolean]
+      def rate_limiter_allow?(limiter, request)
+        if limiter.respond_to?(:allow?)
+          limiter.allow?(request.ip)
+        elsif limiter.respond_to?(:call)
+          limiter.call(request.ip)
+        else
+          true
+        end
+      end
+
+      # Builds CORS response headers when the request origin is allowed.
+      #
+      # @param origin [String, nil] value of the Origin header
+      # @param cors_origins [Array<String>] configured allowed origins
+      # @return [Hash{String => String}, nil] headers to add, or +nil+ when CORS is disabled/unmatched
+      def build_cors_headers(origin, cors_origins)
+        return nil if cors_origins.empty?
+        return nil if origin.blank?
+        return nil unless cors_origins.include?('*') || cors_origins.include?(origin)
+
+        {
+          'Access-Control-Allow-Origin' => origin,
+          'Access-Control-Allow-Methods' => 'GET, POST, OPTIONS',
+          'Access-Control-Allow-Headers' => 'Authorization, Content-Type'
+        }
+      end
     end
   end
 end

data/lib/rails_ai_bridge/instrumentation.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'delegate'
+
+module RailsAiBridge
+  # Thin wrapper around ActiveSupport::Notifications for rails-ai-bridge events.
+  #
+  # Events are namespaced under +rails_ai_bridge+. If ActiveSupport::Notifications
+  # is not available, the helper yields without instrumentation so the code can be
+  # used outside of Rails without a hard dependency.
+  module Instrumentation
+    NAMESPACE = 'rails_ai_bridge'
+
+    # Emits an instrumentation event.
+    #
+    # @param event [String] event name suffix (e.g. +tool.call+)
+    # @param payload [Hash] extra payload attached to the event
+    # @yield optional block to wrap; the block result is returned
+    # @return [Object] the block result, or nil when no block is given
+    def self.instrument(event, payload = {})
+      return yield unless defined?(ActiveSupport::Notifications) && ActiveSupport::Notifications
+
+      ActiveSupport::Notifications.instrument("#{NAMESPACE}.#{event}", payload) do
+        yield if block_given?
+      end
+    end
+
+    # Wraps an MCP tool class so every call emits a +rails_ai_bridge.tool.call+
+    # event. Caching, when enabled, is handled by the inner wrapper so cache
+    # hit/miss events stay separate from the invocation event.
+    class InstrumentedTool < SimpleDelegator
+      def initialize(tool_class)
+        super
+        @tool_class = tool_class
+      end
+
+      # @param server_context [Object, nil]
+      # @param arguments [Hash]
+      # @return [MCP::Tool::Response]
+      def call(server_context: nil, **arguments)
+        Instrumentation.instrument('tool.call', tool_name: @tool_class.tool_name, arguments: arguments) do
+          @tool_class.call(server_context: server_context, **arguments)
+        end
+      end
+    end
+  end
+end

data/lib/rails_ai_bridge/introspectors/auth_introspector.rb

@@ -39,8 +39,8 @@ module RailsAiBridge
         devise_models = scan_models_for(/devise\s+(.+)$/)
         auth[:devise] = devise_models if devise_models.any?
 
-        # Rails 8 built-in auth
-        auth[:rails_auth] = true if model_file_exists?('session.rb') && model_file_exists?('current.rb')
+        # Rails 8 built-in auth generator patterns
+        auth[:rails_auth] = detect_rails_auth_details if model_file_exists?('session.rb') && model_file_exists?('current.rb')
 
         # has_secure_password
         secure_pw = scan_models_for(/has_secure_password/)
@@ -49,6 +49,20 @@ module RailsAiBridge
         auth
       end
 
+      def detect_rails_auth_details
+        details = {
+          authentication_concern: file_exists?('app/controllers/concerns/authentication.rb')
+        }
+
+        token_for = scan_models_for(/generates_token_for\s+:(\w+)/)
+        details[:token_for] = token_for.map { |entry| { model: entry[:model], tokens: entry[:matches] } } if token_for.any?
+
+        normalized = scan_models_for(/normalizes\s+:(\w+)/)
+        details[:normalized_attributes] = normalized.map { |entry| { model: entry[:model], attrs: entry[:matches] } } if normalized.any?
+
+        details
+      end
+
       def detect_authorization
         authz = {}
 

data/lib/rails_ai_bridge/introspectors/config_introspector.rb

@@ -20,6 +20,8 @@ module RailsAiBridge
         result = {
           cache_store: detect_cache_store,
           session_store: detect_session_store,
+          queue_adapter: detect_queue_adapter,
+          cable_adapter: detect_cable_adapter,
           timezone: app.config.time_zone.to_s,
           middleware_stack: extract_middleware,
           initializers: extract_initializers,
@@ -54,6 +56,24 @@ module RailsAiBridge
         'unknown'
       end
 
+      def detect_queue_adapter
+        return 'unknown' unless app.config.respond_to?(:active_job)
+
+        adapter = app.config.active_job&.queue_adapter
+        adapter.is_a?(Symbol) ? adapter.to_s : adapter.class.name
+      rescue StandardError
+        'unknown'
+      end
+
+      def detect_cable_adapter
+        return 'unknown' unless app.config.respond_to?(:action_cable)
+
+        adapter = app.config.action_cable&.adapter
+        adapter.is_a?(Symbol) ? adapter.to_s : adapter.class.name
+      rescue StandardError
+        'unknown'
+      end
+
       def extract_middleware
         app.middleware.map { |m| m.name || m.klass.to_s }.uniq
       rescue StandardError

data/lib/rails_ai_bridge/introspectors/gem_registry.rb

@@ -20,6 +20,7 @@ module RailsAiBridge
         'sidekiq' => { category: :jobs, note: 'Background jobs via Sidekiq. Check config/sidekiq.yml.' },
         'good_job' => { category: :jobs, note: 'Background jobs via GoodJob (Postgres-backed).' },
         'solid_queue' => { category: :jobs, note: 'Background jobs via SolidQueue (Rails 8 default).' },
+        'mission_control-jobs' => { category: :jobs, note: 'Web UI for SolidQueue / Active Job monitoring.' },
         'delayed_job' => { category: :jobs, note: 'Background jobs via DelayedJob.' },
         'resque' => { category: :jobs, note: 'Background jobs via Resque (Redis-backed).' },
         'sneakers' => { category: :jobs, note: 'Background jobs via Sneakers (RabbitMQ).' },

data/lib/rails_ai_bridge/mcp/authenticator.rb

@@ -51,7 +51,13 @@ module RailsAiBridge
           strategy = resolve_strategy
           return AuthResult.ok(nil) if strategy.nil?
 
-          strategy.authenticate(request)
+          strategy.authenticate(request).tap do |result|
+            if result.success?
+              Instrumentation.instrument('auth.success', strategy: strategy_name(strategy), ip: request.ip)
+            else
+              Instrumentation.instrument('auth.failure', strategy: strategy_name(strategy), ip: request.ip, error: result.error)
+            end
+          end
         end
 
         # Returns +true+ when any auth mechanism is configured — static token,
@@ -80,6 +86,14 @@ module RailsAiBridge
           ]
         end
 
+        # Human-readable strategy name for observability payloads.
+        #
+        # @param strategy [Auth::BaseStrategy]
+        # @return [String]
+        def strategy_name(strategy)
+          strategy.class.name&.split('::')&.last || 'unknown'
+        end
+
         private
 
         # Selects the appropriate auth strategy from the current configuration.

data/lib/rails_ai_bridge/mcp/cache_rate_limiter.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module RailsAiBridge
+  module Mcp
+    # Distributed, fixed-window rate limiter backed by +Rails.cache+ (or any
+    # +ActiveSupport::Cache::Store+). Use it when the MCP HTTP endpoint runs
+    # behind multiple processes and the default in-memory limiter is insufficient.
+    #
+    # The limiter relies on the cache's +increment+ operation when available and
+    # falls back to read/write for stores that do not support atomic increments.
+    class CacheRateLimiter
+      # @param max_requests [Integer] allowed hits per window per client IP
+      # @param window_seconds [Integer] TTL for each client's counter
+      # @param cache [Object, nil] +ActiveSupport::Cache::Store+; defaults to +Rails.cache+
+      # @param key_prefix [String] prefix for cache keys
+      def initialize(max_requests:, window_seconds:, cache: nil, key_prefix: 'rab:rl')
+        @max_requests = max_requests
+        @window_seconds = window_seconds.to_i
+        @cache = cache
+        @key_prefix = key_prefix
+      end
+
+      # @param ip [String, nil] client identifier (blank values share the +unknown+ bucket)
+      # @return [Boolean] +true+ if the request may proceed
+      def allow?(ip)
+        store = cache_store
+        return true unless store
+
+        key = cache_key(ip)
+        count = increment(store, key)
+        count <= @max_requests
+      end
+
+      private
+
+      def cache_store
+        @cache || (defined?(Rails) && Rails.cache)
+      end
+
+      def cache_key(ip)
+        client = ip.to_s.presence || 'unknown'
+        "#{@key_prefix}:#{client}"
+      end
+
+      def increment(store, key)
+        if store.respond_to?(:increment)
+          store.increment(key, 1, expires_in: @window_seconds) || fallback_increment(store, key)
+        else
+          fallback_increment(store, key)
+        end
+      rescue StandardError
+        fallback_increment(store, key)
+      end
+
+      def fallback_increment(store, key)
+        if store.respond_to?(:increment)
+          store.write(key, 0, expires_in: @window_seconds, unless_exist: true)
+          store.increment(key, 1) || (store.read(key).to_i + 1)
+        else
+          store.write(key, store.read(key).to_i + 1, expires_in: @window_seconds)
+          store.read(key).to_i
+        end
+      rescue StandardError
+        1
+      end
+    end
+  end
+end

data/lib/rails_ai_bridge/registry/lockfile.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'fileutils'
+
+module RailsAiBridge
+  module Registry
+    # Records and verifies expected git commit SHAs for skill packs.
+    #
+    # The lockfile is a JSON document keyed by pack name. Each entry stores the
+    # pack source, ref, and the resolved commit SHA. When verification is enabled,
+    # {PackResolver} compares the locked SHA against the actual HEAD of the cloned
+    # repository and fails closed on mismatch.
+    class Lockfile
+      # Represents one lockfile entry.
+      Entry = Data.define(:pack_name, :source, :ref, :commit_sha)
+
+      class << self
+        # Loads a lockfile from disk.
+        #
+        # @param path [String, nil] path to the lockfile; nil means no lockfile
+        # @return [Lockfile] empty lockfile when path is nil or the file does not exist
+        def load(path)
+          return new({}) if path.nil? || !File.exist?(path)
+
+          raw = File.read(path)
+          data = JSON.parse(raw)
+          entries = data.transform_values do |entry|
+            Entry.new(
+              pack_name: entry['pack_name'],
+              source: entry['source'],
+              ref: entry['ref'],
+              commit_sha: entry['commit_sha']
+            )
+          end
+          new(entries)
+        rescue JSON::ParserError => error
+          raise ArgumentError, "Invalid lockfile JSON at #{path}: #{error.message}"
+        end
+
+        # Generates lockfile entries by resolving every pack in the manifest.
+        #
+        # @param manifest [RegistryManifest]
+        # @param source_resolver [SkillSourceResolver]
+        # @return [Hash{String => Entry}]
+        def generate(manifest, source_resolver)
+          manifest.packs.each_with_object({}) do |(name, pack_def), entries|
+            base_path = source_resolver.resolve(pack_def.source, ref: pack_def.ref)
+            commit_sha = source_resolver.current_commit(base_path)
+            entries[name] = Entry.new(
+              pack_name: name,
+              source: pack_def.source,
+              ref: pack_def.ref,
+              commit_sha: commit_sha
+            )
+          end
+        end
+
+        # Writes a lockfile to disk for the given manifest.
+        #
+        # @param path [String]
+        # @param manifest [RegistryManifest]
+        # @param source_resolver [SkillSourceResolver]
+        # @return [void]
+        def write(path, manifest, source_resolver)
+          entries = generate(manifest, source_resolver)
+          new(entries).write(path)
+        end
+      end
+
+      # @param entries [Hash{String => Entry}] map of pack name to lockfile entry
+      def initialize(entries)
+        @entries = entries.freeze
+      end
+
+      delegate :any?, to: :@entries
+
+      # @param pack_name [String]
+      # @return [Entry, nil]
+      def entry(pack_name)
+        @entries[pack_name]
+      end
+
+      # Serializes the lockfile to JSON.
+      #
+      # @return [String]
+      def to_json(*)
+        data = @entries.transform_values do |entry|
+          {
+            'pack_name' => entry.pack_name,
+            'source' => entry.source,
+            'ref' => entry.ref,
+            'commit_sha' => entry.commit_sha
+          }
+        end
+        JSON.pretty_generate(data)
+      end
+
+      # Writes the lockfile to disk.
+      #
+      # @param path [String]
+      # @return [void]
+      def write(path)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, "#{to_json}\n")
+      end
+    end
+  end
+end

data/lib/rails_ai_bridge/registry/pack_resolver.rb

@@ -22,15 +22,18 @@ module RailsAiBridge
       #
       # @param source_resolver [SkillSourceResolver] resolver for remote git sources
       # @param pack_detector [Object] optional pack detector for testing (defaults to PackDetector)
-      def initialize(source_resolver, pack_detector = PackDetector)
+      # @param lockfile [Lockfile, nil] optional lockfile for pack verification
+      def initialize(source_resolver, pack_detector = PackDetector, lockfile = nil)
         @source_resolver = source_resolver
         @pack_detector = pack_detector
+        @lockfile = lockfile || default_lockfile
       end
 
       # Resolves active packs from the manifest and custom configuration.
       #
       # This will automatically resolve remote repositories if needed, load the tile
-      # manifest configurations, and merge local directory overrides.
+      # manifest configurations, merge local directory overrides, and verify pack
+      # commit SHAs against the configured lockfile.
       #
       # @param manifest [RegistryManifest] the registry manifest containing pack definitions
       # @param explicit_packs [Array<String>, nil] optional list of pack names to load
@@ -47,6 +50,38 @@ module RailsAiBridge
 
       private
 
+      def default_lockfile
+        Lockfile.load(RailsAiBridge.configuration.registry.lockfile_path)
+      end
+
+      # Verifies the resolved pack commit SHA against the lockfile when one exists.
+      #
+      # Behavior is controlled by +config.registry.lockfile_verification+:
+      #   :strict  — raise on mismatch (default)
+      #   :warn    — log a warning and continue
+      #   :disabled — skip verification entirely
+      #
+      # @param name [String] pack name
+      # @param base_path [String] local path to the resolved pack
+      # @return [void]
+      def verify_pack!(name, base_path)
+        return unless @lockfile&.any?
+
+        mode = RailsAiBridge.configuration.registry.lockfile_verification
+        return if mode == :disabled
+
+        entry = @lockfile.entry(name)
+        return unless entry
+
+        actual = @source_resolver.current_commit(base_path)
+        return if actual == entry.commit_sha
+
+        message = "Lockfile mismatch for pack '#{name}': expected #{entry.commit_sha}, got #{actual}"
+        return warn "[rails-ai-bridge] #{message}" if mode == :warn
+
+        raise SkillSourceResolver::ResolutionError, "#{message}. Run `rails ai:registry:lockfile` to update the lockfile."
+      end
+
       # Gathers the set of pack names that should be loaded.
       #
       # Combines always_loaded packs with either explicit_packs or auto-detected framework packs.
@@ -105,6 +140,8 @@ module RailsAiBridge
           raise SkillSourceResolver::ResolutionError, "Pack '#{name}' not defined in registry manifest" unless pack_def
 
           base_path = @source_resolver.resolve(pack_def.source, ref: pack_def.ref)
+          verify_pack!(name, base_path)
+
           tile_path = File.join(base_path, pack_def.tile)
 
           unless File.exist?(tile_path)

data/lib/rails_ai_bridge/registry/skill_source_resolver.rb

@@ -39,6 +39,15 @@ module RailsAiBridge
       def checkout_ref(_path, _ref)
         raise NotImplementedError
       end
+
+      # Returns the current HEAD commit SHA for the repository at +_path+.
+      #
+      # @param _path [String] path to the local repository
+      # @raise [StandardError] if the commit cannot be determined
+      # @return [String] 40-character hex commit SHA
+      def current_commit(_path)
+        raise NotImplementedError
+      end
     end
 
     # Default implementation of {GitRunner} using Open3 to spawn git subprocesses.
@@ -85,6 +94,20 @@ module RailsAiBridge
         end
       end
 
+      # Returns the current HEAD commit SHA for the repository at +path+.
+      #
+      # @param path [String] path to the local repository
+      # @raise [RuntimeError] if the git command fails or returns non-zero
+      # @return [String] 40-character hex commit SHA
+      def current_commit(path)
+        with_timeout('git rev-parse') do
+          stdout, stderr, status = Open3.capture3('git', 'rev-parse', 'HEAD', chdir: path) # nosemgrep: ruby.lang.security.dangerous-exec.dangerous-exec
+          fail_with_sanitized_error!('git rev-parse', stderr) unless status.success?
+
+          stdout.strip
+        end
+      end
+
       # Checks out a specific git ref inside a local repository directory.
       #
       # @param path [String] path to the local repository
@@ -232,6 +255,17 @@ module RailsAiBridge
         cache_path
       end
 
+      # Returns the current HEAD commit SHA for the repository at +path+.
+      #
+      # @param path [String] path to the local repository
+      # @return [String] 40-character hex commit SHA
+      # @raise [ResolutionError] if the commit cannot be read
+      def current_commit(path)
+        @git_runner.current_commit(path)
+      rescue StandardError => error
+        raise ResolutionError, "failed to read current commit for pack at #{path}: #{error.message}"
+      end
+
       private
 
       # Returns true when no successful pull has been recorded for +cache_path+ within

data/lib/rails_ai_bridge/registry.rb

@@ -18,6 +18,7 @@ require_relative 'registry/resolver'
 require_relative 'registry/source_parser'
 require_relative 'registry/skill_source_resolver'
 require_relative 'registry/pack_resolver'
+require_relative 'registry/lockfile'
 require_relative 'registry/resolver_cache'
 require_relative 'registry/rake_presenter'
 
@@ -81,6 +82,23 @@ module RailsAiBridge
       resolver_cache.fetch(config) { build_resolver_uncached(config) }
     end
 
+    # Writes a lockfile containing the current HEAD commit SHA for every pack in
+    # the registry manifest.
+    #
+    # @param config [RailsAiBridge::Config::Registry] registry configuration
+    # @return [void]
+    # @raise [ArgumentError] when the manifest file does not exist
+    def self.write_lockfile(config = RailsAiBridge.configuration.registry)
+      manifest_path = config.registry_manifest_path
+      raise ArgumentError, "Registry manifest not found at #{manifest_path}" unless File.exist?(manifest_path)
+
+      manifest = RegistryManifest.from_file(manifest_path)
+      git_runner = DefaultGitRunner.new(timeout: config.git_timeout)
+      source_resolver = SkillSourceResolver.new(config.skill_cache_dir, git_runner, pull_ttl: config.git_pull_ttl)
+
+      Lockfile.write(config.lockfile_path, manifest, source_resolver)
+    end
+
     # @api private
     def self.build_resolver_uncached(config)
       manifest_path = config.registry_manifest_path

data/lib/rails_ai_bridge/server.rb

@@ -22,6 +22,11 @@ module RailsAiBridge
     # Error message template for unknown transport types
     UNKNOWN_TRANSPORT_ERROR = 'Unknown transport: %s. Use :stdio, :http, or :streamable_http'
 
+    # Warning printed when HTTP MCP starts without authentication in non-production environments.
+    HTTP_AUTH_WARNING = '[rails-ai-bridge] WARNING: HTTP MCP is running without authentication. ' \
+                        'Set config.mcp.require_http_auth = true or configure http_mcp_token, ' \
+                        'mcp_token_resolver, or mcp_jwt_decoder before exposing this endpoint.'
+
     # Built-in MCP tools that are always available
     # These tools provide Rails application introspection capabilities
     TOOLS = [
@@ -50,9 +55,14 @@ module RailsAiBridge
     end
 
     # Returns all available tool classes including additional configured tools.
-    # @return [Array<Class>] list of tool classes
+    # When tool result caching is enabled, built-in and additional tools are wrapped
+    # so identical argument fingerprints reuse cached +MCP::Tool::Response+ objects.
+    #
+    # @return [Array<Class, ToolResultCache::CachedTool>] list of tool classes
     def tool_classes
-      TOOLS + RailsAiBridge.configuration.additional_tools
+      (TOOLS + RailsAiBridge.configuration.additional_tools).map do |tool_class|
+        Instrumentation::InstrumentedTool.new(ToolResultCache.maybe_wrap(tool_class))
+      end
     end
 
     # Build and return the configured MCP::Server instance.
@@ -114,6 +124,7 @@ module RailsAiBridge
       transport = create_http_transport(server)
       rack_app = build_rack_app(transport, config.http_path)
 
+      warn_if_http_mcp_unauthenticated
       log_http_startup(config)
       run_rack_server(rack_app, config)
     end
@@ -153,6 +164,18 @@ module RailsAiBridge
       warn TOOLS_LIST_MESSAGE % tool_classes.map(&:tool_name).join(', ')
     end
 
+    # Emits a one-time stderr warning when HTTP MCP starts without authentication
+    # in non-production environments. Production deployments either raise during
+    # validation or are assumed to be deliberately configured.
+    #
+    # @return [void]
+    def warn_if_http_mcp_unauthenticated
+      return if defined?(Rails) && Rails.env.production?
+      return if Mcp::Authenticator.any_configured?
+
+      warn HTTP_AUTH_WARNING
+    end
+
     # Runs the Rack server with fallback for older Rack versions.
     # @param rack_app [Object] the Rack application
     # @param config [RailsAiBridge::Configuration] bridge configuration

data/lib/rails_ai_bridge/tasks/rails_ai_bridge.rake

@@ -279,6 +279,19 @@ namespace :ai do
   end
 end
 
+namespace :ai do
+  namespace :registry do
+    desc 'Generate or update the skill pack lockfile (config/rails_ai_bridge/directory.lock)'
+    task lockfile: :environment do
+      require 'rails_ai_bridge'
+
+      config = RailsAiBridge.configuration.registry
+      RailsAiBridge::Registry.write_lockfile(config)
+      puts "📝 Wrote skill pack lockfile to #{config.lockfile_path}"
+    end
+  end
+end
+
 namespace :ai do
   namespace :skills do
     desc 'List all available skills from configured skill packs'

data/lib/rails_ai_bridge/tool_result_cache.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require 'delegate'
+require 'digest'
+require 'json'
+require 'mcp'
+
+module RailsAiBridge
+  # Caches MCP tool call results keyed by a stable fingerprint of the arguments.
+  #
+  # The cache is in-memory, per-process, and TTL-based. It ignores +server_context+
+  # when fingerprinting so identical client requests share the same cached response.
+  #
+  # Enable by setting +config.mcp.tool_result_cache_ttl+ to a positive number of seconds.
+  class ToolResultCache
+    @cache = {}
+    @mutex = Mutex.new
+
+    # Wraps a tool class so that calls are routed through the cache.
+    class CachedTool < SimpleDelegator
+      def initialize(tool_class)
+        super
+        @tool_class = tool_class
+        @server_context_param = detect_server_context_param(tool_class.method(:call))
+      end
+
+      # @param server_context [Object, nil] passed by the MCP transport (ignored for cache keys)
+      # @param arguments [Hash] tool arguments from the client
+      # @return [MCP::Tool::Response]
+      def call(server_context: nil, **arguments)
+        ToolResultCache.fetch_response(@tool_class.tool_name, arguments) do
+          invoke_tool(arguments, server_context)
+        end
+      end
+
+      private
+
+      def invoke_tool(arguments, server_context)
+        case @server_context_param
+        when :server_context
+          @tool_class.call(**arguments, server_context: server_context)
+        when :_server_context
+          @tool_class.call(**arguments, _server_context: server_context)
+        else
+          @tool_class.call(**arguments)
+        end
+      end
+
+      def detect_server_context_param(method_object)
+        parameters = method_object.parameters
+        keyish = %i[key keyreq].freeze
+        return :server_context if parameters.any? { |type, name| name == :server_context && keyish.include?(type) }
+        return :_server_context if parameters.any? { |type, name| name == :_server_context && keyish.include?(type) }
+        return :server_context if parameters.any? { |type, _| type == :keyrest }
+
+        nil
+      end
+    end
+
+    class << self
+      # Wraps a tool class if caching is enabled; otherwise returns the class unchanged.
+      #
+      # @param tool_class [Class] an +MCP::Tool+ subclass
+      # @return [Class, CachedTool]
+      def maybe_wrap(tool_class)
+        enabled? ? wrap(tool_class) : tool_class
+      end
+
+      # Wraps a tool class so every call goes through the cache.
+      #
+      # @param tool_class [Class]
+      # @return [CachedTool]
+      def wrap(tool_class)
+        CachedTool.new(tool_class)
+      end
+
+      # Fetches a cached response or yields to compute it.
+      #
+      # @param tool_name [String]
+      # @param arguments [Hash]
+      # @yieldreturn [MCP::Tool::Response]
+      # @return [MCP::Tool::Response]
+      def fetch_response(tool_name, arguments)
+        return yield unless enabled?
+
+        key = cache_key(tool_name, arguments)
+        fingerprint = key.split(':', 2).last
+
+        mutex.synchronize do
+          entry = cache[key]
+          if entry && ttl_valid?(entry)
+            Instrumentation.instrument('tool.result_cache_hit', tool_name: tool_name, fingerprint: fingerprint)
+            return entry[:response]
+          end
+        end
+
+        Instrumentation.instrument('tool.result_cache_miss', tool_name: tool_name, fingerprint: fingerprint) do
+          response = yield
+          mutex.synchronize { cache[key] = { response: response, fetched_at: monotonic_now } }
+          response
+        end
+      end
+
+      # Clears all cached tool results.
+      #
+      # @return [void]
+      def reset!
+        mutex.synchronize { @cache = {} }
+      end
+
+      # @return [Boolean] whether tool result caching is enabled
+      def enabled?
+        RailsAiBridge.configuration.mcp.tool_result_cache_ttl.to_i.positive?
+      end
+
+      private
+
+      attr_reader :cache, :mutex
+
+      def cache_key(tool_name, arguments)
+        "#{tool_name}:#{argument_fingerprint(arguments)}"
+      end
+
+      def argument_fingerprint(arguments)
+        normalized = arguments.transform_keys(&:to_s).sort.to_h
+        Digest::SHA256.hexdigest(JSON.generate(normalized))
+      end
+
+      def ttl_valid?(entry)
+        (monotonic_now - entry[:fetched_at]) < RailsAiBridge.configuration.mcp.tool_result_cache_ttl.to_i
+      end
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/rails_ai_bridge/tools/get_model_details.rb

@@ -19,8 +19,13 @@ module RailsAiBridge
           detail: {
             type: 'string',
             enum: %w[summary standard full],
-            description: 'Detail level for model listing. summary: names only. standard: names + association/validation counts (default). full: names + full association list.
+            description: 'Detail level for model listing. summary: names only (default). standard: names + association/validation counts. full: names + full association list.
             Ignored when specific model is given (always returns full).'
+          },
+          format: {
+            type: 'string',
+            enum: %w[json markdown],
+            description: 'Output format. Default: markdown.'
           }
         }
       )
@@ -37,13 +42,13 @@ module RailsAiBridge
       # @param detail [String] +summary+, +standard+, or +full+ when listing (ignored when +model+ is set)
       # @param _server_context [Object, nil] reserved for MCP transport metadata (unused)
       # @return [MCP::Tool::Response] Markdown body or an error string wrapped for the MCP client
-      def self.call(model: nil, detail: 'standard', _server_context: nil)
+      def self.call(model: nil, detail: 'summary', format: 'markdown', _server_context: nil)
         models = cached_section(:models)
         return text_response('Model introspection not available. Add :models to introspectors.') unless models
         return text_response("Model introspection failed: #{models[:error]}") if models[:error]
 
         non_ar = cached_section(:non_ar_models)
-        formatter = ResponseFormatter.new(models, model: model, detail: detail, non_ar_models: non_ar)
+        formatter = ResponseFormatter.new(models, model: model, detail: detail, format: format, non_ar_models: non_ar)
         return text_response(formatter.model_not_found_message) if formatter.model_not_found?
         return text_response(formatter.model_error_message) if formatter.model_error?
 
@@ -57,10 +62,11 @@ module RailsAiBridge
         # @param model [String, nil] requested single-model name
         # @param detail [String] list detail level when +model+ is +nil+
         # @param non_ar_models [Hash, nil] +:non_ar_models+ introspection section (may be +nil+ if disabled)
-        def initialize(models, model:, detail:, non_ar_models: nil)
+        def initialize(models, model:, detail:, format:, non_ar_models: nil)
           @models = models
           @model = model
           @detail = detail
+          @format = format
           @non_ar_models = non_ar_models
         end
 
@@ -89,8 +95,10 @@ module RailsAiBridge
           "Error inspecting #{model_key}: #{model_data[:error]}"
         end
 
-        # @return [String] Markdown for one model, POJO stub, or full listing
+        # @return [String] Markdown/JSON for one model, POJO stub, or full listing
         def format
+          return json_payload if @format == 'json'
+
           if @model
             return pojo_detail_markdown if pojo_entry && !model_data
 
@@ -107,6 +115,16 @@ module RailsAiBridge
 
         private
 
+        def json_payload
+          if @model
+            return pojo_entry.to_h.to_json if pojo_entry && !model_data
+
+            model_data.to_json
+          else
+            @models.to_json
+          end
+        end
+
         def pojo_entry
           return @pojo_entry if defined?(@pojo_entry)
 

data/lib/rails_ai_bridge/tools/get_routes.rb

@@ -26,6 +26,11 @@ module RailsAiBridge
           offset: {
             type: 'integer',
             description: 'Skip routes for pagination. Default: 0.'
+          },
+          format: {
+            type: 'string',
+            enum: %w[json markdown],
+            description: 'Output format. Default: markdown.'
           }
         }
       )
@@ -38,12 +43,13 @@ module RailsAiBridge
       # @param offset [Integer] pagination offset
       # @param _server_context [Object, nil] reserved for MCP transport metadata (unused)
       # @return [MCP::Tool::Response] markdown routes output or an error message
-      def self.call(controller: nil, detail: 'standard', limit: nil, offset: 0, _server_context: nil)
+      def self.call(controller: nil, detail: 'standard', limit: nil, offset: 0, format: 'markdown', _server_context: nil)
         routes = cached_section(:routes)
         return text_response('Route introspection not available. Add :routes to introspectors.') unless routes
         return text_response("Route introspection failed: #{routes[:error]}") if routes[:error]
 
-        formatter = ResponseFormatter.new(routes, controller: controller, detail: detail, limit: limit, offset: offset)
+        formatter = ResponseFormatter.new(routes, controller: controller, detail: detail, limit: limit, offset: offset,
+                                                  format: format)
         return text_response(formatter.filter_error_message) if formatter.filter_error?
 
         text_response(formatter.format)
@@ -52,12 +58,13 @@ module RailsAiBridge
       # @private
       # Formats +:routes+ introspection for {GetRoutes}.
       class ResponseFormatter
-        def initialize(routes, controller:, detail:, limit:, offset:)
+        def initialize(routes, controller:, detail:, limit:, offset:, format:)
           @routes = routes
           @controller = controller
           @detail = detail
           @limit = limit
           @offset = [offset.to_i, 0].max
+          @format = format
           @by_controller = filter_by_controller
         end
 
@@ -70,6 +77,8 @@ module RailsAiBridge
         end
 
         def format
+          return json_payload if @format == 'json'
+
           case @detail
           when 'summary' then format_summary
           when 'standard' then format_standard
@@ -80,6 +89,14 @@ module RailsAiBridge
 
         private
 
+        def json_payload
+          {
+            total: route_count,
+            offset: @offset,
+            controllers: @by_controller.sort.to_h
+          }.to_json
+        end
+
         def filter_by_controller
           return @routes[:by_controller] || {} unless @controller
 

data/lib/rails_ai_bridge/tools/get_schema.rb

@@ -17,7 +17,7 @@ module RailsAiBridge
           detail: {
             type: 'string',
             enum: %w[summary standard full],
-            description: 'Detail level. summary: table names + column counts. standard: table names + column names/types (default). ' \
+            description: 'Detail level. summary: table names + column counts (default). standard: table names + column names/types. ' \
                          'full: everything including indexes, FKs, comments.'
           },
           limit: {
@@ -50,7 +50,7 @@ module RailsAiBridge
       # @param format [String] +markdown+ or +json+
       # @param _server_context [Object, nil] reserved for MCP transport metadata (unused)
       # @return [MCP::Tool::Response] schema markdown/JSON or an error message
-      def self.call(table: nil, detail: 'standard', limit: nil, offset: 0, format: 'markdown', _server_context: nil)
+      def self.call(table: nil, detail: 'summary', limit: nil, offset: 0, format: 'markdown', _server_context: nil)
         schema = cached_section(:schema)
         return text_response('Schema introspection not available. Add :schema to introspectors.') unless schema
         return text_response("Schema introspection not available: #{schema[:error]}") if schema[:error]

data/lib/rails_ai_bridge/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RailsAiBridge
-  VERSION = '3.5.1'
+  VERSION = '3.5.2'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-ai-bridge
 version: !ruby/object:Gem::Version
-  version: 3.5.1
+  version: 3.5.2
 platform: ruby
 authors:
 - Ismael Marin
@@ -183,6 +183,7 @@ files:
 - lib/rails_ai_bridge/fingerprinter/cached_snapshot.rb
 - lib/rails_ai_bridge/freshness_header.rb
 - lib/rails_ai_bridge/http_transport_app.rb
+- lib/rails_ai_bridge/instrumentation.rb
 - lib/rails_ai_bridge/introspector.rb
 - lib/rails_ai_bridge/introspector/parallel_runner.rb
 - lib/rails_ai_bridge/introspector/timed_runner.rb
@@ -229,6 +230,7 @@ files:
 - lib/rails_ai_bridge/mcp/auth/strategies/jwt.rb
 - lib/rails_ai_bridge/mcp/auth_result.rb
 - lib/rails_ai_bridge/mcp/authenticator.rb
+- lib/rails_ai_bridge/mcp/cache_rate_limiter.rb
 - lib/rails_ai_bridge/mcp/http_rate_limiter.rb
 - lib/rails_ai_bridge/mcp/http_structured_log.rb
 - lib/rails_ai_bridge/middleware.rb
@@ -236,6 +238,7 @@ files:
 - lib/rails_ai_bridge/path_resolver.rb
 - lib/rails_ai_bridge/registry.rb
 - lib/rails_ai_bridge/registry/frontmatter_parser.rb
+- lib/rails_ai_bridge/registry/lockfile.rb
 - lib/rails_ai_bridge/registry/pack_definition.rb
 - lib/rails_ai_bridge/registry/pack_detector.rb
 - lib/rails_ai_bridge/registry/pack_resolver.rb
@@ -339,6 +342,7 @@ files:
 - lib/rails_ai_bridge/services/context_generation_service.rb
 - lib/rails_ai_bridge/services/file_management_service.rb
 - lib/rails_ai_bridge/tasks/rails_ai_bridge.rake
+- lib/rails_ai_bridge/tool_result_cache.rb
 - lib/rails_ai_bridge/tools/README.md
 - lib/rails_ai_bridge/tools/base_tool.rb
 - lib/rails_ai_bridge/tools/get_config.rb