toolchest 0.3.2 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c78a7f55b37d501c0e2d5c4e164048ea4d176f2eb7126c232953a1c4c52e1da
-  data.tar.gz: 403d4c3b8ee52953630e52f0d4d31f1a31e9d406511fdfdd7c4f47a67f083bf6
+  metadata.gz: 545413528704477fdfc39328f3380e82b1f80c9be8096bc36fe201cddf90ce02
+  data.tar.gz: 4beea37ac5456c21b9b4ec41711643f5c1b2155669e2370badb2e03ad45c0b49
 SHA512:
-  metadata.gz: c4c8ca2520fc43e69398fffa2f25a08db7ec0566c7f9453f5fb5d442744e4c42be5ac53ffcb037ad5181a4bac8395970f0ea9b1c925fd6cfe6ab044f1e097b72
-  data.tar.gz: b0fd64277dd46191d91681b7c3cbaf14b70b03ac80324fe9d1a01e6b2455486e2d6c6c3c2dbd214430be2867d7f5967538f6ad4a2d76ed855664c44d14c0da65
+  metadata.gz: 60ef42ecc96cecf2c0a9b9ea26cf786dc72ced48fafa1840cc56f53141657f9791fc2ec2446dc328f6463aaca9cc37564f9365e8a7c851b30256cdb8fb9e3669
+  data.tar.gz: a8ea33024b69f8154a78d7a4664afdbddc57e01b87c4daa5f01b64dc5a8d1191b44004d9fedd060a57a013bc87cc14f8c462be683d08d82d78708d16210d98e1

data/LLMS.txt

@@ -213,7 +213,12 @@ end
 
 Types: `:string`, `:integer`, `:number`, `:boolean`, `:object`, `[:object]`, `[:string]`, etc.
 
-Options on `tool`: `name: "custom_tool_name"`, `access: :read` or `access: :write` (for scope filtering + annotations), `annotations: { openWorldHint: true }` (override hints).
+Options on `tool`:
+
+- `name: "custom_tool_name"` — override generated tool name
+- `access: :read` or `access: :write` — scope filtering + MCP annotations
+- `scope: "admin"` or `scope: ["admin", "superuser"]` — per-tool scope override (see below)
+- `annotations: { openWorldHint: true }` — override MCP hints
 
 `access: :read` → `readOnlyHint: true, destructiveHint: false`. `access: :write` → `readOnlyHint: false, destructiveHint: true`.
 
@@ -345,6 +350,22 @@ Scopes filter `tools/list` — clients only see tools their token allows. Fails
 
 Disable: `config.filter_tools_by_scope = false`
 
+### Per-tool scope override
+
+When a tool doesn't fit its toolbox's scope boundary, set `scope:` to bypass the convention:
+
+```ruby
+tool "Move ticket", scope: "admin" do       # only "admin" scope grants access
+  param :status, :string, "New status"
+end
+
+tool "Escalate", scope: ["admin", "superuser"] do  # either scope works (OR)
+  param :id, :string, "ID"
+end
+```
+
+`scope:` replaces convention matching for that tool. `tickets:write` won't grant access to a tool with `scope: "admin"`. Enforced on both `tools/list` and `tools/call`.
+
 ### Optional scopes (checkboxes on consent)
 
 ```ruby

data/README.md

@@ -421,6 +421,32 @@ end
 
 Turn it off: `config.filter_tools_by_scope = false`
 
+### Per-tool scope override
+
+The convention derives scopes from the toolbox name — `OrdersToolbox` tools require `orders:*`. When a tool doesn't fit its toolbox's scope boundary, override it:
+
+```ruby
+class TicketsToolbox < ApplicationToolbox
+  tool "List tickets" do
+  end
+  def list = # ... requires tickets:read (convention)
+
+  # Only tokens with the "admin" scope can see or call this tool
+  tool "Move ticket", scope: "admin" do
+    param :status, :string, "New status"
+  end
+  def move = # ...
+
+  # Either "admin" OR "superuser" grants access
+  tool "Escalate ticket", scope: ["admin", "superuser"] do
+    param :id, :string, "Ticket ID"
+  end
+  def escalate = # ...
+end
+```
+
+`scope:` replaces the convention entirely for that tool — `tickets:write` won't grant access to a tool with `scope: "admin"`. The token must include the literal scope string. Enforced on both `tools/list` (visibility) and `tools/call` (execution).
+
 ### Optional scopes (checkboxes)
 
 By default, the consent screen is all-or-nothing — approve all requested scopes or deny. Enable `optional_scopes` and users get checkboxes:

data/lib/toolchest/router.rb

@@ -219,6 +219,10 @@ module Toolchest
     def tool_allowed_by_scopes?(tool_definition, scopes)
       return true if scopes.empty?
 
+      if tool_definition.scope
+        return tool_definition.scope.any? { |s| scopes.include?(s) }
+      end
+
       prefix = tool_definition.toolbox_class.controller_name.split("/").last
       tool_access = tool_definition.access_level ||
         (READ_ACTIONS.include?(tool_definition.method_name) ? :read : :write)

data/lib/toolchest/tool_definition.rb

@@ -1,14 +1,15 @@
 module Toolchest
   class ToolDefinition
-    attr_reader :method_name, :description, :params, :toolbox_class, :custom_name, :access_level, :annotations
+    attr_reader :method_name, :description, :params, :toolbox_class, :custom_name, :access_level, :scope, :annotations
 
-    def initialize(method_name:, description:, params:, toolbox_class:, custom_name: nil, access_level: nil, annotations: nil)
+    def initialize(method_name:, description:, params:, toolbox_class:, custom_name: nil, access_level: nil, scope: 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
+      @scope = scope ? Array(scope) : nil
       @annotations = annotations
     end
 

data/lib/toolchest/toolbox.rb

@@ -46,10 +46,10 @@ module Toolchest
           .flat_map { |a| a.send(:own_prompts) }
       end
 
-      def tool(description, name: nil, access: nil, annotations: nil, &block)
+      def tool(description, name: nil, access: nil, scope: 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 }
+        @_pending_tool = { description:, custom_name: name, access_level: access, scope:, annotations:, builder: }
       end
 
       def default_param(name, type, description = "", **options)
@@ -110,6 +110,7 @@ module Toolchest
           toolbox_class: self,
           custom_name: pending[:custom_name],
           access_level: pending[:access_level],
+          scope: pending[:scope],
           annotations: pending[:annotations]
         )
 

data/lib/toolchest/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: toolchest
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.3.3
 platform: ruby
 authors:
 - Nora