toolchest 0.3.2

data/lib/generators/toolchest/templates/create_toolchest_oauth.rb.tt

@@ -0,0 +1,39 @@
+class CreateToolchestOauth < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :toolchest_oauth_applications do |t|
+      t.string  :name,         null: false
+      t.string  :uid,          null: false, index: { unique: true }
+      t.string  :secret
+      t.text    :redirect_uri, null: false
+      t.string  :scopes,       null: false, default: ""
+      t.boolean :confidential, null: false, default: true
+      t.timestamps
+    end
+
+    create_table :toolchest_oauth_access_grants do |t|
+      t.string     :resource_owner_id, null: false
+      t.references :application, null: false, foreign_key: { to_table: :toolchest_oauth_applications }
+      t.string     :token_digest, null: false, index: { unique: true }
+      t.text       :redirect_uri, null: false
+      t.string     :scopes,     null: false, default: ""
+      t.string     :code_challenge
+      t.string     :code_challenge_method
+      t.string     :mount_key, null: false, default: "default"
+      t.datetime   :expires_at, null: false
+      t.datetime   :revoked_at
+      t.timestamps
+    end
+
+    create_table :toolchest_oauth_access_tokens do |t|
+      t.string     :resource_owner_id
+      t.references :application, null: false, foreign_key: { to_table: :toolchest_oauth_applications }
+      t.string     :token,         null: false, index: { unique: true }
+      t.string     :refresh_token, index: { unique: true }
+      t.string     :scopes
+      t.string     :mount_key, null: false, default: "default"
+      t.datetime   :expires_at
+      t.datetime   :revoked_at
+      t.timestamps
+    end
+  end
+end

data/lib/generators/toolchest/templates/create_toolchest_tokens.rb.tt

@@ -0,0 +1,16 @@
+class CreateToolchestTokens < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :toolchest_tokens do |t|
+      t.string :token_digest, null: false, index: { unique: true }
+      t.string :name
+      t.string :owner_type
+      t.string :owner_id
+      t.string :scopes
+      t.string :namespace, default: "default"
+      t.datetime :expires_at
+      t.datetime :last_used_at
+      t.datetime :revoked_at
+      t.timestamps
+    end
+  end
+end

data/lib/generators/toolchest/templates/initializer.rb.tt

@@ -0,0 +1,41 @@
+Toolchest.configure do |config|
+  config.server_name = "<%= Rails.application.class.module_parent_name %>"
+  # config.server_description = ""
+  config.auth = :<%= auth_strategy %>
+  config.mount_path = "/mcp"
+<% if auth_strategy == :token -%>
+
+  # Resolve the token to a user (or anything). Available as auth.resource_owner in toolboxes.
+  config.authenticate do |token|
+    # User.find(token.owner_id)
+  end
+<% elsif auth_strategy == :oauth -%>
+
+  config.login_path = "/login"
+
+  # Identify the logged-in user during the OAuth consent screen.
+  # Return a user object, or nil to redirect to login_path.
+  config.current_user_for_oauth do |request|
+    # Example with Devise:
+    #   request.env["warden"]&.user
+    # Example with a session:
+    #   User.find_by(id: request.session[:user_id])
+  end
+
+  # Resolve the token to a user (or anything). Available as auth.resource_owner in toolboxes.
+  config.authenticate do |token|
+    # User.find(token.resource_owner_id)
+  end
+
+  # config.scopes = {
+  #   "posts:read"  => "View blog posts",
+  #   "posts:write" => "Create and modify blog posts"
+  # }
+<% end -%>
+
+  # Tool naming strategy: :underscored (default), :dotted, :slashed, or a lambda
+  # config.tool_naming = :underscored
+
+  # Filter tools/list by authenticated scopes (default: true)
+  # config.filter_tools_by_scope = true
+end

data/lib/generators/toolchest/templates/oauth_authorize.html.erb.tt

@@ -0,0 +1,48 @@
+<%% # app/views/toolchest/oauth/authorizations/new.html.erb %>
+<%% # Ejected from toolchest. Customize to match your app's design. %>
+
+<div class="toolchest-consent">
+  <h1><%%= @client_name %> wants access to your account</h1>
+  <p>Make sure you trust this URL: <code><%%= @redirect_uri %></code></p>
+
+  <%%= form_tag @authorize_url, method: :post do %>
+    <%% @oauth_params&.each do |key, value| %>
+      <%%= hidden_field_tag key, value %>
+    <%% end %>
+    <%%= hidden_field_tag "original_scope", @original_scope %>
+
+    <%% if @scope_list&.any? %>
+      <p>It's asking for:</p>
+      <ul>
+        <%% @scope_list.each do |s| %>
+          <li>
+            <%% if @optional %>
+              <label>
+                <%%= check_box_tag "scope[]", s[:name], true,
+                    disabled: s[:required], id: "scope_#{s[:name].parameterize}" %>
+                <%% if s[:required] %>
+                  <%%= hidden_field_tag "scope[]", s[:name] %>
+                <%% end %>
+                <strong><%%= s[:name] %></strong> &mdash; <%%= s[:description] %>
+              </label>
+            <%% else %>
+              <%%= hidden_field_tag "scope[]", s[:name] %>
+              <strong><%%= s[:name] %></strong> &mdash; <%%= s[:description] %>
+            <%% end %>
+          </li>
+        <%% end %>
+      </ul>
+    <%% end %>
+
+    <div class="toolchest-consent-actions" style="display: flex; gap: .5rem">
+      <%%= submit_tag "Authorize" %>
+    </div>
+  <%% end %>
+
+  <%%= form_tag @authorize_url, method: :delete do %>
+    <%% @oauth_params&.each do |key, value| %>
+      <%%= hidden_field_tag key, value %>
+    <%% end %>
+    <%%= submit_tag "Deny" %>
+  <%% end %>
+</div>

data/lib/generators/toolchest/templates/toolbox.rb.tt

@@ -0,0 +1,19 @@
+class <%= class_name %>Toolbox < <%= parent_class %>
+<% actions.each_with_index do |action, i| -%>
+<%= "\n" if i > 0 -%>
+  tool "TODO: describe <%= action %>" do
+    # param :id, :string, "TODO: add params"
+  end
+  def <%= action %>
+    # TODO: implement
+  end
+<% end -%>
+<% if actions.empty? -%>
+  # tool "Description" do
+  #   param :id, :string, "The ID"
+  # end
+  # def show
+  #   @record = Model.find(params[:id])
+  # end
+<% end -%>
+end

data/lib/generators/toolchest/templates/toolbox_spec.rb.tt

@@ -0,0 +1,23 @@
+require "rails_helper"
+
+RSpec.describe <%= class_name %>Toolbox, type: :toolbox do
+<% actions.each_with_index do |action, i| -%>
+<%= "\n" if i > 0 -%>
+  describe "#<%= action %>" do
+    it "works" do
+      call_tool "<%= file_path.gsub("/", "_") %>_<%= action %>",
+        params: {}
+
+      expect(tool_response).to be_success
+    end
+  end
+<% end -%>
+<% if actions.empty? -%>
+  # describe "#show" do
+  #   it "works" do
+  #     call_tool "<%= file_path.gsub("/", "_") %>_show", params: { id: "1" }
+  #     expect(tool_response).to be_success
+  #   end
+  # end
+<% end -%>
+end

data/lib/generators/toolchest/toolbox_generator.rb

@@ -0,0 +1,44 @@
+require "rails/generators"
+require "rails/generators/base"
+
+module Toolchest
+  module Generators
+    class ToolboxGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      argument :toolbox_name, type: :string
+      argument :actions, type: :array, default: []
+
+      def create_toolbox = template "toolbox.rb.tt", "app/toolboxes/#{file_path}_toolbox.rb"
+
+      def create_views
+        return if actions.empty?
+
+        actions.each do |action|
+          create_file "app/views/toolboxes/#{file_path}/#{action}.json.jb", <<~JB
+            {
+              # TODO: return data for #{toolbox_name.underscore}##{action}
+            }
+          JB
+        end
+      end
+
+      def create_spec = template "toolbox_spec.rb.tt", "spec/toolboxes/#{file_path}_toolbox_spec.rb"
+
+      private
+
+      def file_path = toolbox_name.underscore
+
+      def class_name = toolbox_name.camelize
+
+      def parent_class
+        if file_path.include?("/")
+          namespace = file_path.split("/")[0..-2].map(&:camelize).join("::")
+          "#{namespace}::ApplicationToolbox"
+        else
+          "ApplicationToolbox"
+        end
+      end
+    end
+  end
+end

data/lib/toolchest/app.rb

@@ -0,0 +1,47 @@
+require "action_dispatch"
+
+module Toolchest
+  # Rack app for a named mount. Used for multi-mount:
+  #   mount Toolchest.app(:admin) => "/admin-mcp"
+  #
+  # Handles OAuth routes (authorize, token, register, authorized_applications)
+  # and delegates everything else to the MCP transport (RackApp).
+  class App
+    attr_reader :mount_key
+
+    def initialize(mount_key = :default)
+      @mount_key = mount_key.to_sym
+      @router = build_action_dispatch_router
+    end
+
+    def call(env)
+      Engine.ensure_initialized!
+      env["toolchest.mount_key"] = @mount_key.to_s
+      @router.call(env)
+    end
+
+    private
+
+    def build_action_dispatch_router
+      mk = @mount_key
+      endpoint = Endpoint.new
+
+      ActionDispatch::Routing::RouteSet.new.tap do |routes|
+        routes.draw do
+          get    "oauth/authorize", to: "toolchest/oauth/authorizations#new"
+          post   "oauth/authorize", to: "toolchest/oauth/authorizations#create"
+          delete "oauth/authorize", to: "toolchest/oauth/authorizations#deny"
+          post "oauth/token",     to: "toolchest/oauth/tokens#create"
+          post "oauth/register",  to: "toolchest/oauth/registrations#create"
+
+          resources :oauth_authorized_applications, only: [:index, :destroy],
+            path: "oauth/authorized_applications",
+            controller: "toolchest/oauth/authorized_applications"
+
+          match "/", to: endpoint, via: [:get, :post, :delete]
+          match "/*path", to: endpoint, via: [:get, :post, :delete]
+        end
+      end
+    end
+  end
+end

data/lib/toolchest/auth/base.rb

@@ -0,0 +1,15 @@
+module Toolchest
+  module Auth
+    class Base
+      def authenticate(request) = raise NotImplementedError
+
+      private
+
+      def extract_bearer_token(request)
+        auth_header = request.env["HTTP_AUTHORIZATION"] || ""
+        match = auth_header.match(/\ABearer\s+(.+)\z/i)
+        match&.[](1)
+      end
+    end
+  end
+end

data/lib/toolchest/auth/none.rb

@@ -0,0 +1,7 @@
+module Toolchest
+  module Auth
+    class None < Base
+      def authenticate(request) = nil
+    end
+  end
+end

data/lib/toolchest/auth/oauth.rb

@@ -0,0 +1,28 @@
+module Toolchest
+  module Auth
+    class OAuth < Base
+      def initialize(mount_key = :default)
+        @mount_key = mount_key.to_s
+      end
+
+      def authenticate(request)
+        token_string = extract_bearer_token(request)
+        return nil unless token_string
+
+        token = Toolchest::OauthAccessToken.find_by_token(token_string, mount_key: @mount_key)
+        return nil unless token
+
+        config = Toolchest.configuration(@mount_key.to_sym)
+        owner = if config.send(:instance_variable_get, :@authenticate_block)
+          config.authenticate_with(token)
+        end
+
+        AuthContext.new(
+          resource_owner: owner,
+          scopes: token.scopes_array,
+          token: token
+        )
+      end
+    end
+  end
+end

data/lib/toolchest/auth/token.rb

@@ -0,0 +1,73 @@
+require "openssl"
+
+module Toolchest
+  module Auth
+    class Token < Base
+      def authenticate(request)
+        token_string = extract_bearer_token(request)
+        return nil unless token_string
+
+        token_record = find_token(token_string)
+        return nil unless token_record
+
+        scopes = if token_record.respond_to?(:scopes_array)
+          token_record.scopes_array
+        elsif token_record.respond_to?(:scopes)
+          Array(token_record.scopes).flat_map { |s| s.split(" ") }.reject(&:empty?)
+        else
+          []
+        end
+
+        config = Toolchest.configuration
+        owner = if config.respond_to?(:authenticate_with) && config.send(:instance_variable_get, :@authenticate_block)
+          config.authenticate_with(token_record)
+        end
+
+        AuthContext.new(
+          resource_owner: owner,
+          scopes: scopes,
+          token: token_record
+        )
+      end
+
+      private
+
+      def find_token(token_string)
+        env_token = find_env_token(token_string)
+        return env_token if env_token
+
+        find_db_token(token_string)
+      end
+
+      def find_env_token(token_string)
+        expected = ENV["TOOLCHEST_TOKEN"]
+        return nil unless expected
+        return nil unless secure_compare(token_string, expected)
+
+        owner = ENV["TOOLCHEST_TOKEN_OWNER"]
+        EnvTokenRecord.new(token_string, owner)
+      end
+
+      def find_db_token(token_string)
+        return nil unless defined?(Toolchest::Token) && Toolchest::Token.table_exists?
+
+        token = Toolchest::Token.find_by_raw_token(token_string)
+        return nil unless token
+
+        token.update_column(:last_used_at, Time.current)
+        token
+      end
+
+      def secure_compare(a, b) = ActiveSupport::SecurityUtils.secure_compare(a, b)
+
+      EnvTokenRecord = Struct.new(:token, :owner_id) do
+        def owner_type
+          type, _ = owner_id&.split(":", 2)
+          type
+        end
+
+        def scopes = ENV.fetch("TOOLCHEST_TOKEN_SCOPES", "").split(" ").reject(&:empty?)
+      end
+    end
+  end
+end

data/lib/toolchest/auth_context.rb

@@ -0,0 +1,13 @@
+module Toolchest
+  class AuthContext
+    attr_reader :resource_owner, :scopes, :token
+
+    def initialize(resource_owner:, scopes:, token:)
+      @resource_owner = resource_owner
+      @scopes = scopes
+      @token = token
+    end
+
+    def scopes_array = @scopes
+  end
+end

data/lib/toolchest/configuration.rb

@@ -0,0 +1,82 @@
+module Toolchest
+  class Configuration
+    VALID_AUTH_STRATEGIES = %i[none token oauth].freeze
+
+    attr_accessor :tool_naming, :filter_tools_by_scope,
+                  :server_name, :server_version, :server_description, :server_instructions,
+                  :scopes, :login_path, :additional_view_paths,
+                  :access_token_expires_in, :toolboxes, :toolbox_module,
+                  :mount_key, :mount_path,
+                  :optional_scopes, :required_scopes
+    attr_reader :auth
+
+    def initialize(mount_key = :default)
+      @mount_key = mount_key.to_sym
+      @auth = :none
+      @tool_naming = :underscored
+      @filter_tools_by_scope = true
+      @server_name = nil
+      @server_version = Toolchest::VERSION
+      @scopes = {}
+      @login_path = "/login"
+      @authenticate_block = nil
+      @optional_scopes = false
+      @required_scopes = []
+      @allowed_scopes_for_block = nil
+      @additional_view_paths = []
+      @access_token_expires_in = 7200
+      @toolboxes = nil
+      @toolbox_module = nil
+    end
+
+    def auth=(value)
+      if value.respond_to?(:authenticate)
+        @auth = value
+      elsif value.respond_to?(:to_sym)
+        sym = value.to_sym
+        unless VALID_AUTH_STRATEGIES.include?(sym)
+          raise Toolchest::Error,
+            "Invalid auth strategy :#{value}. Valid options: #{VALID_AUTH_STRATEGIES.map { |s| ":#{s}" }.join(', ')}, or an object responding to #authenticate(request)"
+        end
+        @auth = sym
+      else
+        raise Toolchest::Error,
+          "Auth must be a symbol (:none, :token, :oauth) or an object responding to #authenticate(request)"
+      end
+    end
+
+    def authenticate(&block) = @authenticate_block = block
+
+    def authenticate_with(token)
+      return nil unless @authenticate_block
+      @authenticate_block.call(token)
+    end
+
+    def allowed_scopes_for(&block)
+      if block
+        @allowed_scopes_for_block = block
+      else
+        @allowed_scopes_for_block
+      end
+    end
+
+    def resolve_allowed_scopes(user, scopes)
+      @allowed_scopes_for_block ? @allowed_scopes_for_block.call(user, scopes) : scopes
+    end
+
+    def current_user_for_oauth(&block)
+      if block
+        @current_user_for_oauth_block = block
+      else
+        @current_user_for_oauth_block
+      end
+    end
+
+    def resolve_current_user(request)
+      return nil unless @current_user_for_oauth_block
+      @current_user_for_oauth_block.call(request)
+    end
+
+    def resolved_server_name = @server_name || (defined?(Rails) && Rails.application ? Rails.application.class.module_parent_name : "Toolchest")
+  end
+end

data/lib/toolchest/current.rb

@@ -0,0 +1,7 @@
+require "active_support/current_attributes"
+
+module Toolchest
+  class Current < ActiveSupport::CurrentAttributes
+    attribute :auth, :mount_key, :mcp_session, :mcp_request_id, :mcp_progress_token
+  end
+end

data/lib/toolchest/endpoint.rb

@@ -0,0 +1,13 @@
+module Toolchest
+  # Rack app for MCP protocol requests (JSON-RPC over HTTP).
+  # OAuth endpoints are handled by Rails controllers via engine routes.
+  class Endpoint
+    def call(env)
+      Engine.ensure_initialized!
+
+      mount_key = (env["toolchest.mount_key"] || "default").to_sym
+      app = Toolchest.router(mount_key).rack_app ||= RackApp.new(mount_key: mount_key)
+      app.call(env)
+    end
+  end
+end

data/lib/toolchest/engine.rb

@@ -0,0 +1,95 @@
+require "rails/engine"
+
+module Toolchest
+  class Engine < ::Rails::Engine
+    isolate_namespace Toolchest
+
+    rake_tasks do
+      load File.expand_path("tasks/toolchest.rake", __dir__)
+    end
+
+    initializer "toolchest.autoload_paths", before: :set_autoload_paths do |app|
+      app.config.autoload_paths += [Rails.root.join("app", "toolboxes").to_s]
+      app.config.eager_load_paths += [Rails.root.join("app", "toolboxes").to_s]
+    end
+
+    initializer "toolchest.setup" do
+      config.after_initialize do
+        Toolchest::Engine.ensure_initialized!
+      end
+
+      config.to_prepare do
+        Toolchest::Engine.reload!
+      end
+    end
+
+    class << self
+      def ensure_initialized!
+        return if @initialized
+
+        require "mcp"
+
+        discover_and_assign_toolboxes!
+
+        @initialized = true
+      end
+
+      def reload!
+        @initialized = false
+        Toolchest.reset_routers!
+        ensure_initialized!
+      end
+
+      private
+
+      def discover_and_assign_toolboxes!
+        return unless defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+
+        toolboxes_path = Rails.root.join("app", "toolboxes")
+        return unless toolboxes_path.exist?
+
+        all_toolboxes = []
+
+        Dir[toolboxes_path.join("**", "*_toolbox.rb")].each do |file|
+          class_name = file
+            .sub(toolboxes_path.to_s + "/", "")
+            .sub(/\.rb$/, "")
+            .camelize
+
+          next if class_name == "ApplicationToolbox"
+
+          begin
+            klass = class_name.constantize
+            all_toolboxes << klass if klass < Toolchest::Toolbox
+          rescue NameError
+          end
+        end
+
+        # Assign toolboxes to mounts based on config
+        Toolchest.mount_keys.each do |mount_key|
+          cfg = Toolchest.configuration(mount_key)
+          router = Toolchest.router(mount_key)
+
+          assigned = if cfg.toolboxes
+            # Explicit list (supports strings for lazy loading)
+            cfg.toolboxes.map { |t| t.is_a?(String) ? t.constantize : t }
+          elsif cfg.toolbox_module
+            # Module convention
+            all_toolboxes.select { |t| t.name&.start_with?("#{cfg.toolbox_module}::") }
+          else
+            # Default: all toolboxes (only valid for single-mount)
+            all_toolboxes
+          end
+
+          assigned.each { |t| router.register(t) }
+        end
+
+        # If no mounts configured yet, register all to :default
+        if Toolchest.mount_keys.empty?
+          all_toolboxes.each { |t| Toolchest.router(:default).register(t) }
+        end
+      end
+    end
+
+  end
+end

data/lib/toolchest/naming.rb

@@ -0,0 +1,31 @@
+module Toolchest
+  module Naming
+    class << self
+      def generate(toolbox_class, method_name, strategy = :underscored)
+        prefix = toolbox_prefix(toolbox_class)
+
+        case strategy
+        when :underscored
+          "#{prefix}_#{method_name}"
+        when :dotted
+          "#{prefix}.#{method_name}"
+        when :slashed
+          "#{prefix}/#{method_name}"
+        when Proc
+          strategy.call(prefix, method_name.to_s)
+        else
+          "#{prefix}_#{method_name}"
+        end
+      end
+
+        private
+
+      def toolbox_prefix(toolbox_class)
+        name = toolbox_class.name || toolbox_class.to_s
+        name.underscore
+            .chomp("_toolbox")
+            .gsub("/", "_")
+      end
+    end
+  end
+end

data/lib/toolchest/oauth/routes.rb

@@ -0,0 +1,25 @@
+module ActionDispatch
+  module Routing
+    class Mapper
+      # Mount well-known OAuth discovery routes at the app root.
+      # MCP clients discover OAuth endpoints via these paths.
+      #
+      #   mount Toolchest::Engine => "/mcp"
+      #   toolchest_oauth
+      #
+      # For multi-mount, call once — the (/*rest) suffix lets the
+      # MetadataController return the correct endpoints per mount:
+      #   /.well-known/oauth-authorization-server/mcp       → /mcp mount
+      #   /.well-known/oauth-authorization-server/admin-mcp → /admin-mcp mount
+      #
+      def toolchest_oauth(default_mount: nil)
+        Toolchest.default_oauth_mount = default_mount.to_sym if default_mount
+
+        get "/.well-known/oauth-authorization-server(/*rest)",
+          to: "toolchest/oauth/metadata#authorization_server"
+        get "/.well-known/oauth-protected-resource(/*rest)",
+          to: "toolchest/oauth/metadata#protected_resource"
+      end
+    end
+  end
+end