@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.
- package/CHANGELOG.md +31 -0
- package/README.md +280 -9
- package/okf/okf-mcp/distribution/reference-bundle.md +10 -3
- package/okf/okf-mcp/index.md +2 -1
- package/okf/okf-mcp/interfaces/http-authoring-api.md +11 -2
- package/okf/okf-mcp/interfaces/mcp-http.md +64 -0
- package/okf/okf-mcp/interfaces/mcp-tools.md +25 -6
- package/okf/okf-mcp/overview/okf-mcp.md +16 -6
- package/okf/okf-mcp/policies/authoring-safety.md +19 -6
- package/okf/okf-mcp/runtime/indexer.md +14 -1
- package/okf/okf-mcp/runtime/mcp-server.md +16 -8
- package/okf/okf-mcp/specs/producer-api.md +16 -2
- package/package.json +1 -1
- package/server.json +38 -2
- package/src/authoring/candidates.js +43 -0
- package/src/authoring/git-publish.js +16 -9
- package/src/authoring/live.js +18 -50
- package/src/authoring/proposal-policy.js +23 -1
- package/src/authoring/receipts.js +44 -0
- package/src/cli/commands.js +448 -0
- package/src/cli/http-options.js +193 -0
- package/src/cli/options.js +554 -0
- package/src/cli/usage.js +96 -0
- package/src/cli.js +15 -962
- package/src/context/cli-options.js +3 -3
- package/src/error-details.js +53 -0
- package/src/mcp/auth.js +409 -0
- package/src/mcp/http.js +317 -0
- package/src/mcp/principal.js +59 -0
- package/src/mcp/registry.js +50 -22
- package/src/mcp/server.js +106 -11
- package/src/mcp/tools/catalog.js +5 -2
- package/src/mcp/tools/live-authoring.js +12 -12
- package/src/mcp/tools/migration.js +2 -2
- package/src/mcp/tools/proposals.js +32 -20
- package/src/producer-publisher.js +7 -1
- package/src/producers.js +56 -12
- package/src/project.js +69 -0
- package/src/search/embedding-cli.js +1 -1
- 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
|
|
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
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
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
|
|
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.
|
|
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:
|
|
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
|
|
package/okf/okf-mcp/index.md
CHANGED
|
@@ -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
|
|
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:
|
|
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
|
|
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:
|
|
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
|
|
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`
|
|
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)).
|