okf-mcp 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 16fa224a5cb1c83ae561094458afe95726a3f04c94a35e56db94b260a2a213bc
-  data.tar.gz: 06027d6762f7f35510d22fc124ecd8e473249bb492baea09238fcd23dafd01a1
+  metadata.gz: a730c3c4e2bc94cfdc83704f96ae40425cce8e561e8bb77f84abd153607c81d3
+  data.tar.gz: a1651babe0d4dd972d0d83590aafddba43f411a7f70f2047b92933b8f4dbc281
 SHA512:
-  metadata.gz: 7e37dd09203d6ace0e2a6394a3efdc8551bc3f74bd0e53c7e30c27795cbb7f9fa3975bb9d5697bc4afdcabbef075300386362a0f4f7f79d7ec863beb638f31bb
-  data.tar.gz: 4c82c6fdf6fe68a04cc109d4ed3187606f6e276cdfc0cbf0368680d36cd2e2f67c05062304e3698cd473c739de5ac7089c2856c612c742718f5a9e0c251636e6
+  metadata.gz: d979addc867e9ee49f0fe3a5090915c63b3b9da55d92e89863e461022ce1316e110e80f5b4ceee6f4076a5171be3fad3691aa10fd732144b6e0dcf5ec0711c25
+  data.tar.gz: 4b52f99b0b429c500acd8fc2af91614f8a0dad69f6d8877533a701aa66421cac9cf1351e35b7b4eaa463e06a8af86506cb8af366cf21e4d6ebc2a74dea3ee8ce

data/CHANGELOG.md

@@ -5,6 +5,137 @@ 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).
 
+## [Unreleased]
+
+## [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
+
+- **`tags`, `types` and `stats` — the CLI's remaining read views, as tools.** `tags`
+  ships with the `by: "dir" | "type"` curation view — the kernel's
+  `Bundle#tag_groups`, extracted so the within-group-beside-total counting
+  has one home — and `stats` reads the kernel's new `Bundle#stats`, whose
+  `by_dir` keeps the honest zero a directory holding nothing directly
+  reports. `files` is deliberately not a tool: `index`'s per-directory
+  listing and `catalog`'s projection already carry its whole answer, and
+  tool-list weight is a real cost on hosts.
+- **`lint` takes `today`** — the CLI's `--today`, in the same deliberately
+  narrow calendar-day grammar (a reinterpretable `20260101` or a
+  `2026-02-30` is refused by name), so an `expired` report is reproducible
+  and citable. The wall clock stays the default.
+- **`fields`/`except` projection on `search`, and `except` on `catalog`** —
+  the row-key vocabulary is checked either way, so a typo is refused by
+  name even when a query matches nothing; the pair is mutually exclusive.
+- **`references`, the eleventh tool** — the kernel's §6.3 inventory over MCP,
+  and the one lens that sees a bundle's non-markdown files: every
+  `references/` entry with the concepts citing it through the §6.2
+  path-valued fields, plus every pointer that resolves to nothing (a bare
+  `references/…` from a subdirectory is the classic miss; the dangling entry
+  names the leading-slash fix). Advisory like every read tool — dangling
+  pointers are data, never a tool error.
+- **`graph`'s traffic view takes `cut`** — the CLI's `--cut N`, so a client
+  can widen past the fitted threshold or narrow below it. Outside
+  `view: "traffic"` it is refused: a half-honored argument is the
+  silent-wrong-answer shape.
+
+### Changed
+
+- **`search` narrows by `status` and `trust`**, the two filters `catalog` and
+  `okf search` already took. An agent that learned the vocabulary from either
+  one and brought it here got an invalid-argument error. They resolve through
+  the catalog rather than the engine's rows — a search row carries what the
+  engine matched on, and the §5 families are not among it.
+
+- **`lint`'s `stale_after` takes the kernel's cutoff grammar** — a
+  `YYYY-MM-DD` date or a full timestamp — rather than everything
+  `Date.iso8601` parses. `20260101` and `2026-W01-1` are now tool errors
+  naming the accepted shapes; a `generated.at`-shaped timestamp is accepted,
+  as before, and reduced to its date. They were accepted before
+  and silently reinterpreted — `okf lint --stale-after 20260101` exits 2, so
+  the shell and its own CLI answered differently about one bundle's staleness.
+
+- **The okf floor must move to okf's v0.2 release number in the release that
+  ships this** — the shell now reads v0.2 surfaces (the trust catalog column,
+  `Concept.effective_status`/`fold_tier`, the linter's clock contract), none
+  of which exist in published okf 1.13.0; the gemspec carries the same
+  RELEASE OBLIGATION note, and the floor cannot move sooner because the
+  monorepo resolves against the path-sourced okf still versioned 1.13.0.
+  `rake release` now refuses while the floor still admits 1.13.0 (the guard
+  hangs off `release:guard_clean`, ahead of both pushes, and deliberately not
+  off `build` — `rake install` depends on that), so the obligation stops a
+  release rather than riding inside one.
+- The catalog tool speaks v0.2: `CATALOG_FIELDS` matches the new row
+  (`timestamp` is gone — the vocabulary refuses it by name), `status` narrows
+  on the effective value through the kernel's own fold, and a `trust` filter
+  lands beside it. `lint` supplies the clock the `expired` check needs, the
+  way the CLI does, and the client-visible descriptions and prompts cite
+  v0.2's chapter numbers.
+
+### Fixed
+
+- **`search`'s declared output schema now carries `skipped`** — the field the
+  tool emits when `"*"` forgives a vanished bundle. A host typing its
+  structured-content handling off `outputSchema` dropped it, and the SDK's
+  result validation (on in the test suite) failed a payload the tool
+  genuinely produces; slugs, not rows, and never required.
+- **An out-of-range `--port` or unresolvable `--bind` is a usage error.** The
+  socket layer raises `SocketError` (Socket::ResolutionError on newer
+  Rubies), which the boot rescue did not name, so a typo came back as a
+  backtrace and exit 1 instead of the one readable line and exit 2 every
+  other boot failure earns.
+
+
 ## [1.0.0] - 2026-08-07
 
 The first functional release: an MCP server over the okf kernel, judged by
@@ -213,5 +344,7 @@ rather than pretending to be changes somebody could have seen.
 
 The name reservation on RubyGems: an empty gem, no functionality.
 
+[1.2.0]: https://github.com/serradura/okf-gem/compare/okf-mcp/v1.1.0...okf-mcp/v1.2.0
+[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
 [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.
@@ -91,27 +111,38 @@ to pin the set instead.
 
 ## Tools
 
-Ten read-only tools. Every list answer is bounded and names the full count it
-was cut from — the rows the request matched, before any `limit`:
+Fourteen read-only tools. Every list answer is bounded and names the full
+count it was cut from — the rows the request matched, before any `limit`:
 
 | Tool | What it answers |
 |---|---|
 | `list_bundles` | what exists: slug, title, root, concept count, type/tag rollups, the default, the groups, the backend |
 | `dirs` | the shape — one row per directory with direct and subtree counts; **the first move** |
 | `index` | the index map: authored index bodies, rollups, listings, one directory at a time (depth 1 by default) |
-| `search` | pointed questions: ANDed terms, scored rows carrying the fields they matched, across several bundles at once |
+| `search` | pointed questions: ANDed terms, scored rows carrying the fields they matched, across several bundles at once; narrows by `type`, `dir`, `tag`, `status`, `trust`; `fields`/`except` project the rows |
 | `read_concept` | one concept's file, verbatim and live from disk; ids are exact |
-| `catalog` | per-concept metadata with link degrees; filters, paging, field projection |
+| `catalog` | per-concept metadata with link degrees; the same five filters, paging, `fields`/`except` projection |
 | `log` | every `log.md`, root first, live — the newest 3 dated entries per file, each answer held to a byte budget `limit` scales; a cut says `truncated` |
-| `validate` | the spec §9 conformance verdict |
-| `lint` | the curation-quality report; `group: "folder"` lists the unlinked files by folder |
-| `graph` | the knowledge graph in three bounded views: minimal, hubs, traffic — never with bodies |
+| `validate` | the spec §11 conformance verdict |
+| `lint` | the curation-quality report; `group: "folder"` lists the unlinked files by folder; `today` pins the clock for a reproducible `expired` report |
+| `graph` | the knowledge graph in three bounded views: minimal, hubs, traffic (`cut` widens or narrows the arcs) — never with bodies |
+| `references` | the §6.3 inventory: every `references/` file — `.py` attesters and `.sql` computations included — with its citing concepts, and the pointers that resolve to nothing |
+| `tags` | the tag index by count; `by: "dir"` or `"type"` regroups for vocabulary curation, within-group counts beside cross-bundle totals |
+| `types` | the type index by count — how you learn what a producer meant by its open §4.1 vocabulary |
+| `stats` | the sizing rollup: concepts, dirs, cross-links, distinct tags, and the by_type/by_dir/by_top_dir distributions |
 
 Each returns its JSON twice: as text, and as `structuredContent` against a
 declared `outputSchema`, so a host consumes a result without parsing a blob and
 guessing at its shape. `read_concept` is the exception — markdown has no object
 shape to declare.
 
+The `status` and `trust` filters answer with the §5 families' vocabulary
+(`draft | stable | deprecated`; `unverified | machine-confirmed |
+human-reviewed`, either spelling). On `search` they narrow through the
+catalog rather than the engine's rows — a search row carries what the engine
+matched on, and the §5 families are not among it — so a `trust` that narrows
+`catalog` narrows `search` identically.
+
 ## Prompts
 
 Two prompts, the consuming pair: `okf-search` — retrieval as progressive

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

data/lib/okf/mcp/cli.rb

@@ -62,7 +62,7 @@ module OKF
           server = Server.build(registry, engine: engine)
           announce(registry, engine)
           prepare_http(server) if @http
-        rescue Error, OKF::Error, OptionParser::ParseError, SystemCallError => e
+        rescue Error, OKF::Error, OptionParser::ParseError, SystemCallError, SocketError => e
           say("okf-mcp: #{e.message}")
           say(USAGE)
           return 2

data/lib/okf/mcp/filters.rb

@@ -10,13 +10,18 @@ module OKF
     # reported an empty bundle root while `search` and `dirs` answered for it.
     # Two copies of a rule is two answers waiting to disagree, so there is one.
     #
-    # There are genuinely **two** rules here, and the distinction is not drift:
+    # There are genuinely **two** rules here, and the distinction is not drift.
+    # Only one of them still lives in this file:
     #
-    #   #under_dir?  filters *concepts*. A dir names itself and everything
-    #                beneath it; `.` is a prefix of nothing, so the root
+    #   concepts     are filtered by `Bundle::RowFilter`, the kernel's one
+    #                catalog-row predicate — a dir names itself and everything
+    #                beneath it, and `.` is a prefix of nothing, so the root
     #                selects only what lives directly in it (the CLI's `--dir`).
+    #                This module's job there is #normalize_dir, the spelling
+    #                fold the kernel deliberately does not do.
     #   #within?     scopes a *tree* of directory rows, where the root is the
-    #                ancestor of every row (`dirs`/`index` walking down).
+    #                ancestor of every row (`dirs`/`index` walking down). The
+    #                kernel has no view of a directory tree, so this one stays.
     module Filters
       module_function
 
@@ -48,13 +53,6 @@ module OKF
         folded.empty? || folded == "." ? "." : folded
       end
 
-      # Concept filtering: `dir` names itself and everything beneath it.
-      def under_dir?(entry_dir, wanted)
-        entry = fold(entry_dir)
-        path = normalize_dir(wanted)
-        entry == path || entry.start_with?("#{path}/")
-      end
-
       # Tree scoping: the root is the ancestor of every row, so `.` selects
       # the whole tree rather than only what sits directly in it.
       def within?(entry_dir, base)

data/lib/okf/mcp/http.rb

@@ -4,7 +4,7 @@ require "socket"
 require "stringio"
 require "webrick"
 
-require_relative "server"
+require_relative "app"
 
 module OKF
   module MCP
@@ -25,10 +25,111 @@ module OKF
       # Binds that mean "every interface" rather than one address.
       WILDCARD_BINDS = %w[0.0.0.0 :: *].freeze
 
-      # The largest request body the bridge will hand the transport, matching
-      # the SDK's own StreamableHTTPTransport default. Anything past it is 413
-      # before it is allocated (see #read_body).
-      MAX_REQUEST_BYTES = 4 * 1024 * 1024
+      # The largest request body the bridge will hand the transport — the
+      # Rack seam's constant, aliased because #read_body enforces it here too:
+      # anything past it is 413 before it is allocated.
+      MAX_REQUEST_BYTES = App::MAX_REQUEST_BYTES
+
+      # Cap on concurrent `subscriptions/listen` streams, far below the SDK's
+      # 1000 default because the costs differ in kind: under a Rack 3 server a
+      # stream holds no thread, but on this bridge each one parks a WEBrick
+      # handler thread *and* occupies one of WEBrick's 100 connection tokens —
+      # at the SDK default the tokens exhaust at 100 and every tool call
+      # queues behind held streams. 32 leaves two-thirds of the tokens for
+      # request traffic. A constant, not a flag: zero-config is this mode's
+      # posture, and an operator who needs more has the Rack seam.
+      MAX_LISTEN_STREAMS = 32
+
+      # What the SDK writes SSE frames to, adapting its stream contract to
+      # WEBrick's proc-body one. The SDK expects write/flush per frame, EPIPE
+      # out of write to mean the peer is gone, and close to end the stream;
+      # WEBrick ends the response when the body proc returns. So the proc
+      # parks in #wait until the SDK — its keepalive thread on a dead peer, or
+      # the transport's own close — calls #close, and only then hands the
+      # thread back (see #stream_response).
+      class Stream
+        def initialize(wire)
+          @wire = wire
+          @state = Mutex.new
+          @wire_lock = Mutex.new
+          @done = ConditionVariable.new
+          @closed = false
+        end
+
+        # One frame, one chunk. A dead peer raises EPIPE/ECONNRESET straight
+        # out of the socket write — exactly the signal the SDK's stream
+        # cleanup keys on, so it must never be swallowed here.
+        #
+        # The wire has its own lock, deliberately separate from the state's:
+        # a *stalled* peer (alive, not reading, send buffer full) parks the
+        # write with no EPIPE to raise, and #close belongs to shutdown — it
+        # must never queue behind a peer's buffer, so it takes only the state
+        # lock. A write racing close lands on a socket that is closing
+        # anyway; the resulting IOError/EPIPE is the SDK's cleanup signal.
+        def write(data)
+          @state.synchronize do
+            raise IOError, "stream is closed" if @closed
+          end
+          @wire_lock.synchronize { @wire.write(data) }
+        end
+
+        # WEBrick's ChunkedWrapper has no flush; each write already reaches
+        # the socket as a complete chunk.
+        def flush
+          @wire.flush if @wire.respond_to?(:flush)
+          nil
+        end
+
+        def close
+          @state.synchronize do
+            @closed = true
+            @done.broadcast
+          end
+        end
+
+        def wait
+          @state.synchronize { @done.wait(@state) until @closed }
+        end
+      end
+
+      # The bridge's own ledger of parked streams, one per WEBrick server.
+      # The SDK closes the streams it knows about, but a listen that races
+      # the transport's close registers *after* that sweep and would park
+      # forever — and a supervisor sends exactly one signal, so "the second
+      # TERM re-sweeps" is termination lost. The latch closes the race: once
+      # #close_all has run, an admitted stream is closed on the spot and its
+      # handler thread parks for no time at all.
+      class Streams
+        def initialize
+          @lock = Mutex.new
+          @streams = []
+          @closed = false
+        end
+
+        def admit(stream)
+          late = @lock.synchronize do
+            if @closed
+              true
+            else
+              @streams << stream
+              false
+            end
+          end
+          stream.close if late
+        end
+
+        def discard(stream)
+          @lock.synchronize { @streams.delete(stream) }
+        end
+
+        def close_all
+          parked = @lock.synchronize do
+            @closed = true
+            @streams.dup
+          end
+          parked.each(&:close)
+        end
+      end
 
       # Everything before accepting — the bind (where EADDRINUSE, the boot
       # failure that actually happens, raises), the traps and the boot line —
@@ -38,21 +139,40 @@ module OKF
       def prepare(server, bind:, port:, allow_hosts: [], out: $stderr)
         app = app_for(server, bind: bind, allowed_hosts: allowed_hosts_for(bind, extra: allow_hosts))
         httpd = build(app, bind: bind, port: port)
-        %w[INT TERM].each { |signal| trap(signal) { httpd.shutdown } }
+        # The trap spawns a thread because #stop takes the transport's mutex,
+        # and a mutex inside trap context is ThreadError on Ruby 2.7.
+        %w[INT TERM].each { |signal| trap(signal) { Thread.new { stop(httpd, app) } } }
         announce(httpd, bind: bind, out: out)
         httpd
       end
 
+      # Teardown in the only order that terminates: the transport first, so
+      # every open listen stream is closed and its parked handler thread
+      # returns (see #stream_response) — WEBrick's own shutdown *joins* the
+      # connection threads, so closing it first would hang on any open stream.
+      #
+      # The ensure is the signal's guarantee: a supervisor sends exactly one
+      # TERM, so whatever the transport's close raises, the stream latch still
+      # trips (a listen racing the close is closed on admission, never parked)
+      # and WEBrick still comes down. One signal, one dead server, always.
+      def stop(httpd, app)
+        app.close
+      ensure
+        httpd.config[:okf_mcp_streams]&.close_all
+        httpd.shutdown
+      end
+
       # The SDK transport wired to the server, in stateless JSON mode. A
       # non-loopback bind (e.g. 0.0.0.0) is refused by the SDK's DNS-rebinding
       # guard unless its Host is allowlisted; loopback binds keep the SDK
       # defaults. Protection itself stays on either way.
-      def app_for(server, bind:, allowed_hosts: allowed_hosts_for(bind))
-        options = { stateless: true, enable_json_response: true, max_request_bytes: MAX_REQUEST_BYTES }
-        options[:allowed_hosts] = allowed_hosts if allowed_hosts && !allowed_hosts.empty?
-        app = ::MCP::Server::Transports::StreamableHTTPTransport.new(server, **options)
-        server.transport = app
-        app
+      # +listen_options+ passes `max_listen_subscriptions:` /
+      # `listen_keepalive_interval:` through to the SDK — real configuration
+      # for a caller composing the bridge directly; the CLI keeps the
+      # defaults above.
+      def app_for(server, bind:, allowed_hosts: allowed_hosts_for(bind), **listen_options)
+        App.transport(server, allowed_hosts: allowed_hosts,
+          max_listen_subscriptions: MAX_LISTEN_STREAMS, **listen_options)
       end
 
       # The Host allowlist a bind address needs: nil for loopback, which the
@@ -120,19 +240,24 @@ module OKF
         []
       end
 
-      # Returns an unstarted server so tests can drive an ephemeral port.
+      # Returns an unstarted server so tests can drive an ephemeral port. The
+      # stream ledger rides the server instance — one per bridge, reachable
+      # from #stop — because the module itself serves many servers at once
+      # under the test suite.
       def build(app, bind:, port:)
+        streams = Streams.new
         httpd = WEBrick::HTTPServer.new(
           BindAddress: bind,
           Port: port,
           Logger: WEBrick::Log.new($stderr, WEBrick::Log::WARN),
           AccessLog: []
         )
-        httpd.mount_proc("/") { |request, response| handle(app, request, response) }
+        httpd.config[:okf_mcp_streams] = streams
+        httpd.mount_proc("/") { |request, response| handle(app, request, response, streams) }
         httpd
       end
 
-      def handle(app, request, response)
+      def handle(app, request, response, streams = nil)
         # The MCP endpoint is the root and nothing else. The SDK transport
         # routes on method alone, so handing it every path answered the OAuth
         # discovery probes a connecting host sends first (GET /.well-known/*,
@@ -154,11 +279,52 @@ module OKF
         status, headers, out = app.call(env_for(request, body))
         response.status = status
         headers.each { |name, value| response[name] = value }
-        buffer = String.new
-        out.each { |chunk| buffer << chunk }
-        response.body = buffer
-      ensure
-        out.close if out.respond_to?(:close)
+        # A callable body is the Rack 3 streaming shape — the SDK's
+        # `subscriptions/listen` answers with one — and buffering it here
+        # would block forever on a stream that only ends when the peer goes.
+        # The close is per-branch, not a method-level ensure: WEBrick invokes
+        # a streaming body only after this method returns, and a callable
+        # that also responds to close (a shape Rack 3 sanctions) must not be
+        # closed before it is served.
+        if out.respond_to?(:call)
+          stream_response(response, out, streams)
+        else
+          begin
+            buffer = String.new
+            out.each { |chunk| buffer << chunk }
+            response.body = buffer
+          ensure
+            out.close if out.respond_to?(:close)
+          end
+        end
+      end
+
+      # Serves a Rack streaming body through WEBrick's proc-body path: with
+      # `chunked = true`, WEBrick calls the proc with a ChunkedWrapper after
+      # the headers are out, and finalizes the response when it returns. The
+      # SDK's callable returns immediately (it registers the stream, writes
+      # the acknowledgement, and starts its keepalive thread), so the proc
+      # parks this handler thread in Stream#wait until the SDK ends the
+      # stream — a dead peer's EPIPE out of a keepalive write, or the
+      # transport's close on shutdown.
+      def stream_response(response, body, streams = nil)
+        response.keep_alive = false # an SSE stream ends with its connection
+        response.chunked = true
+        response.body = lambda do |wire|
+          stream = Stream.new(wire)
+          # Admitted before the SDK sees it: a stream arriving after the stop
+          # latch tripped is closed here and now, so the SDK's first write
+          # raises IOError into its own cleanup and this thread never parks.
+          streams.admit(stream) if streams
+          begin
+            body.call(stream)
+            stream.wait
+          ensure
+            stream.close # idempotent; covers a body that raised
+            streams.discard(stream) if streams
+            body.close if body.respond_to?(:close)
+          end
+        end
       end
 
       # The request body, or nil when it exceeds MAX_REQUEST_BYTES. A declared