toolchest 0.3.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9c78a7f55b37d501c0e2d5c4e164048ea4d176f2eb7126c232953a1c4c52e1da
+  data.tar.gz: 403d4c3b8ee52953630e52f0d4d31f1a31e9d406511fdfdd7c4f47a67f083bf6
+SHA512:
+  metadata.gz: c4c8ca2520fc43e69398fffa2f25a08db7ec0566c7f9453f5fb5d442744e4c42be5ac53ffcb037ad5181a4bac8395970f0ea9b1c925fd6cfe6ab044f1e097b72
+  data.tar.gz: b0fd64277dd46191d91681b7c3cbaf14b70b03ac80324fe9d1a01e6b2455486e2d6c6c3c2dbd214430be2867d7f5967538f6ad4a2d76ed855664c44d14c0da65

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nora
+
+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/LLMS.txt

@@ -0,0 +1,484 @@
+# Toolchest
+
+MCP (Model Context Protocol) for Rails. Toolboxes are controllers, tools are actions.
+
+## Adding a toolbox (the thing you'll do most)
+
+```bash
+rails g toolchest:toolbox Orders show create update
+```
+
+This creates three files:
+
+- `app/toolboxes/orders_toolbox.rb` — the toolbox (like a controller)
+- `app/views/toolboxes/orders/{show,create,update}.json.jb` — views for each tool
+- `spec/toolboxes/orders_toolbox_spec.rb` — test file
+
+Fill in the toolbox:
+
+```ruby
+class OrdersToolbox < ApplicationToolbox
+  before_action :set_order, only: [:show, :update]
+
+  tool "Look up an order" do
+    param :order_id, :string, "The order ID"
+  end
+  def show
+    # renders app/views/toolboxes/orders/show.json.jb automatically
+  end
+
+  tool "Update order status" do
+    param :order_id, :string, "The order ID"
+    param :status, :string, "New status", enum: %w[pending confirmed shipped]
+  end
+  def update
+    @order.update(params.permit(:status).to_h)
+    render :show
+  end
+
+  tool "Create a new order" do
+    param :customer_id, :string, "Customer"
+  end
+  def create
+    @order = Order.create!(params.permit(:customer_id).to_h)
+    render :show
+  end
+
+  private
+
+  def set_order
+    @order = Order.find(params[:order_id])
+  end
+end
+```
+
+Fill in the view:
+
+```ruby
+# app/views/toolboxes/orders/show.json.jb
+{
+  id: @order.id,
+  status: @order.status,
+  customer: @order.customer.name
+}
+```
+
+Test it:
+
+```ruby
+require "toolchest/rspec"
+
+RSpec.describe OrdersToolbox, type: :toolbox do
+  it "shows an order" do
+    order = create(:order)
+    call_tool "orders_show", params: { order_id: order.id.to_s }, as: user
+    expect(tool_response).to be_success
+    expect(tool_response.text).to include(order.customer.name)
+  end
+end
+```
+
+That's it. The tool is live at your MCP endpoint.
+
+## Common patterns
+
+### Toolbox wrapping an AR model
+
+Use `default_param` to avoid repeating the ID param on every tool, and `before_action` to load the record:
+
+```ruby
+class OrdersToolbox < ApplicationToolbox
+  default_param :order_id, :string, "The order ID", except: [:create, :search]
+  before_action :set_order, except: [:create, :search]
+
+  rescue_from ActiveRecord::RecordNotFound do |e|
+    render_error "Couldn't find that #{e.model.downcase}"
+  end
+
+  tool "Look up an order" do
+  end
+  def show; end  # implicit render
+
+  tool "Update status" do
+    param :status, :string, "New status", enum: %w[pending confirmed shipped]
+  end
+  def update
+    if @order.update(params.permit(:status).to_h)
+      render :show
+    else
+      render_errors @order
+    end
+  end
+
+  private
+  def set_order = @order = Order.find(params[:order_id])
+end
+```
+
+### Sampling (ask the client's LLM)
+
+```ruby
+tool "Summarize an order" do
+  param :order_id, :string, "Order ID"
+end
+def summarize
+  @order = Order.find(params[:order_id])
+  summary = mcp_sample("Summarize this order", context: @order.to_json)
+  render text: summary
+end
+```
+
+Block form: `mcp_sample { |s| s.system "..."; s.user "..."; s.max_tokens 500; s.temperature 0.3 }`
+
+Raises `Toolchest::Error` if the client doesn't support sampling.
+
+### Progress reporting
+
+```ruby
+items.each_with_index do |item, i|
+  process(item)
+  mcp_progress i + 1, total: items.size, message: "Processing #{item.name}"
+end
+```
+
+No-op if no progress token from client.
+
+### Auth checks in before_action
+
+```ruby
+class AdminToolbox < ApplicationToolbox
+  before_action :require_admin!
+
+  private
+  def require_admin!
+    halt error: "forbidden" unless current_user&.admin?
+  end
+end
+```
+
+### Nested object params
+
+```ruby
+tool "Create order with items" do
+  param :customer_id, :string, "Customer"
+  param :items, [:object], "Line items" do
+    param :product_id, :string, "Product SKU"
+    param :quantity, :integer, "How many", default: 1
+  end
+end
+```
+
+### Suggesting the next tool
+
+```ruby
+def create
+  @order = Order.create!(...)
+  render :show
+  suggests :show, "Get the full order details"
+end
+```
+
+## Setup
+
+```bash
+bundle add toolchest jb
+rails g toolchest:install --auth=none   # or --auth=token, --auth=oauth
+```
+
+```ruby
+# config/routes.rb — for :none or :token
+mount Toolchest::Engine => "/mcp"
+
+# for :oauth — use Toolchest.app and add discovery routes
+mount Toolchest.app => "/mcp"
+toolchest_oauth
+```
+
+## Tool DSL reference
+
+```ruby
+tool "Description for the LLM" do
+  param :name, :type, "description"
+  param :name, :type, "description", optional: true
+  param :name, :type, "description", enum: %w[a b c]
+  param :name, :type, "description", default: "value"
+  param :items, [:object], "array of objects" do
+    param :nested_field, :string, "nested"
+  end
+end
+def method_name
+  # implementation
+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).
+
+`access: :read` → `readOnlyHint: true, destructiveHint: false`. `access: :write` → `readOnlyHint: false, destructiveHint: true`.
+
+## Instance methods in toolbox actions
+
+```ruby
+auth                              # Toolchest::AuthContext (nil for :none auth)
+auth.resource_owner               # whatever your authenticate block returns
+auth.scopes                       # token scopes (always preserved)
+auth.token                        # the raw token record
+params                            # Toolchest::Parameters (declared keys only)
+render :action                    # renders app/views/toolboxes/{toolbox}/{action}.json.jb
+render "path/to/template"         # explicit template path
+render json: { ... }              # inline JSON
+render text: "string"             # plain text
+# no render call = implicit render using current action name
+render_error "message"            # MCP error (isError: true)
+render_errors @record             # MCP error from ActiveModel .errors
+suggests :action, "hint"          # suggest next tool call to the LLM
+suggests "full_tool_name", "hint" # suggest by full tool name
+mcp_log :info, "message"          # MCP log notification
+mcp_sample "prompt"               # ask client's LLM, returns text
+mcp_sample { |s| s.user "..." }  # block form with system, max_tokens, temperature
+mcp_progress 3, total: 10        # report progress (optional message:)
+halt error: "forbidden"           # stop execution, render error
+halt                              # stop execution (must have rendered already)
+```
+
+## Auth
+
+Three built-in strategies. Default is `:none`.
+
+### :none
+
+No auth. `auth` is nil. All tools visible.
+
+### :token
+
+```ruby
+Toolchest.configure do |config|
+  config.auth = :token
+  config.authenticate do |token|
+    # token is EnvTokenRecord (owner_id, scopes) or Toolchest::Token AR record
+    # return value becomes auth.resource_owner in toolboxes
+    User.find(token.owner_id)
+  end
+end
+```
+
+Dev setup (env vars, no DB):
+
+```bash
+TOOLCHEST_TOKEN=tcht_dev_secret
+TOOLCHEST_TOKEN_OWNER=user:1
+TOOLCHEST_TOKEN_SCOPES="orders:read orders:write"
+```
+
+Production (DB tokens):
+
+```bash
+rails g toolchest:auth token && rails db:migrate
+rails toolchest:token:generate OWNER=user:1 NAME="claude desktop"
+```
+
+### :oauth
+
+Full OAuth 2.1 with PKCE and DCR. Isolated from host app auth.
+
+```ruby
+Toolchest.configure do |config|
+  config.auth = :oauth
+  config.login_path = "/login"
+
+  config.current_user_for_oauth do |request|
+    request.env["warden"]&.user  # for consent screen
+  end
+
+  config.authenticate do |token|
+    # token is Toolchest::OauthAccessToken (resource_owner_id, scopes, mount_key)
+    # scopes are always preserved — returning a User here is fine
+    User.find(token.resource_owner_id)
+  end
+end
+```
+
+### Custom auth
+
+```ruby
+config.auth = MyAuth.new
+
+class MyAuth < Toolchest::Auth::Base
+  def authenticate(request)
+    key = request.env["HTTP_X_API_KEY"]
+    user = ApiKey.active.find_by(key: key)&.owner
+    return nil unless user
+    Toolchest::AuthContext.new(resource_owner: user, scopes: [], token: nil)
+  end
+end
+```
+
+### AuthContext
+
+`auth` always returns a `Toolchest::AuthContext` (or nil for `:none`):
+
+```ruby
+auth.resource_owner  # whatever your authenticate block returns (User, etc.)
+auth.scopes          # array of scope strings from the token — never lost
+auth.token           # the raw token record
+```
+
+The generator creates `def current_user = auth&.resource_owner` in ApplicationToolbox.
+
+Scopes are always extracted from the token *before* the authenticate block runs. You cannot accidentally lose scopes by returning a User from authenticate.
+
+## Scopes
+
+```ruby
+config.scopes = {
+  "orders:read"  => "View order details",
+  "orders:write" => "Create and modify orders"
+}
+```
+
+Pattern: `{toolbox}:{access}`. Actions named `show`, `index`, `list`, `search` default to `:read`, everything else to `:write`. Override per-tool: `tool "desc", access: :read`.
+
+`write` scope grants both read and write. Bare scope (e.g. `orders`) grants full access.
+
+Scopes filter `tools/list` — clients only see tools their token allows. Fails closed: if scopes can't be determined, no tools are shown.
+
+Disable: `config.filter_tools_by_scope = false`
+
+### Optional scopes (checkboxes on consent)
+
+```ruby
+config.optional_scopes = true                    # users can uncheck scopes (default: false)
+config.required_scopes = ["orders:read"]         # always granted, can't uncheck (default: [])
+config.allowed_scopes_for do |user, requested|   # per-user gating (default: show all)
+  user.admin? ? requested : requested - ["admin:write"]
+end
+```
+
+## Resources and prompts
+
+```ruby
+class OrdersToolbox < ApplicationToolbox
+  resource "orders://schema", name: "Order schema", description: "Fields" do
+    { fields: Order.column_names }
+  end
+
+  resource "orders://{order_id}", name: "Order", description: "Order by ID" do |order_id:|
+    Order.find(order_id).as_json
+  end
+
+  prompt "debug-order", description: "Debug an order",
+    arguments: { order_id: { type: :string, required: true } } do |order_id:|
+    order = Order.find(order_id)
+    [{ role: "user", content: "Debug this order:\n#{order.to_json}" }]
+  end
+end
+```
+
+## Multi-mount
+
+```ruby
+Toolchest.configure { |c| c.auth = :oauth; c.toolbox_module = "Public" }
+Toolchest.configure(:admin) { |c| c.auth = :token; c.toolbox_module = "Admin" }
+
+# routes.rb
+mount Toolchest.app => "/mcp"
+mount Toolchest.app(:admin) => "/admin-mcp"
+toolchest_oauth default_mount: :default
+```
+
+## Tool naming
+
+```ruby
+config.tool_naming = :underscored  # orders_show (default)
+config.tool_naming = :dotted       # orders.show
+config.tool_naming = :slashed      # orders/show
+config.tool_naming = ->(prefix, method) { "#{prefix}__#{method}" }
+```
+
+Per-tool: `tool "desc", name: "custom_name"`
+
+Namespaced toolboxes (`Admin::OrdersToolbox`) produce `admin_orders_{action}`.
+
+## Testing
+
+```ruby
+require "toolchest/rspec"
+
+RSpec.describe OrdersToolbox, type: :toolbox do
+  it "shows an order" do
+    call_tool "orders_show", params: { order_id: "123" }, as: user
+    expect(tool_response).to be_success
+    expect(tool_response.text).to include("shipped")
+  end
+
+  it "handles errors" do
+    call_tool "orders_show", params: { order_id: "missing" }
+    expect(tool_response).to be_error
+    expect(tool_response).to include_text("not found")
+  end
+
+  it "suggests next tool" do
+    call_tool "orders_create", params: { customer_id: "c1" }, as: user
+    expect(tool_response).to suggest("orders_show")
+  end
+end
+```
+
+Matchers: `be_success`, `be_error`, `include_text("str")`, `suggest("tool_name")`
+
+## Generators
+
+```bash
+rails g toolchest:install                # initializer, ApplicationToolbox, routes
+rails g toolchest:install --auth=oauth   # same + OAuth migration
+rails g toolchest:toolbox Orders show    # toolbox + views + spec
+rails g toolchest:auth token             # token migration
+rails g toolchest:auth oauth             # OAuth migration
+rails g toolchest:consent                # eject consent view
+rails g toolchest:oauth_views            # eject all OAuth views + controllers
+rails g toolchest:skills                 # install Claude Code slash commands
+```
+
+## Rake tasks
+
+```bash
+rails toolchest:tools                            # list all registered tools
+rails toolchest:token:generate OWNER=user:1      # create a token
+rails toolchest:token:list                        # list tokens
+rails toolchest:token:revoke TOKEN=tcht_...       # revoke a token
+```
+
+## Error classes
+
+- `Toolchest::ParameterMissing` — raised by `params.require(:key)`
+- `Toolchest::MissingTemplate` — raised when implicit render can't find a view
+- `Toolchest::Error` — base error class
+
+Handle with `rescue_from` in your toolbox.
+
+## File locations
+
+```
+app/toolboxes/application_toolbox.rb          base class
+app/toolboxes/orders_toolbox.rb               toolbox
+app/toolboxes/admin/orders_toolbox.rb         namespaced toolbox
+app/views/toolboxes/orders/show.json.jb       view
+app/views/toolboxes/admin/orders/show.json.jb namespaced view
+spec/toolboxes/orders_toolbox_spec.rb         spec
+config/initializers/toolchest.rb              config
+```
+
+## Server config
+
+```ruby
+Toolchest.configure do |config|
+  config.server_name = "My App"
+  config.server_description = "Order management tools"
+  config.server_instructions = "Always look up the customer before modifying orders."
+end
+```
+
+## Completion
+
+Params with `enum:` automatically power `completion/complete`. No extra code needed.