mcp_authorization 0.1.0

data/lib/mcp_authorization/tool.rb

@@ -0,0 +1,245 @@
+module McpAuthorization
+  # Base class for MCP tools with schema-shaping authorization.
+  #
+  # Subclass this instead of MCP::Tool directly. Each subclass is a thin
+  # declarative wrapper — the actual business logic lives in a *handler
+  # class* (a plain Ruby class that includes DSL) pointed to by
+  # +dynamic_contract+.
+  #
+  # == Defining a tool
+  #
+  #   class Tools::ListOrders < McpAuthorization::Tool
+  #     tool_name "list_orders"
+  #     authorization :view_orders
+  #     tags "operator", "fulfillment"
+  #     read_only!
+  #
+  #     dynamic_contract Handlers::ListOrders
+  #   end
+  #
+  class Tool < MCP::Tool
+    class NotAuthorizedError < StandardError; end
+
+    class << self
+      #: Symbol?
+      attr_reader :_permission
+
+      #: Array[String]?
+      attr_reader :_tags
+
+      #: untyped
+      attr_reader :_contract_handler
+
+      #: (Class) -> void
+      def inherited(subclass)
+        super
+        McpAuthorization::ToolRegistry.register(subclass)
+      end
+
+      # Declare the permission flag required to see this tool.
+      #: (Symbol) -> void
+      def authorization(permission)
+        @_permission = permission
+      end
+
+      # Declare which MCP domains this tool belongs to.
+      #: (*String | Array[String]) -> void
+      def tags(*list)
+        @_tags = list.flatten
+      end
+
+      # MCP annotation hint shorthands
+      #: () -> void
+      def read_only!;       merge_annotations(read_only_hint: true) end
+      #: () -> void
+      def destructive!;     merge_annotations(destructive_hint: true) end
+      #: () -> void
+      def not_destructive!; merge_annotations(destructive_hint: false) end
+      #: () -> void
+      def idempotent!;      merge_annotations(idempotent_hint: true) end
+      #: () -> void
+      def open_world!;      merge_annotations(open_world_hint: true) end
+      #: () -> void
+      def closed_world!;    merge_annotations(open_world_hint: false) end
+
+      # Point this tool at its handler class.
+      #: (untyped) -> void
+      def dynamic_contract(handler_class)
+        @_contract_handler = handler_class
+        @_contract_validated = false
+      end
+
+      # Build the tool description for this user.
+      #: (server_context: untyped) -> String
+      def dynamic_description(server_context:)
+        handler_instance(server_context).description
+      end
+
+      # Compile the input JSON Schema for this user.
+      #: (server_context: untyped) -> Hash[Symbol, untyped]
+      def dynamic_input_schema(server_context:)
+        McpAuthorization::RbsSchemaCompiler.compile_input(
+          _contract_handler,
+          server_context: server_context
+        )
+      end
+
+      # Compile the output JSON Schema for this user.
+      #: (server_context: untyped) -> Hash[Symbol, untyped]?
+      def dynamic_output_schema(server_context:)
+        McpAuthorization::RbsSchemaCompiler.compile_output(
+          _contract_handler,
+          server_context: server_context
+        )
+      end
+
+      # Check whether the current user is allowed to see this tool.
+      #: (untyped) -> bool
+      def permitted?(server_context)
+        return true if _permission.nil?
+        server_context.current_user.can?(_permission)
+      end
+
+      # Build the full MCP tool definition hash for +tools/list+.
+      # Returns nil if the user is not permitted.
+      #: (server_context: untyped) -> Hash[Symbol, untyped]?
+      def to_mcp_definition(server_context:)
+        return nil unless permitted?(server_context)
+        validate_contract!(_contract_handler) unless @_contract_validated
+        @_contract_validated = true
+
+        {
+          name: tool_name,
+          description: dynamic_description(server_context: server_context),
+          inputSchema: dynamic_input_schema(server_context: server_context),
+          outputSchema: dynamic_output_schema(server_context: server_context),
+          annotations: @_annotations_hash || {}
+        }
+      end
+
+      # Execute the tool by delegating to the handler.
+      #: (?server_context: untyped?, **untyped) -> untyped
+      def call(server_context: nil, **params)
+        raise NotAuthorizedError unless server_context && permitted?(server_context)
+        handler_instance(server_context).call(**params)
+      end
+
+      # Create an anonymous MCP::Tool subclass with this user's schemas baked in.
+      #: (untyped) -> Class?
+      def materialize_for(server_context)
+        defn = to_mcp_definition(server_context: server_context)
+        return nil unless defn
+
+        handler = _contract_handler
+        ctx = server_context
+
+        Class.new(MCP::Tool) do
+          tool_name defn[:name]
+          description defn[:description]
+          input_schema defn[:inputSchema]
+          output_schema defn[:outputSchema] if defn[:outputSchema]
+          annotations(**defn[:annotations]) if defn[:annotations]&.any?
+
+          define_singleton_method(:call) do |server_context: nil, **params|
+            effective_ctx = server_context || ctx
+            result = handler.new(server_context: effective_ctx).call(**params)
+            MCP::Tool::Response.new([ { type: "text", text: result.to_json } ])
+          end
+        end
+      end
+
+      private
+
+      #: (**untyped) -> void
+      def merge_annotations(**new_hints)
+        hints = (@_annotation_hints || {}).merge(new_hints)
+        @_annotation_hints = hints
+        annotations(**hints)
+      end
+
+      #: (untyped) -> untyped
+      def handler_instance(server_context)
+        _contract_handler.new(server_context: server_context)
+      end
+
+      #: (untyped) -> void
+      def validate_contract!(handler_class)
+        errors = []
+
+        unless handler_class.method_defined?(:call)
+          errors << "missing instance method #call"
+        end
+        unless handler_class.method_defined?(:description)
+          errors << "missing instance method #description"
+        end
+
+        init = handler_class.instance_method(:initialize) rescue nil
+        unless init&.parameters&.any? { |type, name| name == :server_context && type == :keyreq }
+          errors << "missing initialize(server_context:)"
+        end
+
+        source_file = McpAuthorization::RbsSchemaCompiler.send(:find_source_file, handler_class)
+        if source_file && File.exist?(source_file)
+          content = File.read(source_file)
+          has_input = content.include?("# @rbs type input =")
+          has_call_annotation = content.match?(/^\s*#:.*->/m)
+          has_output = content.include?("# @rbs type output =")
+
+          unless has_input || has_call_annotation
+            errors << "missing input schema (define #: annotation above def call, or # @rbs type input = { ... })"
+          end
+
+          unless has_output
+            errors << "missing output schema (define # @rbs type output = variant1 | variant2 | ...)"
+          end
+
+          if has_output
+            begin
+              cached = McpAuthorization::RbsSchemaCompiler.send(:cache_for, handler_class)
+              if cached[:raw_output]&.dig(:kind) == :union
+                primitives = %w[String Integer Float bool true false]
+                parts = cached[:raw_output][:body].split("|").map(&:strip).reject(&:empty?)
+                parts.each do |part|
+                  name = part.gsub(/\s*@\w+\([^)]*\)/, "").strip
+                  next if primitives.include?(name)
+                  next if cached[:type_map].key?(name)
+                  errors << "output variant '#{name}' does not resolve to a defined type (check @rbs type definitions and @rbs import statements)"
+                end
+              end
+            rescue => e
+              # Don't fail validation if cache isn't ready
+            end
+          end
+        elsif source_file.nil?
+          errors << "could not locate source file (is #call defined?)"
+        end
+
+        return if errors.empty?
+
+        raise ArgumentError, <<~MSG
+          #{handler_class} does not satisfy the McpAuthorization handler contract.
+
+          Problems:
+            #{errors.map { |e| "- #{e}" }.join("\n    ")}
+
+          A handler class should look like:
+
+            class MyHandler
+              include McpAuthorization::DSL
+
+              # @rbs type output = success | error
+
+              def description
+                "What this tool does"
+              end
+
+              #: (name: String, ?force: bool @requires(:admin)) -> Hash[Symbol, untyped]
+              def call(name:, force: false)
+                # ...
+              end
+            end
+        MSG
+      end
+    end
+  end
+end

data/lib/mcp_authorization/tool_registry.rb

@@ -0,0 +1,89 @@
+module McpAuthorization
+  # Global registry of all McpAuthorization::Tool subclasses.
+  #
+  # Tools self-register via the +inherited+ hook in Tool, so there is no
+  # manual registration step — defining a class that inherits from Tool is
+  # enough.
+  #
+  # The registry is the entry point for two main operations:
+  #
+  # * *Listing* — +list_tools+ returns JSON-serialisable tool definitions
+  #   filtered by domain and the current user's permissions.
+  #
+  # * *Materializing* — +tool_classes_for+ returns concrete MCP::Tool
+  #   subclasses with per-user schemas baked in, ready to be handed to an
+  #   MCP::Server for request handling.
+  #
+  class ToolRegistry
+    class << self
+      # Register a tool class. Called automatically by Tool.inherited.
+      #: (Class) -> void
+      def register(tool_class)
+        tools = (@registered_tools ||= [])
+        tools << tool_class unless tools.include?(tool_class)
+      end
+
+      # All registered tool classes. Triggers eager loading on first access.
+      #: () -> Array[singleton(McpAuthorization::Tool)]
+      def registered_tools
+        tools = (@registered_tools ||= [])
+        ensure_tools_loaded! if tools.empty?
+        tools
+      end
+
+      # Force-loads tool directories so tool classes self-register.
+      #: () -> void
+      def ensure_tools_loaded!
+        return if @registered_tools&.any?
+        return unless defined?(Rails)
+
+        McpAuthorization.config.tool_paths.each do |path|
+          full_path = Rails.root.join(path)
+          Rails.autoloaders.main.eager_load_dir(full_path) if File.directory?(full_path)
+        end
+      end
+
+      # Groups registered tools by their domain tags.
+      #: () -> Hash[String, Array[singleton(McpAuthorization::Tool)]]
+      def tools_by_domain
+        initial = Hash.new { |h, k| h[k] = [] } #: Hash[String, Array[singleton(McpAuthorization::Tool)]]
+        registered_tools.each_with_object(initial) do |tool_class, map|
+          (tool_class._tags || ["default"]).each do |tag|
+            map[tag] << tool_class
+          end
+        end
+      end
+
+      # Tool definitions for +tools/list+, filtered by domain and permissions.
+      #: (domain: String, server_context: untyped) -> Array[Hash[Symbol, untyped]]
+      def list_tools(domain:, server_context:)
+        candidates = tools_by_domain[domain] || []
+        candidates.filter_map do |tool_class|
+          tool_class.to_mcp_definition(server_context: server_context)
+        end
+      end
+
+      # Concrete MCP::Tool subclasses with per-user schemas baked in.
+      #: (domain: String, server_context: untyped) -> Array[singleton(MCP::Tool)]
+      def tool_classes_for(domain:, server_context:)
+        candidates = tools_by_domain[domain] || []
+        candidates.filter_map do |tool_class|
+          next unless tool_class.permitted?(server_context)
+          tool_class.materialize_for(server_context)
+        end
+      end
+
+      # Look up a tool by its MCP tool name across all domains.
+      #: (String) -> singleton(McpAuthorization::Tool)?
+      def find_tool(name)
+        registered_tools.find { |t| t.tool_name == name }
+      end
+
+      # Clear the registry. Called by the Engine's reloader on code change.
+      #: () -> void
+      def reset!
+        @registered_tools = []
+      end
+    end
+  end
+end

data/lib/mcp_authorization/version.rb

@@ -0,0 +1,3 @@
+module McpAuthorization
+  VERSION = "0.1.0"
+end

data/lib/mcp_authorization.rb

@@ -0,0 +1,57 @@
+require "mcp"
+require_relative "mcp_authorization/version"
+require_relative "mcp_authorization/configuration"
+require_relative "mcp_authorization/dsl"
+require_relative "mcp_authorization/rbs_schema_compiler"
+require_relative "mcp_authorization/tool_registry"
+require_relative "mcp_authorization/tool"
+require_relative "mcp_authorization/engine" if defined?(Rails)
+
+# MCP Authorization — schema-shaping authorization for MCP tool servers.
+#
+# Instead of rejecting unauthorized requests after the fact, this gem shapes
+# the JSON Schema that each user sees so that fields and output variants they
+# are not permitted to use never appear in the schema at all. The LLM (or
+# any MCP client) therefore never knows those options exist.
+#
+# == Quick start (Rails)
+#
+#   # config/initializers/mcp_authorization.rb
+#   McpAuthorization.configure do |c|
+#     c.server_name    = "my-app"
+#     c.server_version = "1.0.0"
+#     c.context_builder = ->(request) {
+#       ServerContext.new(current_user: current_user_from(request))
+#     }
+#   end
+#
+# == How it works
+#
+# 1. Tool classes inherit from McpAuthorization::Tool and declare a handler
+#    class via +dynamic_contract+.
+# 2. Handler classes use +@rbs type+ comments and +#:+ annotations to define
+#    input/output schemas. Fields can be tagged with +@requires(:flag)+ to
+#    gate them on user permissions.
+# 3. On each request the RbsSchemaCompiler compiles a per-user JSON Schema
+#    by filtering out fields whose +@requires+ flag the user lacks.
+# 4. A fresh set of MCP::Tool subclasses is materialized with the filtered
+#    schemas baked in, and handed to a stateless MCP::Server.
+#
+# See CLAUDE.md for the full architecture walkthrough.
+module McpAuthorization
+  class << self
+    # Yields the global Configuration instance for block-style setup.
+    #: () { (Configuration) -> void } -> void
+    def configure
+      yield configuration
+    end
+
+    # Returns the global Configuration instance, creating it with defaults
+    # on first access.
+    #: () -> Configuration
+    def configuration
+      @configuration ||= Configuration.new
+    end
+    alias_method :config, :configuration
+  end
+end

data/lib/tasks/mcp_authorization.rake

@@ -0,0 +1,99 @@
+namespace :mcp do
+  desc "Start Rails server and MCP Inspector for a given domain and role"
+  task :inspect, [ :domain, :role ] => :environment do |_t, args|
+    domain = args[:domain] || McpAuthorization.config.default_domain
+    role = args[:role] || "operator"
+    port = ENV.fetch("PORT", "3000")
+    mount = McpAuthorization.config.mount_path || "/mcp"
+    url = "http://localhost:#{port}#{mount}/#{domain}"
+
+    puts "Starting MCP Inspector"
+    puts "  Domain:  #{domain}"
+    puts "  Role:    #{role}"
+    puts "  URL:     #{url}"
+    puts ""
+
+    config = {
+      mcpServers: {
+        McpAuthorization.config.server_name => {
+          url: url,
+          headers: { "Authorization" => role }
+        }
+      }
+    }
+    config_path = Rails.root.join("tmp/mcp_inspector.json")
+    File.write(config_path, JSON.pretty_generate(config))
+
+    rails_pid = spawn(
+      "bundle exec rails server -p #{port}",
+      out: File::NULL, err: File::NULL
+    )
+
+    sleep 3
+
+    begin
+      exec(
+        "npx", "@modelcontextprotocol/inspector",
+        "--config", config_path.to_s,
+        "--server", McpAuthorization.config.server_name
+      )
+    ensure
+      Process.kill("TERM", rails_pid) rescue nil
+    end
+  end
+
+  desc "Print Claude Code MCP config for a given domain and role"
+  task :claude, [ :domain, :role ] => :environment do |_t, args|
+    domain = args[:domain] || McpAuthorization.config.default_domain
+    role = args[:role] || "operator"
+    port = ENV.fetch("PORT", "3000")
+    mount = McpAuthorization.config.mount_path || "/mcp"
+    url = "http://localhost:#{port}#{mount}/#{domain}"
+
+    config = {
+      "mcpServers" => {
+        "#{McpAuthorization.config.server_name}-#{domain}" => {
+          "url" => url,
+          "headers" => { "Authorization" => role }
+        }
+      }
+    }
+
+    puts "Add this to your Claude Code settings (~/.claude/settings.json):"
+    puts ""
+    puts JSON.pretty_generate(config)
+    puts ""
+    puts "Make sure Rails is running: bundle exec rails server -p #{port}"
+  end
+
+  desc "List available tools for a domain and role"
+  task :tools, [ :domain, :role ] => :environment do |_t, args|
+    require "json"
+    domain = args[:domain] || McpAuthorization.config.default_domain
+    role = args[:role] || "operator"
+
+    builder = McpAuthorization.config.cli_context_builder
+    unless builder
+      puts "McpAuthorization.config.cli_context_builder is not configured."
+      puts "Set it in config/initializers/mcp_authorization.rb"
+      exit 1
+    end
+
+    ctx = builder.call(domain: domain, role: role)
+
+    tools = McpAuthorization::ToolRegistry.list_tools(domain: domain, server_context: ctx)
+
+    if tools.empty?
+      puts "No tools available for domain '#{domain}' with role '#{role}'"
+    else
+      tools.each do |tool|
+        puts "#{tool[:name]}"
+        puts "  #{tool[:description]}"
+        puts "  input:  #{tool[:inputSchema][:properties].keys.join(', ')}"
+        output_shapes = tool.dig(:outputSchema, :oneOf)&.map { |s| s[:properties]&.keys&.join(', ') }
+        puts "  output: #{output_shapes&.join(' | ')}" if output_shapes
+        puts ""
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification
+name: mcp_authorization
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Andy
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-04-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Add MCP tool serving to any Rails app. Write @rbs type annotations with
+  @requires(:flag) tags and the gem compiles per-user JSON Schema automatically. Feature
+  flags, permissions, and plan tiers all work through a single can?(:symbol) predicate.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- app/controllers/mcp_authorization/mcp_controller.rb
+- lib/mcp_authorization.rb
+- lib/mcp_authorization/configuration.rb
+- lib/mcp_authorization/dsl.rb
+- lib/mcp_authorization/engine.rb
+- lib/mcp_authorization/rbs_schema_compiler.rb
+- lib/mcp_authorization/tool.rb
+- lib/mcp_authorization/tool_registry.rb
+- lib/mcp_authorization/version.rb
+- lib/tasks/mcp_authorization.rake
+homepage:
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: Rails engine for MCP tools with per-request schema discrimination
+test_files: []