okf-mcp 0.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a78bd37b6fbbf5ae6740454269f733373560b8dd2e700f97bfaee18703e22c7c
-  data.tar.gz: f891e4a6918915312f6dd5b059c962ed90f35cb4326596a51613e6b600661b4c
+  metadata.gz: 6f19f69227417cc91ee456e6fca9f517ae1d8f4d571bb7423c7d76d4e38df238
+  data.tar.gz: dcd1b33fb97cb5eb47bbf01681b2b291d26b035c33d9dc5585422edd3f00e165
 SHA512:
-  metadata.gz: 174754a21311bd18764378a70211f0ff4a17c1a141573cf765fcf5ec80d28cef4d6f789c3c2c5b30e756a403af64409f190194c835816a170d43e42f50c293a0
-  data.tar.gz: 34c4ecb1dc3e665af8b7f93a8b524e0c9d705c785f70596dfb1e138253825f7ee89536e9a2cc8777c963d49d4e023511dbd6a8f3c4d20c33fe1ec3daf5cbcd90
+  metadata.gz: 1821ef4c6684ec3ca30d3368f1c4ee07c308f24693278b38866e91f2ad1b12b8f742d45cc42c02d002c5f75bd9cd007e64aec155de439c1f2a47d9c12bedc0f8
+  data.tar.gz: 399fdd6c71fad193ce28256b5982d6de87fe547ac818aa4813a72981f8afe8733488f91a420c0232dc58221bcd29dd31f2a8fa318ffc584af521fd8d1d9d0279

data/CHANGELOG.md

@@ -1,5 +1,296 @@
-## [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.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
+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.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

@@ -1,12 +1,191 @@
-# 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
+
+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; 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; 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 §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
+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