okf-mcp 1.2.0 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a730c3c4e2bc94cfdc83704f96ae40425cce8e561e8bb77f84abd153607c81d3
-  data.tar.gz: a1651babe0d4dd972d0d83590aafddba43f411a7f70f2047b92933b8f4dbc281
+  metadata.gz: 44ae2c50c714bc127ac861756a46e998d20f4310c77165ddcb616f7600c75517
+  data.tar.gz: 9fec8976e46b7bbe983bd0261eba453a4b25c700dcde8085df36f7a0df3f924a
 SHA512:
-  metadata.gz: d979addc867e9ee49f0fe3a5090915c63b3b9da55d92e89863e461022ce1316e110e80f5b4ceee6f4076a5171be3fad3691aa10fd732144b6e0dcf5ec0711c25
-  data.tar.gz: 4b52f99b0b429c500acd8fc2af91614f8a0dad69f6d8877533a701aa66421cac9cf1351e35b7b4eaa463e06a8af86506cb8af366cf21e4d6ebc2a74dea3ee8ce
+  metadata.gz: 7989702891ac272f637306102cadbd68f9e14f458b5cf81b373b681e3f9a8970fc248526f65038c449d498508820e143a2c9795b074ce456e3372882fd51889a
+  data.tar.gz: 0a9f01ba82b4bf10592c23666051617f9be55f80848925cbd029a8ad7e42753d3f597491ea71e45f2a97c817c6d8acbf9203890d4b7afd28a17a6dd4c526207a

data/.okf/capabilities/index.md

@@ -0,0 +1,9 @@
+# Capabilities
+
+What this server offers a host, and what implements each of them. This area is
+the catalog an agent reads instead of opening `lib/okf/mcp/server.rb` to find
+out whether something already exists.
+
+* [The fourteen tools](tools.md) - Every tool: what it answers, the kernel call behind it, and the CLI verb it is kin to.
+* [Resources and prompts](resources-and-prompts.md) - What the protocol offers that a tool does not: bundles and concepts as resources, completions, and the two consuming prompts.
+* [Transports](transports.md) - stdio, Streamable HTTP, and any Rack 3 server — one definition behind all three.

data/.okf/capabilities/resources-and-prompts.md

@@ -0,0 +1,45 @@
+---
+type: Capability
+title: Resources, completions and prompts
+description: What the protocol offers that a tool call does not — bundles and concepts as addressable resources, argument completion, and the two prompts shipped in-gem and read at get-time.
+tags: [mcp, resources, prompts, completion]
+generated:
+  by: human:maintainer
+  at: 2026-08-19T12:00:00Z
+resource: lib/okf/mcp/resources.rb
+---
+
+# Resources: addressable, not just callable
+
+A tool is something a host *invokes*; a resource is something it can *attach*.
+Both bundles and concepts are exposed as resources, so a host can put a concept
+into a conversation without spending a tool call on it.
+
+`Resources.list` enumerates served bundles, `templates` declares the concept
+template, and `read` resolves one URI. The URI grammar is parsed by hand rather
+than templated — see
+[the server definition](../structure/server-definition.md) for why the SDK's
+matcher cannot do it.
+
+`Resources.complete` backs argument completion, which is what makes a concept
+id typeable in a host that offers completion at all. `concept_ids` and
+`prefixed` are its two halves.
+
+# Prompts: the consuming pair
+
+Two, shipped as markdown in `lib/okf/mcp/prompts/` and named by
+`Server::PROMPTS`:
+
+| prompt | for |
+| ------ | --- |
+| `search` | answering a question from a bundle, token-lean: the map, then the finder, then only the winning bodies |
+| `consume` | using a bundle as context for a task |
+
+They are read at get-time by `Server.prompt_text`, so booting never pays for
+their bodies and editing one is not a code change. They are written in **tool
+vocabulary** — they name the tools above, not CLI verbs — because the host
+reading them has no shell.
+
+`test/integration/prompts_test.rb` walks both, and
+`test/integration/resources_test.rb` and `completions_test.rb` cover the
+resource surface.

data/.okf/capabilities/tools.md

@@ -0,0 +1,73 @@
+---
+type: Capability
+title: The fourteen tools
+description: Every tool this server defines — what it answers, what it is kin to on the CLI, and the builder that constructs it — as one table, so nothing gets rebuilt for want of knowing it exists.
+tags: [mcp, tools, catalog, search, retrieval]
+generated:
+  by: human:maintainer
+  at: 2026-08-19T12:00:00Z
+resource: lib/okf/mcp/server.rb
+---
+
+# The catalog
+
+Fourteen, and the number is a decision rather than a resting point: tool-list
+weight is a real cost on every host, so adding one is a design decision. Check
+this table first — `dirs` + `index` + `search` compose to most retrieval, and
+the commonest mistake is building a fifteenth tool for something three of these
+already answer together.
+
+Every one is a **read-only lens**: `readOnlyHint` and a `title` on all fourteen,
+`additionalProperties: false` on every input schema, and a declared output shape
+looked up by name (`read_concept` alone has none — it answers markdown).
+
+| tool | answers | builder |
+| ---- | ------- | ------- |
+| `list_bundles` | what exists: every bundle this server knows — slug, title, root, concept count | `list_bundles_tool` |
+| `dirs` | the first move: a bundle's shape, one row per directory | `dirs_tool` |
+| `index` | the §8 index map, one directory at a time: authored `index.md` bodies, rollups, listings | `index_tool` |
+| `search` | find concepts: every term must match (AND) across title, id, tags, type and body | `search_tool` |
+| `read_concept` | one concept's full markdown, frontmatter and body, live from disk | `read_concept_tool` |
+| `catalog` | per-concept metadata for a whole bundle, projectable down to the fields asked for | `catalog_tool` |
+| `tags` | the tag index: every tag with its count and concepts, ordered by count | `tags_tool` |
+| `types` | the type index: every type with its count and concepts, ordered by count | `types_tool` |
+| `stats` | bundle rollups in one answer: concepts, dirs, types, cross-links, distinct tags | `stats_tool` |
+| `log` | the append-only history: every `log.md`, root scope first | `log_tool` |
+| `validate` | the spec §11 conformance verdict, with every error | `validate_tool` |
+| `lint` | the curation report: reachability, backlog, completeness, freshness, provenance | `lint_tool` |
+| `graph` | the knowledge graph in three bounded views — never with concept bodies | `graph_tool` |
+| `references` | the `references/` tree (§6.3): every file, its citers, and every pointer that resolves to nothing | `references_tool` |
+
+Each builder lives in [the server definition](../structure/server-definition.md)
+and calls the kernel. None of them analyses anything itself.
+
+# Kin to a CLI verb, and that is the point
+
+Every row above has a counterpart in `okf <verb>`, and the answers are the same
+because both call the same kernel method. That is the
+[kernel-first rule](../design/kernel-first.md) doing its job: a host and a
+terminal cannot disagree about whether a bundle is conformant.
+
+So the way to add a capability is usually **not** to add a tool here. It is to
+add it to the kernel, where the CLI, the graph server, the TUI and this shell
+all reach it.
+
+# What every list answer carries
+
+`total` appears on every list answer and means one thing everywhere: **how many
+rows the request matched, before any `limit` cut them**. There is no silent
+truncation anywhere in this gem, and a new tool that returns rows owes the same
+field with the same meaning.
+
+Domain failures become tool errors carrying the kernel's own sentences — never
+a bare `-32603` — and both channels always: the JSON text an older client reads
+and the same object as `structuredContent`.
+
+`test/unit/bundle_catalog_test.rb` fails if this table and the tools
+`server.rb` defines ever disagree, in either direction.
+
+# The doctrine is elsewhere
+
+*Why* each tool exists, what was rejected, and the reasoning behind the
+bounded-output rules is [the tool set](../design/the-tool-set.md). This table
+is the catalog; that concept is the argument. Neither restates the other.

data/.okf/capabilities/transports.md

@@ -0,0 +1,39 @@
+---
+type: Capability
+title: Three transports, one definition
+description: stdio by default, Streamable HTTP behind `--http`, and any Rack 3 server through `OKF::MCP.app` — all three built at one seam so they cannot compose the server differently.
+tags: [mcp, transports, stdio, http, rack]
+generated:
+  by: human:maintainer
+  at: 2026-08-19T12:00:00Z
+resource: lib/okf/mcp/app.rb
+---
+
+# The three
+
+| transport | how | who owns it |
+| --------- | --- | ----------- |
+| stdio | the default for `okf mcp` | `CLI#serve_stdio` |
+| Streamable HTTP | `okf mcp --http` — the WEBrick bridge, stateless JSON mode | [`HTTP`](../structure/http-bridge.md) |
+| any Rack 3 server | `run OKF::MCP.app` in a `config.ru` | [`App`](../structure/doors.md) |
+
+stdio is the default because it is what an agent host launches; nothing has to
+be bound, and there is no port to collide.
+
+# One construction site
+
+All three reach the transport through `App.build` / `App.transport`. This is
+worth protecting: the moment two callers construct their own, they begin to
+disagree about `allowed_hosts`, `allowed_origins` or the engine, and the
+disagreement shows up as a security difference between `--http` and a Rack
+deployment rather than as a test failure.
+
+`test/integration/http_harness.rb` is the same idea one layer up — the three
+HTTP test files share it so they cannot drift in how they compose the bridge.
+
+# No rackup file of its own
+
+This gem ships no `config.ru`. The reader's server is the reader's dependency:
+`OKF::MCP.app` is a complete Rack application, and naming a server here would
+add a dependency to satisfy a convenience. The bridge behind `--http` uses
+WEBrick, which arrives through okf rather than being named in this gemspec.

data/.okf/design/index.md

@@ -0,0 +1,11 @@
+# Design
+
+The rules a change has to keep. `AGENTS.md` states them as a contract in a
+handful of lines; this is where each one's argument lives, so that a rule
+questioned is a rule you can re-read rather than re-derive.
+
+* [The tool set, and why it is this one](the-tool-set.md) - The doctrine: what each tool exists for, the bounded-output argument, and the posture the whole surface takes.
+* [The inherited Ruby floor](ruby-floor.md) - 2.7, the `mcp` SDK's, not okf's 2.4 — and what that admits and forbids.
+* [Two runtime dependencies](runtime-dependencies.md) - Exactly `mcp` and `okf`, with floors that track what the suite proves.
+* [Kernel-first](kernel-first.md) - This shell restates nothing the kernel can answer, which is what stops the CLI and MCP answers drifting apart.
+* [One entry point](one-entry-point.md) - `okf mcp` through the plugin seam, and why the executable was removed before the first release.

data/.okf/design/kernel-first.md

@@ -0,0 +1,42 @@
+---
+type: Constraint
+title: Kernel-first — this shell restates nothing
+description: Logic a tool needs lands in the kernel and is read from there, so a host's answer and a terminal's answer cannot drift apart; the corollary is that most new capabilities are not new tools.
+tags: [architecture, kernel, drift, constraint]
+generated:
+  by: human:maintainer
+  at: 2026-08-19T12:00:00Z
+resource: lib/okf/mcp/server.rb
+---
+
+# The rule
+
+Every tool is a library call. Logic a tool needs that the kernel does not have
+yet — `Bundle#tag_groups`, `Bundle#stats`, the cutoff grammar — is added *to
+the kernel* and read from there, never implemented in this shell.
+
+The reason is drift, and it is not hypothetical: the CLI, the graph server, the
+TUI and this gem all answer the same questions about the same bundles. The
+moment two of them compute an answer independently, they begin to disagree
+under conditions nobody tested, and the disagreement surfaces as a user
+reporting that `okf lint` and their agent say different things.
+
+# The corollary that saves the most work
+
+**Most new capabilities are not new tools here.** If a host needs something,
+ask first whether the kernel could answer it — because if it could, the CLI and
+the TUI want it too, and one kernel method serves all four surfaces.
+
+This is also the repository's standing rule, stated at the seam: every
+user-facing capability lands in the base gem first, and no addon owns semantics
+the base lacks.
+
+# What legitimately lives here
+
+Three things, and it is a short list: **schema** (input shapes, declared output
+shapes), **bounded-output arithmetic** (`total`, the log slicing, projection),
+and **protocol translation** (tool errors carrying the kernel's own sentences,
+both content channels, resource URIs). None of them is analysis.
+
+If a change adds a fourth kind, that is the signal to stop and ask whether it
+belongs in the kernel instead.

data/.okf/design/one-entry-point.md

@@ -0,0 +1,36 @@
+---
+type: Constraint
+title: One entry point, and no executable
+description: "`okf mcp` through the kernel's plugin seam is the only door; the `exe/` that only aliased it was removed before the first release, and adding one back needs an argument stronger than symmetry."
+tags: [cli, plugin, packaging, constraint]
+generated:
+  by: human:maintainer
+  at: 2026-08-19T12:00:00Z
+resource: lib/okf/plugin.rb
+---
+
+# No `exe/`
+
+`lib/okf/plugin.rb` registers `okf mcp` with the kernel's command registry, and
+that is the gem's entire entry surface. `spec.executables` is empty by
+omission, and `test/unit/packaging_test.rb` and `test/integration/cli_plugin_test.rb`
+hold the line from opposite ends — one that nothing ships, one that the verb
+works when spawned as a real process.
+
+The removed executable did nothing but call the same `CLI.run`. It went before
+the first release, while dropping a name still cost nobody anything. What it
+would have cost forever: a second name to install, document, keep working and
+keep in step with the verb's argument grammar.
+
+`okf-tui` made the same call for the same reason, and `okf-pro` made it for a
+sharper one — its hook wrapper has to recognise exactly one `okf` binary.
+
+# The dispatcher adds nothing
+
+Between `okf mcp` and `OKF::MCP::CLI.run` there is argv and the streams, and
+nothing else. That is what makes the plugin seam honest: a verb behaves like a
+built-in because it *is* dispatched like one, and nothing about being an addon
+shows up in how it is invoked or how it exits.
+
+Adding a binary back needs an argument stronger than symmetry with gems that
+have one.

data/.okf/design/ruby-floor.md

@@ -0,0 +1,43 @@
+---
+type: Constraint
+title: The floor is 2.7, and it is inherited
+description: The `mcp` SDK's floor, taken rather than chosen — so okf's 2.4 API list does not bind here, and nothing past 2.7 may appear in lib/ or test/.
+tags: [ruby, floor, constraint]
+generated:
+  by: human:maintainer
+  at: 2026-08-19T12:00:00Z
+resource: okf-mcp.gemspec
+---
+
+# 2.7, from the SDK
+
+The floor is the `mcp` gem's, inherited rather than argued. That makes it
+different in kind from okf's 2.4, which is a *position* — the tool should run
+on the Ruby an OS already ships. Nothing here can run below what the SDK
+supports, so there is no version of this gem that reaches okf's floor.
+
+# What it admits, and what it still forbids
+
+A sibling's floor is its own: **okf's 2.4 API list — `@okf design/ruby-floor` —
+does not bind here.** `filter_map`, `tally`, `Dir.glob(base:)`, `transform_keys`,
+`Struct.new(keyword_init:)` and numbered block params are all available and
+used.
+
+What is forbidden is anything *past* 2.7, in `lib/` **and** in `test/`:
+endless method definitions, hash-literal shorthand (`{x:}`), `Data.define`,
+`it` as a block parameter, and the rest of 3.x. RuboCop's `TargetRubyVersion`
+catches syntax; it does not catch APIs, so a 3.x method that parses fine on 2.7
+is the failure mode to watch.
+
+The suite is the check that matters — CI runs 2.7 through the current stable,
+one job for this gem, and a 3.x-only spelling fails on the oldest column. That
+is the same rule the [dependency floors](runtime-dependencies.md) are held to:
+the floor tracks what the suite proves.
+
+# The trap the floor sets in the HTTP bridge
+
+`ThreadError` on a mutex in trap context is a 2.7 behaviour, and it is why the
+signal trap in [the HTTP bridge](../structure/http-bridge.md) hands teardown to
+a thread instead of doing it inline. That is a floor constraint expressed as
+code, and it is the one place the floor is load-bearing rather than merely
+declared.

data/.okf/design/runtime-dependencies.md

@@ -0,0 +1,45 @@
+---
+type: Constraint
+title: Exactly two runtime dependencies
+description: "`mcp` and `okf`, nothing else — rack and webrick arrive through okf and must never be named here — with both floors held to one rule: the floor tracks what the suite proves."
+tags: [dependencies, gemspec, constraint]
+generated:
+  by: human:maintainer
+  at: 2026-08-19T12:00:00Z
+resource: okf-mcp.gemspec
+---
+
+# The two
+
+`mcp` (the official SDK) and `okf` (the kernel). That is the whole list, and
+`test/unit/gemspec_test.rb` pins it.
+
+**rack and webrick arrive via okf.** Naming either one here would be the
+mistake that looks like diligence: this gem uses both — the Rack seam and the
+WEBrick bridge — but it uses them *because okf already depends on them*, and a
+second declaration is a second version constraint to keep in sync with a gem
+that owns the answer.
+
+A third runtime dependency is a design decision, held to the same bar the
+kernel holds its own: argue it, do not add it for convenience — and
+[kernel-first](kernel-first.md) is usually the reason one is not needed.
+
+# The floor tracks what the suite proves
+
+One rule covers both, and it is the reason the pins are not round numbers.
+
+**`mcp` is pinned pessimistically (`~>`)**, and the suite fails the day the
+lockfile resolves past it. The listen and modern-path tests exercise the
+SEP-2575 wire, which 1.0 and 1.1 never served — against those versions the
+tests fail, so the floor cannot admit them. The floor is not a guess about
+compatibility; it is the oldest version the tests actually pass on.
+
+**The `okf` floor may lead the kernel checkout but never lag it.** It names the
+kernel version that ships what this shell rides — `Search.prepare/with/across`,
+registry groups, project-local discovery, `dirs`, `Bundle#directories`, the
+slug grammar. An earlier floor once admitted a kernel this code raises
+`NoMethodError` against, because `Bundle#directories` did not exist there: the
+gem installed cleanly and broke on the first `dir` refusal.
+
+That is the failure the rule closes, and why the floor moves when the code
+starts calling something new — in the same commit, not at the next release.