okf-mcp 1.2.1 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 44ae2c50c714bc127ac861756a46e998d20f4310c77165ddcb616f7600c75517
4
- data.tar.gz: 9fec8976e46b7bbe983bd0261eba453a4b25c700dcde8085df36f7a0df3f924a
3
+ metadata.gz: 0352b152b315e30e0e1a9d44c73522fda54cd9471e7e270fe80ea6ed779b1130
4
+ data.tar.gz: f20df9a569978beef37ebd38365f743183db05ac2efdac8d0e09f7d2843e2088
5
5
  SHA512:
6
- metadata.gz: 7989702891ac272f637306102cadbd68f9e14f458b5cf81b373b681e3f9a8970fc248526f65038c449d498508820e143a2c9795b074ce456e3372882fd51889a
7
- data.tar.gz: 0a9f01ba82b4bf10592c23666051617f9be55f80848925cbd029a8ad7e42753d3f597491ea71e45f2a97c817c6d8acbf9203890d4b7afd28a17a6dd4c526207a
6
+ metadata.gz: 51ff63a34ff69291a9f13823570280e3322c7b93d79a978244e547b7b55061eb4687e961cfc6fb07160a54a5e7853e82d5bb802c333326711753b9c96368526c
7
+ data.tar.gz: 284db006105634dc0cc99f40620f0c8fe41d10e6bedc4e2b8c81d59ec2a9faef0141c0ac4938410a7fbc4fb85b6067e0768cfeb86f750294bb0e4d19c1e53145
@@ -4,8 +4,8 @@ title: Exactly two runtime dependencies
4
4
  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."
5
5
  tags: [dependencies, gemspec, constraint]
6
6
  generated:
7
- by: human:maintainer
8
- at: 2026-08-19T12:00:00Z
7
+ by: process:okf-maintain
8
+ at: 2026-11-20T22:05:23Z
9
9
  resource: okf-mcp.gemspec
10
10
  ---
11
11
 
@@ -28,11 +28,30 @@ kernel holds its own: argue it, do not add it for convenience — and
28
28
 
29
29
  One rule covers both, and it is the reason the pins are not round numbers.
30
30
 
31
- **`mcp` is pinned pessimistically (`~>`)**, and the suite fails the day the
32
- lockfile resolves past it. The listen and modern-path tests exercise the
33
- SEP-2575 wire, which 1.0 and 1.1 never served — against those versions the
34
- tests fail, so the floor cannot admit them. The floor is not a guess about
35
- compatibility; it is the oldest version the tests actually pass on.
31
+ **`mcp` is pinned pessimistically (`~>`)**, and the floor is not a guess about
32
+ compatibility. It is the oldest version of the supported SDK series the
33
+ suite proves. The supported series now starts at 1.11.0 and stops before 1.12.0.
34
+ Patch releases resolve normally; opening a new SDK minor takes a
35
+ compatibility run.
36
+ The session-dispatch regression exercises the SDK calling both request entry
37
+ points; the transport suites prove stdio and Streamable HTTP still answer.
38
+
39
+ `rake test:sdk_floor` is what makes that sentence true rather than hopeful. It
40
+ runs the whole suite against the oldest SDK the pin admits, and CI runs it on
41
+ the floor Ruby. Every other job resolves the *newest* admissible SDK, so without
42
+ that leg the ceiling was proven on seven Rubies and the floor on none — and the
43
+ floor is the half the gemspec promises an adopter.
44
+
45
+ The gemspec drill used to cover the gap differently, by refusing any floor older
46
+ than the SDK the suite had resolved. That forced the floor up to whatever
47
+ bundler fetched, which makes the claim true by never admitting anything but the
48
+ newest release: an upstream publication nobody here asked for narrowed what an
49
+ adopter may install. It fired twice that way, and on both occasions the suite
50
+ passed against the very floor it was raising away from. **A rule that is kept by
51
+ shrinking what it has to cover is not being kept.** The drill now asks whether
52
+ the requirement *admits* the version CI ran, because a requirement that excludes
53
+ it would mean every assertion above it proved a resolution the gem refuses to
54
+ install with.
36
55
 
37
56
  **The `okf` floor may lead the kernel checkout but never lag it.** It names the
38
57
  kernel version that ships what this shell rides — `Search.prepare/with/across`,
@@ -119,6 +119,24 @@ widen. A file that cannot be read or parsed keeps the last good set *without*
119
119
  latching its stamp, so a transient truncation is survived rather than made
120
120
  permanent until restart.
121
121
 
122
+ **The stamp watches every file the registry reads, not just its own.** okf's
123
+ registry can `link` another registry file, and that file's bundles resolve into
124
+ the served set — so a stamp over one path meant an `okf registry set` in the
125
+ linked file was never seen, and this server kept answering about the set it
126
+ booted with. That is the same silent wrong answer the rule above exists to
127
+ refuse, arriving through a second door. The link list comes from the kernel, so
128
+ adding or dropping a link moves the first path's stamp and the next pass watches
129
+ the new set; nothing has to be registered here.
130
+
131
+ The two kinds of file are watched under **different rules**, and the asymmetry is
132
+ the whole of it. This server's own registry going unreadable answers `nil`, which
133
+ holds the last good set — the paragraph above. A linked file is a pointer's
134
+ target, and okf already treats a missing one as *resolves to nothing, reported*;
135
+ following that here means a vanished target drops its bundles rather than
136
+ freezing them. Riding out an error and following a state change are different
137
+ jobs, and one stamp had to do both.
138
+ <!-- rule:okf-mcp-stamp-watches-links -->
139
+
122
140
  Four consequences of that rule had to be chased down after it landed. Two are
123
141
  the same mistake in different clothes — **something else was still a boot
124
142
  snapshot** — and two are what a *movable* served set costs a cache that was
data/.okf/log.md CHANGED
@@ -1,5 +1,55 @@
1
1
  # Update Log
2
2
 
3
+ ## 2026-11-20
4
+
5
+ * Support MCP 1.11 dispatch on stdio and Streamable HTTP. The
6
+ [server definition](structure/server-definition.md) forwards SDK arguments
7
+ unchanged, and the [runtime dependency](design/runtime-dependencies.md)
8
+ accepts 1.11.x and holds new minors for a compatibility run. The
9
+ [test layers](testing/layers.md) separate the SDK-session regression from
10
+ the transport checks.
11
+
12
+ ## 2026-09-02
13
+
14
+ * **The SDK floor is proven by a run instead of asserted by a ratchet** —
15
+ [runtime-dependencies](design/runtime-dependencies.md). The rule was already
16
+ written down correctly: the floor "is the oldest version the tests actually
17
+ pass on". Nothing ever ran them there. `gemspec_test` closed that gap by
18
+ refusing any floor older than the SDK bundler had just resolved, which is a
19
+ different rule and a weaker one — it made the claim true by never admitting
20
+ anything but the newest release, so an upstream publication narrowed what an
21
+ adopter may install. `rake test:sdk_floor` runs the suite against the oldest
22
+ admissible SDK and CI runs it on the floor Ruby, so the sentence in the
23
+ concept is now a thing that happens rather than a thing that is hoped.
24
+
25
+ * **The two floors are not the same claim, and looking alike is how they got
26
+ confused.** The kernel arrives from a checkout, so this code can start calling
27
+ a surface the day it is written and its floor must follow. The SDK arrives
28
+ from RubyGems, so nothing here calls an mcp surface it was not written
29
+ against. The kernel drill stays exactly as it was; only the SDK one changed.
30
+
31
+ ## 2026-08-21
32
+
33
+ * **The freshness stamp watches every file the registry reads** —
34
+ [the tool set](design/the-tool-set.md). okf's registry can now `link` another
35
+ registry file, and that file's bundles resolve into the served set; the stamp
36
+ still stat'd this server's own file alone, so an `okf registry set` over there
37
+ moved nothing it watched and a long-running server kept answering about the
38
+ set it booted with. That is the silent wrong answer the stamp exists to
39
+ prevent, arriving through a second door. The two kinds of file keep **different
40
+ rules**: this server's own registry going unreadable holds the last good set,
41
+ because a file caught mid-write must not empty what is being served, while a
42
+ linked target that vanishes drops its bundles — okf already reports a missing
43
+ one as resolving to nothing, and following that beats freezing it. Riding out
44
+ an error and following a state change are different jobs, and one stamp had to
45
+ do both.
46
+
47
+ * **`list_bundles` names the linked groups too.** They were resolvable as a
48
+ `bundle` argument and absent from the listing, because okf split them into a
49
+ second method — an agent could open `@brain` and never learn it existed. The
50
+ kernel folded them back into `groups_listing`, so this needed no change here
51
+ beyond the `link` key now on each row.
52
+
3
53
  ## 2026-08-19
4
54
  * **Addition**: **okf-mcp has a knowledge bundle, and `AGENTS.md` now relies on
5
55
  it** — [structure](structure/), [capabilities](capabilities/),
@@ -4,8 +4,8 @@ title: The server definition
4
4
  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.
5
5
  tags: [mcp, server, tools, schemas, resources]
6
6
  generated:
7
- by: human:maintainer
8
- at: 2026-08-19T12:00:00Z
7
+ by: process:okf-maintain
8
+ at: 2026-11-20T22:05:23Z
9
9
  resource: lib/okf/mcp/server.rb
10
10
  ---
11
11
 
@@ -29,7 +29,10 @@ registry and an engine. `Definition` subclasses the SDK's server and adds the
29
29
  per-request wrap: `#in_request` memoizes fingerprints and `#retain_served`
30
30
  prunes cache residency, so a frame's repeated reads cost one stat. `#handle`
31
31
  and `#handle_json` are what the tests drive — real JSON-RPC frames, no
32
- transport involved.
32
+ transport involved. Both entry points forward the SDK's dispatch arguments
33
+ unchanged, including the `auth_info` keyword the supported SDK passes.
34
+ [The test layers](../testing/layers.md) distinguish the dispatch regression
35
+ from the transport checks.
33
36
 
34
37
  **The fourteen builders**, one per tool: `tags_tool`, `types_tool`,
35
38
  `stats_tool`, `list_bundles_tool`, `dirs_tool`, `index_tool`, `search_tool`,
@@ -4,8 +4,8 @@ title: What each test layer proves
4
4
  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.
5
5
  tags: [testing, integration, http, sse]
6
6
  generated:
7
- by: human:maintainer
8
- at: 2026-08-19T12:00:00Z
7
+ by: process:okf-maintain
8
+ at: 2026-11-20T22:05:23Z
9
9
  resource: test/integration
10
10
  ---
11
11
 
@@ -19,6 +19,12 @@ resource: test/integration
19
19
  | the argv shell | flags and exit codes, in-process, spawning nothing | `cli_test.rb` |
20
20
  | units | the pieces with contracts of their own | `test/unit/` |
21
21
 
22
+ `test/unit/server_test.rb` drives both dispatch entry points through a real
23
+ SDK session, so dropping an SDK-supplied keyword fails without spawning a
24
+ process. `test/unit/gemspec_test.rb` checks the dependency bounds and the
25
+ resolved version, while [the SDK-floor task](../design/runtime-dependencies.md)
26
+ runs this same suite at the oldest admitted version.
27
+
22
28
  The three tool directories mirror the kernel's own — the three ways a bundle is
23
29
  named: by directory, through the registry, and several at once.
24
30
 
data/CHANGELOG.md CHANGED
@@ -5,6 +5,55 @@ All notable changes to this project are documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [1.4.0] - 2026-11-20
9
+
10
+ ### Fixed
11
+
12
+ - Preserve the SDK's request arguments through the server's cache wrapper. MCP
13
+ 1.11 passes an `auth_info` keyword during dispatch; the old wrapper rejected
14
+ it before either stdio or Streamable HTTP could answer.
15
+
16
+ ### Changed
17
+
18
+ - Require MCP 1.11.x. Patches can resolve normally; a new minor must be tested
19
+ before the requirement admits it.
20
+
21
+ ## [1.3.0] - 2026-08-22
22
+
23
+ ### Fixed
24
+
25
+ - **A long-running server now sees writes inside a *linked* registry.** okf gained
26
+ `okf registry link`, which folds another registry file's bundles into the served
27
+ set; the freshness stamp still watched only this server's own registry file, so
28
+ an `okf registry set` in the linked file never moved it and the server kept
29
+ answering about the set it booted with. The stamp now covers every file the
30
+ registry reads. The link list comes from the kernel, so adding or dropping a
31
+ link moves the first path's stamp and the next pass watches the new set.
32
+
33
+ The two kinds of file keep different rules. This server's own registry going
34
+ unreadable still answers `nil` and holds the last good set — a file caught
35
+ mid-write must not empty what is being served. A linked file is a pointer's
36
+ target, and okf already reports a missing one as resolving to nothing, so a
37
+ vanished target drops its bundles instead of freezing them.
38
+
39
+ ### Changed
40
+
41
+ - **The `mcp` floor moves to `~> 1.3`.** `Gemfile.lock` is not committed, so the
42
+ suite resolves the newest SDK the requirement admits and proves itself against
43
+ that one; the floor tracks what the suite proves, and 1.3.0 shipped. Nothing in
44
+ this gem changed for it — all 324 tests pass against 1.3.0 — but a floor that
45
+ admits an SDK the suite never ran against is the claim the floor test exists to
46
+ refuse.
47
+
48
+ - **The `okf` floor moves to 2.2.0**, the kernel that ships `registry link` and
49
+ `Registry#links_listing`. The stamp reads that method, and against 2.1.1 every
50
+ refresh would raise NoMethodError straight past the SystemCallError rescue.
51
+ `rake verify_okf_floor` gates `release` on exactly this and now passes.
52
+
53
+ - `list_bundles` groups now carry a `link` key — `null` for a group this registry
54
+ owns, the link's name for one that arrived through a link (okf ≥ 2.2). Linked
55
+ groups were already resolvable as a `bundle` argument and are now listed too.
56
+
8
57
  ## [1.2.1] - 2026-08-20
9
58
 
10
59
  ### Fixed
data/README.md CHANGED
@@ -77,8 +77,9 @@ bundles only when the registry itself is what is being served.
77
77
 
78
78
  With no arguments the registry *is* what is served, so it is followed rather
79
79
  than snapshotted: `okf registry set`, `rename` or `del` in another terminal
80
- shows up on the next tool call, without a restart. The file is re-read only
81
- when its fingerprint moves, so the cost is a `stat`. Bundle contents are never
80
+ shows up on the next tool call, without a restart. A write inside a registry the
81
+ first one *links* counts too. The files are re-read only when a fingerprint
82
+ moves, so the cost is a `stat` each. Bundle contents are never
82
83
  snapshotted either — bodies are read live, and a bundle is re-parsed whenever
83
84
  one of its files changes.
84
85
 
@@ -15,7 +15,7 @@ module OKF
15
15
  # names a registered bundle or group, whose slug is reserved before any
16
16
  # plain-dir basename is deduped — the server verb's rule). No argv means
17
17
  # the active kernel registry, resolved exactly as the CLI resolves it:
18
- # a project-local .okf-registry.json discovered from cwd, else
18
+ # a project-local .okf.json discovered from cwd, else
19
19
  # $OKF_HOME/registry.json, OKF_NO_DISCOVERY=1 forcing global.
20
20
  class Registry
21
21
  # One served bundle: the +slug+ tools name it by, its absolute +root+ on
@@ -297,10 +297,34 @@ module OKF
297
297
  # mtime *and* size, the pair the residency layer already uses: a second
298
298
  # write inside one filesystem timestamp tick moves the size when it does
299
299
  # not move the clock.
300
+ #
301
+ # Every file the registry reads, not just its own. A link puts bundles in a
302
+ # second file, and watching only the first meant a `registry set` over there
303
+ # was never seen: this server would keep answering about the set it booted
304
+ # with, which is the one failure a stamp exists to prevent. The link list
305
+ # itself comes from the kernel, so adding or dropping a link moves the first
306
+ # entry and the next pass watches the new set.
307
+ # The two files are watched under different rules, and the asymmetry is the
308
+ # point. This server's *own* registry going unreadable answers nil, which
309
+ # holds the last good set — a file caught mid-write must not empty what is
310
+ # being served. A *linked* file is only a pointer's target, and the kernel
311
+ # already treats a missing one as "resolves to nothing, reported", so its
312
+ # absence is a state change to follow rather than an error to ride out.
300
313
  def registry_stamp
301
314
  return nil if @kernel.nil?
302
315
 
303
- stat = ::File.stat(@kernel.path)
316
+ own = file_stamp(@kernel.path)
317
+ return nil if own.nil?
318
+
319
+ [ own ] + @kernel.links_listing.map { |row| file_stamp(row[:registry]) }
320
+ rescue OKF::Error, SystemCallError
321
+ nil
322
+ end
323
+
324
+ # nil for a file that is not there — a state in its own right for a link, so
325
+ # a target appearing or vanishing moves the stamp exactly as an edit does.
326
+ def file_stamp(path)
327
+ stat = ::File.stat(path)
304
328
  [ stat.mtime.to_f, stat.size ]
305
329
  rescue SystemCallError
306
330
  nil
@@ -159,11 +159,13 @@ module OKF
159
159
  # honest bound and the registry re-read made the set movable. Anything
160
160
  # the registry no longer names is dropped here, so a repointed entry
161
161
  # stops retaining the bundle its slug used to mean.
162
- def handle(request, session: nil)
162
+ # The SDK owns dispatch arguments, including auth_info from 1.11.
163
+ # Preserve them while wrapping the whole request.
164
+ def handle(...)
163
165
  in_request { super }
164
166
  end
165
167
 
166
- def handle_json(request, session: nil)
168
+ def handle_json(...)
167
169
  in_request { super }
168
170
  end
169
171
 
@@ -2,6 +2,6 @@
2
2
 
3
3
  module OKF
4
4
  module MCP
5
- VERSION = "1.2.1"
5
+ VERSION = "1.4.0"
6
6
  end
7
7
  end
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: okf-mcp
3
3
  version: !ruby/object:Gem::Version
4
- version: 1.2.1
4
+ version: 1.4.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Rodrigo Serradura
@@ -15,21 +15,21 @@ dependencies:
15
15
  requirements:
16
16
  - - "~>"
17
17
  - !ruby/object:Gem::Version
18
- version: '1.2'
18
+ version: 1.11.0
19
19
  type: :runtime
20
20
  prerelease: false
21
21
  version_requirements: !ruby/object:Gem::Requirement
22
22
  requirements:
23
23
  - - "~>"
24
24
  - !ruby/object:Gem::Version
25
- version: '1.2'
25
+ version: 1.11.0
26
26
  - !ruby/object:Gem::Dependency
27
27
  name: okf
28
28
  requirement: !ruby/object:Gem::Requirement
29
29
  requirements:
30
30
  - - ">="
31
31
  - !ruby/object:Gem::Version
32
- version: 2.1.1
32
+ version: 2.2.0
33
33
  - - "<"
34
34
  - !ruby/object:Gem::Version
35
35
  version: '3'
@@ -39,7 +39,7 @@ dependencies:
39
39
  requirements:
40
40
  - - ">="
41
41
  - !ruby/object:Gem::Version
42
- version: 2.1.1
42
+ version: 2.2.0
43
43
  - - "<"
44
44
  - !ruby/object:Gem::Version
45
45
  version: '3'
@@ -119,7 +119,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
119
119
  - !ruby/object:Gem::Version
120
120
  version: '0'
121
121
  requirements: []
122
- rubygems_version: 4.0.16
122
+ rubygems_version: 4.0.10
123
123
  specification_version: 4
124
124
  summary: 'A Model Context Protocol server for OKF: discover, orient in, search, and
125
125
  read knowledge bundles from any MCP-capable agent.'