okf-mcp 0.0.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a78bd37b6fbbf5ae6740454269f733373560b8dd2e700f97bfaee18703e22c7c
-  data.tar.gz: f891e4a6918915312f6dd5b059c962ed90f35cb4326596a51613e6b600661b4c
+  metadata.gz: 16fa224a5cb1c83ae561094458afe95726a3f04c94a35e56db94b260a2a213bc
+  data.tar.gz: 06027d6762f7f35510d22fc124ecd8e473249bb492baea09238fcd23dafd01a1
 SHA512:
-  metadata.gz: 174754a21311bd18764378a70211f0ff4a17c1a141573cf765fcf5ec80d28cef4d6f789c3c2c5b30e756a403af64409f190194c835816a170d43e42f50c293a0
-  data.tar.gz: 34c4ecb1dc3e665af8b7f93a8b524e0c9d705c785f70596dfb1e138253825f7ee89536e9a2cc8777c963d49d4e023511dbd6a8f3c4d20c33fe1ec3daf5cbcd90
+  metadata.gz: 7e37dd09203d6ace0e2a6394a3efdc8551bc3f74bd0e53c7e30c27795cbb7f9fa3975bb9d5697bc4afdcabbef075300386362a0f4f7f79d7ec863beb638f31bb
+  data.tar.gz: 4c82c6fdf6fe68a04cc109d4ed3187606f6e276cdfc0cbf0368680d36cd2e2f67c05062304e3698cd473c739de5ac7089c2856c612c742718f5a9e0c251636e6

data/CHANGELOG.md

@@ -1,5 +1,217 @@
-## [Unreleased]
+# Changelog
 
-## [0.1.0] - 2026-07-13
+All notable changes to this project are documented in this file.
 
-- Initial release
+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.0.0] - 2026-08-07
+
+The first functional release: an MCP server over the okf kernel, judged by
+the kernel's own contracts. Nothing functional precedes it — `0.0.0` below is
+the empty name reservation, and a `0.1.0` section stood here for a version
+that was cut in this file and never published, so its entries have folded in
+rather than pretending to be changes somebody could have seen.
+
+### Added
+
+- **`okf mcp`** — the entry point, and the only one. The gem ships no
+  executable: it registers a verb with the kernel CLI through the
+  `okf/plugin.rb` seam, so installing it is the whole installation and the
+  server appears in `okf help` under *installed extensions*. The MCP SDK loads
+  only when the verb runs, so `okf help` never pays for it.
+- **Ten read-only tools** mapped straight onto the kernel's library API:
+  `list_bundles`, `dirs`, `index`, `search`, `read_concept`, `catalog`, `log`,
+  `validate`, `lint`, `graph`. Every list output is bounded with a visible
+  `total`, and the bound is on the thing the `total` counts — `log` returns the
+  newest three date-grouped entries per file and names how many each holds,
+  after the pre-release eval found it answering "what changed recently" with a
+  whole 119,863-byte history under a `total` that was counting *files*. Every
+  annotation is honest (`readOnlyHint` on all ten, and the handshake declares
+  only capabilities that answer); domain failures surface as tool errors
+  carrying the kernel's own sentences.
+- **Structured output**: nine of the ten declare an `outputSchema` and emit
+  `structuredContent` beside the JSON text, so a host consumes a result instead
+  of parsing a blob and guessing. `read_concept` returns markdown, which has no
+  object shape to declare.
+- **Bundle identity delegated to the kernel registry**: every `bundle` argument
+  is a registry slug — the identity `@slug` resolves at the CLI and
+  `/b/<slug>/` mounts on the hub. One argument name on all ten tools, including
+  `search`, which is the one that accepts a *set* and briefly said so by
+  spelling itself `bundles`: the eval found that the plural's only signal
+  arrived after a failed call, because an unknown property is refused by the
+  schema before any okf sentence can be written. The type already says it takes
+  an array, and the kernel spells the identity slot the same way for every verb. Argv roots are the allowlist (refs and plain
+  dirs mix, registered slugs reserved before basenames are deduped); no argv
+  serves the active registry, project-local discovery and `OKF_NO_DISCOVERY`
+  included. The allowlist is closed at boot as a property of the object rather
+  than a promise: argv mode does not retain the kernel registry, so no tool
+  argument and no resource URI can widen the served set. Groups fan out for
+  `search` and are refused by every single-bundle tool; `"*"` tolerates a
+  vanished directory (`skipped` named in the payload) while naming one demands
+  it.
+- **The residency layer**: one parsed bundle per root, re-read only when the
+  on-disk fingerprint (mtime *and* size) moves, so bodies are always live and
+  canonical. Index queries hold one shared corpus per *searched* set — the
+  bundles a query names, so federated BM25 scores are comparable by
+  construction — built on first use, bounded by an LRU of four, and dropped
+  when any member changes. **The identity map
+  follows the same rule**: served by the registry, the set of bundles tracks
+  the registry file rather than a boot snapshot, so a `set`/`rename`/`del` in
+  another terminal lands on the next tool call — and the `resources/list` set
+  moves with it, since a resource list derived once at boot drifts out of step
+  with the served set it is supposed to describe. A file that cannot be read or
+  parsed keeps the last good set and retries, so a server with a working set is
+  never taken down by a file it does not own. Argv mode does not follow
+  anything — it never carried the registry, so its set cannot widen.
+  Two consequences the re-read carries with it, both handled at the request
+  seam rather than in each tool: the residency is **pruned to the served
+  set** whenever the set moves — the corpus cache with it, since it pins the
+  same parsed bundles plus a prepared index over each and its own LRU evicts
+  only on an index query, which a scan-only workload never sends — because a
+  movable set was the only thing left bounding a cache that never evicted.
+  Pruning on *every* request instead took the residency and corpus locks each
+  time, queuing an unrelated `list_bundles` — or an initialize handshake —
+  behind whatever corpus build another host's index query was holding them
+  for; an unchanged set has nothing to prune and takes no locks at all. And
+  the fingerprint is **computed once per root per request**, because freshness is
+  a question between requests and asking it three times inside one cost three
+  full-tree walks under the residency lock (measured: `list_bundles`, `catalog`
+  and `search` each went from two walks to one, `search` on the index engine from
+  three).
+- **The engine doctrine, the CLI's exactly**: raw-text scan by default,
+  `engine: "index"` opt-in for BM25+/page parity, `fuzzy` implying the index,
+  `regexp` staying on the scan, incompatible pairs refused with the fix named.
+  The payload names the engine that **answered**, resolved rather than echoed —
+  `fuzzy` switches engines without being asked, and a caller cannot infer which
+  ran, so a miss under the index's tokenizer was indistinguishable from a fact
+  the bundle does not carry.
+- **Resources**: every bundle with a root `index.md` at `okf://<slug>`, and
+  every concept under the template `okf://{bundle}/{id}` — the affordance no
+  tool call has, since a host can attach a document to the context without the
+  model deciding to fetch it. Read live through the same residency layer
+  `read_concept` uses, and closed by the same allowlist: a URI is not a path.
+  Concepts are deliberately not enumerated in `resources/list`, which would
+  mean reading every bundle at boot and freezing a list the fingerprint check
+  exists to keep honest. The bundle list is recomputed per `resources/list` for
+  the same reason — one `stat` each, no bundle read — so *listed implies
+  readable* survives the registry moving.
+- **Completions** for the template's `bundle` and `id`, so it is browsable
+  rather than a shape you have to know. An unserved bundle, an unknown argument
+  and a missing context all complete to nothing — a completion cannot be used
+  to probe what argv did not serve.
+- **Two prompts, the consuming pair**: `okf-search` — retrieval as progressive
+  disclosure (map, then search, then only the winning bodies, with the engine
+  doctrine per query shape) — and `okf-consume` — a bundle as working context
+  without reading it whole. Both are this gem's own text, written against the
+  tools rather than the CLI. An earlier cut served all eight of the skill's
+  playbooks verbatim from the installed kernel, on the argument that a prompt
+  is instructions rather than a capability; what that argument missed is
+  *whose* instructions they were. Every playbook speaks in `okf …` invocations
+  and half dead-end a CLI-less host at "install the CLI first", and five teach
+  authoring — a mission every tool here refuses. The consuming doctrine is
+  restated in tool vocabulary and shipped in this gem, which is also the cost
+  accepted: a doctrine change in the skill must be carried here by hand.
+- **Two transports over one server definition**: stdio (default) and `--http` —
+  Streamable HTTP in stateless JSON mode on the WEBrick the kernel already
+  ships. A non-loopback bind works (a wildcard `--bind 0.0.0.0` admits this
+  machine's own addresses and hostname; `--allow-host` adds a name only a proxy
+  or DNS knows) **and warns at boot in plain words**: every served bundle
+  becomes readable, without authentication, by anything that can reach the
+  port. The Host allowlist those flags feed is a DNS-rebinding defence, not
+  access control — a client that is not a browser sets `Host` to whatever it
+  likes — and the docs no longer imply otherwise. The bridge caps a request
+  body at 4 MiB before allocating it.
+- **Every failure reads as one actionable line.** A boot that cannot bind —
+  `okf mcp --http` on a port already serving, which is the likeliest mistake on
+  the flag that exists so one warm process is shared — printed an eleven-frame
+  backtrace and exited 1 while every other boot failure exited 2 with a sentence;
+  `SystemCallError` is rescued with the rest now — around *boot* only: past
+  it, the likeliest errno is the host closing its pipes, a stdio session's
+  normal end, and routing that through the boot rescue printed the usage
+  banner and exited 2, misfiling a shutdown as an operator mistake for any
+  supervisor keyed on the exit status. A stdio host hanging up mid-serve exits
+  0 — exactly the two hang-up errnos, on stdio alone; any other mid-serve
+  errno propagates as the crash it is rather than borrowing the usage
+  banner's exit 2. The split is structural — the HTTP bind happens in boot,
+  so EADDRINUSE stays a sentence and exit 2 — and diagnostics are best-effort
+  throughout: a closed stderr loses the boot line, never the outcome, where
+  it used to re-raise EPIPE out of the boot rescue's own print on stdio and
+  to file a lost `--http` boot line as a clean exit 0 for a server that never
+  started accepting.
+- **The `okf-sqlite3` seam**: `Backend.detect` soft-requires the engine and
+  duck types it; a missing gem, an unloadable native extension and an engine
+  that will not construct all degrade to memory, silently except in the boot
+  line and `list_bundles.backend`.
+- **The `dir` vocabulary in one place**, since two copies of a rule are two
+  answers waiting to disagree: `"."` and `"/"` both name the bundle root, a
+  trailing slash is ignored, matching folds case, and a blank value is "no
+  filter" rather than a third spelling of the root — a client that fills every
+  declared optional property with `""` is doing something routine and must not
+  be read as asking for the root. Not the CLI's other spelling either: `--dir
+  root` exists there because a shell needs no quoting for it, and importing that
+  into a JSON argument would cost any bundle with a real `root/` directory the
+  ability to name it.
+- **A `dir` that names no directory is refused by every tool that takes one.**
+  `dirs` and `index` have always said so; `catalog` and `search` answered
+  `total: 0` and no error, which is the same empty-answer-that-reads-real this
+  gem refuses everywhere else. It was worst for the spelling the CLI and the
+  bundled skill both teach: an agent asked `catalog` for `root`, was told zero,
+  and reported that the bundle root holds no concepts. Across bundles the
+  refusal is a fact about the *searched set* — a directory one of three bundles
+  has still filters and does not refuse. The set consulted is
+  `Bundle#directories` — the same list the `dirs` rows are built from, so the
+  refusal and the tool its message points at ("orient with dirs") can never
+  disagree; a first cut derived it from the raw file list and accepted a
+  directory holding only a file the reader skipped, which `dirs` refuses to
+  list. The message carries the one nuance the source cannot: a directory
+  standing on disk but holding only unparseable files is refused as exactly
+  that — "holds only files the reader could not parse", pointing at validate
+  — because "no directory" would be false about the filesystem and sends the
+  caller off to re-spell a name that was correct.
+- **`total` means one thing on every tool**: how many rows the request matched,
+  before any `limit`. `dirs` and `index` reported the whole bundle's directory
+  count so a narrowing stayed visible — defensible alone, wrong as a set, and
+  against this gem's own "no silent truncation" promise it read as rows withheld
+  by a tool that takes no limit at all.
+- **Every log answer is held to a byte budget `limit` scales.** §7 fixes no
+  heading level, so `###` date groups are conformant and the entry split
+  cannot see them: the file came back entire under `total: 0, returned: 0` —
+  the one unbounded read on this surface surviving the change that was meant
+  to close it, and reporting itself as empty. The first fix counted it as one
+  indivisible entry cut by size, and left the same read alive one shape over:
+  a whole history under a single `## ` heading split into one "entry" and came
+  back whole behind a `total: 1` that read as bounded. The budget caps every
+  answer now, announced with `truncated: true` — and a scaffolded title with
+  no entries yet reports the zero it holds, where counting it as one entry
+  told an agent there is history where there is none. Held to its word twice
+  over since: the budget is enforced in **bytes** as announced (a character
+  count let a multibyte log through at up to 4x the cap, `truncated` silent),
+  `returned` is recounted from what survived the cut rather than claiming
+  entries whose very headings it removed, and the title's zero holds wherever
+  whitespace put the title.
+
+### Fixed
+
+- **Only the root path speaks MCP; every path beside it answers 404.** The SDK
+  transport routes on method alone, so a bridge that handed it every path
+  answered the OAuth-discovery probes a host sends first (`GET /.well-known/*`,
+  `POST /register`) with a 405 and a 200-wrapped JSON-RPC parse error — a broken
+  sign-in service instead of an absent one, and the host refused the connector
+  on it. 404 is the answer a discovering client reads as "no auth here".
+
+### Security
+
+- **A symlinked `index.md` can no longer export an arbitrary file.** The kernel's
+  read guards (okf 1.13.0) protect every concept, but the root-index resource
+  (`okf://<slug>`) read `index.md` directly, outside them — so a bundle whose
+  `index.md` was a symlink out of the root served the target verbatim, and listed
+  the URI besides. That read is now realpath-checked against the root, and a
+  bundle with an escaping index is not listed at all.
+
+## [0.0.0] - 2026-07-14
+
+The name reservation on RubyGems: an empty gem, no functionality.
+
+[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

@@ -1,12 +1,180 @@
-# OKF::MCP
+# okf-mcp
 
-A Model Context Protocol server for [OKF](https://github.com/serradura/okf-gem) —
-it lets any MCP-capable agent host discover, search, and read Open Knowledge
-Format bundles through the `okf` kernel.
+A [Model Context Protocol](https://modelcontextprotocol.io) server for
+[OKF](https://okfgem.com) bundles: any MCP-capable agent host — Claude Desktop,
+Claude Code, anything speaking the protocol — can discover, orient in, search,
+and read the Open Knowledge Format bundles on a machine.
 
-> **Status:** placeholder release (`0.0.0`) reserving the gem name. The MCP tool
-> surface lands in a later version.
+It is a thin shell over the [`okf`](https://rubygems.org/gems/okf) kernel, the
+fourth surface beside its CLI, HTTP server and Ruby library: every tool maps
+onto the kernel's library API, bundles are named by the same registry slugs
+`@slug` resolves at the CLI, and nothing is reimplemented here.
+
+## Install
+
+```bash
+gem install okf-mcp
+```
+
+Ruby >= 2.7 — the official `mcp` gem's own floor, inherited rather than chosen.
+
+Installing the gem is the whole installation: the
+[`okf`](https://rubygems.org/gems/okf) kernel arrives as a dependency, and the
+gem registers an `okf mcp` verb with its CLI through the plugin seam, so
+the server appears in `okf help` under *installed extensions*. There is no
+second binary — this gem ships no executable of its own.
+
+## Run
+
+```bash
+okf mcp <bundle-dir> [<bundle-dir>…]   # serve exactly these directories
+okf mcp @handbook ./scratch            # registry refs and plain dirs mix
+okf mcp                                # no args: serve the registered bundles (okf registry set <dir> adds one)
+okf mcp --http                         # one warm HTTP process instead of stdio-per-host
+```
+
+Stdio is the default — each host spawns its own process, zero config. `--http`
+(`--bind`, default 127.0.0.1; `--port`, default 9134) serves Streamable HTTP in
+stateless JSON mode for every agent at once. The boot line goes to stderr and
+names the backend, the served bundles, and the registry file the slugs came
+from.
+
+`--bind` beyond loopback works — a wildcard `0.0.0.0` admits this machine's own
+addresses and hostname, and `--allow-host HOST` (repeatable) adds a name only a
+proxy or DNS knows — and it publishes your bundles. **There is no
+authentication.** Anything that can reach the port can read every served
+bundle, so the boot line says so.
+
+The Host allowlist those flags feed is a defence against **DNS rebinding**: a
+browser walked into this port by a page you never meant to give it to. It is
+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.
+
+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.
+
+With no arguments the registry *is* what is served, so it is followed rather
+than snapshotted: `okf registry set`, `rename` or `del` in another terminal
+shows up on the next tool call, without a restart. The file is re-read only
+when its fingerprint moves, so the cost is a `stat`. Bundle contents are never
+snapshotted either — bodies are read live, and a bundle is re-parsed whenever
+one of its files changes.
+
+## Host configuration
+
+**Run `which okf` and paste the absolute path.** A desktop app is launched by
+the window manager, not by your shell, so it never runs the rc file that puts
+a version manager's Ruby on `PATH` — and if your Ruby came from mise, rbenv,
+asdf or chruby, a bare `"okf"` is unresolvable there. The binstub's shebang
+pins its own Ruby, so the absolute path needs nothing else set up.
+
+Claude Desktop (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "okf": { "command": "/absolute/path/from/which/okf", "args": ["mcp"] }
+  }
+}
+```
+
+Claude Code inherits your shell, so the bare name is fine there:
+
+```bash
+claude mcp add okf -- okf mcp
+```
+
+Both serve whatever `okf registry` lists; add directories or `@slug`s to `args`
+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`:
+
+| 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 |
+| `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 |
+| `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 |
+
+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.
+
+## Prompts
+
+Two prompts, the consuming pair: `okf-search` — retrieval as progressive
+disclosure (map, then search, then only the winning bodies), with the engine
+doctrine per query shape — and `okf-consume` — using a bundle as working
+context without reading it whole. Both are this gem's own text, written
+against the tools above rather than the CLI, so they work on a host with no
+shell and no filesystem.
+
+The okf skill's playbooks are deliberately not served. They speak in `okf …`
+invocations, and the authoring ones — produce, migrate, maintain, refine,
+curate — carry a mission every tool here refuses: this server makes a client
+an expert *consumer* of bundles. Authoring stays with the skill
+(`okf skill <dest>`), installed where a filesystem and the CLI actually are.
+
+## Resources
+
+Every bundle with a root `index.md` is a resource at `okf://<slug>`, and every
+concept is one under the template `okf://{bundle}/{id}` — so a host can *attach*
+a document to the context directly, instead of the model having to decide to
+fetch it. Both are read live from disk, and `bundle` and `id` complete, so the
+template is browsable rather than a shape you have to know.
+
+Concepts are not enumerated in `resources/list`: that would mean reading every
+bundle at boot — exactly the eager work this server avoids, since bundles are
+parsed on first use and re-read only when their files change — and it would
+freeze a list that live reading is meant to keep honest.
+
+## Engines
+
+Search matches raw text by default — exact, no tokenizer, milliseconds over an
+already-parsed bundle. `engine: "index"` opts into BM25+ ranking on a held corpus,
+the same engine and version the `okf server` page runs, so the two rank
+identically. `fuzzy` implies the index and its tokenizer; `regexp` stays on the
+raw-text scan; incompatible pairs are refused with the fix named.
+
+Every result names the engine that **answered** it, because `fuzzy` picks one
+without being asked and no score tells you which ran. It matters when something
+is missing: under the index's tokenizer a shattered identifier and an absent
+fact look identical, so knowing you were on the index is what turns "not here"
+back into "try the scan". The doctrine runs the other way too — the scan is
+exact, so a typo or a stemmed form misses on it, and that miss is what
+`engine: "index"` and `fuzzy` are for.
+
+## Beside a browser
+
+The MCP surface is for agents; humans get the same bundles as an interactive
+graph:
+
+```bash
+okf server          # the registered bundles, one hub, http://127.0.0.1:8808
+```
+
+Run it beside the MCP config and both read the same live files.
+
+## Development
+
+```bash
+bin/setup                          # install dependencies
+bundle exec rake                   # tests + RuboCop — what CI runs
+bundle exec rake test:integration  # the critical layer alone + coverage/integration/
+```
 
 ## License
 
-Apache-2.0. See [LICENSE.txt](LICENSE.txt) and [NOTICE](NOTICE).
+Apache-2.0, see [LICENSE.txt](LICENSE.txt).

data/lib/okf/mcp/backend.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module OKF
+  module MCP
+    # The seam between the shell and the optional okf-sqlite3 engine. One
+    # `require` answers both "is it installed?" and "does the native extension
+    # load?" — a broken sqlite3 build degrades to the memory backend instead
+    # of crashing the server, silently except in the boot line and
+    # list_bundles.backend. Feature detection, not version pinning: the engine
+    # only has to answer the duck type below, so the gems release
+    # independently. Backends speak symbol-keyed rows in the kernel's catalog
+    # and search shapes; `score` and `snippet` are optional extras.
+    module Backend
+      ENGINE_METHODS = %i[refresh search catalog capabilities].freeze
+
+      def self.detect
+        engine = build_engine
+        suitable?(engine) ? engine : MemoryBackend.new
+      rescue LoadError, StandardError
+        MemoryBackend.new
+      end
+
+      # Both ways the optional engine can fail are on this side of the seam, so
+      # the one rescue above covers both: the `require` (absent gem, native
+      # extension that will not load) and the construction (a connection it
+      # cannot open, a schema check, a constant renamed out from under us).
+      # Catching only LoadError left the second half fatal, which is exactly
+      # what "degrades instead of crashing the server" promises it is not.
+      def self.build_engine
+        require "okf/sqlite3"
+        OKF::Sqlite3::Backend.new
+      end
+
+      def self.suitable?(engine)
+        ENGINE_METHODS.all? { |name| engine.respond_to?(name) }
+      end
+    end
+  end
+end

data/lib/okf/mcp/cli.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+require_relative "server"
+
+module OKF
+  module MCP
+    # The argv-facing shell: parses options, builds the one server definition,
+    # and hands it to a transport — stdio by default (each agent host spawns
+    # its own process), --http for one warm process serving every agent. Exit
+    # codes keep the kernel CLI's contract: 0 ok, 2 usage error. The boot line
+    # goes to stderr because stdout is the stdio protocol channel.
+    class CLI
+      USAGE = "usage: okf mcp [options] [<bundle-dir>|@slug ...]   " \
+              "(no args: serve the bundles registered with `okf registry`)"
+
+      DEFAULT_BIND = "127.0.0.1"
+      DEFAULT_PORT = 9134
+
+      # Two streams, because they carry different things. +out+ is the
+      # diagnostic channel — the boot line, the notes, the refusals — and
+      # defaults to stderr since stdout belongs to the stdio protocol. +stdout+
+      # is the human channel the two informational flags use, and is a
+      # parameter rather than a literal `$stdout` so the `okf mcp` verb can
+      # hand over the streams the kernel injected into it.
+      def self.run(argv, out: $stderr, stdout: $stdout)
+        new(argv, out: out, stdout: stdout).run
+      end
+
+      def initialize(argv, out: $stderr, stdout: $stdout)
+        @argv = argv
+        @out = out
+        @stdout = stdout
+        @http = false
+        @bind = DEFAULT_BIND
+        @port = DEFAULT_PORT
+        @allow_hosts = []
+        @done = false
+      end
+
+      # Boot, then serve — structurally, because the two phases carry
+      # different exit contracts and the rescue below must never see a serving
+      # error. `SystemCallError` belongs in the boot rescue for the same
+      # reason the tool wrapper rescues it: an errno is a fact about the
+      # operator's machine, not a bug, and it must read as one line rather
+      # than a backtrace. The bind is where it actually bites — `--http`
+      # exists so one warm process is shared, which makes "that port is
+      # already serving" the likeliest mistake, and it came back as eleven
+      # frames and exit 1 while every other boot failure exited 2 with a
+      # sentence. The HTTP bind happens *here*, in boot (see #prepare_http),
+      # precisely so that stays true.
+      def run
+        server = nil
+        begin
+          args = parser.parse(@argv)
+          return 0 if @done
+
+          registry = args.empty? ? Registry.from_kernel : Registry.from_argv(args)
+          registry.boot_notes.each { |note| say("okf-mcp: #{note}") }
+          engine = Backend.detect
+          server = Server.build(registry, engine: engine)
+          announce(registry, engine)
+          prepare_http(server) if @http
+        rescue Error, OKF::Error, OptionParser::ParseError, SystemCallError => e
+          say("okf-mcp: #{e.message}")
+          say(USAGE)
+          return 2
+        end
+
+        serve(server)
+      end
+
+      private
+
+      # Serving, past the boot rescue's reach. On stdio the likeliest errno is
+      # the host closing its pipes — the session's normal end, not a mistake —
+      # and nothing is printed: the streams belong to the host that just hung
+      # up. The carve-out is exactly those two errnos, and stdio's alone: on
+      # `--http` a hang-up errno cannot mean "the session ended" (boot output
+      # already went through #say), and any other mid-serve errno on either
+      # transport is a runtime fault hours past a valid invocation — it
+      # propagates as the crash it is, never the usage banner's exit 2.
+      def serve(server)
+        @http ? @httpd.start : serve_stdio(server)
+        0
+      rescue Errno::EPIPE, Errno::ECONNRESET
+        raise if @http
+
+        0
+      end
+
+      # Diagnostics are best-effort: @out belongs to whoever spawned the
+      # process, and a closed stderr must not decide the outcome — it did,
+      # twice: the boot rescue's own puts re-raised EPIPE as a backtrace for
+      # a normal hang-up, and the serve rescue filed a lost `--http` boot
+      # line as a clean exit 0 for a server that never started.
+      def say(line)
+        @out.puts(line)
+      rescue Errno::EPIPE, Errno::ECONNRESET
+        nil
+      end
+
+      def parser
+        OptionParser.new do |opts|
+          opts.banner = USAGE
+          opts.on("--http", "serve Streamable HTTP instead of stdio") { @http = true }
+          opts.on("--bind HOST", "HTTP bind address (default #{DEFAULT_BIND})") { |value| @bind = value }
+          opts.on("--port PORT", Integer, "HTTP port (default #{DEFAULT_PORT})") { |value| @port = value }
+          opts.on("--allow-host HOST", "admit this Host header (repeatable; for a DNS name",
+            "or a reverse proxy no local interface knows about)") { |value| @allow_hosts << value }
+          opts.on("-h", "--help", "print this help") do
+            @stdout.puts(opts)
+            @done = true
+          end
+          opts.on("--version", "print the version") do
+            @stdout.puts(VERSION)
+            @done = true
+          end
+        end
+      end
+
+      # The one-look diagnosis for "why these bundles?" and "why no ranked
+      # results?": which backend answered detection, which bundles are served
+      # under which slugs, and which registry file the names came from.
+      def announce(registry, engine)
+        bundles = registry.entries.map { |entry| "#{entry.slug} (#{entry.root})" }.join(", ")
+        source = registry.source ? " — registry: #{registry.source}" : ""
+        say("okf-mcp #{VERSION} — backend: #{engine.capabilities[:name]} — bundles: #{bundles}#{source}")
+      end
+
+      def serve_stdio(server)
+        transport = ::MCP::Server::Transports::StdioTransport.new(server)
+        server.transport = transport
+        transport.open
+      end
+
+      # The bind, the traps and the boot line — everything that can fail as a
+      # boot failure — so #run's rescue files an EADDRINUSE as the usage error
+      # it is, while whatever #serve raises later is manifestly not boot.
+      def prepare_http(server)
+        require_relative "http"
+        @httpd = HTTP.prepare(server, bind: @bind, port: @port, allow_hosts: @allow_hosts, out: @out)
+      end
+    end
+  end
+end