mcp_toolkit 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f6ccc255fce267fe8c0caafe02f29e8a5db48e9b410494ef463bf9520047cbe2
+  data.tar.gz: feb8b4e46f7e7054abef0bf99ad8d633ebb30d1fb36624b350313d35e83824f9
+SHA512:
+  metadata.gz: 50cc58bd25162c2ecf70b97b90b1de329a8b3858494dc719699d8cf609607d3c6f8abacef5c1ed1f0e0eea8b7dc9760c0a4752a816433e65ee661147404a53d8
+  data.tar.gz: 72474820f84e31bf3601d5ae26e6e153069accf7f51d9c3bc4e11428be2a068139f1ecc9656b5e4fc95bb40275f999a35e24e60bae5c0462dcdf03098e40a030

data/.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    name: RSpec (Ruby ${{ matrix.ruby }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ["3.2", "3.3", "3.4"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - run: bundle exec rspec
+
+  rubocop:
+    name: RuboCop
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+      - run: bundle exec rubocop
+
+  brakeman:
+    name: Brakeman
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+      - run: bundle exec brakeman --force --no-progress --quiet --no-pager

data/.rubocop.yml

@@ -0,0 +1,98 @@
+plugins:
+  - rubocop-performance
+
+AllCops:
+  TargetRubyVersion: 3.2
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - "bin/**/*"
+    - "vendor/**/*"
+    - "tmp/**/*"
+    # Specs follow manual conventions (named subjects, in-example test doubles)
+    # that don't map cleanly to the library cops; they are not linted.
+    - "spec/**/*"
+
+# --- Layout -----------------------------------------------------------------
+
+Layout/LineLength:
+  Max: 120
+
+# --- Style ------------------------------------------------------------------
+
+# Prefer FLAT (compact) leaf declarations — `class McpToolkit::Auth::Authenticator`
+# — over the `module ... module ... class` pyramid. The only exception is the gem
+# entry point, which must open `module McpToolkit` as a block to host the Zeitwerk
+# loader setup, the top-level configuration methods, and the `MCPToolkit` alias;
+# compact is not expressible there. Files that genuinely defined several constants
+# under one namespace (the errors hierarchy) are split one-constant-per-file under
+# lib/mcp_toolkit/errors/ so each can be declared compactly.
+Style/ClassAndModuleChildren:
+  EnforcedStyle: compact
+  Exclude:
+    - "lib/mcp_toolkit.rb"
+
+# Define class methods as `def self.x`, never `class << self` (so the singleton
+# style stays consistent and greppable across the gem).
+Style/ClassMethodsDefinitions:
+  EnforcedStyle: def_self
+
+# The gem (gemspec, Gemfile, lib) is written with double-quoted strings; match
+# that convention instead of churning every literal.
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+# This is a library; per-class/module YARD comments are not enforced.
+Style/Documentation:
+  Enabled: false
+
+# --- Naming -----------------------------------------------------------------
+
+# `has_one` / `has_many` are association-DSL names mirroring AMS / ActiveRecord;
+# they are not boolean predicates.
+Naming/PredicatePrefix:
+  AllowedMethods:
+    - has_one
+    - has_many
+
+# --- Metrics ----------------------------------------------------------------
+# The extracted framework intentionally carries some larger units (the transport
+# controller, the server wiring, the registry/executor dispatch). Bump the
+# metrics cops to fit the code as written rather than contorting it; keep them
+# enabled so genuinely runaway methods still get flagged.
+
+Metrics/MethodLength:
+  Max: 30
+
+Metrics/AbcSize:
+  Max: 30
+
+Metrics/CyclomaticComplexity:
+  Max: 12
+
+Metrics/PerceivedComplexity:
+  Max: 12
+
+Metrics/ClassLength:
+  Max: 250
+
+Metrics/ModuleLength:
+  Max: 250
+
+Metrics/BlockLength:
+  Max: 50
+  Exclude:
+    - "*.gemspec"
+    - "Gemfile"
+
+Metrics/ParameterLists:
+  Max: 6
+
+# `id` is a domain-meaningful record identifier.
+Naming/MethodParameterName:
+  AllowedNames:
+    - id
+    - n

data/CHANGELOG.md

@@ -0,0 +1,123 @@
+## [0.3.0] - 2026-07-03
+
+### Added
+
+- **Resource discovery DX** improvements, closing gaps hit when an MCP agent had to guess a
+  related resource's name rather than discover it:
+  - The `resource_schema` tool now names, for each relationship, the `target_resource` it
+    resolves to (callable via `list` / `get`). A `scheduled_notifications.notification` link is
+    thus discoverably the `notifications` resource instead of a name to guess. Additive and
+    backward compatible: it is omitted when the target can't be resolved (e.g. a polymorphic
+    link), so existing relationship consumers are unaffected.
+  - An unknown resource name now raises a "did you mean" message — the closest registered
+    name(s) via Ruby's stdlib `DidYouMean::SpellChecker` (with a dependency-free edit-distance
+    fallback), plus the full list when the catalog is short. It flows unchanged to the caller as
+    a clean `InvalidParams` tool error via the existing `resolve_descriptor` path.
+
+### Changed
+
+- The transport controller now logs a WARN when a POST arrives with no matching session
+  (`mcp_render_session_not_found`): a greppable, id/token-free line recording only whether a
+  session-id header was present, so a non-shared `cache_store` misconfiguration surfaces in a
+  satellite's own logs instead of only as a client-side 404. The logger defaults to
+  `Rails.logger` and is overridable via the new `mcp_logger` controller hook.
+
+## [0.2.0] - 2026-07-02
+
+### Added
+
+- **Sparse fieldsets** (JSON:API `fields[type]`) on the `get` and `list` tools. Pass
+  `fields` — an array of names or a comma-separated string — to return only the named
+  attributes and/or relationships, shrinking the response (a token win for MCP clients).
+  Attribute and relationship names share one flat namespace; `resource_schema` advertises
+  the valid values. Unknown names are rejected with `InvalidParams` (consistent with
+  unknown filter keys), so a typo is actionable rather than silently dropped.
+  - `McpToolkit::Serializer::Base` honors the selection NATIVELY: `serialize_one` /
+    `serialize_collection` / `serializable_hash` take an optional `fields:` keyword, and
+    unselected `has_many` relationships are never loaded (a query win, not just a payload
+    win). Under a selection the `links` block is omitted entirely when no relationship is
+    selected.
+  - `McpToolkit::FieldSelection` parses + validates the request; `McpToolkit::Serialization`
+    bridges the executors to the serializer.
+- **Backward compatible.** Omitting `fields` returns the full shape exactly as before. An
+  injected serializer that does NOT declare a `fields:` keyword still supports sparse
+  fieldsets — the toolkit prunes its output to the requested `fields` — so the serializer
+  injection contract is unchanged.
+
+## [0.1.0] - 2026-06-28
+
+Initial extraction from two independently-grown internal MCP servers into a single
+shared gem. Standardizes on the official `mcp` gem (`~> 0.18`) as the wrapped
+JSON-RPC core. Per-tool scope is declared explicitly via `required_permissions_scope`,
+and a mountable `McpToolkit::Engine` gives satellites their MCP routes without the
+hand-rolled controller wiring.
+
+### Added
+
+- `McpToolkit.configure` / `config` / `registry` / `reset_config!` — a single
+  injectable `Configuration` object (`MCPToolkit` alias provided).
+- `McpToolkit::Server.build` — wraps `MCP::Server` (the official gem) with the
+  generic toolset registered and the per-request `server_context`.
+- Generic, registry-driven tools subclassing `MCP::Tool`: `resources`,
+  `resource_schema`, `get`, `list`.
+- `McpToolkit::Registry` + `Resource` DSL (`model` / `serializer` / `scope` /
+  `description` / `filterable`) + `ListExecutor` / `GetExecutor` /
+  `ResourceSchema`. The serializer is injectable per resource.
+- `McpToolkit::Serializer::Base` — the default serializer DSL (`attributes`,
+  `has_one`, `has_many`, `translates`), with a documented `serialize_one` /
+  `serialize_collection` contract so an app's existing serializers slot in
+  unchanged.
+- Dual-role authentication: satellite (`Auth::Introspection` +
+  `Auth::Authenticator`, with short-TTL caching) and authority (`Auth::Authority`
+  — local token authentication + introspection payload responder). All
+  config-driven. The introspection HTTP call is owned by
+  `Auth::AuthorityServerClient`.
+- OAuth-style **scope** enforcement, declared EXPLICITLY per resource. Tokens
+  carry `scopes` of the form `<app>__<action>` (e.g. `notifications__read`). A
+  resource declares the scope it requires via `required_permissions_scope`, or a
+  satellite declares one default for all resources via
+  `Registry#default_required_permissions_scope`. A resource's effective scope is
+  its own declaration, else the registry default, else none. A tool is allowed
+  iff the token carries the required scope; a resource (and default) with no
+  declared scope is reachable by any valid token. Whether ANY scope is required
+  is decided per tool — there is NO app-wide permission setting.
+- `Resource#required_permissions_scope` / `#effective_required_permissions_scope`
+  and `Registry#default_required_permissions_scope` / `#required_scope_for` — the
+  explicit scope DSL + resolution. `reset!` preserves the registry default (it's
+  declared in `configure`, not per-reload).
+- `Tools::Base.with_account` / `.with_authentication` take an explicit
+  `required_scope:` keyword (resolved by the caller from the resource); the `list`
+  / `get` / `resource_schema` tools resolve the resource FIRST, then enforce its
+  effective scope. The discovery tools (`resources`, `resource_schema`) require
+  the registry default scope.
+- A **mountable Rails engine**, `McpToolkit::Engine`, plus the gem-provided
+  `McpToolkit::ServerController`: a satellite writes `mount McpToolkit::Engine =>
+  "/mcp"` instead of four hand-declared routes + a controller. The controller's
+  parent class is configurable via `Configuration#parent_controller` (default
+  `"ActionController::Base"`; set `"ApplicationController"` for `helper_method`
+  compat). The engine is ADDITIVE — `Transport::ControllerMethods` remains a
+  standalone concern. Both the engine and the gem's `app/controllers` are loaded
+  only when Rails is present; the gem's non-Rails consumers and unit suite never
+  reference them. The four routes are drawn in the engine's `config/routes.rb`
+  (NOT a class-body `routes.draw`), so they survive Rails' routes_reloader — a
+  class-body draw is wiped on the first route reload, leaving the engine
+  route-less and every `/mcp` 404'ing. A regression spec boots a real
+  `Rails::Application` in an isolated subprocess and asserts the engine route set
+  survives a `reload_routes!`.
+- `Auth::Introspection::Result#authorized_for_scope?(required_scope)` — exact-scope
+  check used by the tool layer.
+- `scopes` field in the introspection contract: parsed by the satellite
+  (`Auth::Introspection`) and emitted by the authority
+  (`Auth::Authority#introspection_payload`).
+- Injectable `Configuration#sql_sanitizer` (defaulting to the ActiveRecord-backed
+  `McpToolkit::SqlSanitizer`) used to escape LIKE wildcards in `matches` /
+  `does_not_match` filters, so a non-Rails host can supply its own.
+- `McpToolkit::Session` — cache-backed, sliding-TTL `Mcp-Session-Id` sessions.
+- `McpToolkit::Transport::ControllerMethods` — an includable Streamable-HTTP
+  controller concern (POST/GET/DELETE/health, SSE-on-`Accept`, 202-for-notifications).
+- `get` accepts a string/UUID record id as well as an integer one.
+
+### Notes
+
+- The gateway / upstream-aggregation layer (`Mcp::Upstreams*`) is intentionally
+  out of scope (core-only).

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Karol Galanciak
+
+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/README.md

@@ -0,0 +1,301 @@
+# mcp_toolkit
+
+An opinionated toolkit for building **account-scoped, read-only MCP servers** on
+top of the official [`mcp`](https://rubygems.org/gems/mcp) gem.
+
+It extracts the shared MCP-server framework that several apps grew independently
+into one versioned, standalone library, so a new app can add an MCP server in
+~20 lines. It ships:
+
+- a **Streamable-HTTP transport** (POST/GET/DELETE/health, SSE-on-`Accept`,
+  `202`-for-notifications) as an includable controller concern;
+- **cache-backed sessions** (`Mcp-Session-Id`, sliding TTL) that survive across
+  Puma workers;
+- **central-app token introspection** in two roles — be the **authority**
+  (authenticate local tokens + answer introspection) or a **satellite**
+  (validate forwarded tokens against the central app);
+- a registry-driven **"generic tools over N resources"** dispatcher
+  (`list` / `get` / `resources` / `resource_schema`) wrapping the official `mcp`
+  gem's JSON-RPC core;
+- an **injectable serializer DSL** (the default base, or your own — e.g. an
+  existing app serializer).
+
+The JSON-RPC protocol, version negotiation, and error envelopes are delegated to
+the official `mcp` gem; this toolkit owns everything around it.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "mcp_toolkit"
+```
+
+```bash
+bundle install
+```
+
+## Concepts
+
+A typical topology is **one central app** responsible for auth and **N
+satellites** that expose their own resources and validate forwarded tokens by
+introspecting against the central app. `mcp_toolkit` makes both roles trivial.
+
+Everything is driven by a single config object:
+
+```ruby
+McpToolkit.configure do |c|
+  # ...
+end
+```
+
+(`MCPToolkit` is an alias — `MCPToolkit.configure { ... }` works identically.)
+
+---
+
+## Quickstart 1 — a satellite MCP server (~20 lines)
+
+A satellite exposes read-only resources and trusts no token locally: it
+introspects each forwarded bearer token against the central app.
+
+**1. Configure** (`config/initializers/mcp_toolkit.rb`):
+
+```ruby
+McpToolkit.configure do |c|
+  c.server_name          = "bsa-notifications-mcp"
+  c.server_instructions  = "Read-only access to this account's notifications domain."
+
+  # --- satellite auth ---
+  c.auth_role            = :satellite
+  c.central_app_url      = ENV.fetch("MCP_CENTRAL_APP_URL") # POSTs <url>/mcp/tokens/introspect
+
+  # The scope every tool requires, declared ONCE for all resources. A resource
+  # can override it per-resource (see below). Omit entirely for "no scope
+  # required". Whether a scope is required is PER TOOL — there is no app-wide
+  # permission flag.
+  c.registry.default_required_permissions_scope "notifications__read"
+
+  # Map the central account id to this app's LOCAL scope root (an Account here).
+  c.account_resolver = ->(synced_account_id) { Account.find_by(synced_id: synced_account_id) }
+
+  # Share sessions/introspection across workers.
+  c.cache_store = Rails.cache
+
+  # The engine's controller inherits ActionController::Base by default; point it
+  # at ApplicationController if your stack needs helper_method (e.g. logstasher).
+  c.parent_controller = "ApplicationController"
+end
+```
+
+**2. Register resources** (same initializer, wrapped in `to_prepare` so they
+refresh on reload). Every `scope` block MUST return a relation already rooted on
+the resolved scope root — this is the single tenancy chokepoint:
+
+```ruby
+Rails.application.config.to_prepare do
+  McpToolkit.registry.reset!
+
+  McpToolkit.registry.register(:notifications) do
+    model       Notification
+    serializer  Mcp::NotificationSerializer        # your serializer (see below)
+    description "Email notification templates + their scheduling rules."
+    scope(&:notifications)                          # account.notifications
+  end
+
+  McpToolkit.registry.register(:scheduled_notifications) do
+    model       ScheduledNotification
+    serializer  Mcp::ScheduledNotificationSerializer
+    description "Scheduled mailings."
+    # Expose a public filter key that maps to a synced storage column:
+    filterable  booking_id: :synced_booking_id
+    # Override the registry default scope for just this resource (optional):
+    required_permissions_scope "notifications__read"
+    scope { |account| ScheduledNotification.where(synced_account_id: account.synced_id) }
+  end
+end
+```
+
+Each resource's effective required scope is its own `required_permissions_scope`
+if declared, else the registry's `default_required_permissions_scope`, else none.
+
+**3. Mount the transport** — one line. The gem ships the engine *and* the
+controller, so a satellite writes no routes and no controller of its own:
+
+```ruby
+# config/routes.rb
+mount McpToolkit::Engine => "/mcp"
+```
+
+That yields `POST/GET/DELETE /mcp` + `GET /mcp/health` exactly as a hand-rolled
+satellite did. The four generic tools (`resources`, `resource_schema`, `get`,
+`list`) are now live over Streamable-HTTP, each call authenticated by
+introspecting the forwarded token and scoped to the resolved account.
+
+> Prefer to keep your own controller? The transport is also a standalone concern
+> — `include McpToolkit::Transport::ControllerMethods` in a controller and route
+> the four endpoints yourself. The engine is purely additive.
+
+---
+
+## Quickstart 2 — make your app the auth authority
+
+The authority authenticates plaintext tokens locally and answers the
+introspection requests satellites send.
+
+**1. Configure** the local token lookup (your `McpToken.authenticate` equivalent):
+
+```ruby
+McpToolkit.configure do |c|
+  c.auth_role          = :authority
+  c.token_authenticator = ->(plaintext) { McpToken.authenticate(plaintext) }
+  c.cache_store        = Rails.cache
+end
+```
+
+The token object your authenticator returns must respond to:
+`kind` (`:accounts_user` | `:user`), `account_id`, `account_ids`, `expires_at`
+(an `#iso8601`-able time or nil), and `scopes` (an array of `<app>__<action>`
+scopes; `[]` = no scopes). Optionally `touch_last_used!`. A typical app token
+model (e.g. `McpToken`) fits.
+
+**2. Expose the introspection endpoint** the satellites call:
+
+```ruby
+class Mcp::TokensController < ActionController::API
+  def introspect
+    token = McpToolkit::Auth::Authority.authenticate(extract_token)
+    return render(json: McpToolkit::Auth::Authority.invalid_payload, status: :unauthorized) unless token
+
+    render json: McpToolkit::Auth::Authority.introspection_payload(token)
+  end
+
+  private
+
+  def extract_token
+    auth = request.headers["Authorization"]
+    return auth.sub("Bearer ", "") if auth&.start_with?("Bearer ")
+
+    request.headers["X-MCP-Token"].presence || params[:token].presence
+  end
+end
+```
+
+```ruby
+# config/routes.rb
+post "mcp/tokens/introspect", to: "mcp/tokens#introspect"
+```
+
+The payload `introspection_payload` emits is exactly the contract the satellite's
+`McpToolkit::Auth::Introspection` parses — the two roles interoperate out of the
+box. (An app can be **both**: a central app that also exposes its own tools just
+sets the authority config and registers resources + the transport controller.)
+
+---
+
+## Serializer injection (e.g. an existing app serializer)
+
+The registry takes a **serializer class per resource**. The gem ships a default
+DSL base (`McpToolkit::Serializer::Base`), but the only thing the executors
+require is that a serializer responds to two class methods:
+
+```ruby
+serializer.serialize_one(record, scope:)
+  # => Hash (a single record's shape), or nil for a nil record
+
+serializer.serialize_collection(records, scope:, total_count:, limit:, offset:)
+  # => { <root_key> => [ <record_hash>, ... ], meta: { total_count:, limit:, offset: } }
+```
+
+Any class satisfying that contract slots in — including an app's existing
+serializers. Register it directly:
+
+> **Sparse fieldsets.** Both methods also accept an optional `fields:` keyword (an
+> array of attribute/relationship names) so `get` / `list` can return a subset of
+> a record's shape. Honoring it natively — the bundled base does — skips computing
+> the unselected members; a serializer that ignores it still works, because the
+> toolkit prunes its output to the requested `fields` instead. Omitting `fields:`
+> (the default) returns the full shape, so this is fully backward-compatible.
+
+```ruby
+McpToolkit.registry.register(:bookings) do
+  model       Booking
+  serializer  BookingSerializer   # your existing serializer
+  scope { |account| account.bookings }
+end
+```
+
+### Using the bundled base
+
+```ruby
+class Mcp::NotificationSerializer < McpToolkit::Serializer::Base
+  attributes :id, :name, :active, :created_at, :updated_at
+  translates :subject, :template_html         # Globalize-backed { locale => value }
+
+  has_one  :account, foreign_key: :synced_account_id
+  has_one  :mail_layout
+  has_many :scheduled_notifications
+end
+```
+
+It emits declared attributes as symbol keys (in declaration order), a sorted
+string-keyed `"links"` hash (ids / `{id:,type:}` for polymorphic / sorted arrays
+for `has_many`), and `iso8601(6)` timestamps. To power the `resource_schema`
+discovery tool, a custom serializer may also expose `declared_attributes` /
+`declared_associations`; this is optional (the base provides them).
+
+---
+
+## Configuration reference
+
+| Setting | Default | Purpose |
+|---|---|---|
+| `server_name` / `server_version` / `server_instructions` | `"mcp-server"` / `"1.0.0"` / `nil` | advertised on `initialize` |
+| `serializer_base` | `McpToolkit::Serializer::Base` | the default base to subclass |
+| `auth_role` | `:satellite` | `:satellite` or `:authority` |
+| `central_app_url` | `nil` | satellite: base URL of the auth authority |
+| `introspect_path` | `"/mcp/tokens/introspect"` | satellite: appended to `central_app_url` |
+| `introspection_cache_ttl` | `45` | seconds to cache introspection results |
+| `introspection_timeout` | `10` | HTTP timeout (s) for the introspection call |
+| `account_resolver` | identity | maps the central account id → local scope root |
+| `token_authenticator` | `nil` | authority: `->(plaintext) { token_or_nil }` |
+| `cache_store` | `MemoryStore` | sessions + introspection cache (set to `Rails.cache`) |
+| `session_ttl` | `3600` | session sliding TTL (s) |
+| `protocol_version` | `nil` (negotiate) | pin an MCP protocol version |
+| `parent_controller` | `"ActionController::Base"` | superclass of the engine's `ServerController` (set to `"ApplicationController"` for `helper_method` compat) |
+| `account_meta_key` | `"mcp-toolkit/account-id"` | `_meta` key a superuser uses to pin the account |
+| `account_id_header` | `"X-MCP-Account-ID"` | header fallback for the account selector |
+
+## Public API surface
+
+- `McpToolkit.configure { |c| ... }`, `McpToolkit.config`, `McpToolkit.registry`,
+  `McpToolkit.reset_config!`
+- `McpToolkit::Registry#register(name) { ... }` (DSL: `model`, `serializer`,
+  `scope`, `description`, `filterable`, `required_permissions_scope`) +
+  `#default_required_permissions_scope`
+- `McpToolkit::Serializer::Base` (DSL: `attributes`, `has_one`, `has_many`,
+  `translates`)
+- `McpToolkit::Server.build(server_context:, config:, extra_tools:)`
+- `McpToolkit::Engine` (mountable; `mount McpToolkit::Engine => "/mcp"`) +
+  `McpToolkit::ServerController` (its controller; parent via `parent_controller`)
+- `McpToolkit::Transport::ControllerMethods` (standalone controller concern;
+  override `mcp_config` / `mcp_extra_tools`)
+- `McpToolkit::Session`
+- `McpToolkit::Auth::Introspection` / `Authenticator` (satellite),
+  `McpToolkit::Auth::Authority` (authority)
+- `McpToolkit::Errors::{InvalidParams, Unauthorized, ConfigurationError}`
+
+## Scope (what's intentionally NOT here)
+
+The gateway / upstream-aggregation layer (a central app's `Mcp::Upstreams*`) is
+**out of scope** — it's core-only and ships to no satellite. This toolkit is for
+servers that expose tools, not for aggregating other servers.
+
+## Development
+
+```bash
+bin/setup
+bundle exec rspec
+```
+
+## License
+
+Available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+# Run brakeman with the same flags CI uses, so a local `rake` catches what the
+# pipeline would.
+desc "Run Brakeman security scanner"
+task :brakeman do
+  sh "bundle exec brakeman --force --no-progress --quiet --no-pager"
+end
+
+# Convenience "everything" task for local runs — mirrors CI (which keeps these as
+# separate jobs: test / rubocop / brakeman) so a green `rake` means a green build.
+task default: %i[spec rubocop brakeman]

data/app/controllers/mcp_toolkit/server_controller.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# The MCP transport controller, provided BY the gem so a satellite mounting
+# McpToolkit::Engine writes no controller of its own. It is the standalone
+# McpToolkit::Transport::ControllerMethods concern wired into a controller.
+#
+# Its parent class is configurable (Doorkeeper-style) via
+# `McpToolkit.config.parent_controller` (default "ActionController::Base"), so a
+# satellite can keep ActionController::Base (NOT ::API) for its logstasher
+# `helper_method` hook:
+#
+#   c.parent_controller = "ApplicationController"
+#
+# Lives under the gem's app/controllers (an engine path), so it's loaded by Rails'
+# autoloader via the engine — never by the gem's own Zeitwerk loader, which only
+# manages lib/. Non-Rails consumers never see it.
+class McpToolkit::ServerController < McpToolkit.config.parent_controller.constantize
+  include McpToolkit::Transport::ControllerMethods
+end

data/config/routes.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Engine routes, drawn through Rails' routes_reloader so they survive route
+# reloads (a class-body `routes.draw` is wiped when the app re-draws the engine's
+# route set on boot/reload). Mounted by a satellite via:
+#
+#   mount McpToolkit::Engine => "/mcp"
+#
+#   POST   /mcp          -> create   (JSON-RPC requests/responses)
+#   GET    /mcp          -> stream   (405; no server-initiated SSE)
+#   DELETE /mcp          -> destroy  (terminate the session)
+#   GET    /mcp/health   -> health   (unauthenticated probe)
+McpToolkit::Engine.routes.draw do
+  post "/", to: "server#create"
+  get "/", to: "server#stream"
+  delete "/", to: "server#destroy"
+  get "health", to: "server#health"
+end