okf-mcp 1.2.0 → 1.2.1

data/.okf/structure/served-set.md

@@ -0,0 +1,58 @@
+---
+type: Component
+title: The served set, and the cache in front of it
+description: Which bundles this server will answer about — resolved once at boot as the tools' allowlist — plus the folder cache, the engine detection and the one place the `dir` vocabulary lives.
+tags: [mcp, registry, cache, backend, filters]
+generated:
+  by: human:maintainer
+  at: 2026-08-19T12:00:00Z
+resource: lib/okf/mcp/registry.rb
+---
+
+# The files
+
+| file | what it owns |
+| ---- | ------------ |
+| `lib/okf/mcp/registry.rb` | `OKF::MCP::Registry` — the served set: argv refs (dirs and `@slug`s) or the kernel registry, resolved once at boot |
+| `lib/okf/mcp/filters.rb` | `OKF::MCP::Filters` — the `dir` vocabulary: folding, normalizing, containment, depth |
+| `lib/okf/mcp/backend.rb` | `OKF::MCP::Backend` — engine detection: the in-memory backend, or `okf-sqlite3` when it is installed and suitable |
+| `lib/okf/mcp/memory_backend.rb` | `OKF::MCP::MemoryBackend` — the always-present folder cache: residency, fingerprints, catalog rows, search pairs |
+
+# The registry is an allowlist, not a lookup
+
+`Registry.from_argv` and `Registry.from_kernel` resolve **once, at boot**. After
+that the entry list is fixed, and `#root!` is the only way a tool turns a bundle
+name into a path — it raises for anything not in the set.
+
+That is the containment property the whole server rests on: a host cannot ask
+this process to read a bundle nobody served it. `#refresh!` re-reads the same
+sources; it does not widen the set.
+
+Identity comes from the kernel's registry, never minted here when a kernel slug
+exists — `resolve_arg`, `ref_entry` and `group_roots` all defer to it, so
+`@handbook` means the same bundle to `okf lint` and to a host. Groups expand to
+their member roots, recursively, at resolve time.
+
+# The `dir` vocabulary lives in exactly one file
+
+`Filters` exists because it did not. The folding, normalizing and containment
+rules lived in two places and **the two copies disagreed about the root** —
+one treated `""` as "everything", the other as "the root directory only". Every
+tool that takes a `dir` now reads them from here.
+
+`normalize_dir`, `within?`, `dir_depth` and `known_dir?` are the whole surface.
+A new tool taking a `dir` uses them rather than writing a third opinion.
+
+# The cache is per-root and fingerprinted
+
+`MemoryBackend#folder` caches an `OKF::Bundle::Folder` per root;
+`#fingerprint` is what decides whether a cached one is still good. `#retain`
+prunes roots that are no longer served, and `#during_request` memoizes
+fingerprints for the span of one request so a single frame does not stat the
+same tree repeatedly.
+
+`Backend.detect` is the seam for a faster engine: if `okf-sqlite3` is installed
+and `suitable?`, it is used; otherwise the memory backend, which is always
+present. Nothing above this layer knows which one answered:
+[the server definition](server-definition.md) asks the backend, never the
+engine.

data/.okf/structure/server-definition.md

@@ -0,0 +1,72 @@
+---
+type: Component
+title: The server definition
+description: The MCP::Server subclass, the fourteen tool builders and the private helpers they share, one declared output shape per tool, and concepts as resources with a URI parser the SDK's matcher cannot supply.
+tags: [mcp, server, tools, schemas, resources]
+generated:
+  by: human:maintainer
+  at: 2026-08-19T12:00:00Z
+resource: lib/okf/mcp/server.rb
+---
+
+# The files
+
+| file | what it owns |
+| ---- | ------------ |
+| `lib/okf/mcp/server.rb` | `OKF::MCP::Server` — `Server::Definition < ::MCP::Server`, `Server.build`, the fourteen `*_tool` builders, the two prompts, and the shared private helpers |
+| `lib/okf/mcp/output_schemas.rb` | `OKF::MCP::OutputSchemas` — one declared result shape per tool, looked up by name |
+| `lib/okf/mcp/resources.rb` | `OKF::MCP::Resources` — bundles and concepts as MCP resources, and the URI grammar |
+
+# server.rb is one file on purpose, in three bands
+
+At ~1,300 lines it is the largest file in the gem, and splitting it has been
+considered and declined: the fourteen builders are near-identical in shape, and
+what makes them safe is that they sit next to each other where a divergence is
+visible. Read it as three bands.
+
+**`Server.build` and `Definition`.** `build` assembles the definition from a
+registry and an engine. `Definition` subclasses the SDK's server and adds the
+per-request wrap: `#in_request` memoizes fingerprints and `#retain_served`
+prunes cache residency, so a frame's repeated reads cost one stat. `#handle`
+and `#handle_json` are what the tests drive — real JSON-RPC frames, no
+transport involved.
+
+**The fourteen builders**, one per tool: `tags_tool`, `types_tool`,
+`stats_tool`, `list_bundles_tool`, `dirs_tool`, `index_tool`, `search_tool`,
+`read_concept_tool`, `catalog_tool`, `log_tool`, `validate_tool`, `lint_tool`,
+`graph_tool`, `references_tool`. Each is a `define_tool` call and a body that
+calls the kernel. The [tool catalog](../capabilities/tools.md) is the reader's
+map of them.
+
+**The shared helpers**, which are where the contracts actually live:
+`define_tool` (the one place `readOnlyHint`, `title` and the output-schema
+lookup are attached — which is why a tool cannot forget them), `respond_json`
+and `respond_error`, the projection and validation helpers (`check_fields`,
+`check_projection`, `check_asked`, `project_rows`), the bounded-log arithmetic
+(`bounded_log`, `sized_log`), and `check_dir!`, which is the refusal every
+`dir`-taking tool shares.
+
+# One declared shape per tool, looked up by name
+
+`OutputSchemas[name]` is a lookup, not a registry a tool writes into. An
+omission is therefore deliberate and visible: `read_concept` has no shape,
+because it answers markdown rather than a structured row, and that is the only
+one. `test/integration/output_schema_test.rb` walks the wire and checks the
+declared shape against the answer actually sent.
+
+# Resources own the URI grammar because the SDK cannot
+
+`Resources.parse` exists for one reason worth knowing before touching it: **OKF
+concept ids carry slashes** (`capabilities/graph-server.md`), and the SDK's
+resource-template matcher stops at `[^/]+`. So a templated match would truncate
+every nested id. This file parses the URI itself.
+
+`list`, `templates`, `read` and `complete` are the surface; `concept_ids` and
+`prefixed` back the completion. `test/integration/resources_test.rb` and
+`completions_test.rb` drive them.
+
+# The prompts are read at get-time
+
+`Server::PROMPTS` names two markdown files shipped in `lib/okf/mcp/prompts/`,
+and `Server.prompt_text` reads one when a host asks for it. Booting never pays
+for prompt bodies, and editing a prompt does not need a code change.

data/.okf/testing/adding-a-tool.md

@@ -0,0 +1,65 @@
+---
+type: Playbook
+title: Adding a tool, end to end
+description: The walk a fifteenth tool owes — the question to answer before writing it, where the code goes, the four files that gain a test, and the three pins that will refuse it if a step is skipped.
+tags: [testing, tools, playbook, contribution]
+generated:
+  by: human:maintainer
+  at: 2026-08-19T12:00:00Z
+resource: lib/okf/mcp/server.rb
+---
+
+# First, the question that usually ends it
+
+**Do the [fourteen](../capabilities/tools.md) already compose to this?**
+`dirs` + `index` + `search` answer most retrieval between them, and tool-list
+weight is a real cost on every host that connects. A tool that duplicates a
+composition is a permanent tax for a one-time convenience.
+
+Second question: **could the kernel answer it?** If it could, it should — see
+[kernel-first](../design/kernel-first.md). A kernel method serves the CLI, the
+graph server, the TUI and this shell; a tool here serves one.
+
+If both answers are no, the walk is below.
+
+# The walk
+
+1. **Write the failing test first**, in the folder that matches how the bundle
+   is named — `test/integration/by_dir/<tool>_test.rb` at minimum, and
+   `by_registry/` and `across_bundles/` if the tool takes a bundle ref or
+   several. Drive real JSON-RPC through `handle_json`. Run it: it must fail
+   because the tool does not exist, not because a fixture is missing.
+2. **Add the kernel call**, if the analysis is not already there. That is a
+   change to `okf`, with its own test, landing first.
+3. **Add the builder** — `<name>_tool(context)` in `lib/okf/mcp/server.rb`,
+   beside its neighbours, and list it in `tools_for`. Use `define_tool`, which
+   is what attaches `readOnlyHint`, the `title` and the output-schema lookup;
+   nothing else may construct a tool.
+4. **Declare the output shape** in `lib/okf/mcp/output_schemas.rb`, keyed by
+   the tool's name. Omit it only for a markdown answer, and expect to defend
+   the omission — `read_concept` is the only one today.
+5. **Carry `total`** if the answer is a list: how many rows matched *before*
+   any `limit`. No silent truncation, ever.
+6. **Reuse the `dir` vocabulary** from `lib/okf/mcp/filters.rb` if the tool
+   takes a `dir`, and `check_dir!` for the refusal. Do not write a third
+   opinion about what the root means — that bug has already happened once.
+7. **Update [the catalog](../capabilities/tools.md)** with the tool's row.
+8. **Run the suite.** The same test from step 1 passes, unedited.
+
+# The three pins that refuse a skipped step
+
+- `test/integration/capabilities_test.rb` reads the wire and fails a tool
+  missing `readOnlyHint` or `title`.
+- `test/integration/output_schema_test.rb` checks each declared shape against
+  the answer actually sent.
+- `test/unit/bundle_catalog_test.rb` fails when the catalog and `server.rb`
+  disagree about which tools exist — so step 7 is not optional, and forgetting
+  it is a red suite rather than a stale document.
+
+# Adding a file, not a tool
+
+A new file under `lib/` needs a line in whichever
+[structure](../structure/) concept owns its layer — or a concept of its own if
+it is a new layer. `bundle_catalog_test.rb` fails on an unowned file, which is
+the point: the Map used to live in `AGENTS.md` where nothing checked it, and it
+went stale silently.

data/.okf/testing/index.md

@@ -0,0 +1,9 @@
+# Testing
+
+How this gem is tested, and what a change owes before it lands. The root
+`AGENTS.md`'s rule applies here as written — a change starts with a failing
+test, red for the reason you predicted, then the code, then the same test green
+and unedited — and what follows is that rule's shape for this gem's surfaces.
+
+* [The layers](layers.md) - What each layer of the suite proves, and the claims it deliberately does not spend a process on.
+* [Adding a tool](adding-a-tool.md) - The walk a new tool owes: where the code goes, which files gain a test, and what the pins will refuse.

data/.okf/testing/layers.md

@@ -0,0 +1,56 @@
+---
+type: Constraint
+title: What each test layer proves
+description: Integration-first over real JSON-RPC frames, with process-spawning confined to the two files that prove the process — plus the wire-reading rules the SSE tests cannot be written without.
+tags: [testing, integration, http, sse]
+generated:
+  by: human:maintainer
+  at: 2026-08-19T12:00:00Z
+resource: test/integration
+---
+
+# The layers
+
+| layer | proves | files |
+| ----- | ------ | ----- |
+| tool integration | a tool's real answer, driven as JSON-RPC through `handle_json` | `test/integration/{by_dir,by_registry,across_bundles}/` |
+| protocol surface | capabilities, output schemas, resources, completions, prompts | `capabilities_test.rb`, `output_schema_test.rb`, `resources_test.rb`, `completions_test.rb`, `prompts_test.rb` |
+| the process | `okf mcp` spawned for real, WEBrick on a real socket | `cli_plugin_test.rb`, `http_test.rb`, `http_modern_test.rb`, `http_listen_test.rb` |
+| the argv shell | flags and exit codes, in-process, spawning nothing | `cli_test.rb` |
+| units | the pieces with contracts of their own | `test/unit/` |
+
+The three tool directories mirror the kernel's own — the three ways a bundle is
+named: by directory, through the registry, and several at once.
+
+# One claim, one place
+
+A claim about **argv** is proven once, cheaply, in `cli_test.rb`, which drives
+the shell in-process and deliberately spawns nothing. A claim about **the
+process** is proven once, in the spawning files. The split is deliberate: every
+spawn is seconds, and a suite that spawns for argv claims spends minutes
+proving something a method call already settled.
+
+The three HTTP files share one harness, `test/integration/http_harness.rb`, so
+they cannot drift in how they compose the bridge — the same reason
+[`App`](../structure/doors.md) is a single construction site in `lib/`.
+
+# Reading the wire, which is where SSE tests go wrong
+
+Two rules, both learned the hard way, and neither optional:
+
+**Use a raw `TCPSocket`, not `Net::HTTP`.** Net::HTTP holds a chunked body
+until EOF, so a stream that stays open — which is the whole point of
+`subscriptions/listen` — reads as a hang rather than as a passing test.
+
+**Thread `read_until`'s returned buffer back in.** One `readpartial` can carry
+the next frame along with the awaited one, so a sequential read that starts
+from an empty buffer drops a frame and then blocks waiting for it.
+
+# The bundle is pinned too
+
+`test/unit/bundle_catalog_test.rb` checks this bundle against the tree: every
+`.rb` under `lib/` named by exactly one concept in
+[`structure/`](../structure/), every path a concept names still present, and
+the [tool catalog](../capabilities/tools.md) agreeing with the tools
+`server.rb` defines. Structural documentation is code-derived, so it is pinned
+like code rather than trusted like prose.

data/CHANGELOG.md

@@ -5,7 +5,56 @@ 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.1] - 2026-08-20
+
+### Fixed
+
+- **The package metadata follows the `gems/` move and the repository rename.**
+  Two URLs on the package page were about to be wrong at once. `changelog_uri`
+  named `blob/main/okf-mcp/CHANGELOG.md`, a path that stopped existing when the
+  four gems moved under `gems/`; `homepage` named `serradura/okf-gem`, and the
+  repository is now **`serradura/okf`** — the name the command has had all
+  along. rubygems.org serves whatever the last release published, so neither
+  corrects itself: only a release republishes metadata, and this is that
+  release. Both land in one round rather than two, which is the whole reason
+  the rename waited for the paths to stop moving.
+
+  `homepage_uri`, `source_code_uri` and `changelog_uri` are all derived from
+  `homepage`, so one line moves four pieces of this gem's metadata. GitHub
+  redirects the old URLs permanently, so anything already published keeps
+  resolving.
+
+### Added
+
+- **The gem ships its own knowledge bundle.** `.okf/` is in `spec.files`, so an
+  installed okf-mcp carries a real bundle — its own — that a host can read
+  through the very tools it serves. It documents the gem's structure: every
+  file under `lib/` grouped by the layer that owns it, the catalog of the
+  fourteen tools, the four design rules, and how to add a tool or a test.
+  `AGENTS.md` now relies on it rather than restating it, and
+  `test/unit/bundle_catalog_test.rb` fails when the two disagree with the tree
+  — a file no concept names, a concept naming a file that is gone, or a tool
+  catalog out of step with `server.rb`.
+
+### Fixed
+
+- **`rake test` on the 2.7 floor.** The Rakefile set
+  `Bundler::GemHelper#tag_prefix=` unguarded, and that accessor arrived in
+  Bundler 2.2 — Ruby 2.7, this gem's floor, ships 2.1.4. Loading the Rakefile
+  there raised `NoMethodError` and took the whole task down before a single
+  test ran. CI never saw it, because `ruby/setup-ruby` installs the newest
+  Bundler each Ruby accepts; only a floor run against the stock image
+  surfaces it. okf-tui and okf-pro have carried the `respond_to?` guard since
+  they were cut, and this gem now does too — on a Bundler without the
+  accessor, `release` aborts rather than pushing a bare `vX.Y.Z` that would
+  trigger the okf image build.
+
+### Changed
+
+- **The okf floor moves to `>= 2.1.1, < 3`** — the kernel this shell develops
+  against released 2.1.1, and `test/unit/gemspec_test.rb` holds the floor to the
+  version the suite actually resolves against. It may lead the kernel; it may
+  never lag. The ceiling is unchanged.
 
 ## [1.2.0] - 2026-08-18
 
@@ -344,7 +393,8 @@ 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
+[1.2.1]: https://github.com/serradura/okf/compare/okf-mcp/v1.2.0...okf-mcp/v1.2.1
+[1.2.0]: https://github.com/serradura/okf/compare/okf-mcp/v1.1.0...okf-mcp/v1.2.0
+[1.1.0]: https://github.com/serradura/okf/compare/okf-mcp/v1.0.0...okf-mcp/v1.1.0
+[1.0.0]: https://github.com/serradura/okf/releases/tag/okf-mcp/v1.0.0
 [0.0.0]: https://rubygems.org/gems/okf-mcp/versions/0.0.0

data/README.md

@@ -206,6 +206,16 @@ bundle exec rake                   # tests + RuboCop — what CI runs
 bundle exec rake test:integration  # the critical layer alone + coverage/integration/
 ```
 
+The gem carries its own OKF bundle in `.okf/` — what each file under `lib/`
+does, the catalog of the fourteen tools, the design rules, and how to add a
+tool. It ships inside the gem, so it is there after `gem install` too, and the
+quickest way to read it is through this server:
+
+```bash
+okf mcp .okf        # serve okf-mcp's own knowledge, over MCP
+okf server .okf     # or read it as a graph
+```
+
 ## License
 
 Apache-2.0, see [LICENSE.txt](LICENSE.txt).

data/lib/okf/mcp/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: okf-mcp
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.2.1
 platform: ruby
 authors:
 - Rodrigo Serradura
@@ -29,7 +29,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: 2.1.1
     - - "<"
       - !ruby/object:Gem::Version
         version: '3'
@@ -39,7 +39,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: 2.1.1
     - - "<"
       - !ruby/object:Gem::Version
         version: '3'
@@ -56,6 +56,27 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".okf/capabilities/index.md"
+- ".okf/capabilities/resources-and-prompts.md"
+- ".okf/capabilities/tools.md"
+- ".okf/capabilities/transports.md"
+- ".okf/design/index.md"
+- ".okf/design/kernel-first.md"
+- ".okf/design/one-entry-point.md"
+- ".okf/design/ruby-floor.md"
+- ".okf/design/runtime-dependencies.md"
+- ".okf/design/the-tool-set.md"
+- ".okf/index.md"
+- ".okf/log.md"
+- ".okf/overview.md"
+- ".okf/structure/doors.md"
+- ".okf/structure/http-bridge.md"
+- ".okf/structure/index.md"
+- ".okf/structure/served-set.md"
+- ".okf/structure/server-definition.md"
+- ".okf/testing/adding-a-tool.md"
+- ".okf/testing/index.md"
+- ".okf/testing/layers.md"
 - CHANGELOG.md
 - LICENSE.txt
 - NOTICE
@@ -75,14 +96,14 @@ files:
 - lib/okf/mcp/server.rb
 - lib/okf/mcp/version.rb
 - lib/okf/plugin.rb
-homepage: https://github.com/serradura/okf-gem
+homepage: https://github.com/serradura/okf
 licenses:
 - Apache-2.0
 metadata:
   allowed_push_host: https://rubygems.org
-  homepage_uri: https://github.com/serradura/okf-gem
-  source_code_uri: https://github.com/serradura/okf-gem
-  changelog_uri: https://github.com/serradura/okf-gem/blob/main/okf-mcp/CHANGELOG.md
+  homepage_uri: https://github.com/serradura/okf
+  source_code_uri: https://github.com/serradura/okf
+  changelog_uri: https://github.com/serradura/okf/blob/main/gems/okf-mcp/CHANGELOG.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: