okf-mcp 1.1.0 → 1.2.1

data/.okf/structure/served-set.md

@@ -0,0 +1,58 @@
+---
+type: Component
+title: The served set, and the cache in front of it
+description: Which bundles this server will answer about — resolved once at boot as the tools' allowlist — plus the folder cache, the engine detection and the one place the `dir` vocabulary lives.
+tags: [mcp, registry, cache, backend, filters]
+generated:
+  by: human:maintainer
+  at: 2026-08-19T12:00:00Z
+resource: lib/okf/mcp/registry.rb
+---
+
+# The files
+
+| file | what it owns |
+| ---- | ------------ |
+| `lib/okf/mcp/registry.rb` | `OKF::MCP::Registry` — the served set: argv refs (dirs and `@slug`s) or the kernel registry, resolved once at boot |
+| `lib/okf/mcp/filters.rb` | `OKF::MCP::Filters` — the `dir` vocabulary: folding, normalizing, containment, depth |
+| `lib/okf/mcp/backend.rb` | `OKF::MCP::Backend` — engine detection: the in-memory backend, or `okf-sqlite3` when it is installed and suitable |
+| `lib/okf/mcp/memory_backend.rb` | `OKF::MCP::MemoryBackend` — the always-present folder cache: residency, fingerprints, catalog rows, search pairs |
+
+# The registry is an allowlist, not a lookup
+
+`Registry.from_argv` and `Registry.from_kernel` resolve **once, at boot**. After
+that the entry list is fixed, and `#root!` is the only way a tool turns a bundle
+name into a path — it raises for anything not in the set.
+
+That is the containment property the whole server rests on: a host cannot ask
+this process to read a bundle nobody served it. `#refresh!` re-reads the same
+sources; it does not widen the set.
+
+Identity comes from the kernel's registry, never minted here when a kernel slug
+exists — `resolve_arg`, `ref_entry` and `group_roots` all defer to it, so
+`@handbook` means the same bundle to `okf lint` and to a host. Groups expand to
+their member roots, recursively, at resolve time.
+
+# The `dir` vocabulary lives in exactly one file
+
+`Filters` exists because it did not. The folding, normalizing and containment
+rules lived in two places and **the two copies disagreed about the root** —
+one treated `""` as "everything", the other as "the root directory only". Every
+tool that takes a `dir` now reads them from here.
+
+`normalize_dir`, `within?`, `dir_depth` and `known_dir?` are the whole surface.
+A new tool taking a `dir` uses them rather than writing a third opinion.
+
+# The cache is per-root and fingerprinted
+
+`MemoryBackend#folder` caches an `OKF::Bundle::Folder` per root;
+`#fingerprint` is what decides whether a cached one is still good. `#retain`
+prunes roots that are no longer served, and `#during_request` memoizes
+fingerprints for the span of one request so a single frame does not stat the
+same tree repeatedly.
+
+`Backend.detect` is the seam for a faster engine: if `okf-sqlite3` is installed
+and `suitable?`, it is used; otherwise the memory backend, which is always
+present. Nothing above this layer knows which one answered:
+[the server definition](server-definition.md) asks the backend, never the
+engine.

data/.okf/structure/server-definition.md

@@ -0,0 +1,72 @@
+---
+type: Component
+title: The server definition
+description: The MCP::Server subclass, the fourteen tool builders and the private helpers they share, one declared output shape per tool, and concepts as resources with a URI parser the SDK's matcher cannot supply.
+tags: [mcp, server, tools, schemas, resources]
+generated:
+  by: human:maintainer
+  at: 2026-08-19T12:00:00Z
+resource: lib/okf/mcp/server.rb
+---
+
+# The files
+
+| file | what it owns |
+| ---- | ------------ |
+| `lib/okf/mcp/server.rb` | `OKF::MCP::Server` — `Server::Definition < ::MCP::Server`, `Server.build`, the fourteen `*_tool` builders, the two prompts, and the shared private helpers |
+| `lib/okf/mcp/output_schemas.rb` | `OKF::MCP::OutputSchemas` — one declared result shape per tool, looked up by name |
+| `lib/okf/mcp/resources.rb` | `OKF::MCP::Resources` — bundles and concepts as MCP resources, and the URI grammar |
+
+# server.rb is one file on purpose, in three bands
+
+At ~1,300 lines it is the largest file in the gem, and splitting it has been
+considered and declined: the fourteen builders are near-identical in shape, and
+what makes them safe is that they sit next to each other where a divergence is
+visible. Read it as three bands.
+
+**`Server.build` and `Definition`.** `build` assembles the definition from a
+registry and an engine. `Definition` subclasses the SDK's server and adds the
+per-request wrap: `#in_request` memoizes fingerprints and `#retain_served`
+prunes cache residency, so a frame's repeated reads cost one stat. `#handle`
+and `#handle_json` are what the tests drive — real JSON-RPC frames, no
+transport involved.
+
+**The fourteen builders**, one per tool: `tags_tool`, `types_tool`,
+`stats_tool`, `list_bundles_tool`, `dirs_tool`, `index_tool`, `search_tool`,
+`read_concept_tool`, `catalog_tool`, `log_tool`, `validate_tool`, `lint_tool`,
+`graph_tool`, `references_tool`. Each is a `define_tool` call and a body that
+calls the kernel. The [tool catalog](../capabilities/tools.md) is the reader's
+map of them.
+
+**The shared helpers**, which are where the contracts actually live:
+`define_tool` (the one place `readOnlyHint`, `title` and the output-schema
+lookup are attached — which is why a tool cannot forget them), `respond_json`
+and `respond_error`, the projection and validation helpers (`check_fields`,
+`check_projection`, `check_asked`, `project_rows`), the bounded-log arithmetic
+(`bounded_log`, `sized_log`), and `check_dir!`, which is the refusal every
+`dir`-taking tool shares.
+
+# One declared shape per tool, looked up by name
+
+`OutputSchemas[name]` is a lookup, not a registry a tool writes into. An
+omission is therefore deliberate and visible: `read_concept` has no shape,
+because it answers markdown rather than a structured row, and that is the only
+one. `test/integration/output_schema_test.rb` walks the wire and checks the
+declared shape against the answer actually sent.
+
+# Resources own the URI grammar because the SDK cannot
+
+`Resources.parse` exists for one reason worth knowing before touching it: **OKF
+concept ids carry slashes** (`capabilities/graph-server.md`), and the SDK's
+resource-template matcher stops at `[^/]+`. So a templated match would truncate
+every nested id. This file parses the URI itself.
+
+`list`, `templates`, `read` and `complete` are the surface; `concept_ids` and
+`prefixed` back the completion. `test/integration/resources_test.rb` and
+`completions_test.rb` drive them.
+
+# The prompts are read at get-time
+
+`Server::PROMPTS` names two markdown files shipped in `lib/okf/mcp/prompts/`,
+and `Server.prompt_text` reads one when a host asks for it. Booting never pays
+for prompt bodies, and editing a prompt does not need a code change.

data/.okf/testing/adding-a-tool.md

@@ -0,0 +1,65 @@
+---
+type: Playbook
+title: Adding a tool, end to end
+description: The walk a fifteenth tool owes — the question to answer before writing it, where the code goes, the four files that gain a test, and the three pins that will refuse it if a step is skipped.
+tags: [testing, tools, playbook, contribution]
+generated:
+  by: human:maintainer
+  at: 2026-08-19T12:00:00Z
+resource: lib/okf/mcp/server.rb
+---
+
+# First, the question that usually ends it
+
+**Do the [fourteen](../capabilities/tools.md) already compose to this?**
+`dirs` + `index` + `search` answer most retrieval between them, and tool-list
+weight is a real cost on every host that connects. A tool that duplicates a
+composition is a permanent tax for a one-time convenience.
+
+Second question: **could the kernel answer it?** If it could, it should — see
+[kernel-first](../design/kernel-first.md). A kernel method serves the CLI, the
+graph server, the TUI and this shell; a tool here serves one.
+
+If both answers are no, the walk is below.
+
+# The walk
+
+1. **Write the failing test first**, in the folder that matches how the bundle
+   is named — `test/integration/by_dir/<tool>_test.rb` at minimum, and
+   `by_registry/` and `across_bundles/` if the tool takes a bundle ref or
+   several. Drive real JSON-RPC through `handle_json`. Run it: it must fail
+   because the tool does not exist, not because a fixture is missing.
+2. **Add the kernel call**, if the analysis is not already there. That is a
+   change to `okf`, with its own test, landing first.
+3. **Add the builder** — `<name>_tool(context)` in `lib/okf/mcp/server.rb`,
+   beside its neighbours, and list it in `tools_for`. Use `define_tool`, which
+   is what attaches `readOnlyHint`, the `title` and the output-schema lookup;
+   nothing else may construct a tool.
+4. **Declare the output shape** in `lib/okf/mcp/output_schemas.rb`, keyed by
+   the tool's name. Omit it only for a markdown answer, and expect to defend
+   the omission — `read_concept` is the only one today.
+5. **Carry `total`** if the answer is a list: how many rows matched *before*
+   any `limit`. No silent truncation, ever.
+6. **Reuse the `dir` vocabulary** from `lib/okf/mcp/filters.rb` if the tool
+   takes a `dir`, and `check_dir!` for the refusal. Do not write a third
+   opinion about what the root means — that bug has already happened once.
+7. **Update [the catalog](../capabilities/tools.md)** with the tool's row.
+8. **Run the suite.** The same test from step 1 passes, unedited.
+
+# The three pins that refuse a skipped step
+
+- `test/integration/capabilities_test.rb` reads the wire and fails a tool
+  missing `readOnlyHint` or `title`.
+- `test/integration/output_schema_test.rb` checks each declared shape against
+  the answer actually sent.
+- `test/unit/bundle_catalog_test.rb` fails when the catalog and `server.rb`
+  disagree about which tools exist — so step 7 is not optional, and forgetting
+  it is a red suite rather than a stale document.
+
+# Adding a file, not a tool
+
+A new file under `lib/` needs a line in whichever
+[structure](../structure/) concept owns its layer — or a concept of its own if
+it is a new layer. `bundle_catalog_test.rb` fails on an unowned file, which is
+the point: the Map used to live in `AGENTS.md` where nothing checked it, and it
+went stale silently.

data/.okf/testing/index.md

@@ -0,0 +1,9 @@
+# Testing
+
+How this gem is tested, and what a change owes before it lands. The root
+`AGENTS.md`'s rule applies here as written — a change starts with a failing
+test, red for the reason you predicted, then the code, then the same test green
+and unedited — and what follows is that rule's shape for this gem's surfaces.
+
+* [The layers](layers.md) - What each layer of the suite proves, and the claims it deliberately does not spend a process on.
+* [Adding a tool](adding-a-tool.md) - The walk a new tool owes: where the code goes, which files gain a test, and what the pins will refuse.

data/.okf/testing/layers.md

@@ -0,0 +1,56 @@
+---
+type: Constraint
+title: What each test layer proves
+description: Integration-first over real JSON-RPC frames, with process-spawning confined to the two files that prove the process — plus the wire-reading rules the SSE tests cannot be written without.
+tags: [testing, integration, http, sse]
+generated:
+  by: human:maintainer
+  at: 2026-08-19T12:00:00Z
+resource: test/integration
+---
+
+# The layers
+
+| layer | proves | files |
+| ----- | ------ | ----- |
+| tool integration | a tool's real answer, driven as JSON-RPC through `handle_json` | `test/integration/{by_dir,by_registry,across_bundles}/` |
+| protocol surface | capabilities, output schemas, resources, completions, prompts | `capabilities_test.rb`, `output_schema_test.rb`, `resources_test.rb`, `completions_test.rb`, `prompts_test.rb` |
+| the process | `okf mcp` spawned for real, WEBrick on a real socket | `cli_plugin_test.rb`, `http_test.rb`, `http_modern_test.rb`, `http_listen_test.rb` |
+| the argv shell | flags and exit codes, in-process, spawning nothing | `cli_test.rb` |
+| units | the pieces with contracts of their own | `test/unit/` |
+
+The three tool directories mirror the kernel's own — the three ways a bundle is
+named: by directory, through the registry, and several at once.
+
+# One claim, one place
+
+A claim about **argv** is proven once, cheaply, in `cli_test.rb`, which drives
+the shell in-process and deliberately spawns nothing. A claim about **the
+process** is proven once, in the spawning files. The split is deliberate: every
+spawn is seconds, and a suite that spawns for argv claims spends minutes
+proving something a method call already settled.
+
+The three HTTP files share one harness, `test/integration/http_harness.rb`, so
+they cannot drift in how they compose the bridge — the same reason
+[`App`](../structure/doors.md) is a single construction site in `lib/`.
+
+# Reading the wire, which is where SSE tests go wrong
+
+Two rules, both learned the hard way, and neither optional:
+
+**Use a raw `TCPSocket`, not `Net::HTTP`.** Net::HTTP holds a chunked body
+until EOF, so a stream that stays open — which is the whole point of
+`subscriptions/listen` — reads as a hang rather than as a passing test.
+
+**Thread `read_until`'s returned buffer back in.** One `readpartial` can carry
+the next frame along with the awaited one, so a sequential read that starts
+from an empty buffer drops a frame and then blocks waiting for it.
+
+# The bundle is pinned too
+
+`test/unit/bundle_catalog_test.rb` checks this bundle against the tree: every
+`.rb` under `lib/` named by exactly one concept in
+[`structure/`](../structure/), every path a concept names still present, and
+the [tool catalog](../capabilities/tools.md) agreeing with the tools
+`server.rb` defines. Structural documentation is code-derived, so it is pinned
+like code rather than trusted like prose.

data/CHANGELOG.md

@@ -5,6 +5,108 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.1] - 2026-08-20
+
+### Fixed
+
+- **The package metadata follows the `gems/` move and the repository rename.**
+  Two URLs on the package page were about to be wrong at once. `changelog_uri`
+  named `blob/main/okf-mcp/CHANGELOG.md`, a path that stopped existing when the
+  four gems moved under `gems/`; `homepage` named `serradura/okf-gem`, and the
+  repository is now **`serradura/okf`** — the name the command has had all
+  along. rubygems.org serves whatever the last release published, so neither
+  corrects itself: only a release republishes metadata, and this is that
+  release. Both land in one round rather than two, which is the whole reason
+  the rename waited for the paths to stop moving.
+
+  `homepage_uri`, `source_code_uri` and `changelog_uri` are all derived from
+  `homepage`, so one line moves four pieces of this gem's metadata. GitHub
+  redirects the old URLs permanently, so anything already published keeps
+  resolving.
+
+### Added
+
+- **The gem ships its own knowledge bundle.** `.okf/` is in `spec.files`, so an
+  installed okf-mcp carries a real bundle — its own — that a host can read
+  through the very tools it serves. It documents the gem's structure: every
+  file under `lib/` grouped by the layer that owns it, the catalog of the
+  fourteen tools, the four design rules, and how to add a tool or a test.
+  `AGENTS.md` now relies on it rather than restating it, and
+  `test/unit/bundle_catalog_test.rb` fails when the two disagree with the tree
+  — a file no concept names, a concept naming a file that is gone, or a tool
+  catalog out of step with `server.rb`.
+
+### Fixed
+
+- **`rake test` on the 2.7 floor.** The Rakefile set
+  `Bundler::GemHelper#tag_prefix=` unguarded, and that accessor arrived in
+  Bundler 2.2 — Ruby 2.7, this gem's floor, ships 2.1.4. Loading the Rakefile
+  there raised `NoMethodError` and took the whole task down before a single
+  test ran. CI never saw it, because `ruby/setup-ruby` installs the newest
+  Bundler each Ruby accepts; only a floor run against the stock image
+  surfaces it. okf-tui and okf-pro have carried the `respond_to?` guard since
+  they were cut, and this gem now does too — on a Bundler without the
+  accessor, `release` aborts rather than pushing a bare `vX.Y.Z` that would
+  trigger the okf image build.
+
+### Changed
+
+- **The okf floor moves to `>= 2.1.1, < 3`** — the kernel this shell develops
+  against released 2.1.1, and `test/unit/gemspec_test.rb` holds the floor to the
+  version the suite actually resolves against. It may lead the kernel; it may
+  never lag. The ceiling is unchanged.
+
+## [1.2.0] - 2026-08-18
+
+### Added
+
+- **`OKF::MCP.app` — the Rack seam.** The same server definition and
+  stateless transport `okf mcp --http` serves, as the app a `config.ru`
+  runs: `run OKF::MCP.app` serves the registered bundles under puma,
+  unicorn, or any Rack 3 server, with argv-shaped refs and
+  `allowed_hosts:`/`allowed_origins:` for a reverse proxy. The server you
+  mount it under is your dependency, not this gem's — the no-rackup
+  position holds, and `--http` on the kernel's WEBrick stays the
+  zero-config default. The entry is lazy and a loading test pins it:
+  `require "okf/mcp"` still loads neither the SDK nor WEBrick.
+
+- **Every tool carries a `title`** — the human name a host displays where it
+  lists tools ("Search concepts", "Validate conformance"), beside the wire
+  name an agent calls. All fourteen or none, and a capabilities test pins
+  all fourteen: a mix of titled and untitled tools reads as a half-finished
+  server in a Desktop listing.
+
+### Fixed
+
+- **`subscriptions/listen` streams through the WEBrick bridge** instead of
+  crashing it. The SDK answers the modern lifecycle's listen with a Rack
+  streaming body — a callable, not an enumerable — and the bridge's buffering
+  loop raised `NoMethodError`, handing the client WEBrick's HTML 500 page
+  with the exception text in it: a broken server where the spec's
+  notification stream should open. The bridge now serves callable bodies over
+  a chunked response, parking the handler thread until the SDK ends the
+  stream (a dead peer's `EPIPE`, or the transport's close at shutdown — which
+  now runs before WEBrick's, whose thread-join would otherwise hang on an
+  open stream). Concurrent listens are capped at 32 on this bridge — each one
+  holds a WEBrick thread and connection token, unlike under a Rack 3 server —
+  and since this server declares no `listChanged` or `subscribe` capability,
+  the acknowledged filter is always empty: a stream carries keepalives, never
+  a notification, and that is the conformant answer.
+
+### Changed
+
+- **The mcp floor moves to `~> 1.2`** — the SDK this shell rides released
+  1.2.0, completing the SEP-2575 stateless modern lifecycle of the
+  2026-07-28 protocol, and the suite now proves wire behavior (the modern
+  envelope, `server/discover`, the streamed `subscriptions/listen`) that
+  1.0 and 1.1 never served. The floor tracks what the suite proves, and a
+  new unit guard pins it the same way the okf floor is pinned: a lockfile
+  that resolves past the floor fails the suite until the gemspec follows.
+- **The okf floor moves to `>= 2.1, < 3`** — the kernel this gem develops
+  against released 2.1.0, and the floor tracks what the suite proves against
+  (the gemspec drill enforces equality as the normal state). Nothing here calls
+  a 2.1-only surface; the ceiling is unchanged.
+
 ## [1.1.0] - 2026-08-14
 
 ### Added
@@ -291,6 +393,8 @@ rather than pretending to be changes somebody could have seen.
 
 The name reservation on RubyGems: an empty gem, no functionality.
 
-[1.1.0]: https://github.com/serradura/okf-gem/compare/okf-mcp/v1.0.0...okf-mcp/v1.1.0
-[1.0.0]: https://github.com/serradura/okf-gem/releases/tag/okf-mcp/v1.0.0
+[1.2.1]: https://github.com/serradura/okf/compare/okf-mcp/v1.2.0...okf-mcp/v1.2.1
+[1.2.0]: https://github.com/serradura/okf/compare/okf-mcp/v1.1.0...okf-mcp/v1.2.0
+[1.1.0]: https://github.com/serradura/okf/compare/okf-mcp/v1.0.0...okf-mcp/v1.1.0
+[1.0.0]: https://github.com/serradura/okf/releases/tag/okf-mcp/v1.0.0
 [0.0.0]: https://rubygems.org/gems/okf-mcp/versions/0.0.0

data/README.md

@@ -51,6 +51,26 @@ not access control, and it cannot be — a client that is not a browser sets
 `Host` to whatever it likes. Treat a non-loopback bind the way you would treat
 serving your notes directory over HTTP, because that is what it is.
 
+`--http` runs on the WEBrick the okf kernel already ships — zero configuration,
+no extra dependency. To host the same server under puma, unicorn, or any other
+Rack server instead, `OKF::MCP.app` is the same definition and stateless
+transport as a Rack app, ready for a `config.ru`:
+
+```ruby
+# config.ru — run with: bundle exec puma
+require "okf/mcp"
+
+run OKF::MCP.app                                          # no args: the registered bundles
+# run OKF::MCP.app([ "@handbook", "./docs" ])             # or exactly these
+# run OKF::MCP.app(allowed_hosts: [ "mcp.example.com" ])  # behind a proxy or DNS name
+```
+
+The server you run it under is your dependency, not this gem's, and it needs
+the Rack 3 SPEC (the `subscriptions/listen` notification stream is a Rack 3
+streaming body). Everything above about non-loopback binds applies verbatim:
+a Rack server reachable beyond loopback publishes every served bundle, with
+no authentication.
+
 Whatever argv names is the whole served set. A registry ref is resolved once, at
 boot; no tool argument can widen the set afterwards, so a group slug reaches
 bundles only when the registry itself is what is being served.
@@ -186,6 +206,16 @@ bundle exec rake                   # tests + RuboCop — what CI runs
 bundle exec rake test:integration  # the critical layer alone + coverage/integration/
 ```
 
+The gem carries its own OKF bundle in `.okf/` — what each file under `lib/`
+does, the catalog of the fourteen tools, the design rules, and how to add a
+tool. It ships inside the gem, so it is there after `gem install` too, and the
+quickest way to read it is through this server:
+
+```bash
+okf mcp .okf        # serve okf-mcp's own knowledge, over MCP
+okf server .okf     # or read it as a graph
+```
+
 ## License
 
 Apache-2.0, see [LICENSE.txt](LICENSE.txt).

data/lib/okf/mcp/app.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "server"
+
+module OKF
+  module MCP
+    # The Rack seam: the same server definition and stateless transport the
+    # `--http` verb serves, as the app a config.ru runs — so puma, unicorn or
+    # any Rack server can host the bundles without this gem depending on one
+    # (the reader's server is the reader's dependency; the no-rackup position
+    # holds). This module owns transport construction; the WEBrick bridge
+    # (okf/mcp/http.rb) builds through it, so the options exist in one place.
+    #
+    # Deliberately no listen cap here, unlike the WEBrick bridge's 32: under
+    # a Rack 3 server a `subscriptions/listen` stream holds no thread — the
+    # SDK's callable body returns immediately — so the SDK's own default is
+    # the right bound.
+    module App
+      # The largest request body the transport reads, matching the SDK's own
+      # StreamableHTTPTransport default.
+      MAX_REQUEST_BYTES = 4 * 1024 * 1024
+
+      # The MCP endpoint is the root and nothing else. The SDK transport
+      # routes on method alone, so handed every path it answers a connecting
+      # host's OAuth discovery probes (GET /.well-known/*, POST /register —
+      # Claude Desktop sends both) with a 405 or a 200-wrapped JSON-RPC parse
+      # error: a *broken* sign-in service instead of an absent one, and the
+      # host refuses the connector on it. The WEBrick bridge scopes in its
+      # own #handle; this wrapper is the same refusal for a config.ru host.
+      class Scope
+        def initialize(transport)
+          @transport = transport
+        end
+
+        def call(env)
+          path = env["PATH_INFO"].to_s
+          # "" is the mounted spelling: `map "/mcp"` hands the mount point
+          # itself an empty PATH_INFO.
+          return not_found unless path.empty? || path == "/"
+
+          @transport.call(env)
+        end
+
+        def close
+          @transport.close
+        end
+
+        private
+
+        def not_found
+          [ 404, { "content-type" => "application/json" },
+            [ JSON.generate(error: "not found: the MCP endpoint is /") ] ]
+        end
+      end
+
+      module_function
+
+      # +refs+ are argv-shaped bundle names — directories and @slugs, exactly
+      # what `okf mcp` takes; empty serves the kernel registry, exactly like
+      # `okf mcp` with no args. +allowed_hosts+/+allowed_origins+ widen the
+      # SDK's DNS-rebinding allowlists for a reverse proxy or a DNS name; the
+      # same posture as `--allow-host`, and the same warning — the allowlist
+      # is not access control, and a Rack server bound beyond loopback
+      # publishes every served bundle with no authentication.
+      def build(refs = [], engine: nil, allowed_hosts: nil, allowed_origins: nil)
+        registry = Array(refs).empty? ? Registry.from_kernel : Registry.from_argv(Array(refs))
+        server = Server.build(registry, engine: engine || Backend.detect)
+        Scope.new(transport(server, allowed_hosts: allowed_hosts, allowed_origins: allowed_origins))
+      end
+
+      # Wires one transport to one server definition. Every construction site
+      # — this seam and the WEBrick bridge — goes through here, so the shared
+      # posture (stateless, JSON responses, the body cap, the blank-allowlist
+      # guard) is stated once and cannot drift between the two; a caller
+      # passes only what is its own (the bridge: its listen cap).
+      def transport(server, allowed_hosts: nil, allowed_origins: nil, **options)
+        options = { stateless: true, enable_json_response: true,
+                    max_request_bytes: MAX_REQUEST_BYTES }.merge(options)
+        hosts = Array(allowed_hosts)
+        options[:allowed_hosts] = hosts unless hosts.empty?
+        origins = Array(allowed_origins)
+        options[:allowed_origins] = origins unless origins.empty?
+        app = ::MCP::Server::Transports::StreamableHTTPTransport.new(server, **options)
+        server.transport = app
+        app
+      end
+    end
+  end
+end