okf-mcp 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f19f69227417cc91ee456e6fca9f517ae1d8f4d571bb7423c7d76d4e38df238
-  data.tar.gz: dcd1b33fb97cb5eb47bbf01681b2b291d26b035c33d9dc5585422edd3f00e165
+  metadata.gz: a730c3c4e2bc94cfdc83704f96ae40425cce8e561e8bb77f84abd153607c81d3
+  data.tar.gz: a1651babe0d4dd972d0d83590aafddba43f411a7f70f2047b92933b8f4dbc281
 SHA512:
-  metadata.gz: 1821ef4c6684ec3ca30d3368f1c4ee07c308f24693278b38866e91f2ad1b12b8f742d45cc42c02d002c5f75bd9cd007e64aec155de439c1f2a47d9c12bedc0f8
-  data.tar.gz: 399fdd6c71fad193ce28256b5982d6de87fe547ac818aa4813a72981f8afe8733488f91a420c0232dc58221bcd29dd31f2a8fa318ffc584af521fd8d1d9d0279
+  metadata.gz: d979addc867e9ee49f0fe3a5090915c63b3b9da55d92e89863e461022ce1316e110e80f5b4ceee6f4076a5171be3fad3691aa10fd732144b6e0dcf5ec0711c25
+  data.tar.gz: 4b52f99b0b429c500acd8fc2af91614f8a0dad69f6d8877533a701aa66421cac9cf1351e35b7b4eaa463e06a8af86506cb8af366cf21e4d6ebc2a74dea3ee8ce

data/CHANGELOG.md

@@ -5,6 +5,59 @@ 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
@@ -291,6 +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.

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/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

data/lib/okf/mcp/server.rb

@@ -253,6 +253,7 @@ module OKF
         def tags_tool(context)
           define_tool(
             name: "tags",
+            title: "Tag index",
             description: "The tag index: every tag with its count and concepts, ordered by count. " \
                          "`by: \"dir\"` or `by: \"type\"` regroups per concept dimension for vocabulary " \
                          "curation — each tag then carries `count` (within the group) beside `total` " \
@@ -285,6 +286,7 @@ module OKF
         def types_tool(context)
           define_tool(
             name: "types",
+            title: "Type index",
             description: "The type index: every type with its count and concepts, ordered by count. " \
                          "§4.1's vocabulary is open — this is how you learn what a bundle's producer " \
                          "meant by its types before filtering the catalog on one.",
@@ -309,6 +311,7 @@ module OKF
         def stats_tool(context)
           define_tool(
             name: "stats",
+            title: "Bundle stats",
             description: "Bundle rollups in one answer: concepts, dirs, types, cross-links, distinct " \
                          "tags, and the by_type/by_dir/by_top_dir distributions — \"how big is what I am " \
                          "about to read\". by_dir counts the file's directory (a dir holding nothing " \
@@ -378,6 +381,7 @@ module OKF
         def list_bundles_tool(context)
           define_tool(
             name: "list_bundles",
+            title: "List bundles",
             description: "What exists: every OKF bundle this server knows — slug, title, root, concept " \
                          "count, type/tag rollups (top #{ROLLUP_LIMIT} each, with other_types/other_tags remainder " \
                          "counts), which is the default, and whether its directory is missing — plus the " \
@@ -402,6 +406,7 @@ module OKF
         def dirs_tool(context)
           define_tool(
             name: "dirs",
+            title: "Directory tree",
             description: "The first move: a bundle's shape as one row per directory — `count` is the " \
                          "concepts living directly there, `subtree` the weight at or below it, `subdirs` " \
                          "its children. Orient here before anything else; it scales with the tree, not " \
@@ -429,6 +434,7 @@ module OKF
         def index_tool(context)
           define_tool(
             name: "index",
+            title: "Bundle index",
             description: "The bundle's index map, one directory at a time: the authored index.md body " \
                          "(or `synthesized: true` where none exists), type/tag rollups, subdirectories, " \
                          "and the concept listing an index there would enumerate — the view that surfaces " \
@@ -461,6 +467,7 @@ module OKF
         def search_tool(context)
           define_tool(
             name: "search",
+            title: "Search concepts",
             description: "Find concepts: every term must match (AND) across title, id, tags, type, " \
                          "description, and body. Returns scored rows — each carrying its `bundle` and the " \
                          "fields it `matched`, so results stay citable — with ids for read_concept. Omit " \
@@ -511,6 +518,7 @@ module OKF
         def read_concept_tool(context)
           define_tool(
             name: "read_concept",
+            title: "Read a concept",
             description: "Read one concept's full markdown (frontmatter and body), live from disk — the " \
                          "canonical copy. Ids are exact: take them from search, index, or catalog results.",
             input_schema: {
@@ -545,6 +553,7 @@ module OKF
         def catalog_tool(context)
           define_tool(
             name: "catalog",
+            title: "Catalog",
             description: "Per-concept metadata for a whole bundle — #{CATALOG_FIELDS.join(", ")} — " \
                          "filterable by type, dir (prefix: a dir names itself and everything beneath " \
                          "it), tag, status (effective: absent reads stable) and trust tier. Use it for " \
@@ -586,6 +595,7 @@ module OKF
         def log_tool(context)
           define_tool(
             name: "log",
+            title: "Update log",
             description: "Read a bundle's append-only history — every log.md, root scope first, content " \
                          "live from disk. Returns the newest #{LOG_LIMIT} date-grouped entries per file; " \
                          "each file's `total` is how many it holds and `returned` how many came back, so " \
@@ -611,6 +621,7 @@ module OKF
         def validate_tool(context)
           define_tool(
             name: "validate",
+            title: "Validate conformance",
             description: "The spec §11 conformance verdict: `conformant` (hard errors empty), every error " \
                          "and soft warning with its file and why — unopenable files included. Read-only: " \
                          "you may flag what it finds; fixing it belongs to the okf skill and CLI. " \
@@ -636,6 +647,7 @@ module OKF
         def lint_tool(context)
           define_tool(
             name: "lint",
+            title: "Lint curation",
             description: "The curation-quality report — reachability, backlog, completeness, freshness, " \
                          "provenance, attestation, migration, hygiene — as warnings and infos that never " \
                          "reject (conformance is validate's question). `only`/`except` select by check id " \
@@ -667,6 +679,7 @@ module OKF
         def graph_tool(context)
           define_tool(
             name: "graph",
+            title: "Concept graph",
             description: "The knowledge graph, in three bounded views — never with concept bodies. " \
                          "\"minimal\" (default): id/title nodes, edges, and the type/tag indexes — the " \
                          "shape for planning a traversal. \"hubs\": concepts ranked by inbound links with " \
@@ -693,6 +706,7 @@ module OKF
         def references_tool(context)
           define_tool(
             name: "references",
+            title: "References inventory",
             description: "Inventory the bundle's references/ tree (§6.3): every file — the .py attesters " \
                          "and .sql computations no other tool can see included — with the concepts citing " \
                          "each through the §6.2 path-valued fields (resource, sources[].resource, " \
@@ -1000,9 +1014,10 @@ module OKF
         # rescue turns domain failures into tool errors an agent can act on
         # instead of opaque JSON-RPC internal errors — carrying the kernel's
         # own sentences, never re-judged here.
-        def define_tool(name:, description:, input_schema:, &body)
+        def define_tool(name:, title:, description:, input_schema:, &body)
           ::MCP::Tool.define(
             name: name,
+            title: title,
             description: description,
             # Looked up rather than passed, so a tool cannot ship without its
             # shape being a deliberate omission — read_concept is the one

data/lib/okf/mcp/version.rb

@@ -2,6 +2,6 @@
 
 module OKF
   module MCP
-    VERSION = "1.1.0"
+    VERSION = "1.2.0"
   end
 end

data/lib/okf/mcp.rb

@@ -16,5 +16,13 @@ module OKF
   # so an embedding app never pays for the protocol machinery.
   module MCP
     class Error < StandardError; end
+
+    # The Rack seam — the same server definition and stateless transport
+    # `--http` serves, as the app a config.ru runs (`run OKF::MCP.app`).
+    # Lazy, so requiring this file never pays for the protocol machinery.
+    def self.app(refs = [], **options)
+      require_relative "mcp/app"
+      App.build(refs, **options)
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: okf-mcp
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Rodrigo Serradura
@@ -15,21 +15,21 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '1.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '1.2'
 - !ruby/object:Gem::Dependency
   name: okf
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '2.1'
     - - "<"
       - !ruby/object:Gem::Version
         version: '3'
@@ -39,7 +39,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '2.1'
     - - "<"
       - !ruby/object:Gem::Version
         version: '3'
@@ -61,6 +61,7 @@ files:
 - NOTICE
 - README.md
 - lib/okf/mcp.rb
+- lib/okf/mcp/app.rb
 - lib/okf/mcp/backend.rb
 - lib/okf/mcp/cli.rb
 - lib/okf/mcp/filters.rb