toolchest 0.3.2

data/lib/toolchest/param_definition.rb

@@ -0,0 +1,69 @@
+module Toolchest
+  class ParamDefinition
+    attr_reader :name, :type, :description, :optional, :enum, :default, :children
+
+    def initialize(name:, type:, description: "", optional: false, enum: nil, default: :__unset__, &block)
+      @name = name.to_sym
+      @type = type
+      @description = description
+      @optional = optional
+      @enum = enum
+      @default = default
+      @children = []
+
+      if block
+        builder = ToolBuilder.new
+        builder.instance_eval(&block)
+        @children = builder.params
+      end
+    end
+
+    def required? = !@optional
+
+    def has_default? = @default != :__unset__
+
+    def to_json_schema
+      schema = case @type
+      when :string
+        { type: "string" }
+      when :integer
+        { type: "integer" }
+      when :number
+        { type: "number" }
+      when :boolean
+        { type: "boolean" }
+      when :object
+        object_schema
+      when Array
+        if @type.first == :object
+          { type: "array", items: object_schema }
+        else
+          { type: "array", items: { type: @type.first.to_s } }
+        end
+      else
+        { type: @type.to_s }
+      end
+
+      schema[:description] = @description if @description.present?
+      schema[:enum] = @enum if @enum
+      schema[:default] = @default if has_default?
+      schema
+    end
+
+    private
+
+    def object_schema
+      props = {}
+      required = []
+
+      @children.each do |child|
+        props[child.name] = child.to_json_schema
+        required << child.name.to_s if child.required?
+      end
+
+      schema = { type: "object", properties: props }
+      schema[:required] = required if required.any?
+      schema
+    end
+  end
+end

data/lib/toolchest/parameters.rb

@@ -0,0 +1,71 @@
+require "active_support/hash_with_indifferent_access"
+
+module Toolchest
+  class Parameters
+    def initialize(raw = {}, tool_definition: nil)
+      @raw = raw.is_a?(Hash) ? raw : {}
+
+      if tool_definition
+        allowed_keys = tool_definition.params.map { |p| p.name.to_s }
+        filtered = @raw.select { |k, _| allowed_keys.include?(k.to_s) }
+        @params = ActiveSupport::HashWithIndifferentAccess.new(filtered)
+      else
+        @params = ActiveSupport::HashWithIndifferentAccess.new(@raw)
+      end
+    end
+
+    def [](key)
+      @params[key]
+    end
+
+    def fetch(key, *args, &block) = @params.fetch(key, *args, &block)
+
+    def key?(key) = @params.key?(key)
+    alias_method :has_key?, :key?
+    alias_method :include?, :key?
+
+    def to_h = @params.to_h
+    alias_method :to_hash, :to_h
+
+    def slice(*keys) = @params.slice(*keys.map(&:to_s))
+
+    def except(*keys) = @params.except(*keys.map(&:to_s))
+
+    def require(key)
+      value = @params[key]
+      if value.nil? && !@params.key?(key.to_s)
+        raise Toolchest::ParameterMissing, "param is missing or the value is empty: #{key}"
+      end
+      value
+    end
+
+    def permit(*keys)
+      permitted = {}
+      keys.each do |key|
+        case key
+        when Symbol, String
+          permitted[key.to_s] = @params[key] if @params.key?(key.to_s)
+        when Hash
+          key.each do |k, v|
+            if @params.key?(k.to_s) && @params[k].is_a?(Array)
+              permitted[k.to_s] = @params[k].map do |item|
+                item.is_a?(Hash) ? item.slice(*v.map(&:to_s)) : item
+              end
+            elsif @params.key?(k.to_s) && @params[k].is_a?(Hash)
+              permitted[k.to_s] = @params[k].slice(*v.map(&:to_s))
+            end
+          end
+        end
+      end
+      ActiveSupport::HashWithIndifferentAccess.new(permitted)
+    end
+
+    def empty? = @params.empty?
+
+    def each(&block) = @params.each(&block)
+
+    def merge(other) = self.class.new(@params.merge(other))
+
+    def inspect = "#<Toolchest::Parameters #{@params.inspect}>"
+  end
+end

data/lib/toolchest/rack_app.rb

@@ -0,0 +1,114 @@
+module Toolchest
+  class RackApp
+    attr_reader :mount_key
+
+    def initialize(mount_key: :default)
+      @mount_key = mount_key.to_sym
+      @server = build_mcp_server
+      @transport = MCP::Server::Transports::StreamableHTTPTransport.new(@server)
+      @server.transport = @transport
+      install_handlers!
+    end
+
+    def call(env)
+      request = Rack::Request.new(env)
+      env["toolchest.mount_key"] ||= @mount_key.to_s
+
+      auth = authenticate(request)
+
+      if auth.nil? && config.auth != :none
+        mount_path = config.mount_path || "/mcp"
+        resource_metadata = "#{request.base_url}/.well-known/oauth-protected-resource#{mount_path}"
+        return [401, {
+          "WWW-Authenticate" => %(Bearer resource_metadata="#{resource_metadata}"),
+          "Content-Type" => "application/json"
+        }, ['{"error":"unauthorized"}']]
+      end
+
+      Toolchest::Current.set(auth: auth, mount_key: @mount_key.to_s) do
+        status, headers, body = @transport.handle_request(request)
+        # The transport may return a streaming body (proc) that executes after
+        # Current.set unwinds. Wrap it to restore Current for the duration.
+        wrapped_body = if body.respond_to?(:call)
+          captured_auth = auth
+          captured_mount = @mount_key.to_s
+          proc { |stream|
+            Toolchest::Current.set(auth: captured_auth, mount_key: captured_mount) do
+              body.call(stream)
+            end
+          }
+        else
+          body
+        end
+        [status, headers.dup, wrapped_body]
+      end
+    end
+
+    private
+
+    def config = Toolchest.configuration(@mount_key)
+
+    def build_mcp_server
+      opts = {
+        name: config.resolved_server_name,
+        version: config.server_version,
+        capabilities: {
+          tools: { listChanged: true },
+          prompts: { listChanged: true },
+          resources: { listChanged: true },
+          logging: {},
+          completions: {}
+        }
+      }
+
+      opts[:description] = config.server_description if config.server_description
+      opts[:instructions] = config.server_instructions if config.server_instructions
+
+      MCP::Server.new(**opts)
+    end
+
+    def install_handlers!
+      router = Toolchest.router(@mount_key)
+      server = @server
+
+      router.mcp_server = server
+
+      handlers = server.instance_variable_get(:@handlers)
+
+      handlers[MCP::Methods::TOOLS_LIST] = ->(params) { router.tools_for_handler }
+      handlers[MCP::Methods::RESOURCES_LIST] = ->(params) { router.resources_for_handler }
+      handlers[MCP::Methods::RESOURCES_READ] = ->(params) { router.resources_read_response(params) }
+      handlers[MCP::Methods::RESOURCES_TEMPLATES_LIST] = ->(params) { router.resource_templates_for_handler }
+      handlers[MCP::Methods::PROMPTS_LIST] = ->(params) { router.prompts_for_handler }
+      handlers[MCP::Methods::PROMPTS_GET] = ->(params) { router.prompts_get_response(params) }
+
+      # tools/call is hardcoded in handle_request to call private call_tool
+      server.define_singleton_method(:call_tool) do |params, session: nil, related_request_id: nil|
+        progress_token = params.dig(:_meta, :progressToken)
+        Toolchest::Current.mcp_session = session
+        Toolchest::Current.mcp_request_id = related_request_id
+        Toolchest::Current.mcp_progress_token = progress_token
+        router.dispatch_response(params)
+      end
+
+      # completion/complete is hardcoded to call private complete, which validates
+      # against registered prompts/resources (we don't register any). override it.
+      server.define_singleton_method(:complete) do |params|
+        arg_name = params.dig(:argument, :name) || params.dig(:argument, "name")
+        values = arg_name ? router.completion_values(arg_name) : []
+        { completion: { values: values, hasMore: false } }
+      end
+    end
+
+    def authenticate(request)
+      strategy = case config.auth
+      when :none then Auth::None.new
+      when :token then Auth::Token.new
+      when :oauth then Auth::OAuth.new(@mount_key)
+      else config.auth
+      end
+
+      strategy.authenticate(request)
+    end
+  end
+end

data/lib/toolchest/renderer.rb

@@ -0,0 +1,88 @@
+require "action_view"
+
+module Toolchest
+  module Renderer
+    class << self
+      def render(toolbox, action_or_template)
+        ensure_handlers_registered!
+
+        name = action_or_template.to_s
+        template_name = name.include?("/") ? name : "#{toolbox.controller_name}/#{name}"
+        assigns = extract_assigns(toolbox)
+
+        lookup = ActionView::LookupContext.new(view_paths)
+        view = ActionView::Base.with_empty_template_cache.new(lookup, assigns, nil)
+
+        result = view.render(template: template_name, formats: [:json])
+
+        case result
+        when String
+          # jb returns JSON string via monkey patches, jbuilder returns JSON string natively
+          begin
+            JSON.parse(result)
+          rescue JSON::ParserError
+            result
+          end
+        when Hash, Array
+          result
+        else
+          result
+        end
+      rescue ActionView::MissingTemplate
+        raise Toolchest::MissingTemplate,
+          "Missing template toolboxes/#{template_name} with formats: json (searched in: #{view_paths.join(", ")})"
+      end
+
+      private
+
+      def ensure_handlers_registered!
+        return if @handlers_registered
+
+        handler_found = false
+
+        # Register jb handler if available
+        begin
+          require "jb/handler"
+          require "jb/action_view_monkeys"
+          ActionView::Template.register_template_handler :jb, Jb::Handler
+          handler_found = true
+        rescue LoadError
+        end
+
+        # jbuilder registers via its own railtie, but if we're outside Rails boot:
+        begin
+          require "jbuilder/jbuilder_template"
+          handler_found = true
+        rescue LoadError
+        end
+
+        unless handler_found
+          warn "[Toolchest] No template handler found. Add gem 'jb' (recommended) or gem 'jbuilder' to your Gemfile."
+        end
+
+        @handlers_registered = true
+      end
+
+      def extract_assigns(toolbox)
+        assigns = {}
+        toolbox.instance_variables.each do |ivar|
+          next if ivar.to_s.start_with?("@_")
+          key = ivar.to_s.sub("@", "")
+          assigns[key] = toolbox.instance_variable_get(ivar)
+        end
+        assigns
+      end
+
+      def view_paths
+        paths = []
+        if defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+          paths << Rails.root.join("app", "views", "toolboxes").to_s
+        end
+        paths += Toolchest.configuration.additional_view_paths
+        paths
+      end
+
+      def reset! = @handlers_registered = false
+    end
+  end
+end

data/lib/toolchest/router.rb

@@ -0,0 +1,277 @@
+module Toolchest
+  class Router
+    attr_accessor :mcp_server, :rack_app
+
+    def initialize(mount_key: :default)
+      @mount_key = mount_key.to_sym
+      @tool_map = {}
+      @toolbox_classes = []
+      @mcp_server = nil
+      @rack_app = nil
+    end
+
+    def register(toolbox_class)
+      @toolbox_classes << toolbox_class unless @toolbox_classes.include?(toolbox_class)
+      rebuild_tool_map!
+    end
+
+    def toolbox_classes = @toolbox_classes
+
+    def tools_list = tool_definitions.map { |td| td.to_mcp_schema }
+
+    # For the MCP SDK handler — returns array (SDK wraps it)
+    def tools_for_handler
+      config = Toolchest.configuration(@mount_key)
+
+      unless config.filter_tools_by_scope
+        return tools_list
+      end
+
+      auth = Toolchest::Current.auth
+
+      # No auth: show all tools for :none, show nothing otherwise
+      unless auth
+        return config.auth == :none ? tools_list : []
+      end
+
+      scopes = extract_scopes(auth)
+
+      # Auth present but no scopes extractable: fail closed
+      unless scopes
+        return []
+      end
+
+      tool_definitions.select { |td| tool_allowed_by_scopes?(td, scopes) }
+                      .map { |td| td.to_mcp_schema }
+    end
+
+    def dispatch(tool_name, arguments = {})
+      definition = find_tool(tool_name)
+      unless definition
+        return { content: [{ type: "text", text: "Unknown tool: #{tool_name}" }], isError: true }
+      end
+
+      config = Toolchest.configuration(@mount_key)
+      if config.filter_tools_by_scope
+        auth = Toolchest::Current.auth
+        scopes = auth ? extract_scopes(auth) : nil
+        if config.auth != :none && (!scopes || !tool_allowed_by_scopes?(definition, scopes))
+          return { content: [{ type: "text", text: "Forbidden: insufficient scope" }], isError: true }
+        end
+      end
+
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      auth = Toolchest::Current.auth
+      token_hint = extract_token_hint(auth)
+
+      log_request_start(definition, arguments, token_hint)
+
+      toolbox = definition.toolbox_class.new(
+        params: arguments,
+        tool_definition: definition
+      )
+      response = toolbox.dispatch(definition.method_name)
+
+      duration = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000).round(1)
+      log_request_complete(definition, response, duration)
+
+      response
+    end
+
+    def dispatch_response(params)
+      name = params[:name] || params["name"]
+      arguments = params[:arguments] || params["arguments"] || {}
+      dispatch(name, arguments)
+    end
+
+    def resources_list = @toolbox_classes.flat_map(&:resources).reject { |r| r[:template] }
+
+    def resources_for_handler
+      resources_list.map { |r|
+        { uri: r[:uri], name: r[:name], description: r[:description] }.compact
+      }
+    end
+
+    def resource_templates_for_handler
+      @toolbox_classes.flat_map(&:resources).select { |r| r[:template] }.map { |r|
+        { uriTemplate: r[:uri], name: r[:name], description: r[:description] }.compact
+      }
+    end
+
+    def resources_read(uri)
+      resource = @toolbox_classes.flat_map(&:resources).find { |r|
+        if r[:template]
+          pattern = r[:uri].gsub(/\{[^}]+\}/, "([^/]+)")
+          uri.match?(Regexp.new("^#{pattern}$"))
+        else
+          r[:uri] == uri
+        end
+      }
+
+      unless resource
+        return [{ uri: uri, mimeType: "text/plain", text: "Resource not found: #{uri}" }]
+      end
+
+      result = if resource[:template]
+        pattern = resource[:uri].gsub(/\{([^}]+)\}/, '(?<\1>[^/]+)')
+        match = uri.match(Regexp.new("^#{pattern}$"))
+        kwargs = match.named_captures.transform_keys(&:to_sym)
+        resource[:block].call(**kwargs)
+      else
+        resource[:block].call
+      end
+
+      [{ uri: uri, mimeType: "application/json", text: result.to_json }]
+    end
+
+    def resources_read_response(params)
+      uri = params[:uri] || params["uri"]
+      resources_read(uri)
+    end
+
+    def prompts_list = @toolbox_classes.flat_map(&:prompts)
+
+    def prompts_for_handler
+      prompts_list.map { |p|
+        prompt = { name: p[:name], description: p[:description] }.compact
+        if p[:arguments].any?
+          prompt[:arguments] = p[:arguments].map { |name, opts|
+            arg = { name: name.to_s }
+            arg[:description] = opts[:description] if opts[:description]
+            arg[:required] = opts[:required] if opts.key?(:required)
+            arg
+          }
+        end
+        prompt
+      }
+    end
+
+    def prompts_get(name, arguments = {})
+      prompt = prompts_list.find { |p| p[:name] == name }
+      return { messages: [] } unless prompt
+
+      kwargs = arguments.transform_keys(&:to_sym)
+      messages = prompt[:block].call(**kwargs)
+      { messages: messages }
+    end
+
+    def prompts_get_response(params)
+      name = params[:name] || params["name"]
+      arguments = params[:arguments] || params["arguments"] || {}
+      prompts_get(name, arguments)
+    end
+
+    def completion_values(argument_name)
+      tool_definitions.flat_map(&:params)
+        .select { |p| p.name.to_s == argument_name.to_s && p.enum }
+        .flat_map(&:enum)
+        .uniq
+    end
+
+    def notify_log(level:, message:)
+      return unless @mcp_server
+      @mcp_server.notify_log_message(
+        data: message,
+        level: level,
+        logger: "Toolchest"
+      )
+    end
+
+    private
+
+    def tool_definitions = @toolbox_classes.flat_map { |klass| klass.tool_definitions.values }
+
+    def find_tool(tool_name)
+      rebuild_tool_map! if @tool_map.empty? && @toolbox_classes.any?
+      @tool_map[tool_name]
+    end
+
+    def rebuild_tool_map!
+      @tool_map = {}
+      tool_definitions.each do |td|
+        if @tool_map.key?(td.tool_name) && @tool_map[td.tool_name].toolbox_class != td.toolbox_class
+          existing = @tool_map[td.tool_name].toolbox_class.name
+          raise Toolchest::Error,
+            "Duplicate tool name '#{td.tool_name}' in #{td.toolbox_class.name} " \
+            "(already defined in #{existing})"
+        end
+        @tool_map[td.tool_name] = td
+      end
+    end
+
+    # --- Scope filtering ---
+
+    def extract_scopes(auth)
+      return nil unless auth
+      if auth.respond_to?(:scopes_array)
+        auth.scopes_array
+      elsif auth.respond_to?(:scopes) && auth.scopes.is_a?(String)
+        auth.scopes.split(" ").reject(&:empty?)
+      elsif auth.respond_to?(:scopes) && auth.scopes.is_a?(Array)
+        auth.scopes
+      else
+        nil
+      end
+    end
+
+    READ_ACTIONS = Set.new(%i[show index list search]).freeze
+
+    def tool_allowed_by_scopes?(tool_definition, scopes)
+      return true if scopes.empty?
+
+      prefix = tool_definition.toolbox_class.controller_name.split("/").last
+      tool_access = tool_definition.access_level ||
+        (READ_ACTIONS.include?(tool_definition.method_name) ? :read : :write)
+
+      scopes.any? { |s|
+        scope_prefix, scope_action = s.split(":", 2)
+        next false unless scope_prefix == prefix
+
+        # No action suffix (e.g. "orders") → full access
+        next true if scope_action.nil?
+
+        # "write" scope grants both read and write
+        scope_action == tool_access.to_s || scope_action == "write"
+      }
+    end
+
+    # --- Request logging ---
+
+    def log_request_start(definition, arguments, token_hint)
+      return unless logger
+
+      toolbox_name = definition.toolbox_class.name || definition.toolbox_class.controller_name.camelize
+      method_name = definition.method_name
+
+      parts = ["MCP #{toolbox_name}##{method_name}"]
+      parts << "(#{token_hint})" if token_hint
+      logger.info parts.join(" ")
+
+      filtered = arguments.respond_to?(:to_h) ? arguments.to_h : arguments
+      logger.info "  Parameters: #{filtered.inspect}" if filtered.any?
+    end
+
+    def log_request_complete(definition, response, duration)
+      return unless logger
+
+      status = response[:isError] ? "Error" : "OK"
+      logger.info "Completed #{status} in #{duration}ms"
+    end
+
+    def extract_token_hint(auth)
+      return nil unless auth
+      if auth.respond_to?(:token) && auth.token.is_a?(String)
+        "#{auth.token[0..8]}..."
+      elsif auth.respond_to?(:token_digest) && auth.token_digest.is_a?(String)
+        "#{auth.token_digest[0..8]}..."
+      else
+        nil
+      end
+    end
+
+    def logger
+      return @logger if defined?(@logger)
+      @logger = defined?(Rails) && Rails.respond_to?(:logger) ? Rails.logger : nil
+    end
+  end
+end

data/lib/toolchest/rspec.rb

@@ -0,0 +1,61 @@
+require "toolchest"
+
+module Toolchest
+  module RSpec
+    class ToolResponse
+      attr_reader :raw
+
+      def initialize(raw) = @raw = raw
+
+      def success? = !error?
+
+      def error? = @raw[:isError] == true
+
+      def content = @raw[:content] || []
+
+      def text = content.map { |c| c[:text] }.compact.join("\n")
+
+      def suggests?(tool_name) = text.include?("Suggested next: call #{tool_name}")
+    end
+
+    module Helpers
+      def call_tool(tool_name, params: {}, as: nil)
+        Toolchest::Current.set(auth: as) do
+          raw = Toolchest.router.dispatch(tool_name, params)
+          @_tool_response = ToolResponse.new(raw)
+        end
+      end
+
+      def tool_response = @_tool_response
+    end
+
+    module Matchers
+      extend ::RSpec::Matchers::DSL
+
+      matcher :be_success do
+        match { |response| response.success? }
+        failure_message { "expected tool response to be success, got error: #{actual.text}" }
+      end
+
+      matcher :be_error do
+        match { |response| response.error? }
+        failure_message { "expected tool response to be an error, but it succeeded" }
+      end
+
+      matcher :include_text do |expected|
+        match { |response| response.text.include?(expected) }
+        failure_message { "expected tool response text to include #{expected.inspect}, got: #{actual.text}" }
+      end
+
+      matcher :suggest do |tool_name|
+        match { |response| response.suggests?(tool_name) }
+        failure_message { "expected tool response to suggest #{tool_name}, got: #{actual.text}" }
+      end
+    end
+  end
+end
+
+RSpec.configure do |config|
+  config.include Toolchest::RSpec::Helpers, type: :toolbox
+  config.include Toolchest::RSpec::Matchers, type: :toolbox
+end