rails-ai-bridge 3.5.1 → 3.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 86847cb1d8613336bb1538fdde0c64461dcc69d2423b48939629695f40c99688
-  data.tar.gz: 65d9c1a4f11b3edc80a077e66c41e339ca845e4d10993d63cddef79be7ef9c5d
+  metadata.gz: b375ce08baa45d08d3c20625d27280862175bb022677e1f5c5ae90d1eb7a1493
+  data.tar.gz: 7d8de9d9b1642b447c03cc3b36820d2008dee648a475ebffaac038a9f081a178
 SHA512:
-  metadata.gz: c6ae4378aa2f3321b0753fb7e111a4d6777bd4de63e5ade3bcf38047affac48ce86630490dcacd33610021f299833bc5d7dd24f9dc238614f60786d8fac42ea4
-  data.tar.gz: 22caf59cc05827c7a5824f17c2dd1a5715b8ba62b70930ef300835bdbdc96506bdae1f2ec8590391272576c097363b45debb605f195e0e7c7b43c227f8a75289
+  metadata.gz: 6ced1f26479b6614723aaba77812ec4efe9ff35c107a40e4e8865ec88553eace62aa5bd990371c0eb1b2ae4bfd13d7983c1d101bb3403ef7b8e8922022150106
+  data.tar.gz: 39b6117bb858aa1dca13e65d05244aeccece63fb6afde51ee5ff1c0d3986512aabd3bd74e0ae00ee5ad0bda3382025573caebe7aa273155ff5a3fd85db03e812

data/CHANGELOG.md

@@ -5,6 +5,50 @@ 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.6.0]
+
+### Changed
+
+- **`mcp` minimum version raised to 0.25** (#92) — the gemspec lower bound is now `>= 0.25` (was `>= 0.10`), matching the minimum version the codebase actually requires. The upper bound remains `< 1.0`.
+- **`rubydex` constraint tightened to `~> 0.2.9`** (#92) — was `~> 0.2.4`. This is a **minor breaking change** for users pinned to rubydex 0.2.4–0.2.8; update your lockfile with `bundle update rubydex`.
+- **`simplecov` bumped to 1.0** (#92) — development dependency only; does not affect gem consumers. The test suite filter was migrated from `add_filter '/spec/'` to `skip 'spec'` per the simplecov 1.0 migration guide (`SourceFile#project_filename` no longer includes a leading separator).
+
+### Fixed
+
+- **`Style/ArrayIntersect` lint offense** (#91/#92) — pre-existing rubocop offense in `context_summary.rb` autocorrected to use `Array#intersect?`. No behavior change.
+
+### Added
+
+- **PathResolver architectural documentation** (#90/#91) — class-level docblock documents PathResolver's intentional role as a shared utility (11 introspector callers, high betweenness centrality). Prevents false "god class" flags from future graph analyses.
+- **PathResolver edge-case tests** (#90/#91) — 6 new specs covering the private `SafeRelativePath` (backslash normalization, Windows path rejection, empty path rejection) and `SafeJoin` (valid joins, traversal escape prevention) helper classes.
+
+## [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/README.md

@@ -780,7 +780,7 @@ Bug reports and pull requests: [github.com/igmarin/rails-ai-bridge/issues](https
 
 ## Acknowledgments & Origins
 
-This gem ships as **rails-ai-bridge** (Ruby **`RailsAiBridge`**, version **3.1.0**). Earlier iterations of the same codebase were distributed as `rails-ai-context`.
+This gem ships as **rails-ai-bridge** (Ruby **`RailsAiBridge`**, version **3.6.0**). Earlier iterations of the same codebase were distributed as `rails-ai-context`.
 
 RailsMCP evolved from 
 [crisnahine/rails-ai-context](https://github.com/crisnahine/rails-ai-context),

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/UPGRADING.md

@@ -1,5 +1,22 @@
 # Upgrading rails-ai-bridge
 
+## Upgrading from 3.5.x to 3.6.0
+
+**One action required if you are pinned to an older `rubydex`:**
+
+The `rubydex` gem constraint was tightened from `~> 0.2.4` to `~> 0.2.9`. If your
+lockfile resolves to rubydex 0.2.4–0.2.8, update it after upgrading:
+
+```bash
+bundle update rubydex
+```
+
+No other configuration or code changes are required. The `mcp` lower bound also
+moved from `>= 0.10` to `>= 0.25`, but if you were already on a recent version
+(no earlier than 0.25) this is a no-op.
+
+---
+
 ## Upgrading from 1.x to 2.x
 
 **No configuration changes required.** Every `config.*` attribute from 1.x is still available — `Configuration` now delegates to focused sub-objects but exposes the same flat DSL. See `CHANGELOG.md` for the full list of internal changes.

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.