toolchest 0.3.2

data/lib/toolchest/sampling_builder.rb

@@ -0,0 +1,38 @@
+module Toolchest
+  class SamplingBuilder
+    attr_reader :messages, :system_value, :max_tokens_value, :temperature_value,
+                :model_preferences_value, :stop_sequences_value
+
+    def initialize
+      @messages = []
+    end
+
+    def system(text)
+      @system_value = text
+    end
+
+    def user(text)
+      @messages << { role: "user", content: { type: "text", text: text } }
+    end
+
+    def assistant(text)
+      @messages << { role: "assistant", content: { type: "text", text: text } }
+    end
+
+    def max_tokens(n)
+      @max_tokens_value = n
+    end
+
+    def temperature(t)
+      @temperature_value = t
+    end
+
+    def model_preferences(prefs)
+      @model_preferences_value = prefs
+    end
+
+    def stop_sequences(seqs)
+      @stop_sequences_value = seqs
+    end
+  end
+end

data/lib/toolchest/tasks/toolchest.rake

@@ -0,0 +1,123 @@
+namespace :toolchest do
+  desc "List all registered MCP tools"
+  task tools: :environment do
+    Toolchest::Engine.ensure_initialized!
+    router = Toolchest.router
+
+    router.toolbox_classes.each do |klass|
+      tools = klass.tool_definitions.values
+      resources = klass.resources
+      prompts = klass.prompts
+
+      parts = []
+      parts << "#{tools.length} tool#{"s" unless tools.length == 1}"
+      parts << "#{resources.length} resource#{"s" unless resources.length == 1}" if resources.any?
+      parts << "#{prompts.length} prompt#{"s" unless prompts.length == 1}" if prompts.any?
+
+      puts "#{klass.name} (#{parts.join(", ")})"
+
+      tools.each do |tool|
+        puts "  #{tool.tool_name.ljust(25)} #{tool.description.inspect}"
+
+        required = tool.params.select(&:required?)
+        optional = tool.params.reject(&:required?)
+
+        if required.any?
+          params_str = required.map { |p|
+            s = "#{p.name} (#{p.type})"
+            s += " [#{p.enum.join("|")}]" if p.enum
+            s
+          }.join(", ")
+          puts "    Params: #{params_str}"
+        end
+
+        if optional.any?
+          optional.each do |p|
+            s = "#{p.name} (#{p.type}, optional)"
+            s += " [#{p.enum.join("|")}]" if p.enum
+            puts "            #{s}"
+          end
+        end
+      end
+
+      resources.each do |r|
+        puts "  Resource: #{r[:uri]} #{r[:name].inspect}"
+      end
+
+      prompts.each do |p|
+        puts "  Prompt:   #{p[:name]} #{p[:description].inspect}"
+      end
+
+      puts
+    end
+
+    if router.toolbox_classes.empty?
+      puts "No toolboxes registered."
+      puts "Generate one: rails g toolchest YourModel show create"
+    end
+  end
+
+  namespace :token do
+    desc "Generate a new API token"
+    task generate: :environment do
+      owner = ENV["OWNER"]
+      name = ENV["NAME"] || "cli-generated"
+      scopes = ENV["SCOPES"]
+
+      if defined?(Toolchest::Token) && Toolchest::Token.table_exists?
+        record = Toolchest::Token.generate(owner: owner, name: name, scopes: scopes)
+        puts "Token created: #{record.raw_token}"
+        puts "  Owner: #{owner}" if owner
+        puts "  Name:  #{name}"
+        puts "  Scopes: #{scopes}" if scopes
+      else
+        token = "tcht_#{SecureRandom.hex(24)}"
+        puts "Token: #{token}"
+        puts ""
+        puts "No toolchest_tokens table found. Use as env var:"
+        puts "  TOOLCHEST_TOKEN=#{token}"
+        puts "  TOOLCHEST_TOKEN_OWNER=#{owner}" if owner
+      end
+    end
+
+    desc "List all tokens"
+    task list: :environment do
+      unless defined?(Toolchest::Token) && Toolchest::Token.table_exists?
+        if ENV["TOOLCHEST_TOKEN"]
+          puts "Env token configured: TOOLCHEST_TOKEN=#{ENV["TOOLCHEST_TOKEN"][0..8]}..."
+          puts "  Owner: #{ENV["TOOLCHEST_TOKEN_OWNER"]}" if ENV["TOOLCHEST_TOKEN_OWNER"]
+        else
+          puts "No tokens configured."
+        end
+        next
+      end
+
+      tokens = Toolchest::Token.where(revoked_at: nil).order(:created_at)
+      if tokens.empty?
+        puts "No active tokens."
+      else
+        tokens.each do |t|
+          puts "#{t.token_digest[0..8]}...  #{t.name || "(unnamed)"}  owner=#{t.owner_type}:#{t.owner_id}  created=#{t.created_at.to_date}"
+          puts "  scopes=#{t.scopes}" if t.scopes.present?
+          puts "  last_used=#{t.last_used_at}" if t.last_used_at
+        end
+      end
+    end
+
+    desc "Revoke a token"
+    task revoke: :environment do
+      token = ENV["TOKEN"]
+      abort "Usage: rails toolchest:token:revoke TOKEN=tcht_..." unless token
+
+      unless defined?(Toolchest::Token) && Toolchest::Token.table_exists?
+        abort "No toolchest_tokens table. Can't revoke env tokens — just unset TOOLCHEST_TOKEN."
+      end
+
+      record = Toolchest::Token.find_by_raw_token(token)
+      abort "Token not found." unless record
+
+      record.revoke!
+      puts "Token revoked: #{record.name || record.token_digest[0..8]}..."
+    end
+  end
+end

data/lib/toolchest/tool_builder.rb

@@ -0,0 +1,19 @@
+module Toolchest
+  class ToolBuilder
+    attr_reader :params
+
+    def initialize = @params = []
+
+    def param(name, type, description = "", **options, &block)
+      @params << ParamDefinition.new(
+        name: name,
+        type: type,
+        description: description,
+        optional: options.fetch(:optional, false),
+        enum: options[:enum],
+        default: options.fetch(:default, :__unset__),
+        &block
+      )
+    end
+  end
+end

data/lib/toolchest/tool_definition.rb

@@ -0,0 +1,58 @@
+module Toolchest
+  class ToolDefinition
+    attr_reader :method_name, :description, :params, :toolbox_class, :custom_name, :access_level, :annotations
+
+    def initialize(method_name:, description:, params:, toolbox_class:, custom_name: nil, access_level: nil, annotations: nil)
+      @method_name = method_name.to_sym
+      @description = description
+      @params = params
+      @toolbox_class = toolbox_class
+      @custom_name = custom_name
+      @access_level = access_level
+      @annotations = annotations
+    end
+
+    def tool_name(naming_strategy = nil)
+      return @custom_name if @custom_name
+      naming_strategy ||= Toolchest.configuration.tool_naming
+      Naming.generate(toolbox_class, method_name, naming_strategy)
+    end
+
+    def to_mcp_schema(naming_strategy = nil)
+      schema = {
+        name: tool_name(naming_strategy),
+        description: @description,
+        inputSchema: input_schema
+      }
+      hints = resolved_annotations
+      schema[:annotations] = hints if hints.any?
+      schema
+    end
+
+    def resolved_annotations
+      base = case @access_level
+      when :read
+        { readOnlyHint: true, destructiveHint: false }
+      when :write
+        { readOnlyHint: false, destructiveHint: true }
+      else
+        {}
+      end
+      base.merge(@annotations || {})
+    end
+
+    def input_schema
+      properties = {}
+      required = []
+
+      @params.each do |param|
+        properties[param.name] = param.to_json_schema
+        required << param.name.to_s if param.required?
+      end
+
+      schema = { type: "object", properties: properties }
+      schema[:required] = required if required.any?
+      schema
+    end
+  end
+end

data/lib/toolchest/toolbox.rb

@@ -0,0 +1,312 @@
+require "abstract_controller/callbacks"
+require "active_support/rescuable"
+require "active_support/concern"
+
+module Toolchest
+  class Toolbox
+    include ActiveSupport::Callbacks
+    include AbstractController::Callbacks
+    include ActiveSupport::Rescuable
+
+    class << self
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@_tool_definitions, {})
+        subclass.instance_variable_set(:@_default_params, [])
+        subclass.instance_variable_set(:@_resources, [])
+        subclass.instance_variable_set(:@_prompts, [])
+        subclass.instance_variable_set(:@_pending_tool, nil)
+      end
+
+      def tool_definitions
+        ancestors
+          .select { |a| a.respond_to?(:own_tool_definitions, true) }
+          .reverse
+          .each_with_object({}) { |a, h| h.merge!(a.send(:own_tool_definitions)) }
+      end
+
+      def default_params
+        ancestors
+          .select { |a| a.respond_to?(:own_default_params, true) }
+          .reverse
+          .flat_map { |a| a.send(:own_default_params) }
+      end
+
+      def resources
+        ancestors
+          .select { |a| a.respond_to?(:own_resources, true) }
+          .reverse
+          .flat_map { |a| a.send(:own_resources) }
+      end
+
+      def prompts
+        ancestors
+          .select { |a| a.respond_to?(:own_prompts, true) }
+          .reverse
+          .flat_map { |a| a.send(:own_prompts) }
+      end
+
+      def tool(description, name: nil, access: nil, annotations: nil, &block)
+        builder = ToolBuilder.new
+        builder.instance_eval(&block) if block
+        @_pending_tool = { description: description, custom_name: name, access_level: access, annotations: annotations, builder: builder }
+      end
+
+      def default_param(name, type, description = "", **options)
+        @_default_params << {
+          param: ParamDefinition.new(
+            name: name, type: type, description: description,
+            optional: options.fetch(:optional, false),
+            enum: options[:enum],
+            default: options.fetch(:default, :__unset__)
+          ),
+          except: Array(options[:except]).map(&:to_sym),
+          only: options[:only] ? Array(options[:only]).map(&:to_sym) : nil
+        }
+      end
+
+      def resource(uri, name: nil, description: nil, &block)
+        template = uri.include?("{")
+        @_resources << {
+          uri: uri,
+          name: name || uri,
+          description: description,
+          block: block,
+          template: template,
+          toolbox_class: self
+        }
+      end
+
+      def prompt(prompt_name, description: nil, arguments: {}, &block)
+        @_prompts << {
+          name: prompt_name,
+          description: description,
+          arguments: arguments,
+          block: block,
+          toolbox_class: self
+        }
+      end
+
+      def method_added(method_name)
+        super
+        return unless @_pending_tool
+
+        pending = @_pending_tool
+        @_pending_tool = nil
+
+        params = pending[:builder].params.dup
+
+        default_params.each do |dp|
+          next if dp[:except].include?(method_name.to_sym)
+          next if dp[:only] && !dp[:only].include?(method_name.to_sym)
+          next if params.any? { |p| p.name == dp[:param].name }
+          params.unshift(dp[:param])
+        end
+
+        definition = ToolDefinition.new(
+          method_name: method_name,
+          description: pending[:description],
+          params: params,
+          toolbox_class: self,
+          custom_name: pending[:custom_name],
+          access_level: pending[:access_level],
+          annotations: pending[:annotations]
+        )
+
+        @_tool_definitions[method_name.to_sym] = definition
+      end
+
+      def controller_name = name&.underscore&.chomp("_toolbox") || "anonymous"
+
+      protected
+
+      def own_tool_definitions = @_tool_definitions || {}
+
+      def own_default_params = @_default_params || []
+
+      def own_resources = @_resources || []
+
+      def own_prompts = @_prompts || []
+    end
+
+    attr_reader :params
+
+    def initialize(params: {}, tool_definition: nil)
+      @params = Parameters.new(params, tool_definition: tool_definition)
+      @_tool_definition = tool_definition
+      @_response = nil
+      @_suggests = []
+    end
+
+    def auth = Toolchest::Current.auth
+
+    def controller_name = self.class.controller_name
+
+    def action_name = @_action_name.to_s
+
+    def performed? = @_response.present?
+
+    def render(action_or_template = nil, json: nil, text: nil)
+      result = if json
+        json.is_a?(String) ? json : json.to_json
+      elsif text
+        text
+      else
+        rendered = Renderer.render(self, action_or_template || action_name)
+        rendered.is_a?(String) ? rendered : rendered.to_json
+      end
+
+      @_response = {
+        content: [{ type: "text", text: result }],
+        isError: false
+      }
+    end
+
+    def render_error(message)
+      @_response = {
+        content: [{ type: "text", text: message }],
+        isError: true
+      }
+    end
+
+    def render_errors(record)
+      messages = record.errors.full_messages.join(", ")
+      render_error("Validation failed: #{messages}")
+    end
+
+    def suggests(tool_name, hint = nil)
+      tool_name = tool_name.to_s
+      if tool_name.exclude?("_") && tool_name.exclude?(".") && tool_name.exclude?("/")
+        tool_name = Naming.generate(self.class, tool_name)
+      end
+      @_suggests << { tool: tool_name, hint: hint }
+    end
+
+    def halt(**response)
+      if response[:error]
+        render_error(response[:error])
+      end
+      throw :halt
+    end
+
+    def mcp_log(level, message) = Toolchest.router(Toolchest::Current.mount_key&.to_sym || :default).notify_log(level: level.to_s, message: message)
+
+    # Report progress during long-running actions.
+    # Client shows a progress bar. total and message are optional.
+    def mcp_progress(progress, total: nil, message: nil)
+      session = Toolchest::Current.mcp_session
+      return unless session
+
+      token = Toolchest::Current.mcp_progress_token
+      return unless token
+
+      session.notify_progress(
+        progress_token: token,
+        progress: progress,
+        total: total,
+        message: message,
+        related_request_id: Toolchest::Current.mcp_request_id
+      )
+    end
+
+    # Ask the client's LLM to do work. Returns the response text.
+    #
+    #   mcp_sample("Summarize this order", context: @order.to_json)
+    #
+    #   mcp_sample do |s|
+    #     s.system "You are a fraud analyst"
+    #     s.user "Analyze: #{@order.to_json}"
+    #     s.max_tokens 500
+    #     s.temperature 0.3
+    #   end
+    def mcp_sample(prompt = nil, context: nil, max_tokens: 1024, **kwargs, &block)
+      session = Toolchest::Current.mcp_session
+      raise Toolchest::Error, "Sampling requires an MCP client that supports it" unless session
+
+      if block
+        builder = SamplingBuilder.new
+        yield builder
+        messages = builder.messages
+        options = { max_tokens: builder.max_tokens_value || max_tokens }
+        options[:system_prompt] = builder.system_value if builder.system_value
+        options[:temperature] = builder.temperature_value if builder.temperature_value
+        options[:model_preferences] = builder.model_preferences_value if builder.model_preferences_value
+        options[:stop_sequences] = builder.stop_sequences_value if builder.stop_sequences_value
+      else
+        text = prompt.to_s
+        text = "#{text}\n\n#{context}" if context
+        messages = [{ role: "user", content: { type: "text", text: text } }]
+        options = { max_tokens: max_tokens }
+        options[:system_prompt] = kwargs[:system] if kwargs[:system]
+        options[:temperature] = kwargs[:temperature] if kwargs[:temperature]
+      end
+
+      begin
+        result = session.create_sampling_message(
+          messages: messages,
+          related_request_id: Toolchest::Current.mcp_request_id,
+          **options
+        )
+      rescue RuntimeError => e
+        raise Toolchest::Error, "Sampling failed: #{e.message}"
+      end
+
+      # Extract text from response
+      content = result[:content] || result["content"]
+      case content
+      when Hash then content[:text] || content["text"]
+      when Array then content.map { |c| c[:text] || c["text"] }.compact.join("\n")
+      when String then content
+      else result.to_s
+      end
+    end
+
+    def dispatch(action_name)
+      @_action_name = action_name
+
+      catch(:halt) do
+        begin
+          process_action(action_name)
+        rescue => e
+          unless rescue_with_handler(e)
+            raise
+          end
+        end
+      end
+
+      implicit_render! unless performed?
+      build_mcp_response
+    end
+
+    private
+
+    def process_action(action_name)
+      run_callbacks :process_action do
+        send(action_name)
+      end
+    end
+
+    def implicit_render!
+      render(action_name)
+    rescue Toolchest::MissingTemplate
+      raise Toolchest::MissingTemplate,
+        "Missing template toolboxes/#{controller_name}/#{action_name}.json.jb"
+    end
+
+    def build_mcp_response
+      response = @_response || { content: [], isError: false }
+
+      if @_suggests.any?
+        hints = @_suggests.map { |s|
+          text = "Suggested next: call #{s[:tool]}"
+          text += " — #{s[:hint]}" if s[:hint]
+          text
+        }.join("\n")
+
+        response[:content] << { type: "text", text: hints }
+      end
+
+      response
+    end
+  end
+end

data/lib/toolchest/version.rb

@@ -0,0 +1,3 @@
+module Toolchest
+  VERSION = "0.3.2"
+end

data/lib/toolchest.rb

@@ -0,0 +1,89 @@
+require "active_support"
+require "active_support/core_ext"
+require "toolchest/version"
+
+module Toolchest
+  autoload :App, "toolchest/app"
+  autoload :AuthContext, "toolchest/auth_context"
+  autoload :Configuration, "toolchest/configuration"
+  autoload :Current, "toolchest/current"
+  autoload :Naming, "toolchest/naming"
+  autoload :Parameters, "toolchest/parameters"
+  autoload :ParamDefinition, "toolchest/param_definition"
+  autoload :Endpoint, "toolchest/endpoint"
+  autoload :RackApp, "toolchest/rack_app"
+  autoload :Renderer, "toolchest/renderer"
+  autoload :Router, "toolchest/router"
+  autoload :SamplingBuilder, "toolchest/sampling_builder"
+  autoload :Toolbox, "toolchest/toolbox"
+  autoload :ToolBuilder, "toolchest/tool_builder"
+  autoload :ToolDefinition, "toolchest/tool_definition"
+
+  module Auth
+    autoload :Base, "toolchest/auth/base"
+    autoload :None, "toolchest/auth/none"
+    autoload :Token, "toolchest/auth/token"
+    autoload :OAuth, "toolchest/auth/oauth"
+  end
+
+  class Error < StandardError; end
+  class MissingTemplate < Error; end
+  class ParameterMissing < Error; end
+
+  class << self
+    # Per-mount configuration
+    # Toolchest.configure { } → configures :default
+    # Toolchest.configure(:admin) { } → configures :admin
+    def configure(name = :default, &block)
+      @configs ||= {}
+      @configs[name.to_sym] ||= Configuration.new(name)
+      yield @configs[name.to_sym] if block
+      @configs[name.to_sym]
+    end
+
+    # Toolchest.configuration → :default config (backward compat)
+    # Toolchest.configuration(:admin) → :admin config
+    def configuration(name = :default)
+      @configs ||= {}
+      @configs[name.to_sym] ||= Configuration.new(name)
+    end
+
+    # Returns a Rack app for a mount.
+    # Toolchest.app → :default app
+    # Toolchest.app(:admin) → :admin app
+    def app(name = :default)
+      @apps ||= {}
+      @apps[name.to_sym] ||= App.new(name.to_sym)
+    end
+
+    # Per-mount router
+    def router(name = :default)
+      @routers ||= {}
+      @routers[name.to_sym] ||= Router.new(mount_key: name.to_sym)
+    end
+
+    # All configured mount names
+    def mount_keys = (@configs || {}).keys
+
+    # When multiple OAuth mounts exist, bare /.well-known/* resolves to this mount
+    attr_accessor :default_oauth_mount
+
+    def reset!
+      @configs = nil
+      @routers = nil
+      @apps = nil
+      @default_oauth_mount = nil
+    end
+
+    # Reset only routers/apps (preserves config set by initializers)
+    def reset_routers!
+      @routers = nil
+      @apps = nil
+    end
+  end
+end
+
+if defined?(Rails::Engine)
+  require "toolchest/engine"
+  require "toolchest/oauth/routes"
+end