mcp_toolkit 0.3.0 → 0.5.0

data/lib/mcp_toolkit/authority/tools/base.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+# Shared base for the four GENERIC, Registry-backed authority tools
+# (McpToolkit::Authority::Tools::{Resources,ResourceSchema,Get,List}) served
+# through McpToolkit::Authority::RegistryToolProvider on the hand-rolled
+# authority dispatch path.
+#
+# Unlike the satellite tools (McpToolkit::Tools::*, which subclass the SDK's
+# MCP::Tool, self-authenticate, and return an MCP::Tool::Response), these are
+# plain objects satisfying the dispatcher's duck-typed tool contract:
+#
+#   tool.required_permissions_scope  -> nil   (see below — no STATIC scope)
+#   tool.call(context:, **arguments) -> Hash  (the dispatcher wraps it into
+#                                              { content: [{ type: "text", ... }] })
+#
+# The scope a caller needs is DYNAMIC — it depends on which `resource` argument
+# was passed — so these tools declare no static scope and instead enforce the
+# resolved resource's `required_scope_for` INSIDE #call (see #ensure_scope!).
+# The `context` (McpToolkit::Authority::Context) supplies the resolved account,
+# the principal, and the derived superuser flag.
+#
+# The tools reuse the existing executors / schema builder UNCHANGED; this base
+# only holds the resolution + gating every one of them repeats: resolve the
+# resource descriptor, gate a superuser-only resource, gate the per-resource
+# scope, and (for get/list) require a selected account.
+class McpToolkit::Authority::Tools::Base
+  class << self
+    attr_reader :_description, :_input_schema
+
+    def tool_name(name = nil)
+      @_tool_name = name.to_s if name
+      @_tool_name
+    end
+
+    def description(text = nil)
+      @_description = text if text
+      @_description
+    end
+
+    def input_schema(schema = nil)
+      @_input_schema = schema if schema
+      @_input_schema || { type: "object", properties: {} }
+    end
+
+    # The static tool definition returned by the provider's `tool_definitions`
+    # (part of `tools/list`). Generic and context-independent. `name_prefix` is
+    # the host's `config.generic_tool_name_prefix`: it prefixes the advertised
+    # name AND is threaded through every sibling-tool reference in the
+    # description / input schema (see McpToolkit::ToolReferenceRewriter).
+    # `config` lets a tool adapt its prose to host configuration (see
+    # .description_text) — served docs must describe the behavior the host
+    # actually configured.
+    def definition(name_prefix: "", config: nil)
+      {
+        name: "#{name_prefix}#{tool_name}",
+        description: McpToolkit::ToolReferenceRewriter.rewrite(description_text(config), name_prefix),
+        inputSchema: McpToolkit::ToolReferenceRewriter.rewrite(input_schema, name_prefix)
+      }
+    end
+
+    # Hook for a tool whose description depends on host configuration
+    # (Tools::List swaps its bare-value grammar per
+    # config.bare_filter_value_semantics). Default: the static description.
+    def description_text(_config)
+      _description
+    end
+  end
+
+  attr_reader :config
+
+  def initialize(config:)
+    @config = config
+  end
+
+  # The dispatcher's central scope gate reads this; nil = no STATIC scope. The
+  # real, per-resource scope is enforced dynamically in #ensure_scope! (the scope
+  # depends on the `resource` argument, unknown until #call).
+  def required_permissions_scope
+    nil
+  end
+
+  private
+
+  def registry
+    config.registry
+  end
+
+  # Resolves the `resource` argument to a registered descriptor, raising the
+  # protocol InvalidParams (=> JSON-RPC -32602) for a blank or unknown name so the
+  # dispatcher renders a clean top-level error.
+  def resolve_descriptor(name)
+    raise McpToolkit::Protocol::InvalidParams, "resource is required" if name.to_s.strip.empty?
+
+    registry.fetch(name)
+  rescue McpToolkit::Registry::UnknownResource => e
+    raise McpToolkit::Protocol::InvalidParams, e.message
+  end
+
+  # Refuses a superuser-only resource for a non-superuser caller (get / list /
+  # resource_schema). `resources` HIDES such resources instead — see that tool.
+  def ensure_resource_accessible!(descriptor, context)
+    return unless descriptor.superusers_only?
+    return if context.superuser?
+
+    raise McpToolkit::Protocol::InvalidRequest,
+          "#{descriptor.name} is restricted to superuser (user-scoped) MCP tokens"
+  end
+
+  # Enforces the resource's effective required scope against the principal. Blank
+  # scope => no check. Mirrors the dispatcher's central gate error shape
+  # (InvalidRequest), keeping scope refusals byte-consistent across host tools.
+  def ensure_scope!(descriptor, context)
+    required = registry.required_scope_for(descriptor)
+    return if required.to_s.empty?
+    return if context.principal&.authorized_for_scope?(required)
+
+    raise McpToolkit::Protocol::InvalidRequest, "This token lacks the #{required.inspect} scope"
+  end
+
+  # get / list read tenant data, so they REQUIRE a resolved account: a superuser
+  # token that selected none would otherwise reach `scope.call(nil)` and leak
+  # across tenants. resource_schema / resources (shape only) do not call this.
+  def ensure_account!(context)
+    return if context.account
+
+    raise McpToolkit::Protocol::InvalidParams,
+          "an account must be selected (pass account_id) to read this resource"
+  end
+
+  # Runs an executor, translating a data-layer McpToolkit::Errors::InvalidParams
+  # (bad id, unknown filter/field key, ...) into the protocol InvalidParams the
+  # dispatcher renders as JSON-RPC -32602 (rather than letting it fall through to
+  # the dispatcher's generic -32603 internal-error mapping).
+  def run_executor
+    yield
+  rescue McpToolkit::Errors::InvalidParams => e
+    raise McpToolkit::Protocol::InvalidParams, e.message
+  end
+
+  # Rejects tool arguments outside the declared input schema (-32602) instead of
+  # silently ignoring them — a typo'd argument name should surface, not no-op.
+  # `list` deliberately does NOT use this: its extra top-level arguments are the
+  # resource-specific custom filters. (`account_id` is consumed by the
+  # transport's account resolution, so every tool tolerates it explicitly.)
+  def reject_unknown_arguments!(extra)
+    return if extra.empty?
+
+    raise McpToolkit::Protocol::InvalidParams, "unknown argument(s): #{extra.keys.join(", ")}"
+  end
+end

data/lib/mcp_toolkit/authority/tools/get.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+# Authority-path tool: fetch a single record by id from a registered resource,
+# scoped to the caller's resolved account. Gates a superuser-only resource, the
+# resource's required scope, and requires a selected account before reading.
+class McpToolkit::Authority::Tools::Get < McpToolkit::Authority::Tools::Base
+  tool_name "get"
+  description <<~DESC.strip
+    Fetch a single record by id from a read-only resource. Pass the resource name as `resource`
+    and the record id as `id`. Use the `resources` tool to discover available resources.
+
+    For tokens that span multiple accounts (superuser), pass `account_id` to pin the active
+    account; account-scoped tokens may omit it. The response mirrors the resource's record
+    shape (attributes + a `links` block).
+
+    Pass `fields` to return a sparse fieldset — the attributes and/or relationships you name
+    (as an array or comma-separated string), omitting everything else. Include "id" if you need
+    it. Valid names come from the resource's `resource_schema`; unknown names are rejected.
+  DESC
+
+  input_schema(
+    {
+      type: "object",
+      properties: {
+        resource: {
+          type: "string",
+          description: "Resource name (use the `resources` tool to discover valid values)"
+        },
+        # The id type is left open so a string/UUID primary key works as well as an
+        # integer one; the record is looked up by the value as given, uncoerced.
+        id: { type: %w[string integer], description: "The record ID (integer or string/UUID)" },
+        account_id: {
+          type: "integer",
+          description: "Account to operate on. Required for superuser tokens; ignored otherwise."
+        },
+        fields: {
+          type: %w[array string],
+          items: { type: "string" },
+          description: "Sparse fieldset — names of attributes and/or relationships to include, as " \
+                       "an array or a comma-separated string. Omit to return every field. Include " \
+                       "\"id\" if you need it. Unknown names are rejected."
+        }
+      },
+      required: %w[resource id]
+    }
+  )
+
+  def call(context:, resource: nil, id: nil, fields: nil, **extra)
+    reject_unknown_arguments!(extra.except(:account_id))
+    descriptor = resolve_descriptor(resource)
+    ensure_resource_accessible!(descriptor, context)
+    ensure_scope!(descriptor, context)
+    ensure_account!(context)
+
+    run_executor do
+      McpToolkit::GetExecutor.call(resource: descriptor, scope_root: context.account, id:, fields:)
+    end
+  end
+end

data/lib/mcp_toolkit/authority/tools/list.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+# Authority-path tool: fetch a paginated list of records from a registered
+# resource, scoped to the caller's resolved account. Gates a superuser-only
+# resource, the resource's required scope, and requires a selected account before
+# reading. Standard filters, per-attribute equality/operator filters, resource
+# custom filters, pagination, and sparse fieldsets are all handled by the reused
+# McpToolkit::ListExecutor.
+class McpToolkit::Authority::Tools::List < McpToolkit::Authority::Tools::Base
+  # The bare-value grammar bullet, per config.bare_filter_value_semantics: the
+  # served description must state the semantics the host ACTUALLY configured —
+  # advertising comma/"null" tokenization to clients of a :literal host would
+  # send them filters that silently match nothing. The :tokenized text is the
+  # exact bullet embedded in the static description below (spec-pinned), so
+  # .description_text can swap it by plain substring substitution; both use
+  # `<<-` (no dedent) to carry the description's rendered 2-space indentation.
+  BARE_VALUE_GRAMMAR = {
+    tokenized: <<-TEXT.rstrip,
+  - A bare value matches by equality. A comma-separated string or an array of scalars
+    matches ANY of the values (IN), e.g. { "status": "booked,canceled" } or
+    { "status": ["booked", "canceled"] }. The string "null" (or a JSON null) matches
+    records where the value is NULL.
+    TEXT
+    literal: <<-TEXT.rstrip
+  - A bare value matches by equality, LITERALLY: a comma-separated string is a single
+    value and the string "null" is the literal string. A JSON null matches records
+    where the value is NULL. An array of scalars matches ANY of its values (IN).
+    TEXT
+  }.freeze
+
+  # Swaps the bare-value bullet for the host's configured semantics; the rest
+  # of the description is mode-independent.
+  def self.description_text(config)
+    return _description unless config && config.bare_filter_value_semantics == :literal
+
+    _description.sub(BARE_VALUE_GRAMMAR[:tokenized], BARE_VALUE_GRAMMAR[:literal])
+  end
+
+  tool_name "list"
+  description <<~DESC.strip
+    Fetch a paginated list of records from a read-only resource. Pass the resource name as
+    `resource`. Use the `resources` tool to discover resources and `resource_schema` to learn a
+    resource's shape.
+
+    Standard filters:
+      - ids: comma-separated list of IDs to fetch
+      - updated_since: ISO 8601 timestamp; only records updated after this time
+      - limit: page size (default 25, max 100)
+      - offset: pagination offset (default 0)
+
+    Per-attribute filters:
+      - filter: an object of { <key>: <value> } filters, applied ON TOP of the account scope
+        (they can only narrow, never widen). Each resource advertises its available filter keys
+        and operators via `resource_schema`. Unknown keys are rejected.
+      - A bare value matches by equality. A comma-separated string or an array of scalars
+        matches ANY of the values (IN), e.g. { "status": "booked,canceled" } or
+        { "status": ["booked", "canceled"] }. The string "null" (or a JSON null) matches
+        records where the value is NULL.
+      - An operator condition is an object { "op": <operator>, "value": <value> }, e.g.
+        { "price": { "op": "gteq", "value": 100 } }. An array of conditions ANDs them into a
+        range: { "price": [{ "op": "gteq", "value": 100 }, { "op": "lt", "value": 200 }] }.
+        Each attribute's supported operators are listed in `resource_schema`.
+      - Some filter keys require a companion key (e.g. a polymorphic id and its type) —
+        `resource_schema` advertises these under a relationship's `filter.requires`; pass
+        both keys together.
+
+    Resource-specific filters:
+      - Some resources accept additional filters advertised in `resource_schema` under
+        `resource_filters`. Pass each as a TOP-LEVEL argument (NOT inside `filter`), e.g.
+        { "resource": "...", "<name>": <value> }.
+
+    Sparse fieldset:
+      - fields: names of the attributes and/or relationships to include in each record, as an
+        array or a comma-separated string. Omit to return every field. Include "id" if you need
+        it. Valid names come from a resource's `resource_schema`; unknown names are rejected.
+
+    For tokens that span multiple accounts (superuser), pass `account_id` to pin the active
+    account; account-scoped tokens may omit it. The response shape is
+    { "<resource>": [...], "meta": { total_count, limit, offset } }.
+  DESC
+
+  input_schema(
+    {
+      type: "object",
+      properties: {
+        resource: {
+          type: "string",
+          description: "Resource name (use the `resources` tool to discover valid values)"
+        },
+        account_id: {
+          type: "integer",
+          description: "Account to operate on. Required for superuser tokens; ignored otherwise."
+        },
+        ids: { type: "string", description: "Comma-separated list of IDs to fetch" },
+        updated_since: {
+          type: "string",
+          description: "ISO 8601 timestamp; only records updated after this time"
+        },
+        filter: {
+          type: "object",
+          description: "Per-attribute filters, e.g. { \"booking_id\": 42 }. See a resource's " \
+                       "`resource_schema` `filters` for the keys and operators it accepts.",
+          additionalProperties: true
+        },
+        limit: { type: "integer", description: "Page size (default 25, max 100)" },
+        offset: { type: "integer", description: "Pagination offset (default 0)" },
+        fields: {
+          type: %w[array string],
+          items: { type: "string" },
+          description: "Sparse fieldset — names of attributes and/or relationships to include in " \
+                       "each record, as an array or a comma-separated string. Omit to return every " \
+                       "field. Include \"id\" if you need it. Unknown names are rejected."
+        }
+      },
+      required: ["resource"],
+      # Resource-specific filters (resource_schema's `resource_filters`) arrive as
+      # top-level arguments, so the schema must not advertise a closed shape.
+      additionalProperties: true
+    }
+  )
+
+  def call(context:, resource: nil, **params)
+    descriptor = resolve_descriptor(resource)
+    ensure_resource_accessible!(descriptor, context)
+    ensure_scope!(descriptor, context)
+    ensure_account!(context)
+
+    run_executor do
+      McpToolkit::ListExecutor.call(resource: descriptor, scope_root: context.account, params:)
+    end
+  end
+end

data/lib/mcp_toolkit/authority/tools/resource_schema.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+# Authority-path discovery tool: the detailed schema (attributes with types +
+# filter operators, relationships, filters, note) of one registered resource.
+#
+# Reveals shape, not tenant data, so it does NOT require a selected account — but
+# it still gates a superuser-only resource (refuse) and the resource's required
+# scope, so a caller can't discover the shape of something it can't read.
+class McpToolkit::Authority::Tools::ResourceSchema < McpToolkit::Authority::Tools::Base
+  tool_name "resource_schema"
+  description <<~DESC.strip
+    Describe a single read-only resource in detail. Pass the resource name as `resource` (use
+    the `resources` tool to discover names). Returns:
+      - attributes: every field in the response, each with its `type`, a value `format` hint,
+        whether it is `filterable`, and the filter `operators` it accepts
+      - relationships: associated resources emitted in the record's `links`; each names the
+        `target_resource` it resolves to (callable via `list`/`get`)
+      - standard_filters: ids, updated_since, limit, offset (accepted by the `list` tool)
+      - filters: the per-attribute equality/operator filter keys the `list` tool accepts in
+        its `filter` argument
+      - resource_filters: resource-specific filters, if any — each is passed as a TOP-LEVEL
+        argument of the `list` tool (NOT inside `filter`), e.g. { "resource": "...",
+        "<name>": <value> }
+      - filter_examples: ready-to-use `filter` payloads for this resource
+    A relationship's `filter` block lists the keys that filter by it; when it names a
+    `requires` key (e.g. a polymorphic id needing its type), pass BOTH keys together.
+    The `attributes` and `relationships` names are also the valid values for the `fields` sparse
+    fieldset argument on `get` / `list`. Call this before `list` to learn a resource's shape.
+  DESC
+
+  input_schema(
+    {
+      type: "object",
+      properties: {
+        resource: {
+          type: "string",
+          description: "Resource name (use the `resources` tool to discover valid values)"
+        }
+      },
+      required: ["resource"]
+    }
+  )
+
+  def call(context:, resource: nil, **extra)
+    reject_unknown_arguments!(extra.except(:account_id))
+    descriptor = resolve_descriptor(resource)
+    ensure_resource_accessible!(descriptor, context)
+    ensure_scope!(descriptor, context)
+
+    McpToolkit::ResourceSchema.call(descriptor, registry:)
+  end
+end

data/lib/mcp_toolkit/authority/tools/resources.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+# Authority-path discovery tool: lists every read-only resource registered in the
+# config's Registry, HIDING superuser-only resources from a non-superuser caller
+# (so they are neither advertised nor discoverable without a superuser token).
+#
+# The top-level list is context-independent except for that visibility filter, so
+# the tool takes no arguments and does no per-resource scope check (per-resource
+# scopes are enforced by `get` / `list` / `resource_schema`).
+class McpToolkit::Authority::Tools::Resources < McpToolkit::Authority::Tools::Base
+  tool_name "resources"
+  description <<~DESC.strip
+    List all read-only resources available via the `list` and `get` tools. Returns each
+    resource's name, a short description, whether it accepts filters (`filterable`) and — when
+    present — a usage `note` (read it before interpreting the resource's data). Call this once
+    at the start of a session to learn what exists, then use `resource_schema` for a specific
+    resource's attributes, relationships and filters.
+  DESC
+
+  # Unlike get / resource_schema (strict kwargs pre-gem), the pre-gem resources
+  # tool tolerated ANY extra argument — so this one stays tolerant.
+  def call(context:, **_args)
+    {
+      resources: visible_resources(context).map do |resource|
+        {
+          name: resource.name,
+          description: resource.description,
+          filterable: filterable?(resource),
+          note: resource.note
+        }.compact
+      end
+    }
+  end
+
+  private
+
+  # Superuser-only resources are hidden from a non-superuser caller.
+  def visible_resources(context)
+    registry.resources.reject { |resource| resource.superusers_only? && !context.superuser? }
+  end
+
+  # Whether the resource can be filtered at all — via the generic allowlist OR a
+  # resource-specific custom filter. Reading `filterable_columns` resolves a
+  # lazily-declared allowlist, which may run host code (e.g. a DB-backed column
+  # list). One resource's failing resolution must not take down the whole
+  # discovery index — this is the tool every session calls first — so a raise
+  # degrades to nil (the `filterable` key is omitted for that resource) and the
+  # unresolved source is retried on the next read (see Resource#filterable).
+  def filterable?(resource)
+    resource.filterable_columns.any? || resource.custom_filters.any?
+  rescue StandardError => e
+    config.logger&.warn("mcp_toolkit: filterable resolution failed for #{resource.name}: #{e.message}")
+    nil
+  end
+end

data/lib/mcp_toolkit/authority.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Namespace for the AUTHORITY-side building blocks: the per-request Context, the
+# transport concern (Authority::ControllerMethods), and the lazily-parented base
+# controller (Authority::ServerController).
+#
+# `ServerController` is NOT a file under this directory: like the engine's
+# controllers, it subclasses a host controller (`config.parent_controller`) that
+# is absent from the gem's own unit suite, so it cannot be a Zeitwerk-managed
+# file (eager-loading it would raise). It is built on demand by
+# `McpToolkit.build_engine_controllers!`, so this `const_missing` triggers that
+# build the first time `McpToolkit::Authority::ServerController` is referenced
+# (which, in a host, is after the app's initializers/to_prepare have run — so the
+# configured parent is read at build time, not at autoload time).
+module McpToolkit::Authority
+  def self.const_missing(name)
+    if name == :ServerController
+      McpToolkit.build_engine_controllers!
+      return const_get(name) if const_defined?(name, false)
+    end
+
+    super
+  end
+end