mcp_on_ruby 1.0.0 → 2.0.0

data/lib/generators/mcp_on_ruby/expose/expose_generator.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module McpOnRuby
+  module Generators
+    # rails generate mcp_on_ruby:expose orders index show
+    class ExposeGenerator < Rails::Generators::Base
+      WRITE_ACTIONS = %w[create update destroy].freeze
+      PARAM_ACTIONS = %w[create update].freeze
+      SKIPPED_COLUMNS = %w[created_at updated_at].freeze
+
+      COLUMN_TYPES = {
+        integer: "type: :integer", bigint: "type: :integer",
+        decimal: "type: :number", float: "type: :number",
+        boolean: "type: :boolean",
+        date: 'type: :string, format: "date"',
+        datetime: 'type: :string, format: "date-time"', timestamp: 'type: :string, format: "date-time"',
+        json: "type: :object", jsonb: "type: :object"
+      }.freeze
+
+      desc "Adds mcp_tool declarations for existing controller actions."
+
+      argument :controller, type: :string, banner: "CONTROLLER", desc: "Controller path, e.g. orders or admin/orders"
+      argument :actions, type: :array, banner: "ACTION ACTION", desc: "Actions to expose"
+
+      def add_declarations
+        unless File.exist?(File.join(destination_root, controller_file))
+          raise Thor::Error, "#{controller_file} does not exist"
+        end
+
+        pending = actions.reject { |action| declared?(action) }
+        return say_status(:identical, controller_file, :blue) if pending.empty?
+
+        inject_into_file controller_file, declarations(pending), after: class_line_pattern
+      end
+
+      private
+
+      def declarations(pending)
+        indent = "#{class_line[:indent]}  "
+        text = pending.map { |action| declaration(action).gsub(/^/, indent) }.join
+        following_line = source[class_line.end(0)..].lines.first.to_s.strip
+        following_line.empty? || following_line == "end" ? text : "#{text}\n"
+      end
+
+      def controller_file
+        "app/controllers/#{controller.underscore.delete_suffix("_controller")}_controller.rb"
+      end
+
+      def controller_class
+        "#{controller.underscore.delete_suffix("_controller").camelize}Controller"
+      end
+
+      # Matches `class ReportsController` as well as `class Admin::ReportsController`.
+      def class_line_pattern
+        /^(?<indent>[ \t]*)class (?:\w+::)*#{controller_class.demodulize}\b.*\n/
+      end
+
+      def class_line
+        @class_line ||= class_line_pattern.match(source) ||
+                        raise(Thor::Error, "#{controller_class} not found in #{controller_file}")
+      end
+
+      def source
+        File.read(File.join(destination_root, controller_file))
+      end
+
+      def declared?(action)
+        source.match?(/mcp_tool\s+:#{action}\b/)
+      end
+
+      def declaration(action)
+        line = %(mcp_tool :#{action}, description: "#{description(action)}")
+        line += ", write: true" if WRITE_ACTIONS.include?(action)
+        params = PARAM_ACTIONS.include?(action) ? model_params : nil
+        params ? "#{line} do\n#{params}end\n" : "#{line}\n"
+      end
+
+      def description(action)
+        resource = controller.split("/").last.humanize(capitalize: false)
+        record = resource.singularize
+        article = record.match?(/\A[aeiou]/i) ? "an" : "a"
+        {
+          "index" => "List #{resource}",
+          "show" => "Show one #{record} by id",
+          "create" => "Create #{article} #{record}",
+          "update" => "Update #{article} #{record}",
+          "destroy" => "Delete #{article} #{record}"
+        }.fetch(action) { "TODO: describe what #{action} does for the agent" }
+      end
+
+      # A params block built from the model's columns, when the controller has an ActiveRecord model.
+      def model_params
+        model = controller.split("/").last.classify.safe_constantize
+        return unless model.respond_to?(:columns_hash)
+
+        columns = model.columns_hash.except(model.primary_key, *SKIPPED_COLUMNS)
+        return if columns.empty?
+
+        lines = columns.map do |name, column|
+          "    param :#{name}, #{COLUMN_TYPES.fetch(column.type, "type: :string")}\n"
+        end
+        "  param :#{model.model_name.param_key}, required: true do\n#{lines.join}  end\n"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module McpOnRuby
+  module Generators
+    # rails generate mcp_on_ruby:install
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Adds the MCP on Ruby initializer and mounts the MCP endpoint at /mcp."
+
+      class_option :path, type: :string, default: "/mcp", desc: "Where to mount the MCP endpoint"
+
+      def create_initializer
+        template "initializer.rb", "config/initializers/mcp_on_ruby.rb"
+      end
+
+      def mount_engine
+        route %(mount McpOnRuby::Engine, at: "#{options[:path]}")
+      end
+
+      def show_next_steps
+        say <<~MESSAGE
+
+          MCP on Ruby is installed. Next:
+
+            1. Expose actions:   bin/rails generate mcp_on_ruby:expose orders index show
+            2. Review them:      bin/rails mcp:tools
+            3. Check the setup:  bin/rails mcp:doctor
+            4. Connect an agent: claude mcp add my-app -- bin/rails mcp:stdio
+
+        MESSAGE
+      end
+    end
+  end
+end

data/lib/generators/mcp_on_ruby/install/templates/initializer.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+McpOnRuby.configure do |config|
+  # Name and version reported to MCP clients.
+  # config.server_name    = "<%= Rails.application.class.module_parent_name.underscore.dasherize %>"
+  # config.server_version = "1.0.0"
+
+  # Guidance sent to agents when they connect.
+  # config.instructions = "Tools for <%= Rails.application.class.module_parent_name.titleize %>."
+
+  # Identity for local sessions started with `bin/rails mcp:stdio`.
+  # Devise / Warden apps: sign in as a user.
+  # config.stdio_user = -> { User.find_by!(email: ENV.fetch("MCP_USER")) }
+  # Token-authenticated APIs: send headers your app already accepts.
+  # config.stdio_headers = -> { { "Authorization" => "Bearer #{ENV.fetch("MCP_TOKEN")}" } }
+
+  # Set to false to hide and refuse every tool declared with `write: true`.
+  # config.allow_writes = true
+
+  # Browser origins allowed to call the HTTP endpoint (non-browser clients send no Origin).
+  # config.allowed_origins = ["https://app.example.com"]
+end

data/lib/mcp_on_ruby/call_context.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module McpOnRuby
+  # Who is calling and over which transport. Passed to tools through the MCP server context.
+  class CallContext
+    attr_reader :transport, :origin_env, :user, :headers
+
+    # A call that arrived over HTTP; the client's credentials are forwarded from its request.
+    def self.http(env)
+      new(transport: :http, origin_env: env)
+    end
+
+    # A call from a local stdio session, acting as the configured user and headers.
+    def self.stdio(configuration = McpOnRuby.configuration)
+      new(
+        transport: :stdio,
+        user: configuration.stdio_user&.call,
+        headers: configuration.stdio_headers&.call || {}
+      )
+    end
+
+    def initialize(transport:, origin_env: nil, user: nil, headers: {})
+      @transport = transport
+      @origin_env = origin_env
+      @user = user
+      @headers = headers.to_h
+    end
+  end
+end

data/lib/mcp_on_ruby/configuration.rb

@@ -1,74 +1,78 @@
 # frozen_string_literal: true
 
-require 'logger'
-
 module McpOnRuby
-  # Configuration class for MCP server
+  # Settings for the MCP endpoint, set in config/initializers/mcp_on_ruby.rb:
+  #
+  #   McpOnRuby.configure do |config|
+  #     config.server_name  = "my-app"
+  #     config.instructions = "Tools for managing orders."
+  #   end
   class Configuration
-    attr_accessor :log_level,
-                  :path,
-                  :authentication_required,
-                  :authentication_token,
-                  :allowed_origins,
-                  :localhost_only,
-                  :rate_limit_per_minute,
-                  :enable_sse,
-                  :request_timeout,
-                  :cors_enabled,
-                  :dns_rebinding_protection
+    DEFAULT_TOOL_NAME = ->(controller_path, action) { "#{controller_path.tr("/", "_")}_#{action}" }
+
+    # Name reported to MCP clients. Defaults to the Rails application name.
+    attr_writer :server_name
+
+    # Version reported to MCP clients.
+    attr_accessor :server_version
+
+    # Server-level guidance sent to agents when they connect.
+    attr_accessor :instructions
+
+    # Callable returning the user that `bin/rails mcp:stdio` sessions act as (Warden/Devise apps).
+    attr_accessor :stdio_user
+
+    # Callable returning extra request headers for `bin/rails mcp:stdio` sessions (token-based apps).
+    attr_accessor :stdio_headers
+
+    # Warden scope used to sign in `stdio_user`.
+    attr_accessor :warden_scope
+
+    # Set to false to hide and refuse every tool declared with `write: true`.
+    attr_accessor :allow_writes
+
+    # Additional MCP::Tool classes served alongside controller tools.
+    attr_accessor :tools
+
+    # Browser origins allowed to call the HTTP endpoint.
+    attr_accessor :allowed_origins
+
+    # Maximum size of an MCP request body, in bytes.
+    attr_accessor :max_request_bytes
+
+    # Builds a tool's default name from its controller path and action.
+    attr_reader :tool_name
 
     def initialize
-      @log_level = Logger::INFO
-      @path = '/mcp'
-      @authentication_required = false
-      @authentication_token = nil
+      @server_name = nil
+      @server_version = nil
+      @instructions = nil
+      @stdio_user = nil
+      @stdio_headers = nil
+      @warden_scope = :user
+      @allow_writes = true
+      @tools = []
       @allowed_origins = []
-      @localhost_only = false
-      @rate_limit_per_minute = 60
-      @enable_sse = true
-      @request_timeout = 30
-      @cors_enabled = true
-      @dns_rebinding_protection = true
+      @max_request_bytes = 4 * 1024 * 1024
+      @tool_name = DEFAULT_TOOL_NAME
     end
 
-    # Check if authentication is configured
-    # @return [Boolean] True if authentication is properly configured
-    def authentication_configured?
-      authentication_required && !authentication_token.nil?
+    def tool_name=(callable)
+      raise ArgumentError, "tool_name must respond to #call" unless callable.respond_to?(:call)
+
+      @tool_name = callable
     end
 
-    # Check if origin is allowed
-    # @param origin [String] The origin to check
-    # @return [Boolean] True if origin is allowed
-    def origin_allowed?(origin)
-      return true if allowed_origins.empty?
-      
-      allowed_origins.any? do |allowed|
-        case allowed
-        when String
-          origin == allowed
-        when Regexp
-          origin =~ allowed
-        else
-          false
-        end
-      end
+    def server_name
+      @server_name || default_server_name
     end
 
-    # Check if localhost only mode and origin is localhost
-    # @param origin [String] The origin to check
-    # @return [Boolean] True if localhost only and origin is localhost
-    def localhost_allowed?(origin)
-      return true unless localhost_only
-      
-      localhost_patterns = [
-        'http://localhost',
-        'https://localhost',
-        'http://127.0.0.1',
-        'https://127.0.0.1'
-      ]
-      
-      localhost_patterns.any? { |pattern| origin&.start_with?(pattern) }
+    private
+
+    def default_server_name
+      return "rails-app" unless defined?(Rails) && Rails.application
+
+      Rails.application.class.module_parent_name.underscore.dasherize
     end
   end
-end
+end

data/lib/mcp_on_ruby/controller.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module McpOnRuby
+  # Included into every Rails controller by the engine.
+  #
+  #   class OrdersController < ApplicationController
+  #     mcp_tool :index, description: "Search orders", params: { status: :string }
+  #     mcp_tool :update, description: "Update an order", write: true
+  #   end
+  module Controller
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :mcp_declarations, instance_accessor: false, default: {}.freeze
+      helper_method :mcp_request? if respond_to?(:helper_method)
+    end
+
+    class_methods do
+      # Exposes an action of this controller as an MCP tool.
+      #
+      # @param action [Symbol] the controller action
+      # @param description [String] what the tool does, written for the agent
+      # @param title [String] optional human-readable name
+      # @param name [String] tool name; defaults to "<controller>_<action>"
+      # @param params [Hash] parameter schema, see McpOnRuby::Schema
+      # @param write [Boolean] required for actions routed with POST, PUT, PATCH, or DELETE
+      # @param annotations [Hash] overrides for the hints derived from the HTTP verb
+      def mcp_tool(action, **, &)
+        declaration = Declaration.new(action:, **, &)
+        self.mcp_declarations = mcp_declarations.merge(declaration.action => declaration).freeze
+        declaration
+      end
+    end
+
+    # True while this action is running because an MCP client called it.
+    def mcp_request?
+      request.env.key?(McpOnRuby::TOOL_ENV_KEY)
+    end
+
+    # The name of the MCP tool being called, or nil outside MCP requests.
+    def mcp_tool_name
+      request.env[McpOnRuby::TOOL_ENV_KEY]
+    end
+
+    # The user a local `bin/rails mcp:stdio` session acts as, from `config.stdio_user`.
+    # Apps without Warden can use this in their own authentication filter.
+    def mcp_user
+      request.env[McpOnRuby::USER_ENV_KEY]
+    end
+
+    private
+
+    # Requests dispatched by an MCP tool call pass CSRF verification. They cannot be forged
+    # cross-site: the flag lives in the Rack env and is set only by the dispatcher, and the MCP
+    # endpoint itself rejects requests from foreign browser origins.
+    def verified_request?
+      mcp_request? || super
+    end
+  end
+end

data/lib/mcp_on_ruby/declaration.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module McpOnRuby
+  # What a controller declared with `mcp_tool`, before it is matched to a route.
+  class Declaration
+    attr_reader :action, :description, :title, :name, :input_schema, :annotations
+
+    def initialize(action:, description:, title: nil, name: nil, params: {}, write: false, annotations: {}, &)
+      @action = action.to_s
+      @description = description.to_s.strip
+      @title = title
+      @name = name&.to_s
+      @write = write ? true : false
+      @annotations = annotations.to_h.transform_keys(&:to_sym)
+      @input_schema = Schema.build(params, &)
+
+      raise ArgumentError, "mcp_tool :#{@action} needs a description" if @description.empty?
+    end
+
+    def write?
+      @write
+    end
+  end
+end

data/lib/mcp_on_ruby/dispatcher.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "rack/mock"
+
+module McpOnRuby
+  # Runs a tool call as an in-process request through the full Rails stack:
+  # middleware, routes, filters, and the controller action itself.
+  class Dispatcher
+    # Headers copied from the MCP client's HTTP request so the app sees the same caller.
+    FORWARDED_HEADERS = %w[
+      HTTP_AUTHORIZATION HTTP_COOKIE HTTP_USER_AGENT HTTP_ACCEPT_LANGUAGE HTTP_X_REQUEST_ID
+      HTTP_X_FORWARDED_FOR HTTP_X_FORWARDED_PROTO HTTP_X_FORWARDED_HOST REMOTE_ADDR
+    ].freeze
+
+    EVENT = "tool_call.mcp_on_ruby"
+
+    def initialize(app: nil)
+      @app = app
+    end
+
+    # @return [MCP::Tool::Response]
+    def call(spec, arguments, context)
+      payload = { tool: spec.name, controller: spec.controller.name, action: spec.action,
+                  transport: context.transport }
+
+      ActiveSupport::Notifications.instrument(EVENT, payload) do
+        status, response = dispatch(spec, arguments, context)
+        payload[:status] = status
+        payload[:error] = response.error?
+        response
+      end
+    end
+
+    private
+
+    def app
+      @app || Rails.application
+    end
+
+    def dispatch(spec, arguments, context)
+      status, headers, body = app.call(build_env(spec, arguments, context))
+      [status, Result.from_rack(status, headers, body)]
+    rescue StandardError => e
+      Rails.error.report(e, handled: true, context: { mcp_tool: spec.name })
+      [500, Result.internal_error]
+    end
+
+    def build_env(spec, arguments, context)
+      arguments = arguments.deep_stringify_keys
+      path_values = spec.path_params.to_h { |param| [param.to_sym, arguments.delete(param)] }
+      read = ToolSpec::READ_VERBS.include?(spec.verb)
+      path = path_for(spec, path_values.merge(read ? arguments.symbolize_keys : {}))
+
+      host = host(context)
+      env = Rack::MockRequest.env_for(
+        "#{scheme(context)}://#{host}#{path}",
+        method: spec.verb,
+        input: read ? "" : JSON.generate(arguments),
+        "CONTENT_TYPE" => "application/json",
+        "HTTP_ACCEPT" => "application/json",
+        "HTTP_HOST" => host
+      )
+      apply_identity(env, context)
+      env[TOOL_ENV_KEY] = spec.name
+      env
+    end
+
+    def path_for(spec, params)
+      app.routes.path_for(controller: spec.controller_path, action: spec.action, **params)
+    end
+
+    def apply_identity(env, context)
+      context.origin_env&.slice(*FORWARDED_HEADERS)&.each { |key, value| env[key] = value }
+      context.headers.each { |name, value| env[rack_header(name)] = value.to_s }
+      env[USER_ENV_KEY] = context.user if context.user
+    end
+
+    def rack_header(name)
+      "HTTP_#{name.to_s.upcase.tr("-", "_")}"
+    end
+
+    def host(context)
+      context.origin_env&.fetch("HTTP_HOST", nil) || local_host
+    end
+
+    # Host for stdio sessions: one the app's host authorization already accepts.
+    def local_host
+      app.routes.default_url_options[:host] ||
+        app.config.hosts.find { |host| host.is_a?(String) && !host.start_with?(".") } ||
+        "localhost"
+    end
+
+    def scheme(context)
+      context.origin_env&.fetch("rack.url_scheme", nil) || "http"
+    end
+  end
+end

data/lib/mcp_on_ruby/doctor.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module McpOnRuby
+  # Checks an app's MCP setup for `bin/rails mcp:doctor`.
+  class Doctor
+    Check = Struct.new(:status, :message)
+
+    attr_reader :checks
+
+    def initialize(app: Rails.application, registry: McpOnRuby.registry, configuration: McpOnRuby.configuration)
+      @app = app
+      @registry = registry
+      @configuration = configuration
+      @checks = []
+    end
+
+    def run
+      check_mount
+      check_registry
+      check_stdio_identity
+      self
+    end
+
+    def ok?
+      checks.none? { |check| check.status == :fail }
+    end
+
+    def report
+      checks.map { |check| "#{check.status.to_s.upcase.ljust(4)}  #{check.message}" }.join("\n") << "\n"
+    end
+
+    private
+
+    def pass(message) = checks << Check.new(:ok, message)
+    def warn(message) = checks << Check.new(:warn, message)
+    def fail(message) = checks << Check.new(:fail, message)
+
+    def check_mount
+      route = @app.routes.routes.find { |candidate| candidate.app.app == McpOnRuby::Engine }
+      if route
+        pass("Engine mounted at #{route.path.spec.to_s.delete_suffix("(.:format)")}")
+      else
+        warn('Engine is not mounted; add `mount McpOnRuby::Engine, at: "/mcp"` to config/routes.rb for HTTP clients')
+      end
+    end
+
+    def check_registry
+      specs = @registry.tools
+      if specs.empty?
+        warn("No tools are exposed yet; add `mcp_tool` declarations to your controllers")
+      else
+        writes = specs.count(&:write?)
+        pass("#{specs.size} tools exposed (#{specs.size - writes} read-only, #{writes} write)")
+      end
+    rescue ConfigurationError => e
+      fail(e.message)
+    end
+
+    def check_stdio_identity
+      if @configuration.stdio_user || @configuration.stdio_headers
+        pass("stdio sessions have an identity (#{@configuration.stdio_user ? "stdio_user" : "stdio_headers"})")
+      else
+        warn("No stdio identity: set config.stdio_user or config.stdio_headers to use `bin/rails mcp:stdio`")
+      end
+    end
+  end
+end

data/lib/mcp_on_ruby/endpoint.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module McpOnRuby
+  # The Rack app behind `mount McpOnRuby::Engine, at: "/mcp"`.
+  #
+  # Each request gets its own stateless Streamable HTTP transport and server, so tools run as the
+  # caller whose credentials arrived with that request, and any process can serve any request.
+  class Endpoint
+    def initialize(factory: nil, configuration: nil)
+      @factory = factory
+      @configuration = configuration
+    end
+
+    def call(env)
+      server = factory.build(CallContext.http(env))
+      transport(server, Rack::Request.new(env)).call(env)
+    end
+
+    private
+
+    def factory
+      @factory || McpOnRuby.server_factory
+    end
+
+    def configuration
+      @configuration || McpOnRuby.configuration
+    end
+
+    # Rails' host authorization has already accepted this request's Host, so the transport only needs
+    # to enforce the Origin check that protects local servers from malicious web pages.
+    def transport(server, request)
+      MCP::Server::Transports::StreamableHTTPTransport.new(
+        server,
+        stateless: true,
+        enable_json_response: true,
+        serve_subscriptions_listen: false,
+        allowed_hosts: [request.host, request.host_with_port].uniq,
+        allowed_origins: configuration.allowed_origins,
+        max_request_bytes: configuration.max_request_bytes
+      )
+    end
+  end
+end

data/lib/mcp_on_ruby/engine.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+
+module McpOnRuby
+  # Mount in config/routes.rb:
+  #
+  #   mount McpOnRuby::Engine, at: "/mcp"
+  class Engine < ::Rails::Engine
+    isolate_namespace McpOnRuby
+
+    initializer "mcp_on_ruby.controller" do
+      ActiveSupport.on_load(:action_controller) do
+        include McpOnRuby::Controller
+      end
+    end
+
+    # Controllers and routes can change on reload; resolve tools again on next use.
+    config.to_prepare do
+      McpOnRuby.registry.reset!
+    end
+
+    # Fail at boot, not on the first agent request, when declarations do not match routes.
+    config.after_initialize do |app|
+      McpOnRuby::WardenHook.install!
+      McpOnRuby.registry.tools if app.config.eager_load
+    end
+  end
+end