mcp_toolkit 0.3.0

data/lib/mcp_toolkit/tools/base.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+# Base class for the generic MCP tools. Subclasses an official-SDK `MCP::Tool`,
+# so `name`/`description`/`input_schema` and the `call` contract are the gem's.
+# This base adds the shared concern every tool needs: authenticating +
+# scope-resolving the caller (via McpToolkit::Auth::Authenticator) before
+# running, and turning tool-level errors into `isError: true` MCP results
+# (rather than letting them become JSON-RPC protocol errors).
+#
+# The bearer token, JSON-RPC `_meta`, and the account-id header are threaded in
+# through `server_context` (set per-request by the controller). The active
+# McpToolkit config is also threaded in as `server_context[:mcp_config]` so a
+# process can, in principle, host more than one configured server; it falls back
+# to `McpToolkit.config`.
+class McpToolkit::Tools::Base < MCP::Tool
+  # Runs `block` with an authenticated, scoped context, serializing any
+  # McpToolkit::Errors into a clean text tool error.
+  #
+  # The resolved `scope_root` is yielded — it is the tools' serializer `scope`
+  # AND the root every query is scoped through.
+  #
+  # `account_id` is the superuser account selector arriving as a tool
+  # argument (the gem passes tool args as kwargs, not via server_context),
+  # threaded here so it joins `_meta` / the header in the resolution order.
+  #
+  # `required_scope` is the explicitly-declared scope a token must carry (the
+  # caller resolves it from the resource — see Registry#required_scope_for).
+  # Empty/nil => no scope check (authorized_for_scope? treats "" as a pass).
+  def self.with_account(server_context, account_id: nil, required_scope: nil)
+    config = config_from(server_context)
+    context = McpToolkit::Auth::Authenticator.call(
+      token: server_context[:bearer_token],
+      meta: meta_from(server_context),
+      arguments: { "account_id" => account_id }.compact,
+      header_account_id: server_context[:header_account_id],
+      config:
+    )
+
+    unless context.introspection.authorized_for_scope?(required_scope)
+      return error_response("Unauthorized: token lacks the #{required_scope.inspect} scope")
+    end
+
+    text_response(yield(context.scope_root))
+  rescue McpToolkit::Errors::Unauthorized => e
+    error_response("Unauthorized: #{e.message}")
+  rescue McpToolkit::Errors::InvalidParams => e
+    error_response("Invalid request: #{e.message}")
+  end
+
+  # Authenticates the token (valid + the explicitly-declared `required_scope`)
+  # WITHOUT requiring an account selection. Used by the schema-discovery tools,
+  # which reveal shape, not tenant data, so a superuser shouldn't have to pin an
+  # account just to discover what exists. Empty/nil `required_scope` => no scope
+  # check.
+  def self.with_authentication(server_context, required_scope: nil)
+    config = config_from(server_context)
+    introspection = McpToolkit::Auth::Introspection.call(server_context[:bearer_token], config:)
+    return error_response("Unauthorized: invalid or expired token") unless introspection.valid?
+
+    unless introspection.authorized_for_scope?(required_scope)
+      return error_response("Unauthorized: token lacks the #{required_scope.inspect} scope")
+    end
+
+    text_response(yield)
+  rescue McpToolkit::Errors::InvalidParams => e
+    error_response("Invalid request: #{e.message}")
+  end
+
+  def self.text_response(payload)
+    text = payload.is_a?(String) ? payload : JSON.generate(payload)
+    MCP::Tool::Response.new([{ type: "text", text: }])
+  end
+
+  def self.error_response(message)
+    MCP::Tool::Response.new([{ type: "text", text: message }], error: true)
+  end
+
+  # The gem nests the request `_meta` under server_context[:_meta].
+  def self.meta_from(server_context)
+    server_context[:_meta] || {}
+  end
+
+  def self.config_from(server_context)
+    server_context[:mcp_config] || McpToolkit.config
+  end
+
+  def self.lookup_resource(name, config)
+    config.registry.fetch(name)
+  rescue McpToolkit::Registry::UnknownResource => e
+    raise McpToolkit::Errors::InvalidParams, e.message
+  end
+
+  # Validates the `resource` argument is present and resolves its descriptor,
+  # raising InvalidParams (=> clean tool error) for a blank or unknown resource.
+  def self.resolve_descriptor(name, config)
+    raise McpToolkit::Errors::InvalidParams, "resource is required" if name.to_s.strip.empty?
+
+    lookup_resource(name, config)
+  end
+end

data/lib/mcp_toolkit/tools/get.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+# Fetches a single record by id from a registered resource, scoped to the
+# resolved scope root.
+class McpToolkit::Tools::Get < McpToolkit::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(
+    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; see the resource's " \
+                     "`resource_schema` for valid attribute and relationship names."
+      }
+    },
+    required: %w[resource id]
+  )
+
+  def self.call(server_context:, resource: nil, id: nil, account_id: nil, fields: nil, **_args)
+    config = config_from(server_context)
+    # Resolve the resource FIRST so its effective required scope is known before
+    # the scope check (and so an unknown resource is a clean tool error).
+    descriptor = resolve_descriptor(resource, config)
+    required_scope = config.registry.required_scope_for(descriptor)
+    with_account(server_context, account_id:, required_scope:) do |scope_root|
+      McpToolkit::GetExecutor.call(resource: descriptor, scope_root:, id:, fields:)
+    end
+  rescue McpToolkit::Errors::InvalidParams => e
+    error_response("Invalid request: #{e.message}")
+  end
+end

data/lib/mcp_toolkit/tools/list.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+# Fetches a paginated list of records from a registered resource, scoped to the
+# resolved scope root.
+class McpToolkit::Tools::List < McpToolkit::Tools::Base
+  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 equality filters:
+      - filter: an object of { <key>: <value> } exact-match filters, applied ON TOP of the
+        account scope (they can only narrow, never widen). Each resource advertises its
+        available filter keys via `resource_schema` (the `filters` array). Unknown keys are
+        rejected.
+
+    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. Narrowing the set shrinks
+        the response (and skips loading unselected relationships) — prefer it when you only need a
+        few fields. Include "id" if you need it. Valid names come from a resource's
+        `resource_schema` (its `attributes` and `relationships`); 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(
+    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 exact-match equality filters, e.g. { \"booking_id\": 42 }. " \
+                     "See a resource's `resource_schema` `filters` for the keys 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; see a " \
+                     "resource's `resource_schema` for valid attribute and relationship names."
+      }
+    },
+    required: ["resource"]
+  )
+
+  def self.call(server_context:, resource: nil, account_id: nil, **params)
+    config = config_from(server_context)
+    # Resolve the resource FIRST so its effective required scope is known before
+    # the scope check (and so an unknown resource is a clean tool error).
+    descriptor = resolve_descriptor(resource, config)
+    required_scope = config.registry.required_scope_for(descriptor)
+    with_account(server_context, account_id:, required_scope:) do |scope_root|
+      McpToolkit::ListExecutor.call(resource: descriptor, scope_root:, params:)
+    end
+  rescue McpToolkit::Errors::InvalidParams => e
+    error_response("Invalid request: #{e.message}")
+  end
+end

data/lib/mcp_toolkit/tools/resource_schema.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# Discovery tool: the detailed schema (attributes + relationships) of one
+# resource.
+class McpToolkit::Tools::ResourceSchema < McpToolkit::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` and a value `format` hint
+      - 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 filter keys the `list` tool accepts
+    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(
+    properties: {
+      resource: {
+        type: "string",
+        description: "Resource name (use the `resources` tool to discover valid values)"
+      }
+    },
+    required: ["resource"]
+  )
+
+  def self.call(server_context:, resource: nil, **_args)
+    config = config_from(server_context)
+    # Resolve the resource FIRST so its effective required scope gates discovery
+    # of THIS resource's shape (and an unknown resource is a clean tool error).
+    descriptor = resolve_descriptor(resource, config)
+    with_authentication(server_context, required_scope: config.registry.required_scope_for(descriptor)) do
+      McpToolkit::ResourceSchema.call(descriptor, registry: config.registry)
+    end
+  rescue McpToolkit::Errors::InvalidParams => e
+    error_response("Invalid request: #{e.message}")
+  end
+end

data/lib/mcp_toolkit/tools/resources.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Discovery tool: lists every read-only resource exposed by this server.
+class McpToolkit::Tools::Resources < McpToolkit::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 and a short description. Call this once at the start of a session to learn
+    what exists, then use `resource_schema` for a specific resource's attributes and
+    relationships.
+  DESC
+
+  input_schema(properties: {})
+
+  def self.call(server_context:, **_args)
+    config = config_from(server_context)
+    # Discovery requires the registry-level default scope (the satellite's
+    # app-wide scope); per-resource scopes are enforced by `get` / `list`.
+    with_authentication(server_context, required_scope: config.registry.default_required_permissions_scope) do
+      {
+        resources: config.registry.resources.map do |resource|
+          { name: resource.name, description: resource.description }
+        end
+      }
+    end
+  end
+end

data/lib/mcp_toolkit/transport/controller_methods.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require "logger"
+
+# The MCP Streamable-HTTP transport, provided as an includable concern. An
+# app's controller includes this to get the full transport with no per-app code:
+#
+#   class Mcp::ServerController < ApplicationController
+#     include McpToolkit::Transport::ControllerMethods
+#   end
+#
+# and routes the four endpoints at its actions:
+#
+#   post   "mcp",        to: "mcp/server#create"
+#   get    "mcp",        to: "mcp/server#stream"
+#   delete "mcp",        to: "mcp/server#destroy"
+#   get    "mcp/health", to: "mcp/server#health"
+#
+# Endpoints
+#   POST   /mcp          - JSON-RPC requests/responses
+#   GET    /mcp          - server-initiated SSE stream (none emitted; 405)
+#   DELETE /mcp          - terminate the current session
+#   GET    /mcp/health   - unauthenticated health probe
+#
+# Authentication
+#   The bearer token is NOT verified at the transport boundary; it is forwarded
+#   into each tool, which authenticates it against the central app's
+#   introspection endpoint (McpToolkit::Auth::Authenticator). The transport only
+#   requires that *a* token be present (so unauthenticated calls are refused
+#   before any work). Tools resolve the active account from `_meta` /
+#   `account_id` argument / the account-id header.
+#
+# Session lifecycle
+#   - First `initialize` POST: create a session, return its id in the
+#     `Mcp-Session-Id` response header. The client echoes it on later requests.
+#   - Subsequent POSTs: validate the session id; missing/expired => 404.
+#   - DELETE /mcp ends the session.
+#
+# Notifications (requests without an `id`) get a 202 with no body.
+#
+# Overridable hooks
+#   - `mcp_config`      -> the McpToolkit::Configuration to use (default: McpToolkit.config)
+#   - `mcp_extra_tools` -> Array of additional MCP::Tool subclasses (default: [])
+#
+# CSRF: the concern disables forgery protection (this is a token-authenticated
+# JSON API). Inherit from ActionController::Base (not ::API) if your app's
+# controller stack needs helper_method, as bsa-notifications does.
+module McpToolkit::Transport::ControllerMethods
+  extend ActiveSupport::Concern
+
+  SESSION_HEADER = "Mcp-Session-Id"
+
+  included do
+    protect_from_forgery with: :null_session if respond_to?(:protect_from_forgery)
+
+    before_action :mcp_require_token!, except: [:health]
+    before_action :mcp_resolve_session!, only: [:create]
+  end
+
+  def create
+    request_body = mcp_parsed_body
+    server = McpToolkit::Server.build(
+      server_context: mcp_server_context,
+      config: mcp_config,
+      extra_tools: mcp_extra_tools
+    )
+    response_json = server.handle_json(JSON.generate(request_body))
+
+    # handle_json returns nil for notifications (no id) -> 202 Accepted, no body.
+    return head :accepted if response_json.nil?
+
+    mcp_render_response(response_json)
+  end
+
+  # GET /mcp - no server-initiated SSE stream is emitted; 405 per MCP spec.
+  def stream
+    head :method_not_allowed
+  end
+
+  # DELETE /mcp - terminate the current session.
+  def destroy
+    McpToolkit::Session.delete(request.headers[SESSION_HEADER], config: mcp_config)
+    head :no_content
+  end
+
+  # GET /mcp/health - unauthenticated probe.
+  def health
+    render json: {
+      status: "ok",
+      server: mcp_config.server_name,
+      version: mcp_config.server_version
+    }
+  end
+
+  private
+
+  # ---- overridable hooks ----------------------------------------------
+
+  def mcp_config
+    McpToolkit.config
+  end
+
+  def mcp_extra_tools
+    []
+  end
+
+  # Logger for transport-level diagnostics. Defaults to Rails.logger when running
+  # inside Rails, and to a $stdout logger otherwise (e.g. the gem's own unit suite)
+  # so a diagnostic is never silently dropped. Overridable so a host can inject its
+  # own; never returns nil.
+  def mcp_logger
+    return Rails.logger if defined?(Rails)
+
+    @mcp_logger ||= Logger.new($stdout)
+  end
+
+  # ---- per-request context --------------------------------------------
+
+  # Per-request context threaded to the tools. The gem merges the request's
+  # `_meta` into this hash (as `:_meta`) at tool-call time.
+  def mcp_server_context
+    {
+      bearer_token: mcp_extract_token,
+      header_account_id: request.headers[mcp_config.account_id_header].presence,
+      mcp_config: mcp_config
+    }
+  end
+
+  # Renders the JSON-RPC payload as application/json by default, or as a single
+  # SSE `message` frame when the client's Accept header asks for it. We never
+  # actually stream (one message + EOF) so a strict client interoperates either
+  # way.
+  def mcp_render_response(response_json)
+    if mcp_event_stream_requested?
+      response.headers["Cache-Control"] = "no-cache"
+      body = "event: message\ndata: #{response_json}\n\n"
+      render body:, content_type: Mime::Type.lookup("text/event-stream").to_s
+    else
+      render json: response_json
+    end
+  end
+
+  def mcp_event_stream_requested?
+    request.headers["Accept"].to_s.include?("text/event-stream")
+  end
+
+  # ---- auth (presence only; real auth is per-tool) --------------------
+
+  # A token must be present; its validity is enforced per-tool. Extraction
+  # order: Bearer header, then X-MCP-Token, then ?token=.
+  def mcp_require_token!
+    return if mcp_extract_token.present?
+
+    mcp_render_unauthorized("Missing authorization token")
+  end
+
+  def mcp_extract_token
+    auth_header = request.headers["Authorization"]
+    return auth_header.sub("Bearer ", "") if auth_header&.start_with?("Bearer ")
+
+    request.headers["X-MCP-Token"].presence || params[:token].presence
+  end
+
+  # ---- session lifecycle ----------------------------------------------
+
+  # POST: create a session on `initialize`, otherwise require an existing one.
+  def mcp_resolve_session!
+    methods = mcp_methods_from(mcp_parsed_body)
+
+    if methods.include?("initialize")
+      @mcp_session = McpToolkit::Session.create!(config: mcp_config)
+    else
+      @mcp_session = McpToolkit::Session.find(request.headers[SESSION_HEADER], config: mcp_config)
+      return mcp_render_session_not_found if @mcp_session.nil?
+    end
+
+    response.headers[SESSION_HEADER] = @mcp_session.id
+  end
+
+  def mcp_methods_from(request_body)
+    # Array.wrap (not Kernel#Array): a single JSON-RPC Hash must wrap to
+    # [hash], whereas Kernel#Array(hash) would explode it into [[k, v], ...].
+    Array.wrap(request_body).filter_map { |req| req.is_a?(Hash) ? req["method"] : nil }
+  end
+
+  def mcp_parsed_body
+    return @mcp_parsed_body if defined?(@mcp_parsed_body)
+
+    @mcp_parsed_body = JSON.parse(request.body.read)
+  rescue JSON::ParserError
+    @mcp_parsed_body = {}
+  end
+
+  # ---- error renders ---------------------------------------------------
+
+  def mcp_render_unauthorized(message)
+    render json: {
+      jsonrpc: "2.0",
+      id: nil,
+      error: { code: -32_000, message: "Unauthorized: #{message}" }
+    }, status: :unauthorized
+  end
+
+  def mcp_render_session_not_found
+    mcp_log_session_not_found
+    render json: {
+      jsonrpc: "2.0",
+      id: nil,
+      error: { code: -32_001, message: "Session not found or expired" }
+    }, status: :not_found
+  end
+
+  # Warns (greppable, no id/token) when a POST arrives with no matching session.
+  # The common cause is a session created on one process but looked up on another
+  # because `cache_store` isn't a shared store — invisible otherwise, since the
+  # caller just sees a 404. Records only whether a session-id header was PRESENT so
+  # a header-missing client bug is distinguishable from a cache misconfiguration.
+  def mcp_log_session_not_found
+    header_present = request.headers[SESSION_HEADER].present?
+    mcp_logger.warn(
+      "[McpToolkit] MCP session not found or expired " \
+      "(#{SESSION_HEADER} header present: #{header_present}). If sessions are created but not " \
+      "found, cache_store is likely not shared across processes (set it to a shared store, e.g. Rails.cache)."
+    )
+  end
+end

data/lib/mcp_toolkit/unknown_resource_message.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+begin
+  require "did_you_mean"
+rescue LoadError
+  nil
+end
+
+# Builds the McpToolkit::Registry::UnknownResource message from a bad name and the
+# registered resource names: it states the bad name, then (a) suggests the nearest
+# registered name(s) for a near-miss — via Ruby's stdlib DidYouMean spell checker
+# when available, else a dependency-free prefix/substring + edit-distance fallback —
+# and (b), when the catalog is short, lists them all, so a caller (typically an MCP
+# agent that guessed a name) can self-correct without another round-trip to the
+# `resources` tool.
+class McpToolkit::UnknownResourceMessage
+  FULL_LIST_MAX = 10
+  MAX_SUGGESTIONS = 3
+
+  def initialize(name, resource_names)
+    @name = name
+    @resource_names = resource_names
+  end
+
+  def build
+    message = "unknown resource: #{@name.inspect}"
+    return message if @resource_names.empty?
+
+    suggestions = suggestions_for(@name.to_s, @resource_names)
+    message += ". Did you mean #{quote_join(suggestions)}?" if suggestions.any?
+    message += " Registered resources: #{quote_join(@resource_names.sort)}." if @resource_names.size <= FULL_LIST_MAX
+    message
+  end
+
+  private
+
+  def suggestions_for(name, names)
+    if defined?(DidYouMean::SpellChecker)
+      Array(DidYouMean::SpellChecker.new(dictionary: names).correct(name)).first(MAX_SUGGESTIONS)
+    else
+      fallback_suggestions(name, names)
+    end
+  end
+
+  def fallback_suggestions(name, names)
+    target = name.downcase
+    matches = names.select { |candidate| near_miss?(candidate.downcase, target) }
+    matches.sort_by { |candidate| levenshtein(candidate.downcase, target) }.first(MAX_SUGGESTIONS)
+  end
+
+  def near_miss?(candidate, target)
+    candidate.start_with?(target) || target.start_with?(candidate) ||
+      candidate.include?(target) || levenshtein(candidate, target) <= 2
+  end
+
+  def levenshtein(source, target)
+    return target.length if source.empty?
+    return source.length if target.empty?
+
+    previous = (0..target.length).to_a
+    source.each_char.with_index do |source_char, row|
+      current = [row + 1]
+      target.each_char.with_index do |target_char, col|
+        cost = source_char == target_char ? 0 : 1
+        current << [previous[col + 1] + 1, current[col] + 1, previous[col] + cost].min
+      end
+      previous = current
+    end
+    previous.last
+  end
+
+  def quote_join(names)
+    names.map { |name| "\"#{name}\"" }.join(", ")
+  end
+end

data/lib/mcp_toolkit/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module McpToolkit
+  VERSION = "0.3.0"
+end