mcp_on_ruby 1.0.0 → 2.0.0

data/lib/mcp_on_ruby/registry.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module McpOnRuby
+  # Matches `mcp_tool` declarations to the application's routes and validates them.
+  #
+  # Tools are resolved lazily and cached until #reset!, which the engine calls on every code reload.
+  class Registry
+    WRITE_VERB_PREFERENCE = %w[PATCH PUT POST DELETE].freeze
+
+    # @param routes [ActionDispatch::Routing::RouteSet] defaults to the application's routes
+    # @param configuration [McpOnRuby::Configuration] defaults to McpOnRuby.configuration
+    # @param root [String, Pathname] only controllers defined under this directory are checked for
+    #   declarations without a route; defaults to Rails.root
+    def initialize(routes: nil, configuration: nil, root: nil)
+      @routes = routes
+      @configuration = configuration
+      @root = root
+      @mutex = Mutex.new
+      @tools = nil
+    end
+
+    # All exposed tools, including write tools.
+    def tools
+      @tools || @mutex.synchronize { @tools ||= build }
+    end
+
+    def find(name)
+      tools.find { |tool| tool.name == name }
+    end
+
+    def reset!
+      @mutex.synchronize { @tools = nil }
+    end
+
+    private
+
+    def routes
+      @routes || Rails.application.routes
+    end
+
+    def configuration
+      @configuration || McpOnRuby.configuration
+    end
+
+    def build
+      tools = routed_actions.filter_map do |(controller, action), route_list|
+        declaration = controller.mcp_declarations[action]
+        build_tool(controller, declaration, route_list) if declaration
+      end
+
+      check_unrouted_declarations!(tools)
+      check_unique_names!(tools)
+      tools.sort_by(&:name).freeze
+    end
+
+    # { [controller_class, action] => [routes...] } for every routed controller action.
+    def routed_actions
+      routes.routes.each_with_object({}) do |route, actions|
+        controller = controller_for(route)
+        next unless controller
+
+        (actions[[controller, route.defaults[:action].to_s]] ||= []) << route
+      end
+    end
+
+    def controller_for(route)
+      path = route.defaults[:controller]
+      return unless path && route.defaults[:action]
+
+      controller = "#{path.camelize}Controller".safe_constantize
+      controller if controller.respond_to?(:mcp_declarations)
+    end
+
+    def build_tool(controller, declaration, route_list)
+      route = pick_route(route_list)
+      verb = verb_for(route)
+
+      if !ToolSpec::READ_VERBS.include?(verb) && !declaration.write?
+        raise ConfigurationError,
+              "#{controller.name}##{declaration.action} is routed as #{verb}; " \
+              "add `write: true` to its mcp_tool declaration to expose it"
+      end
+
+      ToolSpec.new(
+        name: declaration.name || configuration.tool_name.call(controller.controller_path, declaration.action),
+        controller:, action: declaration.action, verb:,
+        path: route.path.spec.to_s.delete_suffix("(.:format)"),
+        path_params: route.required_parts.map(&:to_s) - ["format"],
+        declaration:
+      )
+    end
+
+    # Prefers a read route; among write routes prefers PATCH over PUT, as Rails' resources do.
+    def pick_route(route_list)
+      route_list.min_by do |route|
+        verb = verb_for(route)
+        ToolSpec::READ_VERBS.include?(verb) ? -1 : WRITE_VERB_PREFERENCE.index(verb) || WRITE_VERB_PREFERENCE.size
+      end
+    end
+
+    def verb_for(route)
+      verbs = route.verb.to_s.split("|").map(&:upcase)
+      return "GET" if verbs.empty? || verbs.include?("GET")
+
+      verbs.first
+    end
+
+    def check_unrouted_declarations!(tools)
+      exposed = tools.to_set { |tool| [tool.controller, tool.action] }
+
+      declaring_controllers.each do |controller|
+        controller.mcp_declarations.each_key do |action|
+          next if exposed.include?([controller, action]) || inherited_and_routed_elsewhere?(controller, action, exposed)
+
+          raise ConfigurationError,
+                "#{controller.name} declares mcp_tool :#{action}, but no route points to #{controller.name}##{action}"
+        end
+      end
+    end
+
+    # Loaded controllers with declarations whose source lives in the application, not in gems or engines.
+    def declaring_controllers
+      root = (@root || Rails.root).to_s
+      [ActionController::Base, ActionController::API].flat_map(&:descendants).select do |controller|
+        next false unless controller.name && controller.mcp_declarations.any?
+
+        Object.const_source_location(controller.name)&.first.to_s.start_with?(root)
+      end
+    end
+
+    # Base controllers may declare tools that only their routed subclasses serve.
+    def inherited_and_routed_elsewhere?(controller, action, exposed)
+      exposed.any? { |klass, routed_action| routed_action == action && klass < controller }
+    end
+
+    def check_unique_names!(tools)
+      tools.group_by(&:name).each do |name, duplicates|
+        next if duplicates.one?
+
+        actions = duplicates.map { |tool| "#{tool.controller.name}##{tool.action}" }.join(" and ")
+        raise ConfigurationError,
+              "tool name #{name.inspect} is used by #{actions}; pass name: to mcp_tool to disambiguate"
+      end
+    end
+  end
+end

data/lib/mcp_on_ruby/result.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module McpOnRuby
+  # Turns the controller's Rack response into an MCP tool result an agent can act on.
+  module Result
+    JSON_TYPE = %r{\Aapplication/(?:[\w.+-]+\+)?json\b}i
+    HTML_TYPE = %r{\Atext/html\b}i
+
+    module_function
+
+    def from_rack(status, headers, body)
+      text = read(body)
+      content_type = header(headers, "content-type").to_s
+      json = parse_json(text) if content_type.match?(JSON_TYPE)
+
+      case status
+      when 200..299 then success(status, text, json, content_type)
+      when 300..399 then error(status, "Redirected to #{header(headers, "location") || "another page"}; " \
+                                       "redirects are not followed")
+      when 400..499 then client_error(status, text, json)
+      else error(status, "Internal server error (#{status})")
+      end
+    end
+
+    def internal_error
+      error(500, "Internal server error (500)")
+    end
+
+    def success(status, text, json, content_type)
+      return text_response("Success (#{status}), no content") if text.empty?
+      return MCP::Tool::Response.new([text_block(text)], structured_content: json) unless json.nil?
+      if content_type.match?(HTML_TYPE)
+        return error(status, "The action responded with HTML; render JSON for MCP tools")
+      end
+
+      text_response(text)
+    end
+
+    def client_error(status, text, json)
+      message = {
+        401 => "Not authenticated (401)",
+        403 => "Not permitted (403)",
+        404 => "Not found (404)",
+        422 => "Unprocessable (422)"
+      }.fetch(status) { "Request failed (#{status})" }
+
+      detail = json.nil? ? nil : text
+      error(status, [message, detail].compact.join(": "), json)
+    end
+
+    def error(status, message, body = nil)
+      structured = { "status" => status }
+      structured["body"] = body unless body.nil?
+      MCP::Tool::Response.new([text_block(message)], structured_content: structured, error: true)
+    end
+
+    def text_response(text)
+      MCP::Tool::Response.new([text_block(text)])
+    end
+
+    def text_block(text)
+      { type: "text", text: }
+    end
+
+    def read(body)
+      text = +""
+      body.each { |chunk| text << chunk.to_s }
+      text
+    ensure
+      body.close if body.respond_to?(:close)
+    end
+
+    def header(headers, name)
+      headers[name] || headers.find { |key, _| key.to_s.casecmp?(name) }&.last
+    end
+
+    def parse_json(text)
+      JSON.parse(text) unless text.empty?
+    rescue JSON::ParserError
+      nil
+    end
+  end
+end

data/lib/mcp_on_ruby/rspec.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "mcp_on_ruby"
+require "mcp_on_ruby/test_helper"
+
+RSpec.configure do |config|
+  config.include McpOnRuby::TestHelper
+end

data/lib/mcp_on_ruby/schema.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module McpOnRuby
+  # Builds the JSON Schema for a tool's input from a compact Ruby DSL.
+  #
+  #   Schema.build(q: :string, status: { type: :string, enum: %w[paid pending], required: true })
+  #
+  #   Schema.build do
+  #     param :order, type: :object, required: true do
+  #       param :sku, type: :string, required: true
+  #       param :quantity, type: :integer, minimum: 1
+  #     end
+  #   end
+  class Schema
+    TYPES = %w[string integer number boolean array object null].freeze
+
+    # Ruby-style option names and the JSON Schema keywords they map to.
+    KEYWORDS = {
+      description: :description,
+      title: :title,
+      enum: :enum,
+      const: :const,
+      default: :default,
+      examples: :examples,
+      format: :format,
+      pattern: :pattern,
+      minimum: :minimum,
+      maximum: :maximum,
+      exclusive_minimum: :exclusiveMinimum,
+      exclusive_maximum: :exclusiveMaximum,
+      multiple_of: :multipleOf,
+      min_length: :minLength,
+      max_length: :maxLength,
+      min_items: :minItems,
+      max_items: :maxItems,
+      unique_items: :uniqueItems
+    }.freeze
+
+    def self.build(params = {}, &)
+      new.tap do |schema|
+        schema.params(params)
+        schema.instance_eval(&) if block_given?
+      end.to_h
+    end
+
+    def initialize
+      @properties = {}
+      @required = []
+    end
+
+    # Declares several parameters from a hash of `name => type` or `name => options`.
+    def params(definitions)
+      definitions.each do |name, definition|
+        case definition
+        when Hash then param(name, **definition)
+        else param(name, type: definition)
+        end
+      end
+      self
+    end
+
+    # Declares a single parameter. A block describes the properties of an object,
+    # or of the objects inside an array.
+    def param(name, type: nil, required: false, nullable: false, items: nil, **options, &)
+      name = name.to_s
+      raise ArgumentError, "parameter #{name.inspect} is declared twice" if @properties.key?(name)
+
+      type ||= "object" if block_given?
+      raise ArgumentError, "parameter #{name.inspect} needs a type" unless type
+
+      @properties[name] = property(name, type, nullable:, items:, options:, &)
+      @required << name if required
+      self
+    end
+
+    def to_h
+      schema = { type: "object", properties: @properties }
+      schema[:required] = @required unless @required.empty?
+      schema
+    end
+
+    private
+
+    def property(name, type, nullable:, items:, options:, &)
+      types = json_types(name, type, nullable)
+      schema = type_schema(types)
+      schema.merge!(keywords(name, options))
+      schema.merge!(nested(name, types, items, &))
+      schema
+    end
+
+    def json_types(name, type, nullable)
+      types = Array(type).map(&:to_s)
+      unknown = types - TYPES
+      raise ArgumentError, "parameter #{name.inspect} has unknown type #{unknown.join(", ")}" if unknown.any?
+
+      types << "null" if nullable && !types.include?("null")
+      types
+    end
+
+    # Several types become `anyOf` branches rather than a `type` array, which some model
+    # providers' schema dialects reject.
+    def type_schema(types)
+      types.one? ? { type: types.first } : { anyOf: types.map { |type| { type: } } }
+    end
+
+    def keywords(name, options)
+      options.each_with_object({}) do |(option, value), schema|
+        keyword = KEYWORDS.fetch(option) do
+          raise ArgumentError, "parameter #{name.inspect} has unknown option #{option.inspect}"
+        end
+        schema[keyword] = value
+      end
+    end
+
+    def nested(name, types, items, &)
+      if types.include?("array")
+        array_items(name, items, &)
+      elsif block_given?
+        unless types.include?("object")
+          raise ArgumentError, "parameter #{name.inspect} takes a block only as an object or array"
+        end
+
+        nested_object(&)
+      else
+        {}
+      end
+    end
+
+    def array_items(name, items, &)
+      raise ArgumentError, "parameter #{name.inspect} takes either items: or a block, not both" if items && block_given?
+
+      return { items: { type: "object" }.merge(nested_object(&)) } if block_given?
+      return {} unless items
+
+      { items: items.is_a?(Hash) ? item_schema(name, **items) : type_schema(json_types(name, items, false)) }
+    end
+
+    def item_schema(name, type:, nullable: false, **options)
+      type_schema(json_types(name, type, nullable)).merge(keywords(name, options))
+    end
+
+    def nested_object(&)
+      object = self.class.new
+      object.instance_eval(&)
+      object.to_h.except(:type)
+    end
+  end
+end

data/lib/mcp_on_ruby/server_factory.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module McpOnRuby
+  # Builds the official MCP::Server for one caller, serving the registry's tools.
+  class ServerFactory
+    CONTEXT_KEY = :mcp_on_ruby
+
+    def initialize(registry: nil, configuration: nil, dispatcher: nil)
+      @registry = registry
+      @configuration = configuration
+      @dispatcher = dispatcher
+      @mutex = Mutex.new
+    end
+
+    # @param context [McpOnRuby::CallContext] who is calling; tools dispatch as this caller
+    # @return [MCP::Server]
+    def build(context)
+      options = {
+        name: configuration.server_name,
+        instructions: configuration.instructions,
+        tools: mcp_tools + Array(configuration.tools),
+        server_context: { CONTEXT_KEY => context }
+      }
+      options[:version] = configuration.server_version if configuration.server_version
+      MCP::Server.new(**options.compact)
+    end
+
+    # The tool specs currently served, honoring `allow_writes`.
+    def served_specs
+      specs = registry.tools
+      configuration.allow_writes ? specs : specs.reject(&:write?)
+    end
+
+    private
+
+    def registry
+      @registry || McpOnRuby.registry
+    end
+
+    def configuration
+      @configuration || McpOnRuby.configuration
+    end
+
+    def dispatcher
+      @dispatcher ||= Dispatcher.new
+    end
+
+    # Tool classes are rebuilt only when the registry is (on boot and code reload).
+    def mcp_tools
+      specs = served_specs
+      @mutex.synchronize do
+        @cache = [specs, specs.map { |spec| spec.to_mcp_tool(handler) }] unless @cache&.first.equal?(specs)
+        @cache.last
+      end
+    end
+
+    def handler
+      @handler ||= lambda do |spec, arguments, server_context|
+        context = server_context && server_context[CONTEXT_KEY]
+        raise Error, "tool #{spec.name} was called without a McpOnRuby::CallContext" unless context
+
+        dispatcher.call(spec, arguments, context)
+      end
+    end
+  end
+end

data/lib/mcp_on_ruby/stdio.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module McpOnRuby
+  # Serves the app's tools over stdio for local agents (Claude Code, Claude Desktop, Cursor, …).
+  #
+  # Started by `bin/rails mcp:stdio`. Protocol frames go to the original stdout; anything else the
+  # app prints, including loggers attached to STDOUT, is redirected to stderr so it cannot corrupt
+  # the stream.
+  module Stdio
+    # The SDK's stdio transport, writing frames to a dedicated IO instead of $stdout.
+    class Transport < MCP::Server::Transports::StdioTransport
+      def initialize(server, output:)
+        super(server)
+        @output = output
+      end
+
+      def send_response(message)
+        @output.puts(message.is_a?(String) ? message : JSON.generate(message))
+        @output.flush
+      end
+    end
+
+    module_function
+
+    def run(configuration: McpOnRuby.configuration, factory: McpOnRuby.server_factory)
+      output = $stdout.dup
+      $stdout.reopen($stderr)
+
+      context = CallContext.stdio(configuration)
+      warn_without_identity(context)
+      factory.served_specs # fail fast on invalid declarations
+      Transport.new(factory.build(context), output:).open
+    end
+
+    def warn_without_identity(context)
+      return if context.user || context.headers.any?
+
+      warn "[mcp_on_ruby] No stdio identity configured; tools run unauthenticated. " \
+           "Set config.stdio_user or config.stdio_headers in config/initializers/mcp_on_ruby.rb."
+    end
+  end
+end

data/lib/mcp_on_ruby/test_helper.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module McpOnRuby
+  # Test helpers for apps using MCP on Ruby. Calls go through the real MCP server and your real
+  # controllers, so schema, authentication, and authorization mistakes all surface in tests.
+  #
+  # Minitest:
+  #   class ActiveSupport::TestCase
+  #     include McpOnRuby::TestHelper
+  #   end
+  #
+  # RSpec:
+  #   require "mcp_on_ruby/rspec"
+  module TestHelper
+    # The outcome of a tool call made in a test.
+    class Result
+      attr_reader :response
+
+      def initialize(response)
+        @response = response
+      end
+
+      def success?
+        !error?
+      end
+
+      def error?
+        result["isError"] == true || response.key?("error")
+      end
+
+      # Parsed JSON the action rendered (or, for errors, `{ "status" => ..., "body" => ... }`).
+      def structured
+        result["structuredContent"]
+      end
+
+      # HTTP status of a failed call, e.g. 403. Nil for successful calls.
+      def status
+        structured["status"] if result["isError"] && structured.is_a?(Hash)
+      end
+
+      # Text content the agent sees.
+      def text
+        Array(result["content"]).filter_map { |block| block["text"] }.join("\n")
+      end
+
+      # JSON-RPC error message for protocol-level failures, such as an unknown tool or invalid arguments.
+      def protocol_error
+        response.dig("error", "data") || response.dig("error", "message")
+      end
+
+      def inspect
+        "#<#{self.class.name} #{error? ? "error" : "success"} #{text.inspect}>"
+      end
+
+      private
+
+      def result
+        response.fetch("result", {})
+      end
+    end
+
+    # Calls an MCP tool the way an agent would.
+    #
+    # @param tool [String, Symbol] tool name, e.g. :orders_index
+    # @param arguments [Hash] tool arguments
+    # @param as [Object] user to sign in through Warden/Devise (like `config.stdio_user`)
+    # @param headers [Hash] request headers, e.g. { "Authorization" => "Bearer token" }
+    # @return [McpOnRuby::TestHelper::Result]
+    def mcp_call(tool, arguments = {}, as: nil, headers: {})
+      Result.new(mcp_rpc("tools/call", { name: tool.to_s, arguments: }, as:, headers:))
+    end
+
+    # Names of the tools an agent can see.
+    def mcp_tools
+      mcp_rpc("tools/list", {}).dig("result", "tools").map { |tool| tool["name"] }
+    end
+
+    private
+
+    def mcp_rpc(method, params, as: nil, headers: {})
+      context = CallContext.new(transport: :test, user: as, headers:)
+      server = McpOnRuby.server_factory.build(context)
+      JSON.parse(server.handle_json(JSON.generate(jsonrpc: "2.0", id: 1, method:, params:)))
+    end
+  end
+end

data/lib/mcp_on_ruby/tool_spec.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module McpOnRuby
+  # A declared action matched to its route: everything needed to list the tool and dispatch calls to it.
+  class ToolSpec
+    READ_VERBS = %w[GET HEAD].freeze
+
+    HINTS = {
+      "GET" => { read_only_hint: true, destructive_hint: false, idempotent_hint: true },
+      "POST" => { read_only_hint: false, destructive_hint: false, idempotent_hint: false },
+      "PUT" => { read_only_hint: false, destructive_hint: true, idempotent_hint: true },
+      "PATCH" => { read_only_hint: false, destructive_hint: true, idempotent_hint: true },
+      "DELETE" => { read_only_hint: false, destructive_hint: true, idempotent_hint: true }
+    }.freeze
+
+    attr_reader :name, :controller, :action, :verb, :path, :path_params, :declaration
+
+    def initialize(name:, controller:, action:, verb:, path:, path_params:, declaration:)
+      @name = name
+      @controller = controller
+      @action = action
+      @verb = verb
+      @path = path
+      @path_params = path_params
+      @declaration = declaration
+    end
+
+    def controller_path
+      controller.controller_path
+    end
+
+    def description
+      declaration.description
+    end
+
+    def title
+      declaration.title
+    end
+
+    def write?
+      declaration.write? || !READ_VERBS.include?(verb)
+    end
+
+    # The declared parameters plus the route's path parameters, which are always required.
+    def input_schema
+      @input_schema ||= begin
+        schema = declaration.input_schema
+        path_properties = path_params.to_h { |param| [param, path_param_schema(param)] }
+        properties = path_properties.merge(schema[:properties])
+        required = (path_params + schema.fetch(:required, [])).uniq
+
+        { type: "object", properties: }.tap { |result| result[:required] = required if required.any? }
+      end
+    end
+
+    def annotations
+      hints = HINTS.fetch(READ_VERBS.include?(verb) ? "GET" : verb, HINTS["POST"])
+      hints = hints.merge(read_only_hint: false) if write?
+      { open_world_hint: false, title: }.compact.merge(hints).merge(declaration.annotations)
+    end
+
+    # Builds the MCP::Tool class served for this spec. Calls are forwarded to the handler.
+    def to_mcp_tool(handler)
+      spec = self
+      Class.new(MCP::Tool) do
+        tool_name spec.name
+        title spec.title if spec.title
+        description spec.description
+        input_schema spec.input_schema
+        annotations spec.annotations
+        define_singleton_method(:call) do |server_context:, **arguments|
+          handler.call(spec, arguments, server_context)
+        end
+      end
+    end
+
+    def to_s
+      "#{name} (#{controller.name}##{action}, #{verb} #{path})"
+    end
+
+    private
+
+    def path_param_schema(param)
+      { anyOf: [{ type: "string" }, { type: "integer" }], description: "The :#{param} segment of #{path}" }
+    end
+  end
+end

data/lib/mcp_on_ruby/tool_table.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module McpOnRuby
+  # Renders the exposed tools as a table for `bin/rails mcp:tools`.
+  module ToolTable
+    HEADERS = %w[TOOL ACTION VERB PATH ACCESS].freeze
+
+    module_function
+
+    def render(specs, configuration: McpOnRuby.configuration)
+      return "No tools are exposed. Add `mcp_tool` declarations to your controllers.\n" if specs.empty?
+
+      rows = specs.map do |spec|
+        [spec.name, "#{spec.controller.name}##{spec.action}", spec.verb, spec.path, access(spec, configuration)]
+      end
+      widths = HEADERS.each_index.map { |index| ([HEADERS] + rows).map { |row| row[index].length }.max }
+
+      ([HEADERS] + rows).map { |row| format_row(row, widths) }.join("\n") << "\n"
+    end
+
+    def access(spec, configuration)
+      return "read-only" unless spec.write?
+
+      configuration.allow_writes ? "write" : "write (disabled)"
+    end
+
+    def format_row(row, widths)
+      row.each_with_index.map { |cell, index| cell.ljust(widths[index]) }.join("  ").rstrip
+    end
+  end
+end