@mfdaves/okf-mcp 0.12.0-rc.1 → 0.13.0-rc.1

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.
Files changed (40) hide show
  1. package/CHANGELOG.md +31 -0
  2. package/README.md +280 -9
  3. package/okf/okf-mcp/distribution/reference-bundle.md +10 -3
  4. package/okf/okf-mcp/index.md +2 -1
  5. package/okf/okf-mcp/interfaces/http-authoring-api.md +11 -2
  6. package/okf/okf-mcp/interfaces/mcp-http.md +64 -0
  7. package/okf/okf-mcp/interfaces/mcp-tools.md +25 -6
  8. package/okf/okf-mcp/overview/okf-mcp.md +16 -6
  9. package/okf/okf-mcp/policies/authoring-safety.md +19 -6
  10. package/okf/okf-mcp/runtime/indexer.md +14 -1
  11. package/okf/okf-mcp/runtime/mcp-server.md +16 -8
  12. package/okf/okf-mcp/specs/producer-api.md +16 -2
  13. package/package.json +1 -1
  14. package/server.json +38 -2
  15. package/src/authoring/candidates.js +43 -0
  16. package/src/authoring/git-publish.js +16 -9
  17. package/src/authoring/live.js +18 -50
  18. package/src/authoring/proposal-policy.js +23 -1
  19. package/src/authoring/receipts.js +44 -0
  20. package/src/cli/commands.js +448 -0
  21. package/src/cli/http-options.js +193 -0
  22. package/src/cli/options.js +554 -0
  23. package/src/cli/usage.js +96 -0
  24. package/src/cli.js +15 -962
  25. package/src/context/cli-options.js +3 -3
  26. package/src/error-details.js +53 -0
  27. package/src/mcp/auth.js +409 -0
  28. package/src/mcp/http.js +317 -0
  29. package/src/mcp/principal.js +59 -0
  30. package/src/mcp/registry.js +50 -22
  31. package/src/mcp/server.js +106 -11
  32. package/src/mcp/tools/catalog.js +5 -2
  33. package/src/mcp/tools/live-authoring.js +12 -12
  34. package/src/mcp/tools/migration.js +2 -2
  35. package/src/mcp/tools/proposals.js +32 -20
  36. package/src/producer-publisher.js +7 -1
  37. package/src/producers.js +56 -12
  38. package/src/project.js +69 -0
  39. package/src/search/embedding-cli.js +1 -1
  40. package/src/tool-packs.js +346 -0
package/CHANGELOG.md CHANGED
@@ -2,6 +2,37 @@
2
2
 
3
3
  All notable changes to `@mfdaves/okf-mcp`. The format follows Keep a Changelog; versions follow SemVer. Until 1.0, minor versions may change defaults where this file says so.
4
4
 
5
+ ## 0.13.0-rc.1 — 2026-11-14
6
+
7
+ MCP over Streamable HTTP with a principal per request (WP6a in `docs/plan-1.0.md`, requirements I-2 and I-2a to I-2c). Stdio is unchanged: the six stdio MCP contract snapshots are byte-identical to 0.12.0-rc.1.
8
+
9
+ ### Added
10
+
11
+ - `okf mcp --http [--host 127.0.0.1] [--port 8766] [--public-url URL] [--allowed-host H]... [--allowed-origin O]...` serves the stdio tools, resources and schemas over Streamable HTTP through the SDK's `createMcpHandler`: protocol revision 2026-07-28 and, statelessly, 2025-era clients including the 2025-11-25 `initialize`. A small `node:http` bridge in `src/mcp/http.js` replaces an `@modelcontextprotocol/node` dependency. The endpoint answers its path with and without one trailing slash. `Host` is checked on every request and `Origin` on the MCP endpoint (403, without CORS headers); an accepted browser origin gets CORS on the endpoint and on the protected-resource metadata: an `OPTIONS` preflight is answered 204 before authentication, and every answer, 401 and 403 included, echoes the exact origin (`Vary: Origin`) and exposes `WWW-Authenticate` and `Mcp-Session-Id`. Bodies above 1 MiB get 413, and `GET /health` answers `{"status":"ok"}`, also beside a deeper endpoint path (`/okf/mcp` → `/okf/health`). Binding a non-loopback host without `--auth` is a usage error (exit 2).
12
+ - Principals: every call runs for `{ subject, actor, scopes, name?, email? }`. `okf.read` is required for any call; `okf.write` enables the live write tools and producer runs and, over HTTP, also `load_remote_bundle` (with `--allow-remote-tool`; it changes the index every principal reads) the stored-proposal reads `okf_list_proposals` / `okf_get_proposal` (their candidate Markdown is what the REST API guards with its write token) and `okf_list_producers` / `okf_preview_producer` (a preview runs the producer with the server's own source credentials); over stdio the flags alone still enable those. `list_bundles` shows absolute server paths only to principals with `okf.write`. A principal without `okf.write` sees no write tool in `tools/list`, and calling one fails as a disabled tool does. Over stdio the principal comes from the flags (`--actor`; `okf.write` only with `--write`). Without `--auth` an HTTP caller is anonymous and read-only.
13
+ - Writes made for a principal stamp its actor in `generated.by` and are judged by the write policy for that actor; with `--git-commit`, a principal's `name` and `email` become the commit author, each optional (a missing one falls back to the configured identity, which also stays the committer). Author data never fails or blocks a write: `<`, `>` and control characters are removed, a name made only of characters git refuses and an implausible email are dropped, and a dropped field falls back to the configured identity. `LiveAuthoringService.validateChanges/applyChanges` accept `context.actor` and `context.author`. Proposal tools act for the call's principal, so `proposedBy` names its actor (over stdio, `--actor` as before). Producer runs keep `process:<producer>`.
14
+ - `--auth tokens:<file>`: a YAML list of `{ sha256, subject, actor, scopes }`, tokens kept only as SHA-256 hashes.
15
+ - `--auth introspect:<url>` with `--authorization-server <issuer>`: RFC 7662 introspection with HTTP Basic client credentials from `OKF_INTROSPECTION_CLIENT_ID` / `OKF_INTROSPECTION_CLIENT_SECRET`. A token is accepted when `active` is true, `aud` equals `--public-url` (one trailing slash ignored on either side), `exp` is in the future and `scope` holds `okf.read`; the actor is `human:<username>` with every character outside `[A-Za-z0-9._@+-]` mapped to `-`, so a username can never take the `provider/model` form, and `name` and `email` are optional. Accepted answers are cached by token hash until the earlier of `exp` and 60 s, refused ones for 30 s, in bounded LRU caches; at most 8 introspections run at once, and a request beyond that gets 503. A request without credentials gets 401 with `WWW-Authenticate: Bearer realm, scope, resource_metadata` and no `error` attribute (RFC 6750 section 3.1); a presented token that is refused gets `error="invalid_token"`; the challenge's `scope` lists every scope the server offers, so an authorization server narrows it to the user's rights (an editor signing in with a standard MCP client obtains `okf.write`). A missing `okf.read` gets 403 `insufficient_scope`, an unreachable or failing authorization server 503 without detail. The server publishes RFC 9728 protected-resource metadata naming the issuer; okf-mcp never issues tokens. Token values never appear in responses, errors, logs or the MCP request context.
16
+ - `--refresh-interval <ms>` (default 2000): over HTTP, files changed outside okf-mcp are picked up before a tool call or resource read (never `initialize`, `ping` or `tools/list`) at most once per interval, inside the call queue in the calls' order, and a changed index is handed to live authoring. An unchanged check costs p50 33.7 ms / p95 37.1 ms at 5,000 concepts; `npm run bench:index` now reports it.
17
+ - Producer error codes reach the caller: a producer whose `generate()` throws an error carrying its own code (`^[a-z][a-z0-9_]{0,63}$`, for example `access_denied`) and an optional `details` object gets an invalid preview or run receipt with one producer-layer diagnostic holding the code and the bounded scalar details (identifier keys; finite numbers, booleans, null, single-line strings up to 200 characters that hold no secret the producer read). The error's message is never forwarded; an error without such a code is still `producer_execution_failed`.
18
+ - Tool packs, experimental and outside the 1.0 freeze (plan D1): npm packages listed by exact name in the trusted project config (`toolPacks: [{ package, config, timeoutMs? }]`) and loaded from the project's `node_modules` add read tools after the core tools. A package exports `okfToolPack = { apiVersion: "1", id, validateConfig, tools, serialize? }`, each tool `{ description, annotations, inputSchema, outputSchema?, scope, handler(args, ctx) }` with `ctx = { principal, subjectToken, config, getSecret, signal }`. A principal sees a pack tool with `okf.read` and the tool's scope (over stdio the operator holds every non-`okf.*` scope the packs declare), and a tool that sets `requiresSubjectToken: true` only when the request carries a subject token (HTTP with `--auth`; hidden and refused like a disabled tool over stdio and anonymous HTTP); arguments are validated like core tool arguments; `subjectToken` is the HTTP caller's verified bearer token and absent over stdio; `ctx.config` is the config `validateConfig` normalised; `getSecret` reads only environment variables named by `*Env` config keys; calls are bounded by `timeoutMs` (default 30 s) and the request's abort signal and run outside the call queue unless the pack sets `serialize: true`. Errors reach the caller as a bounded code and scalar details, never their message (`tool_pack_execution_failed` otherwise); a detail string longer than 500 characters is truncated to 500 ending in `…` (producer details keep the 200-character limit), so a pack can pass on a database's error message for a query. A failed pack call's text content is the fixed message followed by one JSON line with the same `code` and `details` as the structured content, for clients that read only text. Name collisions with core or other pack tools, a package not installed under the project, a refused configuration and inline secrets stop the server at startup. Principals now keep well-formed scopes outside `okf.*` (such as `odoo.read`), and a token file accepts them. Over HTTP the protected-resource metadata's `scopes_supported` and the `scope` of the `401` challenge list `okf.read`, `okf.write` and every scope the configured packs declare, each once in a stable order (the `403` insufficient-scope challenge still names `okf.read`); users who signed in before a pack was added must sign in again to obtain its scope.
19
+ - `server.json` describes a second package transport: Streamable HTTP at `http://127.0.0.1:8766/mcp`, started with `--http`.
20
+
21
+ ### Fixed
22
+
23
+ - A producer could not update its own reserved `index.md` once its content changed (for example when the source gained a module): the host requires generation provenance on every file it rewrites or removes, and a reserved index cannot carry `generated` frontmatter, so the run was refused with `producer_manifest_claims_unmanaged_file`. For a reserved `index.md` or `log.md` owned by the manifest, bytes that still match the manifest's digest are now the proof that it was not hand-edited; a hand-edited one is refused with `producer_owned_file_modified`, and every other file still needs generation provenance. Publication diagnostics now name the offending file in `details.path` (a bundle-relative path, never content).
24
+
25
+ ### Changed
26
+
27
+ - All MCP sessions built over one server state share one tool-call queue (`state.callQueue`) instead of one queue per `McpServer` instance; over stdio there is still one session per process.
28
+ - `src/cli.js` is split into `src/cli/{options,usage,commands,http-options}.js` with no behaviour change; it leaves the Q-1 size ratchet's grandfather list.
29
+
30
+ ### Known issues
31
+
32
+ - `--authoring` is refused with `--http`: which scope may create and accept proposals over HTTP is not decided, and under the stdio rule the proposal tools would be open to read-only principals.
33
+ - A revoked introspected token stays valid for up to 60 seconds (the answer cache).
34
+ - Refresh while serving detects changes by size and modification time, like the write path (W-6); an edit that keeps both is missed.
35
+
5
36
  ## 0.12.0-rc.1 — 2026-10-25
6
37
 
7
38
  Retrieval level-up (WP3c-2): an adaptive fusion weight, contextual embedding units and a confidence block with opt-in abstention, each measured against pre-registered targets on both fixtures and on a real 560-concept catalog (`test/fixtures/retrieval/reports/hybrid-0.12-2026-10-25.md`, `context-0.12-2026-10-25.md`). No default ranking changes: the fixed fusion weight 0.4 and concept units stay the defaults because the new options did not meet their conditions for becoming defaults.
package/README.md CHANGED
@@ -6,7 +6,7 @@ The part that is hard is writing to a catalog safely. A configured producer read
6
6
 
7
7
  Reading is the ordinary half. It consumes an OKF bundle directory of Markdown files with YAML frontmatter. An optional workspace mode can federate several bundles. Concepts are exposed through CLI commands and MCP resources and tools for validation, structured search, graph navigation, provenance inspection, and proposal-based authoring.
8
8
 
9
- The core intentionally has no database, embeddings, build step, or hosted-service dependency. It uses `js-yaml` for safe YAML, CommonMark for Markdown structure, MiniSearch for in-memory BM25+ text retrieval, and the official Model Context Protocol TypeScript SDK v2 for stdio MCP. Local root mode makes no network calls. Optional remote loading fetches public Markdown concepts and only their explicitly referenced inert assets from GitHub. Nothing in the v0.2 computation support executes code or attests a receipt.
9
+ The core intentionally has no database, embeddings, build step, or hosted-service dependency. It uses `js-yaml` for safe YAML, CommonMark for Markdown structure, MiniSearch for in-memory BM25+ text retrieval, and the official Model Context Protocol TypeScript SDK v2 for MCP over stdio and Streamable HTTP. Local root mode makes no network calls. Optional remote loading fetches public Markdown concepts and only their explicitly referenced inert assets from GitHub. Nothing in the v0.2 computation support executes code or attests a receipt.
10
10
 
11
11
  ## OKF v0.2 Support And Extensions
12
12
 
@@ -200,7 +200,7 @@ okf --project okf.project.yaml producer preview main-database
200
200
  okf --project okf.project.yaml producer run main-database --write --actor process:nightly-refresh
201
201
  ```
202
202
 
203
- `producer preview` exits `1` when the candidate is invalid; `producer run` exits `1` when nothing was published. Both print the same receipt the MCP tools return.
203
+ `producer preview` exits `1` when the candidate is invalid; `producer run` exits `1` when nothing was published. Both print the same receipt the MCP tools return. A producer that cannot generate may throw an error with its own `code` (lowercase, `^[a-z][a-z0-9_]{0,63}$`, for example `access_denied`) and a `details` object of scalar values; the receipt then carries one producer-layer diagnostic with that code and the bounded details (identifier keys, finite numbers, booleans, null, single-line strings up to 200 characters that hold no secret the producer read). The error's message is never reported. An error without such a code is reported as `producer_execution_failed`.
204
204
 
205
205
  For a configured project, MCP exposes:
206
206
 
@@ -213,7 +213,7 @@ Preview and run accept only the configured producer name plus optional receipt d
213
213
  Two rules keep a managed bundle stable across repeated runs:
214
214
 
215
215
  - A producer restamps `generated.at` on every run. The host compares each candidate against the published file ignoring that stamp, so a source that did not change reports `unchanged` and leaves the bytes, the timestamps, and the manifest untouched. Publication-diff counts therefore describe the source, not the run.
216
- - A manifest entry alone is not authority to destroy work. Any file the host would rewrite or remove must itself carry `generated` provenance, so a damaged, hand-merged, or forged manifest cannot make a producer delete hand-authored content.
216
+ - A manifest entry alone is not authority to destroy work. Any file the host would rewrite or remove must itself carry `generated` provenance, so a damaged, hand-merged, or forged manifest cannot make a producer delete hand-authored content. A reserved `index.md` or `log.md` cannot carry `generated` frontmatter, so for those the proof is that their bytes still match the manifest's digest; a hand-edited one stops the run with `producer_owned_file_modified`. A refusal names the file in its diagnostic's `details.path`.
217
217
 
218
218
  Directories emptied by a stale deletion are removed with their last managed file.
219
219
 
@@ -283,12 +283,280 @@ returned as MCP tool results with `isError: true`. Calls to tools that are not
283
283
  enabled are rejected by SDK dispatch. Unexpected implementation errors are
284
284
  masked instead of exposing internal details.
285
285
 
286
+ ## MCP over HTTP
287
+
288
+ From 0.13.0-rc.1 the `mcp` command can serve the same tools, resources and
289
+ schemas over Streamable HTTP instead of stdio:
290
+
291
+ ```bash
292
+ okf --root /path/to/okf mcp --http
293
+ # OKF MCP HTTP server listening on http://127.0.0.1:8766/mcp
294
+ ```
295
+
296
+ | Flag | Meaning |
297
+ | --- | --- |
298
+ | `--http` | Serve MCP over Streamable HTTP. |
299
+ | `--host <host>` | Address to bind (default `127.0.0.1`). A non-loopback address requires `--auth`. |
300
+ | `--port <port>` | Port (default `8766`; `0` picks a free one). |
301
+ | `--public-url <url>` | The URL clients use for the MCP endpoint. Its path is the endpoint path (default `/mcp`; served with and without one trailing slash), its host is accepted in `Host` headers, and with introspection it is the token audience and the advertised `resource`, as written. |
302
+ | `--allowed-host <host>` | Another accepted `Host` header (hostname; the port is ignored); repeatable. `localhost`, `127.0.0.1` and `[::1]` are always accepted. |
303
+ | `--allowed-origin <origin>` | Another accepted browser `Origin` (hostname or origin URL); repeatable. Requests without an `Origin` header are not affected. |
304
+ | `--auth tokens:<file>`, `--auth introspect:<url>` | Bearer authentication, see below. |
305
+ | `--authorization-server <issuer>` | With introspection, the issuer named in the protected-resource metadata. |
306
+ | `--refresh-interval <ms>` | Check the files for changes made outside okf-mcp before a tool call or resource read at most this often (default `2000`; `0` checks before every one). |
307
+
308
+ The server answers:
309
+
310
+ - the MCP endpoint, through the SDK's `createMcpHandler`: protocol revision
311
+ `2026-07-28`, and 2025-era clients (including the `2025-11-25` `initialize`
312
+ handshake) through its stateless fallback. No session is kept: `GET` and
313
+ `DELETE` on the endpoint answer `405` to 2025-era clients.
314
+ - `GET /health` with `{"status":"ok"}`, also beside the endpoint when its
315
+ path is deeper (`/okf/mcp` → `/okf/health`).
316
+ - with introspection, the RFC 9728 protected-resource metadata at
317
+ `/.well-known/oauth-protected-resource` plus the path of `--public-url`
318
+ (for example `/.well-known/oauth-protected-resource/mcp`) and at
319
+ `/.well-known/oauth-protected-resource`.
320
+
321
+ Every request is checked against the accepted `Host` names (`403`
322
+ otherwise); requests to the MCP endpoint are also checked against the accepted
323
+ origins (`403`, without CORS headers) and refused above 1 MiB (`413`). For an
324
+ accepted browser origin the endpoint answers CORS: an `OPTIONS` preflight gets
325
+ `204` without authentication, with `Access-Control-Allow-Origin` (the exact
326
+ origin, `Vary: Origin`), `Access-Control-Allow-Methods: GET, POST, DELETE,
327
+ OPTIONS` and `Access-Control-Allow-Headers: Authorization, Content-Type,
328
+ Mcp-Session-Id, MCP-Protocol-Version, Last-Event-ID`; every other answer,
329
+ `401` and `403` included, carries the same `Access-Control-Allow-Origin` and
330
+ `Access-Control-Expose-Headers: WWW-Authenticate, Mcp-Session-Id`. The
331
+ protected-resource metadata is answered the same way (its preflight allows
332
+ `GET, HEAD, OPTIONS`), so a browser client can discover the authorization
333
+ server. Each request builds its MCP
334
+ server over the one shared catalog state, and tool calls from all clients run
335
+ one at a time through one queue.
336
+
337
+ ### Principals and scopes
338
+
339
+ Every HTTP request runs for a principal: a subject, an actor, scopes, and
340
+ optionally a name and an email. `okf.read` is required for any call.
341
+ `okf.write` adds the live write tools (`okf_validate_changes`,
342
+ `okf_apply_changes`, when the server runs with `--write`), producer runs
343
+ (`okf_run_producer`) and, over HTTP, producer listing and previews
344
+ (`okf_list_producers`, `okf_preview_producer`, which run the producer with
345
+ the server's own source credentials), the stored proposals (`okf_list_proposals`,
346
+ `okf_get_proposal`, which can hold complete candidate Markdown) and, with
347
+ `--allow-remote-tool`, `load_remote_bundle`, which changes the index every
348
+ principal reads. Over stdio those flags alone enable them, as before. A principal without `okf.write` does not see those
349
+ tools in `tools/list`, and calling one fails as calling a disabled tool does.
350
+
351
+ Writes made for a principal stamp its actor in `generated.by` and are judged
352
+ by the write policy for that actor. With `--git-commit`, the principal's name
353
+ and email become the commit author; a missing one falls back to the
354
+ repository's configured Git identity, which also stays the committer. Author
355
+ data never fails or blocks a write: `<`, `>`, control characters and
356
+ surrounding whitespace are removed, a name made only of characters git
357
+ refuses (such as `'` or `"`) and an email that is not a plausible address are
358
+ dropped, and the dropped field falls back to the configured identity.
359
+ Producer runs keep
360
+ `process:<producer>`. `--write` still requires `--actor`, which names the
361
+ server process as over stdio; every authenticated HTTP principal writes as
362
+ its own actor.
363
+
364
+ Without `--auth`, every caller is an anonymous read-only principal. That mode
365
+ is allowed only on a loopback address, and `--write` is a usage error there.
366
+ `--authoring` is not available with `--http` in this release: which scope may
367
+ create and accept proposals over HTTP is not decided yet. Over stdio the
368
+ principal comes from the flags (`--actor`, and `okf.write` only with
369
+ `--write`), so stdio behaves as before.
370
+
371
+ ### Token file
372
+
373
+ `--auth tokens:<file>` reads a YAML list of tokens by their SHA-256 hash;
374
+ plaintext tokens are never stored:
375
+
376
+ ```yaml
377
+ tokens:
378
+ - sha256: 3f0c… # hex SHA-256 of the bearer token
379
+ subject: ci
380
+ actor: process:ci-nightly
381
+ scopes: [okf.read, okf.write]
382
+ ```
383
+
384
+ `printf %s "$TOKEN" | sha256sum` prints the hash. The file must be a regular
385
+ file of at most 1 MiB; scopes are `okf.read`, `okf.write` or well-formed
386
+ names outside `okf.*` (for tool packs), and unknown fields, other scopes, invalid actors and
387
+ repeated hashes are startup errors that name the entry and field, never a
388
+ value. Listed tokens do not expire; remove an entry and restart the server to
389
+ revoke it.
390
+
391
+ ### Token introspection
392
+
393
+ `--auth introspect:<url>` checks opaque bearer tokens against an external
394
+ OAuth 2.0 authorization server with RFC 7662 introspection. okf-mcp is only a
395
+ resource server: it never issues tokens, and clients obtain them from the
396
+ authorization server named in the protected-resource metadata.
397
+
398
+ ```bash
399
+ OKF_INTROSPECTION_CLIENT_ID=okf-mcp OKF_INTROSPECTION_CLIENT_SECRET=… \
400
+ okf --root /srv/okf --write --actor process:okf-mcp --git-commit mcp --http \
401
+ --public-url https://mcp.example.com/mcp \
402
+ --auth introspect:https://auth.example.com/oauth/introspect \
403
+ --authorization-server https://auth.example.com
404
+ ```
405
+
406
+ - okf-mcp posts `token=<access token>` as a form to the URL, with HTTP Basic
407
+ client credentials (form-urlencoded before base64, RFC 6749 section 2.3.1)
408
+ read from `OKF_INTROSPECTION_CLIENT_ID` and
409
+ `OKF_INTROSPECTION_CLIENT_SECRET` only. The URL must be `https`, or `http`
410
+ on a loopback host, without credentials, query or fragment; redirects are
411
+ not followed.
412
+ - A token is accepted when `active` is `true`, `aud` equals `--public-url`
413
+ (one trailing slash ignored on either side), `exp` is in the future and
414
+ `scope` holds `okf.read`. The principal's subject
415
+ is `sub`, its actor `human:<username>` (every character outside
416
+ `A-Z`, `a-z`, `0-9` and `._@+-` replaced by `-`, so a username can never
417
+ take the `provider/model` form), its scopes every well-formed entry of
418
+ `scope` (`okf.read` and `okf.write` gate the core tools, scopes outside
419
+ `okf.*` such as `odoo.read` gate [tool-pack](#tool-packs-experimental)
420
+ tools, other `okf.*` names are ignored), and its git author `name` and
421
+ `email`, each optional.
422
+ - A request without credentials gets `401` with
423
+ `WWW-Authenticate: Bearer realm="okf-mcp", scope="…", resource_metadata="…"`
424
+ and no `error` attribute (RFC 6750 section 3.1); a presented Bearer token
425
+ that is refused gets the same challenge with `error="invalid_token"`. The
426
+ `scope` lists every scope the server offers, the same list as
427
+ `scopes_supported`, so the authorization server narrows it to the user's
428
+ rights. A token without `okf.read` gets `403` with
429
+ `error="insufficient_scope", scope="okf.read"`. When the authorization server cannot be reached,
430
+ times out (5 s) or answers anything but `200` with JSON, the request gets
431
+ `503` with `{"error":"temporarily_unavailable"}` and no further detail.
432
+ - Answers are cached by the token's SHA-256 in two bounded caches: accepted
433
+ ones until the earlier of `exp` and 60 seconds (a revoked token keeps
434
+ working for up to a minute), refused ones for 30 seconds. At most 8
435
+ introspection requests run at once; a request that would need a ninth gets
436
+ `503` with `{"error":"temporarily_unavailable"}`.
437
+
438
+ Token values never appear in a response, an error or a log line, and the
439
+ caches keep only their hash; the verified token is handed on only to
440
+ [tool-pack](#tool-packs-experimental) handlers, as `ctx.subjectToken`.
441
+
442
+ ### Index freshness
443
+
444
+ Over HTTP the server re-reads files changed outside okf-mcp (for example by
445
+ `git pull` or an editor) before a tool call or a resource read, at most once
446
+ per `--refresh-interval`; `initialize`, `ping` and `tools/list` never trigger
447
+ it. The check runs in the call queue, in the same order as the calls. Changes are detected by file size and modification time,
448
+ as for writes. An unchanged check costs about 35 ms at 5,000 concepts.
449
+
450
+ ### Behind a reverse proxy
451
+
452
+ - Bind okf-mcp to a loopback address and let the proxy terminate TLS.
453
+ - Set `--public-url` to the external URL of the endpoint and forward that
454
+ path unchanged; forward the health path and
455
+ `/.well-known/oauth-protected-resource…` as well.
456
+ - Forward the `Host` header as the public host (accepted automatically), or
457
+ accept the host the proxy sends with `--allowed-host`.
458
+ - Forward the `Authorization` header unchanged.
459
+ - Responses can be Server-Sent Events streams: turn response buffering off
460
+ for the endpoint and allow long-lived responses.
461
+ - One process serves one root or one project; run one process per catalog.
462
+
463
+ ## Tool packs (experimental)
464
+
465
+ Experimental from 0.13.0-rc.1 and outside the 1.0 freeze: the interface may
466
+ change in any release.
467
+
468
+ A tool pack is an npm package that adds read tools to the MCP server, next to
469
+ the core tools. Like a producer, it is listed by exact package name in the
470
+ trusted project config and loaded only from the project's `node_modules`:
471
+
472
+ ```yaml
473
+ toolPacks:
474
+ - package: "@example/okf-data-pack"
475
+ timeoutMs: 30000 # optional, per call; default 30000, at most 300000
476
+ config:
477
+ url: https://data.example.com
478
+ clientIdEnv: DATA_CLIENT_ID
479
+ clientSecretEnv: DATA_CLIENT_SECRET
480
+ ```
481
+
482
+ The package exports:
483
+
484
+ ```js
485
+ exports.okfToolPack = {
486
+ apiVersion: "1",
487
+ id: "data", // ^[a-z][a-z0-9_]{2,63}$
488
+ validateConfig(config) { return { valid: true, config }; },
489
+ serialize: false, // optional, see below
490
+ tools: {
491
+ data_search: { // ^[a-z][a-z0-9_]{2,63}$
492
+ description: "…",
493
+ annotations: { readOnlyHint: true },
494
+ inputSchema: { type: "object", properties: { … }, additionalProperties: false },
495
+ outputSchema: { type: "object", … }, // optional
496
+ scope: "data.read",
497
+ async handler(args, ctx) { return { records: [] }; },
498
+ },
499
+ },
500
+ };
501
+ ```
502
+
503
+ - **Loading.** Packs load when the server starts with `--project`, in config
504
+ order. A package that is not installed under the project's `node_modules`,
505
+ a descriptor the host does not accept, a configuration `validateConfig`
506
+ refuses, an inline secret in the config (`password`, `secret`, `token`,
507
+ `apiKey`, `credential(s)`), or a tool name that repeats a core tool or
508
+ another pack's tool stops the server with an error naming the package and
509
+ tool. Descriptions and schemas come from the package, never from config.
510
+ - **Listing and access.** Pack tools are listed after the core tools, packs
511
+ in config order and each pack's tools in the order it declares them. A
512
+ principal sees a pack tool when it holds `okf.read` and the tool's `scope`;
513
+ calling a tool it does not see fails as calling a disabled tool does. Over
514
+ stdio the principal is the process's operator and holds every scope outside
515
+ `okf.*` that the configured packs declare (an `okf.write` scope still needs
516
+ `--write`). A tool that sets `requiresSubjectToken: true` (because it acts
517
+ for the caller elsewhere) is listed and callable only when the request
518
+ carries a subject token, that is over HTTP with `--auth`; over stdio and
519
+ anonymous HTTP it is hidden and refused like a disabled tool.
520
+ - **Calls.** Arguments are validated against `inputSchema` exactly like core
521
+ tool arguments. `ctx` holds `principal` (a frozen copy of subject, actor,
522
+ scopes, name and email), `subjectToken` (over HTTP the caller's verified
523
+ bearer token, absent over stdio), `config` (the normalised config
524
+ `validateConfig` returned, else the configured one; a fresh copy per call),
525
+ `getSecret(name)` (only for environment variables named by config keys
526
+ ending in `Env`) and `signal`, which aborts when `timeoutMs` passes or the
527
+ request is cancelled. A handler returns a JSON value (at most 1 MiB;
528
+ returned as structured content when the tool declares an `outputSchema`).
529
+ - **Errors.** A handler may throw an error with a snake_case `code` and a
530
+ `details` object; the caller receives
531
+ `{ "error": "Tool execution failed", "tool", "message", "code", "details" }`
532
+ with a fixed message, the code, and only bounded scalar details: at most
533
+ 16 entries under identifier keys, values null, booleans, finite numbers or
534
+ single-line strings, a string longer than 500 characters cut to 500 ending
535
+ in `…`, and no string holding the caller's token or a secret the pack read.
536
+ The text content repeats this for clients that read only text: the fixed
537
+ message, then one JSON line with `code` and `details`. The error's own
538
+ message is never forwarded. Any other failure is
539
+ `tool_pack_execution_failed`; the host's own codes are `tool_pack_timeout`,
540
+ `tool_pack_cancelled`, `tool_pack_result_too_large`,
541
+ `tool_pack_secret_not_allowed` and `tool_pack_secret_unavailable`.
542
+ - **Concurrency.** Pack tools are read tools and run outside the call queue
543
+ that serialises knowledge reads and writes, so a slow pack never blocks a
544
+ write. A pack that needs the queue sets `serialize: true`.
545
+ - **Scopes over HTTP.** The server advertises `okf.read`, `okf.write` and
546
+ every scope its packs declare, each once, in config and declaration order:
547
+ in the protected-resource metadata's `scopes_supported` and in the `scope`
548
+ of the `401` challenge, so a client signing in asks for all of them. An
549
+ authorization server puts into a token only the scopes asked for at sign-in,
550
+ so users who signed in before a pack was added must sign in again to obtain
551
+ its scope.
552
+
286
553
  ## MCP Registry Metadata
287
554
 
288
- `server.json` describes the npm package as the stdio server
289
- `io.github.mfdaves/okf-mcp`. Registry-aware clients should prompt for an
290
- absolute OKF root path, pass it through `--root`, and append the fixed `mcp`
291
- command.
555
+ `server.json` describes the npm package `io.github.mfdaves/okf-mcp` twice:
556
+ as a stdio server, and as a Streamable HTTP server at
557
+ `http://127.0.0.1:8766/mcp` started with the extra `--http` argument.
558
+ Registry-aware clients should prompt for an absolute OKF root path, pass it
559
+ through `--root`, and append the fixed `mcp` command.
292
560
 
293
561
  ## Concept Identity And Extensions
294
562
 
@@ -546,6 +814,8 @@ Safety rules:
546
814
 
547
815
  ## HTTP API
548
816
 
817
+ The REST authoring API below is separate from [MCP over HTTP](#mcp-over-http) (`mcp --http`).
818
+
549
819
  Start the HTTP server:
550
820
 
551
821
  ```bash
@@ -935,8 +1205,9 @@ Generated output is regular Markdown/YAML OKF and is validated by the same index
935
1205
 
936
1206
  ## Limitations
937
1207
 
938
- - MCP transport is stdio only. The separate HTTP authoring API is not MCP over HTTP.
1208
+ - MCP is served over stdio and, with `mcp --http`, over Streamable HTTP. The separate HTTP authoring API (`serve`) is not MCP over HTTP.
939
1209
  - MCP protocol compatibility follows the pinned official SDK v2 dependency.
940
- - There is no file watcher. Restart the server after external file changes. Concepts accepted through MCP authoring refresh the MCP server index immediately.
1210
+ - There is no file watcher. Over stdio, restart the server after external file changes; over HTTP, changes are picked up before a request at most once per `--refresh-interval`. Concepts accepted through MCP authoring refresh the MCP server index immediately.
1211
+ - With `mcp --http`, proposal authoring (`--authoring`) is not available, a revoked introspected token stays valid for up to 60 seconds, and one process still serves one root or project for every principal.
941
1212
  - The HTTP API is a lightweight built-in server, not a full hosted multi-tenant service.
942
1213
  - OKF v0.2 computation support is static inspection and preflight only; no computation or attester is executed.
@@ -3,7 +3,11 @@ id: okf://okf-mcp/distribution/reference-bundle
3
3
  type: OKF Distribution
4
4
  title: Published okf-mcp Reference Bundle
5
5
  description: Canonical public OKF bundle describing the okf-mcp product and its durable contracts.
6
- tags: [distribution, reference, remote-bundle, dogfooding]
6
+ tags:
7
+ - distribution
8
+ - reference
9
+ - remote-bundle
10
+ - dogfooding
7
11
  relations:
8
12
  - type: consumes
9
13
  target: okf://okf-mcp/specs/concept-format
@@ -23,6 +27,9 @@ relations:
23
27
  target: repo://.github/workflows/release.yml
24
28
  - type: configured_by
25
29
  target: repo://.agents/skills/okf-mcp-release/SKILL.md
30
+ generated:
31
+ by: anthropic/claude-code
32
+ at: 2026-11-14T17:33:39.682Z
26
33
  ---
27
34
 
28
35
  # Published okf-mcp Reference Bundle
@@ -35,9 +42,9 @@ The latest public bundle can be loaded from:
35
42
 
36
43
  Consumers that need reproducibility should replace `main` with a release tag. Remote loading indexes only the Markdown tree and does not execute repository code.
37
44
 
38
- The public npm package is `@mfdaves/okf-mcp`. Its allowlist includes `okf.project.yaml`, `server.json`, and the `okf` directory so installed artifacts carry the same reference bundle and MCP Registry metadata. The package declares the Registry name `io.github.mfdaves/okf-mcp`.
45
+ The public npm package is `@mfdaves/okf-mcp`. Its allowlist includes `okf.project.yaml`, `server.json`, and the `okf` directory so installed artifacts carry the same reference bundle and MCP Registry metadata. The package declares the Registry name `io.github.mfdaves/okf-mcp`, and `server.json` describes two transports of the same package: stdio, and Streamable HTTP at `http://127.0.0.1:8766/mcp` started with the extra `--http` argument.
39
46
 
40
- The package smoke gate verifies that package, lockfile, CLI, MCP server, and Registry versions and identities agree. It installs the generated tarball into a clean temporary project, executes both binaries, validates this bundle, and uses the official client SDK to exercise both modern `2026-07-28` and legacy `2025-11-25` stdio sessions through tool discovery, resource discovery, resource reads, and concept retrieval.
47
+ The package smoke gate verifies that package, lockfile, CLI, MCP server, and Registry versions and identities agree. It installs the generated tarball into a clean temporary project, executes both binaries, validates this bundle, and uses the official client SDK to exercise both modern `2026-07-28` and legacy `2025-11-25` stdio sessions through tool discovery, resource discovery, resource reads, and concept retrieval. It also serves the installed package over Streamable HTTP and lists tools and searches in both revisions.
41
48
 
42
49
  The repository release skill defines the package identity, capability matrix, protocol, schema enforcement, self-validation, tarball, clean-install, prerelease, and registry synchronization gates. The trusted-publishing workflow repeats those checks against an exact Git release tag before publishing. Release-candidate metadata is not published to the MCP Registry; stable Registry publication follows successful npm and `npx` verification.
43
50
 
@@ -13,11 +13,12 @@ This bundle is the canonical machine-readable reference for the `okf-mcp` runtim
13
13
  - [Attested Computation Support](specs/attested-computation.md)
14
14
  - [Pinned Git Sources](specs/git-sources.md)
15
15
  - [Producer API](specs/producer-api.md)
16
- - [MCP Stdio Server](runtime/mcp-server.md)
16
+ - [MCP Server](runtime/mcp-server.md)
17
17
  - [OKF Indexer](runtime/indexer.md)
18
18
  - [File Concept Store](runtime/file-concept-store.md)
19
19
  - [Producer Host](runtime/producer-host.md)
20
20
  - [MCP Tool Catalog](interfaces/mcp-tools.md)
21
+ - [MCP HTTP Transport](interfaces/mcp-http.md)
21
22
  - [HTTP Authoring API](interfaces/http-authoring-api.md)
22
23
  - [Concept Authoring](workflows/concept-authoring.md)
23
24
  - [Concept Update](workflows/concept-update.md)
@@ -3,7 +3,11 @@ id: okf://okf-mcp/interfaces/http-authoring-api
3
3
  type: OKF Interface
4
4
  title: HTTP Authoring API
5
5
  description: Optional local HTTP interface for validation and proposal-based concept authoring.
6
- tags: [http, api, authoring, interface]
6
+ tags:
7
+ - http
8
+ - api
9
+ - authoring
10
+ - interface
7
11
  relations:
8
12
  - type: depends_on
9
13
  target: okf://okf-mcp/workflows/concept-authoring
@@ -13,6 +17,11 @@ relations:
13
17
  target: repo://src/http-server.js
14
18
  - type: checked_by
15
19
  target: repo://test/okf-mcp.test.js
20
+ - type: related_to
21
+ target: okf://okf-mcp/interfaces/mcp-http
22
+ generated:
23
+ by: anthropic/claude-code
24
+ at: 2026-11-14T17:33:39.682Z
16
25
  ---
17
26
 
18
27
  # HTTP Authoring API
@@ -23,4 +32,4 @@ Proposal inspection and mutation endpoints require an exact bearer token supplie
23
32
 
24
33
  The API delegates all authoring behavior to the same service and file store used by MCP root and project modes. Proposal acceptance therefore uses the same validation, identity, revision, and path safeguards described by the [authoring safety policy](../policies/authoring-safety.md).
25
34
 
26
- The default listener is local. This API is not an MCP Streamable HTTP transport, authentication service, hosted multi-tenant control plane, or distributed storage layer. Public deployment requires additional transport, identity, TLS, persistence, and concurrency design.
35
+ The default listener is local. This API is not MCP over HTTP, which `mcp --http` serves (the [MCP HTTP transport](mcp-http.md)), nor an authentication service, hosted multi-tenant control plane, or distributed storage layer. Public deployment requires additional transport, identity, TLS, persistence, and concurrency design.
@@ -0,0 +1,64 @@
1
+ ---
2
+ type: OKF Interface
3
+ title: MCP HTTP Transport
4
+ description: Streamable HTTP serving of the MCP tools with per-request principals, bearer authentication, and index refresh while serving.
5
+ tags:
6
+ - mcp
7
+ - http
8
+ - streamable-http
9
+ - authentication
10
+ - interface
11
+ - cors
12
+ relations:
13
+ - type: depends_on
14
+ target: okf://okf-mcp/runtime/mcp-server
15
+ - type: related_to
16
+ target: okf://okf-mcp/interfaces/mcp-tools
17
+ - type: related_to
18
+ target: okf://okf-mcp/policies/authoring-safety
19
+ - type: configured_by
20
+ target: repo://src/mcp/http.js
21
+ - type: configured_by
22
+ target: repo://src/mcp/auth.js
23
+ - type: configured_by
24
+ target: repo://src/mcp/principal.js
25
+ - type: configured_by
26
+ target: repo://src/cli/http-options.js
27
+ - type: checked_by
28
+ target: repo://test/call-queue.test.js
29
+ - type: checked_by
30
+ target: repo://test/mcp-principal.test.js
31
+ - type: checked_by
32
+ target: repo://test/http-mcp-contract.test.js
33
+ - type: checked_by
34
+ target: repo://test/http-auth.test.js
35
+ - type: checked_by
36
+ target: repo://test/http-refresh.test.js
37
+ - type: checked_by
38
+ target: repo://test/http-remote-load.test.js
39
+ - type: configured_by
40
+ target: repo://src/tool-packs.js
41
+ - type: checked_by
42
+ target: repo://test/http-cors.test.js
43
+ - type: checked_by
44
+ target: repo://test/http-proposals.test.js
45
+ - type: checked_by
46
+ target: repo://test/tool-packs.test.js
47
+ generated:
48
+ by: anthropic/claude-code
49
+ at: 2026-11-14T18:17:23.039Z
50
+ ---
51
+
52
+ # MCP HTTP Transport
53
+
54
+ `okf mcp --http` serves the [MCP server](../runtime/mcp-server.md)'s resources, tools and schemas over Streamable HTTP instead of stdio. A small `node:http` bridge hands each request to the SDK's `createMcpHandler` as a web `Request`; the handler serves the `2026-07-28` revision and, through its stateless fallback, 2025-era clients including the `2025-11-25` `initialize` handshake. No session is kept, so `GET` and `DELETE` on the endpoint answer `405` to 2025-era clients.
55
+
56
+ The server binds `--host` (default `127.0.0.1`) and `--port` (default `8766`). `--public-url` names the URL clients use: its path is the endpoint path (default `/mcp`, answered with and without one trailing slash), its host is an accepted `Host`, and with introspection it is the token audience. Every request must carry an accepted `Host` (the localhost names, the public host, and `--allowed-host` values); requests to the endpoint must also come from an accepted browser `Origin` when they carry one (`--allowed-origin`), and are refused above 1 MiB with `413`. For an accepted browser origin the endpoint answers CORS: an `OPTIONS` preflight gets `204` before any authentication, and every answer, refusals included, echoes the exact origin (`Vary: Origin`) and exposes `WWW-Authenticate` and `Mcp-Session-Id`; a foreign origin gets `403` without CORS headers. `GET /health` answers `{"status":"ok"}`, also beside a deeper endpoint path (`/okf/mcp` gives `/okf/health`).
57
+
58
+ Each request builds an MCP server over the one shared catalog state for the request's principal, so tool calls from every client go through the state's single call queue. A principal carries a subject, an actor, scopes and optionally a name and an email. `okf.read` is required for any call; `okf.write` adds the live batch tools (with `--write`), producer runs, the stored-proposal reads `okf_list_proposals` and `okf_get_proposal` (whose candidate Markdown the REST API guards with its write token) and runtime remote loading (with `--allow-remote-tool`), which a principal without it neither sees nor can call; `list_bundles` shows absolute server paths only to it. Scopes outside `okf.*`, such as `odoo.read`, gate tool-pack tools. Writes stamp the principal's actor and are judged by the write policy for it; with `--git-commit` its name and email become the commit author, a missing one falling back to the configured identity, which stays the committer.
59
+
60
+ Without `--auth` every caller is anonymous and read-only, which is allowed only on a loopback address; `--write` then is a usage error, and `--authoring` is not available over HTTP. `--auth tokens:<file>` reads a YAML list of `{ sha256, subject, actor, scopes }`, so tokens are kept only as SHA-256 hashes. `--auth introspect:<url>` with `--authorization-server <issuer>` checks opaque bearer tokens by RFC 7662 introspection: it posts `token=<access token>` with HTTP Basic client credentials taken only from `OKF_INTROSPECTION_CLIENT_ID` and `OKF_INTROSPECTION_CLIENT_SECRET`, and accepts a token when `active` is true, `aud` equals the public URL (one trailing slash ignored on either side), `exp` is in the future and `scope` holds `okf.read`. The actor is `human:<username>` with every character outside `[A-Za-z0-9._@+-]` mapped to `-`, so it can never take the `provider/model` form. Accepted answers are cached by token hash until the earlier of `exp` and 60 seconds and refused ones for 30 seconds, in bounded LRU caches; at most 8 introspections run at once, and a request that would need a ninth gets `503`.
61
+
62
+ A refused or missing token gets `401` with a `WWW-Authenticate` challenge naming the RFC 9728 protected-resource metadata, which the server publishes with the configured issuer; a token without `okf.read` gets `403`; an authorization server that cannot answer gives `503` without detail. okf-mcp is only a resource server and never issues tokens. Token values never appear in responses, errors or logs, and the caches keep only their hash; the verified token is handed on only to tool-pack handlers, as `ctx.subjectToken`, so a pack can act for the caller on a data API of the authorization server.
63
+
64
+ Before a tool call or resource read (never `initialize`, `ping` or `tools/list`), at most once per `--refresh-interval` (default 2,000 ms), the server refreshes its index from disk inside the call queue, in the calls' order, so files changed outside okf-mcp are served without a restart. Behind a reverse proxy, okf-mcp binds a loopback address, the proxy terminates TLS, forwards the endpoint path, the health path and the metadata path unchanged with the `Authorization` header, sends an accepted `Host`, and does not buffer the Server-Sent Events responses. The [tool catalog](mcp-tools.md) and the [authoring safety policy](../policies/authoring-safety.md) apply unchanged.
@@ -3,7 +3,11 @@ id: okf://okf-mcp/interfaces/mcp-tools
3
3
  type: OKF Interface
4
4
  title: MCP Tool Catalog
5
5
  description: Agent-facing tool contract for discovery, graph navigation, validation, producer execution, remote loading, and authoring.
6
- tags: [mcp, tools, interface, agents]
6
+ tags:
7
+ - mcp
8
+ - tools
9
+ - interface
10
+ - agents
7
11
  relations:
8
12
  - type: depends_on
9
13
  target: okf://okf-mcp/runtime/mcp-server
@@ -27,6 +31,19 @@ relations:
27
31
  target: repo://test/live-agent-workflow.test.js
28
32
  - type: checked_by
29
33
  target: repo://test/producer.test.js
34
+ - type: related_to
35
+ target: okf://okf-mcp/interfaces/mcp-http
36
+ - type: checked_by
37
+ target: repo://test/mcp-principal.test.js
38
+ - type: checked_by
39
+ target: repo://test/http-remote-load.test.js
40
+ - type: configured_by
41
+ target: repo://src/tool-packs.js
42
+ - type: checked_by
43
+ target: repo://test/tool-packs.test.js
44
+ generated:
45
+ by: anthropic/claude-code
46
+ at: 2026-11-14T18:17:23.039Z
30
47
  ---
31
48
 
32
49
  # MCP Tool Catalog
@@ -43,18 +60,20 @@ Static computation tools inspect contracts, read indexed assets, prepare paramet
43
60
 
44
61
  `read_git_source` reads one pinned `sources[].git` entry from a checkout or bare repository explicitly mapped by the MCP host. It reads the Git object database rather than the working tree and never fetches. Oversized content errors include the observed size, active limit, maximum supported limit, and whether a bounded retry can succeed.
45
62
 
46
- An explicit local root or project workspace exposes candidate validation, path suggestion, and proposal inspection. Normal proposal mutations require `--authoring`; the coordinated computation proposal additionally requires `--allow-computation-authoring`. `--write --actor <actor>` exposes read-only `okf_validate_changes` plus destructive `okf_apply_changes`, both accepting the same structured create/update batch grammar without requiring agents to compose YAML. Runtime calls to `load_remote_bundle` require `--allow-remote-tool`.
63
+ An explicit local root or project workspace exposes candidate validation, path suggestion, and proposal inspection. Normal proposal mutations require `--authoring`; the coordinated computation proposal additionally requires `--allow-computation-authoring`. `--write --actor <actor>` exposes read-only `okf_validate_changes` plus destructive `okf_apply_changes`, both accepting the same structured create/update batch grammar without requiring agents to compose YAML. Runtime calls to `load_remote_bundle` require `--allow-remote-tool`. Over HTTP the calling principal also needs the `okf.write` scope for the live batch tools, `okf_run_producer` and `load_remote_bundle`; without it they are neither listed nor callable, exactly as when the flag is missing.
47
64
 
48
65
  A project with configured producers exposes `okf_list_producers` and `okf_preview_producer`. Listing is static and does not execute producer packages. Preview loads only the package allowlisted by the selected project entry, reads source metadata, and validates a complete candidate graph without changing destination files. `--write --actor <actor>` additionally exposes destructive `okf_run_producer`. Producer tool inputs select only a configured instance and receipt detail; clients cannot supply packages, connection values, SQL, bundle IDs, configuration, or output paths.
49
66
 
50
- Producer receipts report configured identity, bounded numeric source summaries, relative-path diffs, publication counts, and validation. They omit generated contents, configuration, secrets, connection details, and absolute paths. Run repeats generation and strict OKF v0.2 validation under the shared writer queue, publishes only manifest-owned files, validates persisted state, and refreshes the index.
67
+ Producer receipts report configured identity, bounded numeric source summaries, relative-path diffs, publication counts, and validation. They omit generated contents, configuration, secrets, connection details, and absolute paths. A producer that fails with its own bounded error code reports that code and its scalar details as one diagnostic; its error message is never forwarded. Run repeats generation and strict OKF v0.2 validation under the shared writer queue, publishes only manifest-owned files, validates persisted state, and refreshes the index.
51
68
 
52
- `okf_validate_changes` and `okf_apply_changes` plan 1–100 operations as one future graph, including cross-batch and loaded-remote references plus same-type/title conflicts. Validation returns a non-durable time-of-check receipt. Apply repeats planning under the process-local writer queue, stamps one server-owned `generated.at` with the configured `generated.by`, publishes the complete local batch, validates persisted state, and refreshes the index. Compact receipts are the default; `detail: "full"` retains the richer planning layout. Relation effects are structured, and generated provenance is separate from substantive changed fields.
69
+ `okf_validate_changes` and `okf_apply_changes` plan 1–100 operations as one future graph, including cross-batch and loaded-remote references plus same-type/title conflicts. Validation returns a non-durable time-of-check receipt. Apply repeats planning under the process-local writer queue, stamps one server-owned `generated.at` with the call's actor as `generated.by` (`--actor` over stdio, the principal's actor over HTTP), publishes the complete local batch, validates persisted state, and refreshes the index. Compact receipts are the default; `detail: "full"` retains the richer planning layout. Relation effects are structured, and generated provenance is separate from substantive changed fields.
53
70
 
54
71
  Optional `--git-commit` policy rejects filter declarations and hidden `assume-unchanged`/`skip-worktree` index flags, disables replace-object resolution, pins the checked-out symbolic branch, constructs an isolated index from validated bytes, and publishes its exact tree with a compare-and-swap ref update from a clean worktree. The shared index is not used to assemble the commit, so unrelated concurrently staged paths cannot enter it; only affected index paths are synchronized after publication. Determinate failures preserve matching valid working-tree files. Ambiguous outcomes, checkout changes, target replacements, and best-effort revision-checked rollback conflicts are reported explicitly; the tool never pushes.
55
72
 
56
- Every tool supplies a purpose-specific description, descriptions for all input parameters, and MCP annotations for read behavior, destructive behavior, idempotency, and external access. Tool discovery and direct invocation use the same capability checks, so a hidden tool also fails when called by name. Annotations remain hints to clients; server-side validation is authoritative.
73
+ Every tool supplies a purpose-specific description, descriptions for all input parameters, and MCP annotations for read behavior, destructive behavior, idempotency, and external access. Tool discovery and direct invocation use the same capability checks for the same principal, so a hidden tool also fails when called by name. Annotations remain hints to clients; server-side validation is authoritative.
57
74
 
58
75
  The official MCP SDK validates tool arguments against the advertised schema without coercion. Unknown or disabled tools are rejected by SDK dispatch. Argument-schema failures and expected validation, storage, network, read-only, and proposal-conflict failures from enabled tools are returned as tool results with `isError: true`. A validation operation that successfully reports invalid OKF remains a successful tool result.
59
76
 
60
- `search_concepts` and the optional text query on `list_concepts` require every case-insensitive query term, regardless of order. They rank title, type, tags, aliases, description, path, and body while keeping arbitrary frontmatter as an exact structured filter. Compact MCP results expose the URI plus bounded title, type, and description; `detail: "full"` returns navigation metadata, signals, ranking, and snippets. Queries are bounded to 512 characters and 16 terms; fuzzy, prefix, stemming, and stop-word expansion are not applied. Scores are relative retrieval scores rather than a stable public scale. Relation-type filtering selects concepts with an outgoing relation of the requested type.
77
+ `search_concepts` and the optional text query on `list_concepts` run in mode `auto` by default: concepts matching every term come first, and when fewer than `autoFill` (default 3) do, concepts matching some of the terms follow; `all` and `any` are explicit modes. Terms are stemmed in the catalog's languages (`auto` uses the Italian and English stemmers a bundle's documents call for; `languages` overrides it), diacritics are folded, stop words and single letters are dropped, and quoted or identifier-like terms are matched literally against ids, paths, aliases, titles and raw tokens. Queries are bounded to 512 characters and 16 terms after stop words. Each result carries `coverage` and `relevance`; the response reports the mode that ran, `queryTerms`, `droppedTerms`, `allTermsTotal`, `lowConfidence` and a `confidence` block, and with a configured embedder the ranking fuses lexical and semantic scores. Compact MCP results expose the URI plus bounded title, type, and description; `detail: "full"` returns navigation metadata, signals, ranking, and snippets. Scores are relative retrieval scores rather than a stable public scale. Relation-type filtering selects concepts with an outgoing relation of the requested type.
78
+
79
+ Configured tool packs, experimental and outside the 1.0 freeze, add read tools after the core tools: npm packages listed by exact name in the project's `toolPacks` and loaded from its `node_modules`. A principal sees a pack tool with `okf.read` and the tool's scope; its arguments are validated like core tool arguments, its errors reach the caller only as bounded codes and scalar details, and it runs outside the call queue unless the pack serializes. Over HTTP the caller's verified token reaches the pack's handler as its subject (the [MCP HTTP transport](mcp-http.md)).