mcp_authorization 0.1.0

data/lib/mcp_authorization/dsl.rb

@@ -0,0 +1,64 @@
+module McpAuthorization
+  # Mixin for handler classes — the plain Ruby objects that implement the
+  # business logic behind each MCP tool.
+  #
+  # Include this module instead of hand-rolling +initialize+, permission
+  # checks, and MCP notification plumbing:
+  #
+  #   class Handlers::ListOrders
+  #     include McpAuthorization::DSL
+  #
+  #     def description
+  #       "List recent orders"
+  #     end
+  #
+  #     #: (status: String, ?limit: Integer @requires(:admin)) -> Hash[Symbol, untyped]
+  #     def call(status:, limit: 25)
+  #       orders = Order.where(status: status).limit(limit)
+  #       { orders: orders.map(&:as_json) }
+  #     end
+  #   end
+  #
+  # == What it provides
+  #
+  # * +server_context+ — the per-request context object built by the host
+  #   app's +context_builder+.
+  # * +can?(flag)+ — convenience delegation to +current_user.can?+.
+  # * +report_progress+ / +notify_log_message+ — thin wrappers around MCP
+  #   session notifications, safe to call even when the context doesn't
+  #   support them (e.g. during +tools/list+).
+  #
+  module DSL
+    # The per-request context built by the host app's +context_builder+.
+    #: untyped
+    attr_reader :server_context
+
+    #: (server_context: untyped) -> void
+    def initialize(server_context:)
+      @server_context = server_context
+    end
+
+    # Convenience check — delegates to +server_context.current_user.can?+.
+    # Use inside +#call+ for runtime branching beyond +@requires+ filtering.
+    #: (Symbol) -> bool
+    def can?(flag)
+      server_context.current_user.can?(flag)
+    end
+
+    # Send a progress notification to the MCP client (MCP 0.10+).
+    # Safe to call unconditionally — no-ops when context lacks support.
+    #: (Numeric, ?total: Numeric?, ?message: String?) -> void
+    def report_progress(progress, total: nil, message: nil)
+      return unless server_context.respond_to?(:report_progress)
+      server_context.report_progress(progress, total: total, message: message)
+    end
+
+    # Send a log message notification to the MCP client (MCP 0.10+).
+    # Safe to call unconditionally — no-ops when context lacks support.
+    #: (data: untyped, level: String | Symbol, ?logger: String?) -> void
+    def notify_log_message(data:, level:, logger: nil)
+      return unless server_context.respond_to?(:notify_log_message)
+      server_context.notify_log_message(data: data, level: level, logger: logger)
+    end
+  end
+end

data/lib/mcp_authorization/engine.rb

@@ -0,0 +1,68 @@
+module McpAuthorization
+  # Rails Engine that wires the gem into a host application.
+  #
+  # The engine handles three things automatically so the host app doesn't
+  # have to:
+  #
+  # 1. *Autoload paths* — tool directories (default +app/mcp+) are added to
+  #    the Rails autoloader so tool and handler classes are discovered
+  #    without explicit requires.
+  #
+  # 2. *Cache invalidation* — on code reload (development mode) the
+  #    ToolRegistry and RbsSchemaCompiler caches are cleared. Tools
+  #    re-register themselves via the +inherited+ hook when their classes
+  #    are reloaded.
+  #
+  # 3. *Route mounting* — MCP endpoints are prepended to the host app's
+  #    router at +config.mount_path+ (default +/mcp+). The routes support
+  #    multi-domain routing via an optional +:domain+ segment:
+  #
+  #      POST /mcp              → default domain
+  #      POST /mcp/operator     → "operator" domain
+  #      POST /mcp/recruiting   → "recruiting" domain
+  #
+  #    All three HTTP methods required by the MCP StreamableHTTP transport
+  #    (GET, POST, DELETE) are accepted.
+  #
+  class Engine < ::Rails::Engine
+    isolate_namespace McpAuthorization
+
+    # Add configured tool_paths to the Rails autoloader so tool classes
+    # (and their handler classes) are discovered without manual requires.
+    initializer "mcp_authorization.autoload_paths", before: :set_autoload_paths do |app|
+      McpAuthorization.config.tool_paths.each do |path|
+        full_path = Rails.root.join(path).to_s
+        if File.directory?(full_path)
+          app.config.autoload_paths << full_path
+          app.config.eager_load_paths << full_path
+        end
+      end
+    end
+
+    # Clear caches on code reload so stale class references and parsed
+    # schemas are dropped. Tools re-register via the inherited hook when
+    # their classes are reloaded by Zeitwerk.
+    initializer "mcp_authorization.reloader" do |app|
+      app.reloader.to_prepare do
+        McpAuthorization::ToolRegistry.reset!
+        McpAuthorization::RbsSchemaCompiler.reset_cache!
+      end
+    end
+
+    # Prepend MCP routes into the host app's router. Uses +prepend+ so the
+    # MCP endpoint is available before any catch-all routes the host may
+    # define. Supports both domain-scoped and bare paths.
+    initializer "mcp_authorization.routes", before: :finisher_hook do |app|
+      default_domain = McpAuthorization.config.default_domain
+      mount_path = McpAuthorization.config.mount_path
+
+      app.routes.prepend do
+        scope mount_path, module: :mcp_authorization do
+          match ":domain", to: "mcp#handle", via: [ :get, :post, :delete ]
+          match "/", to: "mcp#handle", via: [ :get, :post, :delete ],
+                defaults: { domain: default_domain }
+        end
+      end
+    end
+  end
+end