okf-mcp 0.0.0 → 1.0.0

data/lib/okf/mcp/filters.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module OKF
+  module MCP
+    # The `dir` vocabulary, in one place.
+    #
+    # It lived in two — one copy in the server, one in the memory backend, each
+    # commented "the CLI's one rule kept verbatim" — and they drifted: only one
+    # of them mapped `""` and `"/"` onto the root, so `catalog(dir: "/")`
+    # reported an empty bundle root while `search` and `dirs` answered for it.
+    # Two copies of a rule is two answers waiting to disagree, so there is one.
+    #
+    # There are genuinely **two** rules here, and the distinction is not drift:
+    #
+    #   #under_dir?  filters *concepts*. A dir names itself and everything
+    #                beneath it; `.` is a prefix of nothing, so the root
+    #                selects only what lives directly in it (the CLI's `--dir`).
+    #   #within?     scopes a *tree* of directory rows, where the root is the
+    #                ancestor of every row (`dirs`/`index` walking down).
+    module Filters
+      module_function
+
+      def fold(value)
+        value.to_s.downcase
+      end
+
+      # A `dir` argument as the tools compare it: case-folded, trailing slashes
+      # gone, and both spellings of the bundle root — "." and "/" — normalized
+      # to ".".
+      #
+      # A *blank* argument never reaches here as a filter. Every concept filter
+      # short-circuits on `OKF.blank?` first, because a client that fills each
+      # declared optional property with "" is doing something routine and means
+      # "no filter" by it — so "" and an omitted `dir` are the same ask, and
+      # neither is a synonym for the root. In the tree scoping the two coincide
+      # anyway: `.` is the ancestor of every row, so a blank normalizes to "."
+      # and selects the whole tree.
+      #
+      # Deliberately **not** the CLI's `fold_dir`, which also folds the literal
+      # name "root". Its whole rationale there is that a shell needs no quoting
+      # for it; a JSON argument has no such problem, and no `dir` description on
+      # this surface ever advertised the spelling. Importing it cost a bundle
+      # with a real `root/` directory the ability to name it — `dir: "root"`
+      # answered for the bundle root instead, and `scoped_rows` skips its
+      # existence check for the root, so not even the refusal fired.
+      def normalize_dir(value)
+        folded = fold(value).sub(%r{/+\z}, "")
+        folded.empty? || folded == "." ? "." : folded
+      end
+
+      # Concept filtering: `dir` names itself and everything beneath it.
+      def under_dir?(entry_dir, wanted)
+        entry = fold(entry_dir)
+        path = normalize_dir(wanted)
+        entry == path || entry.start_with?("#{path}/")
+      end
+
+      # Tree scoping: the root is the ancestor of every row, so `.` selects
+      # the whole tree rather than only what sits directly in it.
+      def within?(entry_dir, base)
+        return true if base == "."
+
+        entry = fold(entry_dir)
+        entry == base || entry.start_with?("#{base}/")
+      end
+
+      def dir_depth(dir)
+        dir == "." ? 0 : dir.split("/").length
+      end
+
+      # Is +wanted+ a directory this set actually has? Folded, and blind to a
+      # trailing slash, so it accepts the spelling the views print back.
+      def known_dir?(dirs, wanted)
+        base = normalize_dir(wanted)
+        return true if base == "."
+
+        dirs.any? { |dir| fold(dir) == base }
+      end
+    end
+  end
+end

data/lib/okf/mcp/http.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require "socket"
+require "stringio"
+require "webrick"
+
+require_relative "server"
+
+module OKF
+  module MCP
+    # Bridges the SDK's StreamableHTTPTransport — a plain Rack app — onto the
+    # WEBrick that okf already depends on, mirroring the kernel's
+    # server/runner pattern (rack and webrick both arrive via the okf gem).
+    # Stateless JSON mode: every POST is a self-contained JSON-RPC exchange
+    # answered with a single JSON object, so plain buffered responses hold —
+    # no SSE stream to keep open. The SDK validates Host/Origin against DNS
+    # rebinding for locally bound servers.
+    module HTTP
+      module_function
+
+      # The Hosts the SDK's StreamableHTTPTransport admits without any extra
+      # allowlist — its DNS-rebinding protection accepts these out of the box.
+      LOOPBACK_HOSTS = %w[127.0.0.1 ::1 localhost].freeze
+
+      # Binds that mean "every interface" rather than one address.
+      WILDCARD_BINDS = %w[0.0.0.0 :: *].freeze
+
+      # The largest request body the bridge will hand the transport, matching
+      # the SDK's own StreamableHTTPTransport default. Anything past it is 413
+      # before it is allocated (see #read_body).
+      MAX_REQUEST_BYTES = 4 * 1024 * 1024
+
+      # Everything before accepting — the bind (where EADDRINUSE, the boot
+      # failure that actually happens, raises), the traps and the boot line —
+      # split from #start so the CLI can run this under its *boot* rescue and
+      # file a bind failure as the usage error it is, while a mid-serve errno
+      # out of #start stays the crash it is.
+      def prepare(server, bind:, port:, allow_hosts: [], out: $stderr)
+        app = app_for(server, bind: bind, allowed_hosts: allowed_hosts_for(bind, extra: allow_hosts))
+        httpd = build(app, bind: bind, port: port)
+        %w[INT TERM].each { |signal| trap(signal) { httpd.shutdown } }
+        announce(httpd, bind: bind, out: out)
+        httpd
+      end
+
+      # The SDK transport wired to the server, in stateless JSON mode. A
+      # non-loopback bind (e.g. 0.0.0.0) is refused by the SDK's DNS-rebinding
+      # guard unless its Host is allowlisted; loopback binds keep the SDK
+      # defaults. Protection itself stays on either way.
+      def app_for(server, bind:, allowed_hosts: allowed_hosts_for(bind))
+        options = { stateless: true, enable_json_response: true, max_request_bytes: MAX_REQUEST_BYTES }
+        options[:allowed_hosts] = allowed_hosts if allowed_hosts && !allowed_hosts.empty?
+        app = ::MCP::Server::Transports::StreamableHTTPTransport.new(server, **options)
+        server.transport = app
+        app
+      end
+
+      # The Host allowlist a bind address needs: nil for loopback, which the
+      # SDK already admits.
+      #
+      # A **wildcard** bind is the case that was broken. `--bind 0.0.0.0` says
+      # "serve every interface", and allowlisting the literal string "0.0.0.0"
+      # allowlists a Host header no client ever sends: the server bound
+      # everything and answered every real request with 403. What a client
+      # actually sends is the address it dialled, so a wildcard expands to this
+      # machine's own addresses plus its hostname.
+      #
+      # +extra+ (the repeatable --allow-host) covers what cannot be derived: a
+      # DNS name or a reverse proxy's Host, which no local interface knows.
+      # The boot line, plus what a non-loopback bind actually means.
+      #
+      # The Host allowlist below is a defence against **DNS rebinding** — a
+      # browser walked into this port by a page the reader never meant to give
+      # it to. It is not access control and must never be sold as one: a client
+      # that is not a browser sets `Host` to whatever it likes, and there is no
+      # authentication behind it. So binding anywhere but loopback publishes
+      # every served bundle to anything that can reach the port, and the boot
+      # line says so rather than reading like a URL somebody can safely share.
+      #
+      # Loopback stays quiet: it is the default and the posture the tool was
+      # built for, and a warning printed every time is a warning nobody reads.
+      def announce(httpd, bind:, out:)
+        # The listener's own port, not the asked-for one: with --port 0 the OS
+        # picks, and a boot line reporting 0 would name a port nothing answers.
+        bound = httpd.listeners.first.addr[1]
+        say(out, "okf-mcp listening on http://#{bind}:#{bound}")
+        return if LOOPBACK_HOSTS.include?(bind.to_s)
+
+        say(out, "okf-mcp: WARNING — #{bind} is not loopback. Every served bundle is")
+        say(out, "  readable by anything that can reach this port, with no authentication. The Host")
+        say(out, "  allowlist only stops browser DNS rebinding; it is not access control.")
+      end
+
+      # The boot line is diagnostics, and diagnostics are best-effort: stderr
+      # belongs to whoever spawned the process, and a collector that died must
+      # not take a bound, healthy server down with it. An EPIPE here is lost
+      # output, not a lost server.
+      def say(out, line)
+        out.puts(line)
+      rescue Errno::EPIPE, Errno::ECONNRESET
+        nil
+      end
+
+      def allowed_hosts_for(bind, extra: [])
+        extra = Array(extra).reject { |host| OKF.blank?(host) }
+        return (extra.empty? ? nil : extra) if LOOPBACK_HOSTS.include?(bind)
+
+        hosts = WILDCARD_BINDS.include?(bind.to_s) ? local_hosts : [ bind ]
+        (hosts + extra).uniq
+      end
+
+      # Every address this machine answers on, plus its hostname. Loopback is
+      # left out only because the SDK admits it already.
+      def local_hosts
+        addresses = Socket.ip_address_list.reject(&:ipv4_loopback?).reject(&:ipv6_loopback?)
+        names = addresses.map(&:ip_address)
+        names << Socket.gethostname.to_s
+        names.reject { |name| OKF.blank?(name) }.uniq
+      rescue SocketError, SystemCallError
+        []
+      end
+
+      # Returns an unstarted server so tests can drive an ephemeral port.
+      def build(app, bind:, port:)
+        httpd = WEBrick::HTTPServer.new(
+          BindAddress: bind,
+          Port: port,
+          Logger: WEBrick::Log.new($stderr, WEBrick::Log::WARN),
+          AccessLog: []
+        )
+        httpd.mount_proc("/") { |request, response| handle(app, request, response) }
+        httpd
+      end
+
+      def handle(app, request, response)
+        # The MCP endpoint is the root and nothing else. The SDK transport
+        # routes on method alone, so handing it every path answered the OAuth
+        # discovery probes a connecting host sends first (GET /.well-known/*,
+        # POST /register — Claude Desktop does) 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 that reads as absence.
+        return not_found(response) unless request.path == "/"
+
+        # The cap is enforced *here*, before the body is materialized. The SDK
+        # transport has its own `max_request_bytes` and never reads more than
+        # that off `rack.input` — but WEBrick's `request.body` has no limit, so
+        # handing the transport a StringIO of it meant the allocation the cap
+        # exists to prevent had already happened. A few concurrent 2 GB POSTs
+        # would OOM the warm shared process that `--http` exists to provide.
+        body = read_body(request)
+        return oversized(response) if body.nil?
+
+        status, headers, out = app.call(env_for(request, body))
+        response.status = status
+        headers.each { |name, value| response[name] = value }
+        buffer = String.new
+        out.each { |chunk| buffer << chunk }
+        response.body = buffer
+      ensure
+        out.close if out.respond_to?(:close)
+      end
+
+      # The request body, or nil when it exceeds MAX_REQUEST_BYTES. A declared
+      # Content-Length past the cap is refused without reading a byte; an
+      # undeclared (chunked) body is streamed and abandoned the moment it grows
+      # past it.
+      def read_body(request)
+        # The raw header, not WEBrick's #content_length: that helper is
+        # `Integer(self["content-length"])`, which raises TypeError on a
+        # chunked request that legitimately carries no Content-Length at all.
+        declared = request["content-length"]
+        return nil if declared && declared.to_i > MAX_REQUEST_BYTES
+
+        # Always the block form: `request.body` with no block materializes the
+        # whole entity body, which for an undeclared (chunked) request is the
+        # very allocation this method exists to bound. With a block WEBrick
+        # streams, and a request carrying no body simply never yields.
+        buffer = String.new
+        request.body do |chunk|
+          buffer << chunk
+          return nil if buffer.bytesize > MAX_REQUEST_BYTES
+        end
+        buffer
+      end
+
+      def not_found(response)
+        response.status = 404
+        response["Content-Type"] = "application/json"
+        response.body = JSON.generate(error: "not found: the MCP endpoint is /")
+      end
+
+      def oversized(response)
+        response.status = 413
+        response["Content-Type"] = "application/json"
+        response.body = JSON.generate(
+          jsonrpc: "2.0", id: nil,
+          error: { code: -32_600, message: "Request body exceeds #{MAX_REQUEST_BYTES} bytes" }
+        )
+      end
+
+      def env_for(request, body = request.body.to_s)
+        env = {
+          "REQUEST_METHOD" => request.request_method,
+          "SCRIPT_NAME" => "",
+          "PATH_INFO" => request.path,
+          "QUERY_STRING" => request.query_string.to_s,
+          "SERVER_NAME" => request.host.to_s,
+          "SERVER_PORT" => request.port.to_s,
+          "rack.url_scheme" => "http",
+          "rack.input" => StringIO.new(body.to_s),
+          "rack.errors" => $stderr
+        }
+        request.each do |name, value|
+          key = name.upcase.tr("-", "_")
+          key = "HTTP_#{key}" unless %w[CONTENT_TYPE CONTENT_LENGTH].include?(key)
+          env[key] = value
+        end
+        env
+      end
+    end
+  end
+end

data/lib/okf/mcp/memory_backend.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+module OKF
+  module MCP
+    # The residency cache and the corpus holder — the long-lived holder's branch
+    # of the kernel's lifecycle asymmetry. One parsed bundle per registered
+    # root, re-read only when the on-disk fingerprint (the markdown file list
+    # plus the newest mtime) moves; bodies always come from this layer, live
+    # from disk and canonical, whichever engine answers search. There is
+    # deliberately no disk cache here — the process is the cache; disk-side
+    # state is okf-sqlite3's territory.
+    class MemoryBackend
+      FILTER_KEYS = %i[type tag dir status].freeze
+
+      # How many prepared corpora to hold at once, most-recently-used first.
+      # It used to be unbounded, keyed on the queried subset — a long-lived
+      # --http process answering `bundles: ["a","b"]`, then ["a","c"], then
+      # ["b","c","d"] retained a full index for each of up to 2^n subsets until
+      # the box swapped. Four covers the real pattern ("*" plus a couple of
+      # working sets) and bounds the worst case at four indexes.
+      MAX_CORPORA = 4
+
+      def initialize
+        @mutex = Mutex.new
+        @cache = {}
+        @corpus_mutex = Mutex.new
+        @corpora = {}
+      end
+
+      def capabilities
+        { name: "memory", ranked: false }
+      end
+
+      def refresh(root)
+        folder(root)
+        nil
+      end
+
+      # Engine doctrine, the CLI's exactly: the scan answers by default — no
+      # tokenizer recall holes, milliseconds over a resident bundle — and the
+      # index (BM25+, page parity) is opt-in by name or implied by fuzzy. The
+      # kernel routes and refuses incompatible asks (regexp needs the scan,
+      # fuzzy needs the index); those refusals surface as tool errors.
+      #
+      # Index queries go through a held corpus: one shared index over the whole
+      # served set, so federated BM25 scores are comparable by construction
+      # (Search.across's own argument). The corpus is built on the first index
+      # query, not at boot, and dropped when any member bundle's fingerprint
+      # moves — a held index outliving its set is a wrong answer, not a slow one.
+      def search_pairs(pairs, terms, fields: nil, regexp: false, fuzzy: false, engine: nil)
+        bundles = pairs.map { |slug, root| [ slug, folder(root).bundle ] }
+        options = { fields: fields, regexp: regexp, fuzzy: fuzzy, engine: engine }
+        if index_query?(engine, fuzzy: fuzzy)
+          Bundle::Search.with(corpus_for(pairs), terms, **options)
+        else
+          Bundle::Search.across(bundles, terms, **options)
+        end
+      end
+
+      def catalog(root, filters = {})
+        folder(root).catalog.select { |row| matches?(row, filters) }
+      end
+
+      # Drop every parsed bundle the caller no longer serves. The residency was
+      # bounded only by the served set being fixed at boot, and the registry
+      # re-read ended that: an operator repointing entries (a checkout per
+      # branch, rotating CI worktrees, remove-then-add) left every root the
+      # registry had *ever* named keyed here, each holding a parsed bundle with
+      # its id maps memoized, until the box swapped and every connected host
+      # dropped at once. The sibling corpus cache has been capped since it was
+      # written; this one lost its bound without gaining one.
+      #
+      # An LRU would be the obvious cap and the wrong one: the natural bound is
+      # the served set, and a cap below it would thrash — re-parsing on every
+      # call for any operator who registered more bundles than the number
+      # guessed.
+      #
+      # The corpus cache is pruned by the same rule, because it pins the same
+      # parsed bundles — plus a prepared index over each. Its LRU is not a
+      # substitute: eviction there happens only on an *index* query, which a
+      # scan-only workload never sends, so a corpus over a repointed root
+      # stayed resident indefinitely and the memory this prune claims to
+      # release was still held.
+      def retain(roots)
+        kept = {}
+        roots.each { |root| kept[root] = true }
+        @mutex.synchronize { @cache.delete_if { |root, _| !kept.key?(root) } }
+        @corpus_mutex.synchronize { @corpora.delete_if { |key, _| key.any? { |root| !kept.key?(root) } } }
+        nil
+      end
+
+      # One unit of work, for the fingerprint memo below. The freshness check
+      # belongs *between* requests: within one, a tool asks the engine for the
+      # catalog and then reads the unparseable count off the same folder, and
+      # each ask re-walked the whole tree — a glob plus a stat per markdown
+      # file, all of it inside the lock.
+      def during_request
+        previous = Thread.current.thread_variable_get(:okf_mcp_prints)
+        Thread.current.thread_variable_set(:okf_mcp_prints, {})
+        yield
+      ensure
+        Thread.current.thread_variable_set(:okf_mcp_prints, previous)
+      end
+
+      # The disk handle behind read_concept, index and dirs — those stay on the
+      # parsed bundle whichever engine answers search: bodies are read live from
+      # disk (canonical), and the directory index needs the authored index.md
+      # bodies no derived store carries.
+      def folder(root)
+        @mutex.synchronize do
+          entry = @cache[root]
+          print = print_for(root)
+          unless entry && entry[:fingerprint] == print
+            folder = Bundle::Folder.load(root)
+            # The threaded HTTP transport can hit these lazy memos from two
+            # threads at once; build them once here, under this lock.
+            folder.bundle.concept_by_id(nil)
+            folder.bundle.paths_by_id
+            folder.bundle.directories
+            entry = { folder: folder, fingerprint: print }
+            @cache[root] = entry
+          end
+          entry[:folder]
+        end
+      end
+
+      private
+
+      # The fingerprint, computed at most once per root per request. Outside a
+      # request (a library caller, a warm-up `refresh`) there is no memo and
+      # every call walks, which is the old behaviour and the safe default: a
+      # memo that outlived its request would be a stale answer, and staleness is
+      # the one thing this layer exists to prevent.
+      def print_for(root)
+        memo = Thread.current.thread_variable_get(:okf_mcp_prints)
+        return fingerprint(root) if memo.nil?
+
+        memo.key?(root) ? memo[root] : (memo[root] = fingerprint(root))
+      end
+
+      # Does this query need the prepared index? A named "index" engine, or
+      # fuzzy with no engine named (the kernel would route it to the index
+      # anyway). "scan" plus fuzzy deliberately skips the corpus so the kernel
+      # can refuse it with its own sentence.
+      def index_query?(engine, fuzzy:)
+        engine.to_s == "index" || (fuzzy && OKF.blank?(engine))
+      end
+
+      # One corpus per searched set, keyed by its roots and pinned to the exact
+      # folder objects it was built from. #folder returns a new object only
+      # when a fingerprint moved, so identity comparison is the staleness check.
+      #
+      # Both the key and the pinned folders are sorted, so `["a","b"]` and
+      # `["b","a"]` are the same entry rather than two that evict each other on
+      # every alternation. The cache is an LRU bounded at MAX_CORPORA: re-inserting
+      # on a hit moves the entry to the end, and the oldest is dropped past the cap.
+      def corpus_for(pairs)
+        sorted = pairs.sort_by { |slug, root| [ root, slug.to_s ] }
+        folders = sorted.map { |slug, root| [ slug, folder(root) ] }
+        key = sorted.map { |_, root| root }
+        @corpus_mutex.synchronize do
+          held = @corpora.delete(key)
+          held = nil unless held && held[:folders] == folders
+          held ||= { corpus: Bundle::Search.prepare(folders.map { |slug, f| [ slug, f.bundle ] }, engine: "index"), folders: folders }
+          @corpora[key] = held
+          @corpora.shift while @corpora.size > MAX_CORPORA
+          held[:corpus]
+        end
+      end
+
+      def matches?(row, filters)
+        FILTER_KEYS.all? do |key|
+          wanted = filters[key]
+          next true if OKF.blank?(wanted)
+
+          case key
+          when :tag then Array(row[:tags]).map { |tag| Filters.fold(tag) }.include?(Filters.fold(wanted))
+          when :dir then Filters.under_dir?(row[:dir], wanted)
+          else Filters.fold(row[key]) == Filters.fold(wanted)
+          end
+        end
+      end
+
+      # What the residency cache watches: every markdown file with its mtime
+      # **and its size**.
+      #
+      # The size is what makes a same-second edit visible. mtime alone has
+      # 1-second granularity on HFS+, NFS and Docker bind mounts, so a second
+      # save inside one tick left the file list and the newest mtime unmoved
+      # and the bundle was never re-read — against the server's own promise
+      # that results reflect the current files. A same-second edit that also
+      # preserves the byte count is still invisible; catching that needs a
+      # content hash on every call, which is the whole cost this cache exists
+      # to avoid.
+      #
+      # `stat` is rescued per path because the glob is a moment old by the time
+      # it is walked: a `git checkout` or `rm` mid-call would otherwise raise
+      # ENOENT and answer the tool with an errno instead of results. A file
+      # that vanished simply drops out — which changes the fingerprint, which
+      # is exactly the reload the disappearance should trigger.
+      def fingerprint(root)
+        Dir.glob(::File.join(root, "**", "*.md")).sort.map do |path|
+          stat = begin
+            ::File.stat(path)
+          rescue SystemCallError
+            next nil
+          end
+          [ path, stat.mtime.to_f, stat.size ]
+        end.compact
+      end
+    end
+  end
+end

data/lib/okf/mcp/output_schemas.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module OKF
+  module MCP
+    # The shape each tool answers with, declared so a host consumes a result
+    # instead of parsing a blob and guessing. Every tool emits both: the JSON
+    # text in `content` (what a pre-2025-06-18 client reads) and the same
+    # object in `structuredContent`.
+    #
+    # They live in one table rather than beside each tool because the useful
+    # question is comparative — *every* list view carries `total`, and reading
+    # them together is what keeps that true. `define_tool` looks the name up;
+    # a tool with no entry declares no schema, which is `read_concept`, whose
+    # answer is markdown and has no object shape to describe.
+    #
+    # Two rules hold them honest. `required` is the **intersection** across a
+    # tool's variants, never one variant's keys — `lint` answers two shapes and
+    # `graph` three, so only `bundle` (and `view`) survive. And the row arrays
+    # are typed as arrays of objects but their *items* are left open, because
+    # `fields` projects a row down to what the caller asked for; naming the row
+    # properties here would make a projection a schema violation.
+    #
+    # `test/integration/output_schema_test.rb` runs every variant with the
+    # SDK's result validation switched on, so drift fails there rather than in
+    # somebody's host.
+    module OutputSchemas
+      ROWS = { type: "array", items: { type: "object" } }.freeze
+      COUNT = { type: "integer" }.freeze
+      SLUG = { type: "string" }.freeze
+
+      # `unparseable` rides along on any bundle-scoped view whose reader hit a
+      # file it could not parse, so it is optional everywhere and required
+      # nowhere.
+      UNPARSEABLE = { type: "integer" }.freeze
+
+      SCHEMAS = {
+        "list_bundles" => {
+          properties: {
+            backend: { type: "object" },
+            registry_source: { type: %w[string null] },
+            default: SLUG,
+            groups: { type: "array" },
+            total: COUNT,
+            bundles: ROWS
+          },
+          required: %w[backend total bundles]
+        },
+        "dirs" => {
+          properties: { bundle: SLUG, total: COUNT, dirs: ROWS, unparseable: UNPARSEABLE },
+          required: %w[bundle total dirs]
+        },
+        "index" => {
+          properties: { bundle: SLUG, total: COUNT, dirs: ROWS, unparseable: UNPARSEABLE },
+          required: %w[bundle total dirs]
+        },
+        "search" => {
+          properties: {
+            query: { type: "array", items: { type: "string" } },
+            # Resolved, not echoed — `fuzzy` picks the index without being
+            # asked — so it is always present and belongs in `required`.
+            engine: { type: "string", enum: %w[scan index] },
+            bundles: ROWS,
+            total: COUNT,
+            results: ROWS,
+            unparseable: UNPARSEABLE
+          },
+          required: %w[query engine bundles total results]
+        },
+        "catalog" => {
+          properties: { bundle: SLUG, total: COUNT, concepts: ROWS, unparseable: UNPARSEABLE },
+          required: %w[bundle total concepts]
+        },
+        # `total` is entries across every log file and `files` how many files
+        # they came from — two different counts, both named, because one
+        # standing for the other is what let an unbounded 119 KB answer read
+        # as bounded.
+        "log" => {
+          properties: { bundle: SLUG, total: COUNT, files: COUNT, logs: ROWS },
+          required: %w[bundle total files logs]
+        },
+        "validate" => {
+          properties: {
+            bundle: SLUG,
+            conformant: { type: "boolean" },
+            errors: ROWS,
+            warnings: ROWS,
+            counts: { type: "object" }
+          },
+          required: %w[bundle conformant errors warnings counts]
+        },
+        # Two shapes: the findings report, and `group: "folder"`'s file
+        # listing. Only what both carry is required.
+        "lint" => {
+          properties: {
+            bundle: SLUG,
+            total: COUNT,
+            healthy: { type: "boolean" },
+            stats: { type: "object" },
+            findings: ROWS,
+            group: { type: "string" },
+            files: ROWS,
+            unparseable: UNPARSEABLE
+          },
+          required: %w[bundle total]
+        },
+        # Three shapes — minimal, hubs, traffic — sharing only their identity.
+        "graph" => {
+          properties: {
+            bundle: SLUG,
+            view: { type: "string" },
+            total_nodes: COUNT,
+            total_edges: COUNT,
+            nodes: ROWS,
+            edges: ROWS,
+            types: { type: "object" },
+            tags: { type: "object" },
+            total: COUNT,
+            hubs: ROWS,
+            cut: COUNT,
+            total_arcs: COUNT,
+            dirs: ROWS,
+            arcs: ROWS,
+            unparseable: UNPARSEABLE
+          },
+          required: %w[bundle view]
+        }
+      }.freeze
+
+      def self.[](name)
+        SCHEMAS[name.to_s]
+      end
+    end
+  end
+end

data/lib/okf/mcp/prompts/consume.md

@@ -0,0 +1,17 @@
+# Prompt: consume — use a bundle as context
+
+1. **Orient first.** `list_bundles` names every bundle this server holds and
+   the slug each answers to. `dirs` gives a bundle's shape; `index` with `dir`
+   opens the branch you want — its authored index body, rollups and concept
+   listing — and `log` gives recent history. Then follow links only into the
+   concepts the task needs, one `read_concept` at a time. For a *pointed
+   question* rather than broad context, switch to the okf-search prompt's
+   discipline: map → `search` → only the winning bodies. For a large bundle,
+   `graph` with view `"minimal"` gives the whole link structure at once, so
+   you can plan a traversal without reading a single body.
+2. Treat broken links as not-yet-written knowledge, not errors.
+3. **Surface what you learn.** This server never writes. If you learn
+   something durable while working — a fact the bundle lacks, a link it is
+   missing, a concept that no longer matches reality — say so instead of
+   letting it evaporate: recording it belongs to the bundle's maintainers
+   through the okf skill and CLI, and what keeps a bundle alive is being told.