stateless-mcp-rails 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d41343376a7f17949bbde534012b83b287aa9f833b066d9a61560009f5be419d
+  data.tar.gz: d60c6604a3b37a53937383c5a69ee8beeecdb2622e4b7a8b4838b8f83d7984ee
+SHA512:
+  metadata.gz: 356d860719f2539f74f485642333305214a335a419e5afc751d94af3ee42ec93835ccd9f0ec913d97ae930af4c1d8ff5073a5d67f3d5b40e8547ca773367d60d
+  data.tar.gz: 3052880407f485fef014e07a8e6697ccad0b02b57bae8780adbbfc57576312face3850f7b0fd770d696469ceb32cb136091bc01af4117403c97376e3c51ef18f

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+Changes to the `stateless-mcp-rails` gem. It's released at the same version as `stateless-mcp`, whose [changelog](../stateless-mcp/CHANGELOG.md) covers the protocol. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.0.1] - 2026-10-19
+
+First release: MCP servers declared in Rails routes, with tools as controller actions.
+
+- An engine building a default server from `config.stateless_mcp`, and the `mcp_server`, `mcp_resource`, `mcp_member` and `mcp_tool` route macros.
+- `server/discover` and `tools/list` answered from config and routes, each server listing only its own tools.
+- Tool calls: arguments checked against the declared schema and read through `tool_params`, refusals the model can act on, and internal errors reported to `Rails.error`.
+- `paginate_list` and `paginate_text`, plus keyset paging for ActiveRecord from `require "stateless_mcp/rails/active_record"`.
+- `rake mcp:tools`, listing each server's tools.
+- Boot refused until `parent_controller` names the app's own base controller, or `allow_unauthenticated` is `true`.
+
+[Unreleased]: https://github.com/Jamedjo/stateless-mcp/compare/v0.0.1...HEAD
+[0.0.1]: https://github.com/Jamedjo/stateless-mcp/tree/v0.0.1/stateless-mcp-rails

data/LICENSE-APACHE

@@ -0,0 +1,203 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+

data/LICENSE-MIT

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 James Edwards-Jones
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,13 @@
+# stateless-mcp-rails
+
+Rails support for [stateless-mcp](https://github.com/Jamedjo/stateless-mcp): [Model Context Protocol](https://modelcontextprotocol.io/specification/2026-07-28) tools as ordinary routes and controller actions, served without sessions.
+
+> **Status:** early. Releases before 1.0 may change the API.
+
+```ruby
+gem "stateless-mcp-rails"
+```
+
+The documentation is in the [main README](https://github.com/Jamedjo/stateless-mcp#readme) and the [Rails guide](https://github.com/Jamedjo/stateless-mcp/blob/main/docs/rails.md).
+
+Licensed under either of Apache-2.0 or MIT, at your option.

data/app/controllers/stateless_mcp/rails/server_controller.rb

@@ -0,0 +1,11 @@
+module StatelessMcp
+  module Rails
+    # Answers the protocol's own methods, such as server/discover and
+    # tools/list, for every server drawn with mcp_server. It inherits from
+    # config.stateless_mcp.parent_controller, so whatever guards the app's
+    # tools guards these too.
+    class ServerController < ::Rails.application.config.stateless_mcp.parent_controller.constantize
+      include ServerActions
+    end
+  end
+end

data/lib/stateless-mcp-rails.rb

@@ -0,0 +1 @@
+require "stateless_mcp/rails"

data/lib/stateless_mcp/rails/active_record.rb

@@ -0,0 +1,41 @@
+require "active_record"
+require "stateless_mcp/rails"
+
+module StatelessMcp
+  module Rails
+    # Keyset paging for ActiveRecord, newest first. Optional, so neither gem
+    # depends on ActiveRecord: an app that wants it requires this file and
+    # includes the module beside StatelessMcp::Rails::Controller.
+    #
+    #   require "stateless_mcp/rails/active_record"
+    #
+    #   class Mcp::BaseController < ActionController::API
+    #     include StatelessMcp::Rails::Controller
+    #     include StatelessMcp::Rails::RecordPagination
+    #   end
+    module RecordPagination
+      private
+
+      # One page of records, newest first by (created_at, id), and the
+      # next_cursor for the page after. Each page continues after the last
+      # record of the one before, so a deep page costs the same as the first
+      # and records added meanwhile don't shift it.
+      def paginate(records, limit: page_limit)
+        records = records.reorder(created_at: :desc, id: :desc)
+        records = after_cursor(records, *Cursor.decode(tool_params[:cursor], count: 2)) if tool_params[:cursor].present?
+        rows = records.limit(limit + 1).to_a
+        page = rows.first(limit)
+        [page, (Cursor.encode(page.last.created_at.iso8601(6), page.last.id) if rows.size > limit)]
+      end
+
+      # The id keeps its JSON type, so integer and string keys both work.
+      def after_cursor(records, created_at, id)
+        raise Cursor::Invalid unless id.is_a?(Integer) || id.is_a?(String)
+        created_at = Time.iso8601(created_at.to_s)
+        records.where(created_at: ...created_at).or(records.where(created_at: created_at, id: ...id))
+      rescue ArgumentError
+        raise Cursor::Invalid
+      end
+    end
+  end
+end

data/lib/stateless_mcp/rails/controller.rb

@@ -0,0 +1,143 @@
+module StatelessMcp
+  module Rails
+    # Turns a controller's actions into MCP tools. Include it in the base
+    # controller the app's tools inherit from, declare each tool beside its
+    # action, read its arguments from tool_params, and answer with render_tool
+    # or refuse:
+    #
+    #   tool :show, "Gets one note.", title: "Get a note" do
+    #     argument :note_id, :integer, "The note id from list_notes", required: true
+    #   end
+    #   def show
+    #     note = Note.find_by(id: tool_params[:note_id]) or return refuse("No note #{tool_params[:note_id]}")
+    #     render_tool id: note.id, title: note.title
+    #   end
+    module Controller
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :mcp_tools, instance_writer: false, default: {}
+        # MCP clients accept JSON or an event stream, and every answer goes back
+        # as JSON whichever they listed first.
+        prepend_before_action { request.format = :json }
+        before_action :check_tool_arguments, if: :tool_call?
+        rescue_from StandardError, with: :internal_error
+        rescue_from InvalidArgument, with: ->(error) { refuse(error.message) }
+        rescue_from Cursor::Invalid, with: -> { refuse("cursor must be a next_cursor from an earlier result") }
+      end
+
+      class_methods do
+        # Declares the tool an action serves, as tools/list shows it. The block
+        # declares its arguments; see StatelessMcp::ToolDeclaration.
+        def tool(action, description, title:, annotations: ToolDeclaration::READ_ONLY, &arguments)
+          self.mcp_tools = mcp_tools.merge(action.to_s => ToolDeclaration.new(title: title, description: description, annotations: annotations, &arguments))
+        end
+
+        def mcp_tool_declaration(action)
+          mcp_tools.fetch(action.to_s) { raise UndeclaredTool, "#{name}##{action} is routed as a tool but declares none; declare it with `tool :#{action}, ...`" }
+        end
+      end
+
+      private
+
+      # The server this request was routed to.
+      def mcp_server
+        request.get_header(Server::ENV_KEY) or raise "No StatelessMcp::Middleware serves #{request.path}; is the server's middleware in the app's stack?"
+      end
+
+      # The parsed JSON-RPC body.
+      def mcp_request
+        request.get_header(REQUEST_ENV_KEY) || {}
+      end
+
+      def tool_call?
+        params[:mcp_tool].present?
+      end
+
+      def tool_declaration
+        self.class.mcp_tool_declaration(action_name)
+      end
+
+      # Strong parameters permitting exactly the declared arguments.
+      def tool_params
+        @tool_params ||= params.fetch(:params, {}).fetch(:arguments, {}).permit(*permitted_arguments)
+      end
+
+      # Reads a :datetime argument, refusing anything that isn't ISO 8601.
+      def tool_time(name)
+        value = tool_params[name]
+        value.blank? ? nil : Time.zone.iso8601(value)
+      rescue ArgumentError
+        raise InvalidArgument, "#{name} must be an ISO 8601 date or time, like 2026-10-01 or 2026-10-01T09:00:00Z"
+      end
+
+      # The page size the call asked for, held to the server's limits.
+      def page_limit
+        Pagination.limit(tool_params[:limit], mcp_server)
+      end
+
+      # One page of a list, and the next_cursor for the page after.
+      def paginate_list(items)
+        Pagination.list(items, cursor: tool_params[:cursor], limit: page_limit)
+      end
+
+      # A long text in parts of part_size characters, and the next_cursor for
+      # the part after. The block reads a slice of the text from a start
+      # position and length.
+      def paginate_text(part_size, &read)
+        Pagination.text(tool_params[:cursor], part_size, &read)
+      end
+
+      def render_tool(payload)
+        render_result Result.tool(payload)
+      end
+
+      # A refusal the model can read and act on, rather than a protocol error.
+      def refuse(message)
+        render_result Result.refusal(message)
+      end
+
+      def render_result(result)
+        render json: Rpc.success(mcp_request["id"], result)
+      end
+
+      def render_rpc_error(code, message, data: nil)
+        render json: Rpc.error(mcp_request["id"], code, message, data: data), status: Rpc.status_for(code)
+      end
+
+      # The arguments are checked against the raw JSON, before strong
+      # parameters coerce anything. Arguments that aren't an object make the
+      # call itself malformed, which is a protocol error.
+      def check_tool_arguments
+        arguments = mcp_request.dig("params", "arguments") || {}
+        return render_rpc_error(Rpc::ErrorCode::INVALID_PARAMS, "arguments must be an object") unless arguments.is_a?(Hash)
+        schema = tool_declaration.input_schema(mcp_server)
+        missing = schema.missing_required_arguments(arguments)
+        return refuse("Missing required arguments: #{missing.join(", ")}") if missing.any?
+        schema.validate_arguments(arguments)
+      rescue MCP::Tool::InputSchema::ValidationError => error
+        refuse(error.message)
+      end
+
+      def permitted_arguments
+        tool_declaration.input_schema(mcp_server).to_h.fetch(:properties, {}).map do |name, property|
+          case property[:type]
+          when "array" then { name => [] }
+          when "object" then { name => {} }
+          else name
+          end
+        end
+      end
+
+      # Errors Rails answers with a status of its own, such as a rate limit's
+      # 429, keep it. Anything else reaches the client only as "Internal error",
+      # so its cause has to reach the app's error reporting from here or it is
+      # lost.
+      def internal_error(exception)
+        raise exception if exception.is_a?(ActionController::ActionControllerError)
+        ::Rails.error.report(exception, source: "stateless_mcp")
+        render_rpc_error(Rpc::ErrorCode::INTERNAL_ERROR, "Internal error")
+      end
+    end
+  end
+end

data/lib/stateless_mcp/rails/engine.rb

@@ -0,0 +1,36 @@
+module StatelessMcp
+  module Rails
+    # Builds the default server from config.stateless_mcp and puts its
+    # middleware on the app's stack. An engine rather than a plain railtie, so
+    # the server controller under app/controllers is autoloaded and can
+    # inherit from a controller of the app's.
+    class Engine < ::Rails::Engine
+      config.stateless_mcp = ActiveSupport::OrderedOptions.new
+      # Every StatelessMcp::Server setting can be set here too, such as path,
+      # name and max_body_bytes. The server controller inherits from this one,
+      # so the app's sign-in and rate limits cover it too. Left as the default,
+      # the app doesn't boot unless allow_unauthenticated is true.
+      config.stateless_mcp.parent_controller = DEFAULT_PARENT_CONTROLLER
+      config.stateless_mcp.allow_unauthenticated = false
+
+      rake_tasks do
+        namespace :mcp do
+          desc "Lists each MCP server's tools. VERBOSE=1 adds each tool's argument schema"
+          task tools: :environment do
+            puts ToolsReport.new(::Rails.application.routes, verbose: ENV["VERBOSE"].present?)
+          end
+        end
+      end
+
+      initializer "stateless_mcp.routing" do
+        ActionDispatch::Routing::Mapper.include(Routing)
+      end
+
+      # After the app's own initializers, which may set config.stateless_mcp.
+      initializer "stateless_mcp.default_server", after: :load_config_initializers do |app|
+        StatelessMcp::Rails.default_server = StatelessMcp::Rails.build_default_server(app.config.stateless_mcp.to_h, default_name: app.class.module_parent_name.underscore)
+        app.config.middleware.use Middleware, server: StatelessMcp::Rails.default_server
+      end
+    end
+  end
+end

data/lib/stateless_mcp/rails/routing.rb

@@ -0,0 +1,121 @@
+module StatelessMcp
+  module Rails
+    # Route macros for config/routes.rb. Every MCP request is a POST to the
+    # server's path, told apart by its Mcp-Method and Mcp-Name headers:
+    #
+    #   mcp_server module: "mcp" do
+    #     mcp_resource :notes, only: [:index, :show] do
+    #       mcp_member :body
+    #     end
+    #     mcp_tool "search", to: "search#show"
+    #   end
+    #
+    # draws list_notes, get_note, get_note_body and search as tools, routed to
+    # mcp/notes#index, #show, #body and mcp/search#show. tools/list is built
+    # from these routes, so a tool is listed exactly when it is routed.
+    module Routing
+      SERVER_CONTROLLER = "stateless_mcp/rails/server"
+
+      # The servers each route set draws, by path. An app has one route set, so
+      # holding on to them costs nothing.
+      DRAWN_SERVERS = Hash.new { |sets, route_set| sets[route_set] = {} }.compare_by_identity
+
+      # Matches a request by the headers the middleware has already checked
+      # against its body.
+      class Constraint
+        def initialize(method, name: nil)
+          @method = method
+          @name = name
+        end
+
+        def matches?(request)
+          request.headers["Mcp-Method"] == @method && (@name.nil? || request.headers["Mcp-Name"] == @name)
+        end
+      end
+
+      # Each tool routed to a server's path, as [name, controller class, action],
+      # in the order the routes are drawn.
+      def self.tools(server, route_set)
+        route_set.routes.filter_map do |route|
+          name = route.defaults[:mcp_tool]
+          next unless name && route.path.spec.to_s == server.path
+          [name, "#{route.defaults[:controller]}_controller".camelize.constantize, route.defaults[:action]]
+        end
+      end
+
+      # Each tool's tools/list entry, with the controller and action it's
+      # routed to. tools/list and `rake mcp:tools` both read this, so the two
+      # always agree.
+      def self.listed_tools(server, route_set)
+        tools(server, route_set).map do |name, controller, action|
+          [controller.mcp_tool_declaration(action).to_h(name, server), controller, action]
+        end
+      end
+
+      # Each server drawn with mcp_server and still routed, in the order the
+      # routes are drawn. Reading the routes first loads them if Rails has
+      # deferred that.
+      def self.servers(route_set)
+        routed_paths = route_set.routes.map { |route| route.path.spec.to_s }
+        DRAWN_SERVERS[route_set].values.select { |server| routed_paths.include?(server.path) }
+      end
+
+      # Draws a server's routes: its tools, from the block, and the protocol's
+      # own methods, answered by the controller given. Options such as module:
+      # scope the tools' controllers but not the server controller. The server
+      # is the default one built from config.stateless_mcp unless another is
+      # given.
+      def mcp_server(server = nil, controller: SERVER_CONTROLLER, **options)
+        server ||= StatelessMcp::Rails.default_server
+        raise ArgumentError, "mcp_server draws at its server's own path, #{server.path}, so it can't be inside a path scope" if @scope[:path]
+        @mcp_server = server
+        DRAWN_SERVERS[@set][server.path] = server
+        scope(as: nil, format: false) do
+          mcp_method MCP::Methods::SERVER_DISCOVER, to: "#{controller}#discover"
+          mcp_method MCP::Methods::TOOLS_LIST, to: "#{controller}#tools"
+          scope(**options) { yield } if block_given?
+          post server.path, to: "#{controller}#unknown_method", as: nil
+        end
+      ensure
+        @mcp_server = nil
+      end
+
+      # A tool for each action, named by the server's tool_verbs: index on
+      # notes is list_notes, show is get_note.
+      def mcp_resource(resources, only:)
+        @mcp_resource = resources.to_s
+        Array(only).each do |action|
+          verb = current_mcp_server.tool_verbs[action.to_sym] or raise ArgumentError, "No tool verb for :#{action}; add one to tool_verbs, or route it with mcp_member or mcp_tool"
+          noun = action.to_sym == :index ? @mcp_resource : @mcp_resource.singularize
+          mcp_tool "#{verb}_#{noun}", to: "#{@mcp_resource}##{action}"
+        end
+        yield if block_given?
+      ensure
+        @mcp_resource = nil
+      end
+
+      # A tool reading one more thing about a member of the resource it's
+      # drawn in, named get_<singular>_<action>.
+      def mcp_member(action, verb: "get")
+        raise ArgumentError, "mcp_member belongs inside an mcp_resource block" unless @mcp_resource
+        mcp_tool "#{verb}_#{@mcp_resource.singularize}_#{action}", to: "#{@mcp_resource}##{action}"
+      end
+
+      # The tool name is kept as a route default, which is where tools/list
+      # reads it back from.
+      def mcp_tool(name, to:)
+        post current_mcp_server.path, to: to, constraints: Constraint.new(MCP::Methods::TOOLS_CALL, name: name.to_s), defaults: { mcp_tool: name.to_s }, as: nil
+      end
+
+      def mcp_method(method, to:)
+        post current_mcp_server.path, to: to, constraints: Constraint.new(method), as: nil
+      end
+
+      private
+
+      def current_mcp_server
+        @mcp_server or raise ArgumentError, "MCP tools and methods are drawn inside an mcp_server block"
+      end
+    end
+  end
+end

data/lib/stateless_mcp/rails/server_actions.rb

@@ -0,0 +1,37 @@
+module StatelessMcp
+  module Rails
+    # The protocol's own methods, which mcp_server routes to the server
+    # controller. The gem's StatelessMcp::Rails::ServerController includes
+    # this; an app that writes its own server controller includes it there.
+    module ServerActions
+      extend ActiveSupport::Concern
+
+      include Controller
+
+      def discover
+        render_result Result.discover(mcp_server, capabilities: capabilities)
+      end
+
+      def tools
+        tools = Routing.listed_tools(mcp_server, _routes).map(&:first)
+        render_result Result.complete({ tools: tools }, cacheable: true)
+      end
+
+      # Any request no route claimed. A notification needs no answer, and a
+      # tool that isn't routed is a bad argument to tools/call rather than an
+      # unknown method.
+      def unknown_method
+        method = mcp_request["method"]
+        return head(:accepted) if MCP::Methods.notification?(method)
+        return render_rpc_error(Rpc::ErrorCode::INVALID_PARAMS, "Unknown tool: #{mcp_request.dig("params", "name")}") if method == MCP::Methods::TOOLS_CALL
+        render_rpc_error(Rpc::ErrorCode::METHOD_NOT_FOUND, "Method not found", data: method)
+      end
+
+      private
+
+      def capabilities
+        { tools: {} }
+      end
+    end
+  end
+end

data/lib/stateless_mcp/rails/tools_report.rb

@@ -0,0 +1,42 @@
+module StatelessMcp
+  module Rails
+    # The text `rake mcp:tools` prints: each server's tools as a table, with
+    # each tool's argument schema on the line below it when verbose.
+    class ToolsReport
+      HEADINGS = ["Tool", "Title", "Action", "Read-only"].freeze
+
+      def initialize(route_set, verbose: false)
+        @route_set = route_set
+        @verbose = verbose
+      end
+
+      def to_s
+        Routing.servers(@route_set).map { |server| server_section(server) }.join("\n")
+      end
+
+      private
+
+      def server_section(server)
+        tools = Routing.listed_tools(server, @route_set)
+        return "#{server.name} (#{server.path})\n  No tools\n" if tools.empty?
+        rows = tools.map { |entry, controller, action| row(entry, controller, action) }
+        widths = HEADINGS.each_index.map { |column| ([HEADINGS] + rows).map { |cells| cells[column].length }.max }
+        lines = [format_row(HEADINGS, widths)]
+        rows.zip(tools) do |cells, (entry, _, _)|
+          lines << format_row(cells, widths)
+          lines << "    #{JSON.generate(entry[:inputSchema].except(:"$schema"))}" if @verbose
+        end
+        "#{server.name} (#{server.path})\n#{lines.join("\n")}\n"
+      end
+
+      def row(entry, controller, action)
+        read_only = entry.dig(:annotations, :readOnlyHint)
+        [entry[:name], entry[:title].to_s, "#{controller.controller_path}##{action}", read_only.nil? ? "" : (read_only ? "yes" : "no")]
+      end
+
+      def format_row(cells, widths)
+        "  #{cells.zip(widths).map { |cell, width| cell.ljust(width) }.join("  ")}".rstrip
+      end
+    end
+  end
+end

data/lib/stateless_mcp/rails.rb

@@ -0,0 +1,55 @@
+require "stateless_mcp"
+require "rails"
+require "action_controller"
+
+module StatelessMcp
+  # Rails support: a tool is a controller action, routed by the Mcp-Method and
+  # Mcp-Name headers. Inside StatelessMcp, `Rails` names this module, so the
+  # framework itself is always written `::Rails`.
+  module Rails
+    # Raised when a routed action has no tool declaration to list it by.
+    UndeclaredTool = Class.new(StandardError)
+
+    # Raised at boot when the app has set neither parent_controller nor
+    # allow_unauthenticated, as the tools would be open to anyone.
+    AuthenticationNotConfigured = Class.new(Server::Invalid)
+
+    DEFAULT_PARENT_CONTROLLER = "ActionController::API"
+
+    class << self
+      # The server built from config.stateless_mcp at boot. Only the engine
+      # sets it, and only `mcp_server` without a server argument reads it.
+      attr_writer :default_server
+
+      def default_server
+        @default_server or raise "The default MCP server is built from config.stateless_mcp when the app boots, and it hasn't booted yet"
+      end
+
+      # The default server, from the settings in config.stateless_mcp.
+      def build_default_server(settings, default_name:)
+        check_authentication(settings)
+        server_settings = settings.except(:parent_controller, :allow_unauthenticated)
+        server_settings[:name] ||= default_name
+        Server.new(**server_settings)
+      end
+
+      private
+
+      # A parent controller of the app's own is trusted to authenticate. The
+      # gem can't tell whether it does, only that the app has chosen one.
+      def check_authentication(settings)
+        return if settings[:allow_unauthenticated] == true
+        return if settings.fetch(:parent_controller, DEFAULT_PARENT_CONTROLLER).to_s != DEFAULT_PARENT_CONTROLLER
+        raise AuthenticationNotConfigured, "config.stateless_mcp.parent_controller is #{DEFAULT_PARENT_CONTROLLER}, so anyone who can reach the MCP endpoint can call every tool. " \
+          "Set config.stateless_mcp.parent_controller to a controller that authenticates, such as \"Mcp::BaseController\", " \
+          "or set config.stateless_mcp.allow_unauthenticated = true for a server that is open on purpose."
+      end
+    end
+  end
+end
+
+require_relative "rails/routing"
+require_relative "rails/controller"
+require_relative "rails/server_actions"
+require_relative "rails/tools_report"
+require_relative "rails/engine"

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification
+name: stateless-mcp-rails
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- James Edwards-Jones
+bindir: bin
+cert_chain: []
+date: 2026-10-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: stateless-mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.0.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.0.1
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+description: 'Rails support for stateless-mcp: a tool is a controller action, routed
+  by the Mcp-Method and Mcp-Name headers of the 2026-07-28 Model Context Protocol,
+  and tools/list is drawn from the routes.'
+email:
+- git@jamedjo.co.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE-APACHE
+- LICENSE-MIT
+- README.md
+- app/controllers/stateless_mcp/rails/server_controller.rb
+- lib/stateless-mcp-rails.rb
+- lib/stateless_mcp/rails.rb
+- lib/stateless_mcp/rails/active_record.rb
+- lib/stateless_mcp/rails/controller.rb
+- lib/stateless_mcp/rails/engine.rb
+- lib/stateless_mcp/rails/routing.rb
+- lib/stateless_mcp/rails/server_actions.rb
+- lib/stateless_mcp/rails/tools_report.rb
+homepage: https://github.com/Jamedjo/stateless-mcp
+licenses:
+- MIT
+- Apache-2.0
+metadata:
+  homepage_uri: https://github.com/Jamedjo/stateless-mcp
+  source_code_uri: https://github.com/Jamedjo/stateless-mcp/tree/v0.0.1/stateless-mcp-rails
+  changelog_uri: https://github.com/Jamedjo/stateless-mcp/blob/main/stateless-mcp-rails/CHANGELOG.md
+  documentation_uri: https://github.com/Jamedjo/stateless-mcp/blob/main/README.md
+  bug_tracker_uri: https://github.com/Jamedjo/stateless-mcp/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Model Context Protocol tools as ordinary Rails routes and controller actions
+test_files: []