@mfdaves/okf-mcp 0.3.3-rc.1 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/.agents/skills/okf-v02-migration/SKILL.md +37 -0
  2. package/.agents/skills/okf-v02-migration/agents/openai.yaml +6 -0
  3. package/.agents/skills/okf-v02-migration/references/field-mapping.md +26 -0
  4. package/README.md +192 -78
  5. package/okf/bundles/okf-mcp/distribution/reference-bundle.md +2 -2
  6. package/okf/bundles/okf-mcp/index.md +7 -0
  7. package/okf/bundles/okf-mcp/interfaces/http-authoring-api.md +2 -2
  8. package/okf/bundles/okf-mcp/interfaces/mcp-tools.md +8 -4
  9. package/okf/bundles/okf-mcp/overview/okf-mcp.md +2 -2
  10. package/okf/bundles/okf-mcp/policies/authoring-safety.md +5 -3
  11. package/okf/bundles/okf-mcp/runtime/file-concept-store.md +7 -5
  12. package/okf/bundles/okf-mcp/runtime/indexer.md +6 -4
  13. package/okf/bundles/okf-mcp/runtime/mcp-server.md +6 -6
  14. package/okf/bundles/okf-mcp/specs/attested-computation.md +24 -0
  15. package/okf/bundles/okf-mcp/specs/concept-format.md +5 -3
  16. package/okf/bundles/okf-mcp/specs/git-sources.md +23 -0
  17. package/okf/bundles/okf-mcp/workflows/v02-migration.md +24 -0
  18. package/package.json +9 -3
  19. package/server.json +5 -5
  20. package/src/assets.js +469 -0
  21. package/src/authoring.js +492 -20
  22. package/src/cli.js +467 -37
  23. package/src/computation.js +366 -0
  24. package/src/git-source.js +551 -0
  25. package/src/graph.js +71 -18
  26. package/src/http-server.js +8 -1
  27. package/src/index.js +5 -0
  28. package/src/indexer.js +428 -24
  29. package/src/markdown.js +129 -0
  30. package/src/mcp-server.js +447 -313
  31. package/src/migration.js +687 -0
  32. package/src/parser.js +135 -54
  33. package/src/plugins.js +30 -50
  34. package/src/project.js +74 -17
  35. package/src/remote.js +232 -17
  36. package/src/search.js +69 -6
  37. package/src/store.js +421 -25
  38. package/src/v02.js +545 -0
  39. package/src/validation.js +13 -2
  40. package/src/mcp-protocol.js +0 -283
@@ -0,0 +1,37 @@
1
+ ---
2
+ name: okf-v02-migration
3
+ description: Safely analyze and stage an existing Open Knowledge Format catalog migration to OKF v0.2. Use only when explicitly asked to check, preview, or propose a v0.1 or mixed catalog migration.
4
+ ---
5
+
6
+ # OKF v0.2 Migration
7
+
8
+ Use the package's deterministic migration checker and proposal tools. Never rewrite catalog files directly, invent provenance or verification claims, accept proposals automatically, or mutate a remote bundle.
9
+
10
+ ## Workflow
11
+
12
+ 1. Confirm the repository worktree state before creating proposals. Preserve unrelated changes and stop if migration targets overlap unreviewed edits.
13
+ 2. Run `okf --root <catalog> migrate check`. In an optional multi-root project, run `okf --project <config> migrate check <bundle>`. Record the classification, blockers, identity collisions, generated-file skips, referenced assets, and migration readiness.
14
+ 3. Resolve blockers before proposing anything:
15
+ - Ask the catalog owner for a truthful `generated.by` actor for every legacy `timestamp`; require an explicit confirmed mapping.
16
+ - Route generated files back to their generator instead of proposing direct edits.
17
+ - Resolve malformed citations, conformance errors, unsafe paths, and ID or alias collisions without guessing.
18
+ - Supply mappings as `{"<concept-uri-or-path>":{"by":"<actor>","confirmed":true}}`; `$default` may be used only after the owner confirms that one actor truthfully applies to every reported timestamp.
19
+ - Use `human:<id>`, `process:<id>`, or `<provider>/<model>` actor syntax. The checker rejects an omitted or non-boolean confirmation.
20
+ 4. Run `okf --root <catalog> migrate preview '<actor-mappings-json>'`, or supply the bundle id in multi-root project mode. Review every per-file change against [field-mapping.md](references/field-mapping.md).
21
+ 5. Present the preview and wait for explicit approval before calling `okf_propose_v02_migration`. That MCP tool requires a writable local root and `--authoring`; there is intentionally no CLI command that creates proposals.
22
+ 6. The proposal tool may create a migration manifest and individual child proposals only. Do not accept any child unless the user explicitly approves that proposal.
23
+ 7. Accept the reserved `index.md` version proposal only after every Stage-A concept proposal is accepted and the whole bundle validates.
24
+ 8. Run project validation again and report local evidence, retained legacy fields, remaining generator work, and any external or remote state not verified.
25
+
26
+ ## Safety Boundaries
27
+
28
+ - Native `generated` and `sources` always win over legacy fallbacks.
29
+ - Migration adds native v0.2 fields while retaining `timestamp` and `# Citations` for compatibility.
30
+ - Do not add `verified`, credibility signals, lifecycle fields, or freshness claims unless independently authorized and evidenced.
31
+ - Never execute a computation, executor, or attester as part of migration.
32
+ - Remote bundles are report-only. Make proposals in the source repository under separate authority.
33
+ - A checker result is analysis, not approval. Proposal creation is a write; proposal acceptance is a separate explicit write.
34
+
35
+ ## Completion
36
+
37
+ Report the checker classification, proposed child files, manifest ID, validation result, retained compatibility fields, and anything blocked on an owner mapping or external repository. Do not describe a migration as complete while the version-declaration proposal or validation remains pending.
@@ -0,0 +1,6 @@
1
+ interface:
2
+ display_name: "OKF v0.2 Migration"
3
+ short_description: "Safely stage catalog migrations to OKF v0.2"
4
+ default_prompt: "Use $okf-v02-migration to check and preview this catalog's staged OKF v0.2 migration."
5
+ policy:
6
+ allow_implicit_invocation: false
@@ -0,0 +1,26 @@
1
+ # OKF v0.2 Stage-A Field Mapping
2
+
3
+ | Legacy input | Native v0.2 addition | Preconditions | Retained by migration |
4
+ | --- | --- | --- | --- |
5
+ | `timestamp` | `generated.at` | Valid ISO datetime and a confirmed truthful `generated.by` actor mapping | Yes |
6
+ | `# Citations` list | `sources[]` with `resource` and an optional literal title | Every entry has a stable, unambiguous resource; native `sources` is absent | Yes |
7
+ | Undeclared root index | `okf_version: "0.2"` | All Stage-A child proposals accepted, no blockers, whole bundle validates | N/A |
8
+
9
+ Do not infer author, usage count, last modified time, usage windows, verification events, status, or `stale_after` from legacy prose. Native fields already present are authoritative and are never overwritten by the migration planner.
10
+
11
+ Generated concepts must be changed in their generator and regenerated. Remote concepts are reported but never proposed or written by this workflow.
12
+
13
+ ## Actor mapping JSON
14
+
15
+ Keys may be a canonical concept URI, compatibility path URI, bundle-relative path, or `$default`. Every value must contain an exact actor and explicit confirmation:
16
+
17
+ ```json
18
+ {
19
+ "okf://finance/metrics/revenue": {
20
+ "by": "process:nightly-import",
21
+ "confirmed": true
22
+ }
23
+ }
24
+ ```
25
+
26
+ Allowed actor forms are `human:<id>`, `process:<id>`, and `<provider>/<model>`. A plausible name is not evidence: never set `confirmed` until the catalog owner confirms the mapping is truthful.
package/README.md CHANGED
@@ -1,32 +1,64 @@
1
1
  # okf-mcp
2
2
 
3
- `okf-mcp` is a project-agnostic Open Knowledge Format CLI, graph index, generator runner, MCP stdio server, and optional HTTP authoring API.
3
+ `okf-mcp` is a local-first consumer, validator, graph index, CLI, and MCP server for [Open Knowledge Format v0.2](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md).
4
4
 
5
- It consumes one or more directories of Markdown files with YAML frontmatter, treats non-reserved Markdown files as OKF concepts, and exposes those concepts through CLI commands plus MCP resources and tools for structured search, validation, graph navigation, and proposal-based authoring.
5
+ 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.
6
6
 
7
- The core intentionally has no database, embeddings, build step, or hosted-service dependency. It uses `js-yaml` for standards-oriented YAML parsing. Local bundle mode makes no network calls. Optional remote bundles can fetch public Markdown concepts from GitHub when configured. Generator plugins and accepted authoring proposals are the write paths, and both write only under configured project directories.
7
+ The core intentionally has no database, embeddings, build step, or hosted-service dependency. It uses `js-yaml` for safe YAML, CommonMark for Markdown structure, 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.
8
+
9
+ ## OKF v0.2 Support And Extensions
10
+
11
+ OKF v0.2 intentionally specifies a portable file format, not a serving or query runtime. `okf-mcp` keeps that boundary explicit:
12
+
13
+ | Area | Official OKF v0.2 | okf-mcp behavior |
14
+ | --- | --- | --- |
15
+ | Bundle and identity | A directory tree of Markdown files; a Concept ID is its bundle-relative path without `.md` | `--root` maps directly to one bundle; `okf://` is an optional workspace locator, not the portable Concept ID |
16
+ | Concept metadata | Required `type`; recommended `title`, `description`, `resource`, and `tags`; unknown keys are allowed | Preserves extension fields and unknown types while reporting normative conformance separately from workspace policy |
17
+ | Provenance and lifecycle | `sources`, `usage_window`, `generated`, `verified`, `status`, and `stale_after` | Normalizes these fields for search, provenance traversal, trust tiers, and deterministic freshness checks |
18
+ | References | Markdown links and path-valued `resource`, `sources[].resource`, `computation`, `executor.resource`, and `attester.resource` fields | Builds graph edges and bounded inert asset snapshots without executing or implicitly fetching referenced code |
19
+ | Attested Computation | Defines contract fields and an informative consumer flow while deferring runtime wire protocols and attester packaging | Statically inspects contracts and digests, checks declared parameter and receipt field names, and never executes or claims attestation |
20
+ | v0.1 compatibility | Allows `timestamp` fallback when the whole `generated` mapping is absent and `# Citations` fallback when the `sources` key is absent | Consumes both forms and adds review-only migration checks and proposals |
21
+
22
+ The following are okf-mcp extensions rather than requirements of the format:
23
+
24
+ - CLI, MCP, and HTTP interfaces; in-memory search and graph views
25
+ - optional multi-bundle `okf.project.yaml` workspaces and typed `relations`
26
+ - compatibility `id`, `aliases`, and `okf://` locators
27
+ - proposal-backed authoring with explicit acceptance
28
+ - bounded GitHub remote loading and explicitly mapped pinned Git sources
29
+ - generator plugins and stricter opt-in project policies such as `strictLinks`
8
30
 
9
31
  ## Install And Run
10
32
 
11
- This checkout is the `0.3.3-rc.1` release candidate published under npm's
12
- `next` tag. Pin the exact version while testing it:
33
+ Node 22 or newer is required.
34
+
35
+ Install from the GitHub release:
36
+
37
+ ```bash
38
+ git clone --branch v0.5.0 https://github.com/mfdaves/okf-mcp.git
39
+ cd okf-mcp
40
+ npm ci
41
+ node bin/okf-mcp.js --root ./path/to/okf validate
42
+ ```
43
+
44
+ After version `0.5.0` is published on npm, pin it for reproducible use:
13
45
 
14
46
  ```bash
15
- npx -y @mfdaves/okf-mcp@0.3.3-rc.1 --version
16
- npx -y @mfdaves/okf-mcp@0.3.3-rc.1 --project ./okf.project.yaml validate
47
+ npx -y @mfdaves/okf-mcp@0.5.0 --version
48
+ npx -y @mfdaves/okf-mcp@0.5.0 --root ./path/to/okf validate
17
49
  ```
18
50
 
19
51
  For a persistent installation:
20
52
 
21
53
  ```bash
22
- npm install --global @mfdaves/okf-mcp@0.3.3-rc.1
54
+ npm install --global @mfdaves/okf-mcp@0.5.0
23
55
 
24
56
  okf --version
25
- okf --project ./okf.project.yaml validate
26
- okf-mcp --project ./okf.project.yaml mcp
57
+ okf --root ./path/to/okf validate
58
+ okf-mcp --root ./path/to/okf mcp
27
59
  ```
28
60
 
29
- To work from the source repository:
61
+ To work from the current source branch:
30
62
 
31
63
  ```bash
32
64
  git clone https://github.com/mfdaves/okf-mcp.git
@@ -36,46 +68,46 @@ npm test
36
68
  node bin/okf-mcp.js --version
37
69
  ```
38
70
 
39
- Node 22 or newer is required.
71
+ `--root` accepts one local OKF bundle directory and is the recommended okf-mcp interface for a single bundle. The portable identity of each concept is its extensionless path inside that root.
40
72
 
41
- `--bundle` accepts either a path or `id=path`. Multiple `--bundle` flags are allowed.
73
+ `--bundle` accepts either a path or `id=path`. Multiple flags remain supported for compatibility. `--project` and its `bundles:` list are an optional okf-mcp federation/authoring extension, not part of OKF v0.2.
42
74
 
43
- `--remote-bundle` accepts `id=https://github.com/<owner>/<repo>/tree/<ref>/<path>`. It fetches public Markdown files from that GitHub tree and indexes them as a read-only bundle.
75
+ `--remote-bundle` accepts `id=https://github.com/<owner>/<repo>/tree/<ref>/<path>`. It fetches public Markdown first, then only bundle-local files explicitly named by standard v0.2 resource fields. Remote content remains read-only and inert.
44
76
 
45
77
  `--inspect` prints a compact graph summary and exits. Without `--inspect` and without an explicit command, the process starts a stdio MCP server.
46
78
 
47
- The package exposes both `okf` and `okf-mcp` binaries when installed. If neither `--project` nor a bundle source is passed, the CLI discovers the nearest `okf.project.yaml` or `okf.project.json` from the current directory.
79
+ The package exposes both `okf` and `okf-mcp` binaries when installed. Without an explicit source, the CLI first discovers the nearest root `index.md` declaring `okf_version`; nearest-project discovery remains a compatibility fallback.
48
80
 
49
81
  CLI exit statuses are `0` for success, `1` for validation or operational failure, and `2` for invalid usage. Unknown options are rejected.
50
82
 
51
- ## Published OKF Reference
83
+ ## Included OKF Reference
52
84
 
53
- This repository publishes a self-describing OKF bundle for the product, its runtime boundaries, interfaces, authoring workflows, and safety policy. The canonical entry point is `okf://okf-mcp/overview/okf-mcp`.
85
+ This repository publishes a self-describing OKF bundle for the product, its runtime boundaries, interfaces, authoring workflows, and safety policy. Its portable entry Concept ID is `overview/okf-mcp`; `okf://okf-mcp/overview/okf-mcp` remains the workspace/MCP resource locator.
54
86
 
55
87
  Validate and query the bundled reference from a checkout or installed package:
56
88
 
57
89
  ```bash
58
- okf --project okf.project.yaml validate
59
- okf --project okf.project.yaml search "proposal"
60
- okf --project okf.project.yaml concept okf://okf-mcp/overview/okf-mcp
90
+ okf --root okf/bundles/okf-mcp validate
91
+ okf --root okf/bundles/okf-mcp search "proposal"
92
+ okf --root okf/bundles/okf-mcp concept overview/okf-mcp
61
93
  ```
62
94
 
63
- Load the latest published reference directly from GitHub:
95
+ Load the reference bundle directly from this release:
64
96
 
65
97
  ```bash
66
- okf --remote-bundle okf-mcp=https://github.com/mfdaves/okf-mcp/tree/main/okf/bundles/okf-mcp --inspect
98
+ okf --remote-bundle okf-mcp=https://github.com/mfdaves/okf-mcp/tree/v0.5.0/okf/bundles/okf-mcp --inspect
67
99
  ```
68
100
 
69
- For reproducible consumption, replace `main` with a release tag. The
70
- `@mfdaves/okf-mcp` npm package includes both `okf.project.yaml` and the
101
+ The `@mfdaves/okf-mcp` npm package includes both `okf.project.yaml` and the
71
102
  complete reference bundle.
72
103
 
73
- ## Project Config
104
+ ## Optional Multi-Bundle Project Config
74
105
 
75
- For project-agnostic use, create an `okf.project.yaml` at a repository root:
106
+ Use `okf.project.yaml` only when one process must federate multiple roots, configure generators, or enforce a project-wide relation vocabulary:
76
107
 
77
108
  ```yaml
78
109
  project: Example
110
+ strictLinks: false
79
111
  bundles:
80
112
  - id: app
81
113
  root: okf/bundles/app
@@ -118,9 +150,15 @@ Commands:
118
150
  - `validate`
119
151
  - `graph [json|dot|mermaid]`
120
152
  - `search <query>`
121
- - `concept <uri>`
122
- - `neighbors <uri>`
153
+ - `concept <concept-id-or-locator>`
154
+ - `neighbors <concept-id-or-locator>`
123
155
  - `paths <from> <to>`
156
+ - `provenance <uri>`
157
+ - `edge-kinds`
158
+ - `computation inspect|prepare|check-receipt`
159
+ - `asset <okf-asset-uri>`
160
+ - `source <concept-id-or-locator> <source-id>`
161
+ - `migrate check|preview`
124
162
  - `generate`
125
163
  - `serve`
126
164
 
@@ -129,10 +167,12 @@ Commands:
129
167
  - `--host <host>`: bind host, default `127.0.0.1`
130
168
  - `--port <port>`: bind port, default `8765`
131
169
  - `--write-token <token>`: bearer token for write endpoints; defaults to `OKF_WRITE_TOKEN`
132
- - `--proposal-root <path>`: proposal JSON directory; defaults to `.okf-proposals` under the project root
170
+ - `--proposal-root <path>`: proposal JSON directory; defaults to `.okf-proposals` under the selected local root or project
133
171
 
134
172
  ## MCP Client Config
135
173
 
174
+ The npm-based examples below apply after version `0.5.0` is published there. A source checkout can invoke its executable `bin/okf-mcp.js` with the same arguments.
175
+
136
176
  Example client configuration:
137
177
 
138
178
  ```json
@@ -142,9 +182,9 @@ Example client configuration:
142
182
  "command": "npx",
143
183
  "args": [
144
184
  "-y",
145
- "@mfdaves/okf-mcp@0.3.3-rc.1",
146
- "--bundle",
147
- "app=/absolute/path/to/repo/okf/bundles/app",
185
+ "@mfdaves/okf-mcp@0.5.0",
186
+ "--root",
187
+ "/absolute/path/to/okf",
148
188
  "mcp"
149
189
  ]
150
190
  }
@@ -161,7 +201,7 @@ Project config mode, with read-only project helpers but without proposal mutatio
161
201
  "command": "npx",
162
202
  "args": [
163
203
  "-y",
164
- "@mfdaves/okf-mcp@0.3.3-rc.1",
204
+ "@mfdaves/okf-mcp@0.5.0",
165
205
  "--project",
166
206
  "/absolute/path/to/repo/okf.project.yaml",
167
207
  "mcp"
@@ -173,41 +213,35 @@ Project config mode, with read-only project helpers but without proposal mutatio
173
213
 
174
214
  Add `--authoring` to enable proposal creation, acceptance, and rejection. Add `--allow-remote-tool` to let MCP clients load arbitrary supported public remote bundles at runtime. Configured remote bundles remain readable without that runtime-loading flag.
175
215
 
176
- The stdio server supports MCP protocol versions `2025-11-25`, `2025-06-18`,
177
- `2025-03-26`, and `2024-11-05`. It returns a requested supported version.
178
- For a well-formed unsupported version, it returns its preferred supported
179
- version, `2025-11-25`, so the client can continue or disconnect.
216
+ The stdio server uses `@modelcontextprotocol/server` v2. It serves the modern
217
+ `2026-07-28` MCP revision and the SDK's compatibility path for 2025-era
218
+ clients, including `2025-11-25`. The SDK owns protocol negotiation, framing,
219
+ resource dispatch, tool dispatch, and advertised-schema validation.
180
220
 
181
- The transport uses standard JSON-RPC error codes for malformed messages,
182
- invalid requests, unknown methods, invalid method parameters, missing
183
- resources, and internal failures. Notifications never receive responses.
184
221
  Expected failures from a known tool, such as a missing concept, a read-only
185
- bundle, a failed remote fetch, or a proposal conflict, are returned as MCP
186
- tool results with `isError: true`.
222
+ bundle, a failed remote fetch, invalid arguments, or a proposal conflict, are
223
+ returned as MCP tool results with `isError: true`. Calls to tools that are not
224
+ enabled are rejected by SDK dispatch. Unexpected implementation errors are
225
+ masked instead of exposing internal details.
187
226
 
188
227
  ## MCP Registry Metadata
189
228
 
190
229
  `server.json` describes the npm package as the stdio server
191
230
  `io.github.mfdaves/okf-mcp`. Registry-aware clients should prompt for an
192
- absolute `okf.project.yaml` path, pass it through `--project`, and append the
193
- fixed `mcp` command.
194
-
195
- The package, lockfile, CLI, MCP `serverInfo`, `package.json` `mcpName`, and
196
- both versions in `server.json` are kept synchronized by the package smoke
197
- gate. Release candidates remain available through npm's `next` tag; only a
198
- verified stable version is published to the official MCP Registry.
231
+ absolute OKF root path, pass it through `--root`, and append the fixed `mcp`
232
+ command.
199
233
 
200
- ## Concept Format
234
+ ## Concept Identity And Extensions
201
235
 
202
- The server exposes one resource per Markdown document:
236
+ Concept IDs are their bundle-relative Markdown paths with `.md` removed. This extensionless path is the portable OKF identity. okf-mcp also exposes a workspace-scoped compatibility locator:
203
237
 
204
238
  ```text
205
- okf://<bundle-id>/<relative-path>
239
+ okf://<bundle-id>/<extensionless-concept-id>
206
240
  ```
207
241
 
208
- Resources use `text/markdown`. Reserved `index.md` and `log.md` files are resources, but they are not concept documents.
242
+ The former `.md` URI and a valid custom `id` remain compatibility lookup aliases. A bare Concept ID resolves only when unique across loaded bundles; `okf://` remains deterministic for federated workspaces. Reserved `index.md` and `log.md` resources retain their filenames because they are not concepts.
209
243
 
210
- Concept files may use a path-derived URI or set a stable `id`:
244
+ The `id`, `aliases`, and typed `relations` fields below are `okf-mcp` extensions. The standard v0.2 identity remains path-derived:
211
245
 
212
246
  ```markdown
213
247
  ---
@@ -227,7 +261,31 @@ relations:
227
261
  # Order Status Route
228
262
  ```
229
263
 
230
- `okf://` relation targets must resolve to a known concept. Non-OKF targets such as `repo://` are treated as external opaque references.
264
+ New content should use normal relative or bundle-root Markdown paths for internal links and extension relation targets. Existing `okf://` targets remain supported; non-OKF schemes such as `repo://` remain opaque compatibility references.
265
+
266
+ ### Pinned Git Sources
267
+
268
+ Code knowledge may live outside the code repository without recording a machine-specific path. Point a standard `sources` entry at a `Git Repository` concept and add the okf-mcp `git` extension below:
269
+
270
+ ```yaml
271
+ sources:
272
+ - id: implementation
273
+ resource: /repositories/application.md
274
+ git:
275
+ revision: 0123456789abcdef0123456789abcdef01234567
276
+ path: src/application.js
277
+ lines: { from: 10, to: 30 }
278
+ ```
279
+
280
+ Map the repository concept only in the local process configuration:
281
+
282
+ ```bash
283
+ okf --root /path/to/catalog \
284
+ --repo repositories/application=/work/application \
285
+ source architecture/application implementation
286
+ ```
287
+
288
+ `read_git_source` and the `source` CLI command read the pinned blob from the mapped Git object database. They never read the dirty worktree or fetch. Missing mappings and unpinned revisions remain visible but unavailable. Repository mappings may point to normal checkouts, bare repositories, or mounted paths; credentials and local paths stay outside the OKF bundle.
231
289
 
232
290
  ## Tools
233
291
 
@@ -238,12 +296,22 @@ relations:
238
296
  - `list_types`
239
297
  - `list_tags`
240
298
  - `list_relation_types`
299
+ - `list_edge_kinds`
300
+ - `get_provenance`
301
+ - `inspect_attested_computation`
302
+ - `read_bundle_asset`
303
+ - `read_git_source`
304
+ - `prepare_attested_computation`
305
+ - `check_computation_receipt`
306
+ - `check_v02_migration`
241
307
  - `load_remote_bundle`
242
308
  - `list_remote_bundles`
243
309
  - `okf_validate_concept`
244
310
  - `okf_suggest_concept_path`
245
311
  - `okf_propose_concept`
246
312
  - `okf_propose_update`
313
+ - `okf_propose_attested_computation`
314
+ - `okf_propose_v02_migration`
247
315
  - `okf_list_proposals`
248
316
  - `okf_get_proposal`
249
317
  - `okf_accept_proposal`
@@ -268,14 +336,16 @@ disabled tool names remain protocol-level invalid-parameter errors.
268
336
 
269
337
  Tool discovery and direct invocation use the same capability checks:
270
338
 
271
- | Mode | Proposal mutations | Runtime remote load | Configured remote reads |
339
+ | Mode | Normal proposals | Computation proposal | Runtime remote load |
272
340
  | --- | --- | --- | --- |
273
- | default | disabled | disabled | enabled |
274
- | `--authoring` | enabled | disabled | enabled |
275
- | `--allow-remote-tool` | disabled | enabled | enabled |
276
- | both flags | enabled | enabled | enabled |
341
+ | default | disabled | disabled | disabled |
342
+ | `--authoring` | enabled | disabled | disabled |
343
+ | `--authoring --allow-computation-authoring` | enabled | enabled | disabled |
344
+ | `--allow-remote-tool` | disabled | disabled | enabled |
277
345
 
278
- Project mode may expose read-only concept validation, path suggestion, and proposal inspection helpers. The `okf_*` mutation tools are proposal-first and require both project mode and `--authoring`. Proposing a concept or update writes only a proposal record. Accepting a proposal writes the Markdown concept into the configured bundle root and rebuilds the complete index from configured local bundles, configured remote bundles, and runtime-loaded remote bundles.
346
+ An explicit local root or project workspace exposes concept validation, path suggestion, and proposal inspection helpers. The `okf_*` mutation tools are proposal-first and require `--authoring`. In normal single-root mode, callers omit `bundle`; it is required only to select among multiple project roots. Proposing a concept or update writes only a proposal record. Acceptance writes Markdown inside the selected local root and rebuilds the index; remote roots remain read only.
347
+
348
+ Generic concept tools cannot create or change an Attested Computation contract. `okf_propose_attested_computation` additionally requires `--allow-computation-authoring` and creates one coordinated review proposal for the concept plus an optional external computation file.
279
349
 
280
350
  ## Authoring Concepts
281
351
 
@@ -287,7 +357,6 @@ MCP proposal flow:
287
357
  {
288
358
  "name": "okf_propose_concept",
289
359
  "arguments": {
290
- "bundle": "app",
291
360
  "path": "tools/create-order.md",
292
361
  "frontmatter": {
293
362
  "type": "MCP Tool",
@@ -295,7 +364,7 @@ MCP proposal flow:
295
364
  "relations": [
296
365
  {
297
366
  "type": "related_to",
298
- "target": "okf://app/workflows/order-creation"
367
+ "target": "/workflows/order-creation.md"
299
368
  }
300
369
  ]
301
370
  },
@@ -342,7 +411,7 @@ Safety rules:
342
411
  Start the HTTP server:
343
412
 
344
413
  ```bash
345
- OKF_WRITE_TOKEN=change-me okf --project okf.project.yaml serve --host 127.0.0.1 --port 8765
414
+ OKF_WRITE_TOKEN=change-me okf --root /path/to/catalog serve --host 127.0.0.1 --port 8765
346
415
  ```
347
416
 
348
417
  Read/validation endpoints:
@@ -351,23 +420,23 @@ Read/validation endpoints:
351
420
  - `GET /v1/bundles`
352
421
  - `POST /v1/concepts/validate`
353
422
  - `POST /v1/concepts/suggest-path`
354
- - `GET /v1/proposals`
355
- - `GET /v1/proposals/:id`
356
423
 
357
- Mutation endpoints require `Authorization: Bearer <OKF_WRITE_TOKEN>`:
424
+ Proposal inspection and mutation endpoints require `Authorization: Bearer <OKF_WRITE_TOKEN>` because pending records can contain complete candidate Markdown and computation code:
358
425
 
426
+ - `GET /v1/proposals`
427
+ - `GET /v1/proposals/:id`
359
428
  - `POST /v1/proposals`
360
429
  - `POST /v1/proposals/update`
361
430
  - `POST /v1/proposals/:id/accept`
362
431
  - `POST /v1/proposals/:id/reject`
363
432
 
364
- The default file-backed proposal store writes proposal JSON under `.okf-proposals` in the project root. Accepted proposals write Markdown concepts into the configured bundle root.
433
+ The default file-backed proposal store writes proposal JSON under `.okf-proposals` in the selected root or project. Accepted proposals write Markdown concepts into the selected local root.
365
434
 
366
435
  `POST /v1/concepts/validate` and `POST /v1/concepts/suggest-path` do not persist anything. `POST /v1/proposals` persists only a proposal record. Only `POST /v1/proposals/:id/accept` writes a concept Markdown file.
367
436
 
368
437
  ## Remote Bundles
369
438
 
370
- Remote bundles let one project consume concepts published by another repository without cloning or vendoring them locally.
439
+ Remote bundles let one workspace consume concepts published by another repository without vendoring them. For a host-agnostic setup, clone or mount an OKF repository from any Git host and pass its directory through `--root`; transport and synchronization remain outside the OKF specification.
371
440
 
372
441
  Supported source:
373
442
 
@@ -375,8 +444,9 @@ Supported source:
375
444
 
376
445
  Remote loading:
377
446
 
378
- - indexes only `.md` files
379
- - ignores non-Markdown files
447
+ - inventories the tree, fetches selected `.md` documents first, then fetches only explicitly referenced bundle-local assets
448
+ - records resolved revision metadata, SHA256 digests, document/asset byte counts, and unresolved references
449
+ - inventories remote paths but never downloads the contents of unreferenced `.sql`, `.py`, or binary files
380
450
  - keeps each remote bundle under its configured bundle id
381
451
  - supports `include` and `exclude` filters
382
452
  - resolves Markdown links inside the remote bundle path
@@ -422,6 +492,12 @@ Use `list_remote_bundles` to inspect what was loaded.
422
492
  - `linkedFrom`
423
493
  - `relationType`
424
494
  - `orphanOnly`
495
+ - `statuses`
496
+ - `trustTiers`
497
+ - `freshness` and deterministic `asOf`
498
+ - `hasSources`
499
+ - `runtime` and `attestationReady`
500
+ - `generatedBy` and `verifiedBy`
425
501
  - `limit`
426
502
  - `offset`
427
503
 
@@ -444,9 +520,9 @@ Example:
444
520
 
445
521
  ## Graph Behavior
446
522
 
447
- Markdown links between OKF documents become `markdown_link` edges. Frontmatter `relations` become typed `relation` edges.
523
+ As an okf-mcp graph projection, Markdown links become `markdown_link` edges, extension `relations` become typed `relation` edges, and standard v0.2 path-valued fields become `resource`, `source`, `computation`, `executor`, and `attester` edges. Internal concept references resolve to canonical nodes; explicitly referenced non-Markdown files resolve to okf-mcp `okf-asset://` nodes; URLs and scope descriptors remain unfetched external or opaque leaves.
448
524
 
449
- Links to a nested bundle directory resolve to that directory's reserved
525
+ For navigation convenience, okf-mcp resolves links to a nested bundle directory to that directory's reserved
450
526
  `index.md` when there is no exact document target. This applies to local and
451
527
  remote bundles and to candidate validation during proposal authoring.
452
528
 
@@ -470,7 +546,7 @@ Graph tools return compact JSON:
470
546
  }
471
547
  ```
472
548
 
473
- Use `graph_summary` first for a compact overview, `get_neighbors` for local traversal, and `get_subgraph` for bounded expansion around seed concepts. `export_graph` supports `json`, `dot`, and `mermaid`. Pass `includeExternal: true` to graph tools when opaque external targets should appear as graph nodes.
549
+ Use `graph_summary` first for counts by lifecycle, trust, freshness, runtime, readiness, and edge kind. Graph tools accept `edgeKinds`; pass `includeExternal: true` or `includeAssets: true` when those leaf nodes are needed.
474
550
 
475
551
  Default relation types:
476
552
 
@@ -500,7 +576,7 @@ Bundle `include` and `exclude` filters use simple path patterns:
500
576
 
501
577
  `validate`, `validate_bundle`, and `validate_project` return separate `conformant` and `validForProject` fields plus structured diagnostics. `valid` remains a compatibility alias for `validForProject`.
502
578
 
503
- OKF conformance covers:
579
+ OKF conformance covers, when the corresponding files are present:
504
580
 
505
581
  - parseable YAML mapping frontmatter on non-reserved concept documents
506
582
  - a non-empty `type`
@@ -508,10 +584,12 @@ OKF conformance covers:
508
584
 
509
585
  Unknown frontmatter keys and unknown concept type values do not fail conformance. The YAML parser supports nested mappings, arrays, block scalars, and other structures accepted by its safe YAML core schema; duplicate keys and unsupported custom tags are rejected.
510
586
 
587
+ Missing `index.md` files and broken cross-links do not fail OKF conformance. `strictLinks` affects only okf-mcp workspace validity (`validForProject`), not the normative `conformant` result.
588
+
511
589
  Project validity additionally reports:
512
590
 
513
591
  - duplicate OKF URIs
514
- - broken internal Markdown links
592
+ - broken internal Markdown links as advisories by default; set project `strictLinks: true` or pass `--strict-links` to make them project-invalid
515
593
  - invalid relation types
516
594
  - missing relation targets
517
595
  - broken `okf://` relation targets
@@ -522,6 +600,41 @@ Project validity additionally reports:
522
600
 
523
601
  The server keeps serving valid concepts from partial bundles.
524
602
 
603
+ Optional v0.2 families are normalized into `signals`. Malformed provenance, generation, verification, lifecycle, freshness, or computation metadata produces an advisory and never creates a fourth trust tier. Verification fails closed to `unverified`; absent status defaults to `stable`; freshness is evaluated at an explicit `asOf` date when supplied. Authoring is stricter than consumption and rejects malformed known v0.2 fields.
604
+
605
+ ## Attested Computation
606
+
607
+ `inspect_attested_computation` reports the runtime, declared parameters, sanctioned inline or file computation digest, executor receipt fields, attester reference, indexed assets, readiness, and diagnostics. `prepare_attested_computation` checks declared parameter names and returns digests without returning values. `check_computation_receipt` checks field presence without returning values, persisting the receipt, or claiming attestation.
608
+
609
+ okf-mcp has no execution or attestation adapter. It never runs the computation, executor resource, or attester resource, and it never fetches an external contract URI on demand.
610
+
611
+ CLI parity is available through `computation inspect|prepare|check-receipt`, `provenance`, `edge-kinds`, and `asset`. Supply sensitive values with `--parameters-file <path|->` or `--receipt-file <path|->`; raw parameter and receipt JSON is intentionally rejected in process arguments. `-` reads one JSON object from stdin. Asset reads accept `--max-content-bytes` up to the indexed 1 MiB limit.
612
+
613
+ ## Migrating Existing Catalogs To v0.2
614
+
615
+ The v0.2 specification keeps v0.1 bundles consumable through two fallbacks: legacy `timestamp` when `generated` is absent, and a legacy body `# Citations` list when `sources` is absent. okf-mcp applies those fallbacks during reads and offers an optional review-only conversion workflow.
616
+
617
+ For one root, inspect migration readiness and preview the proposed native fields without writing anything:
618
+
619
+ ```bash
620
+ okf --root /path/to/catalog migrate check
621
+ okf --root /path/to/catalog migrate preview \
622
+ '{"metrics/revenue.md":{"by":"human:owner","confirmed":true}}'
623
+ ```
624
+
625
+ In optional multi-root project mode, supply the root id before the actor-mapping JSON.
626
+
627
+ Migration is deliberately conservative:
628
+
629
+ - native `generated` and `sources` fields always win
630
+ - a valid `timestamp` is copied into a new `generated: { by, at }` mapping only after a truthful `by` actor is explicitly confirmed
631
+ - `# Citations` becomes `sources` only from one top-level H1 section containing at least one safely parseable list entry and no unparsed prose, nested sections, ambiguous entries, or escaping paths
632
+ - legacy fields and citation prose are retained for compatibility
633
+ - concepts marked by `--generated-path`, a document flag, or `generated_file`/`generatedFile` frontmatter must be changed through their generator; remote roots are report-only
634
+ - identity collisions, invalid documents, unsafe references, and unresolved assets block the version declaration
635
+
636
+ `okf_propose_v02_migration` requires local-root authoring. It creates a review manifest, one proposal per affected file, and a gated root `okf_version: "0.2"` proposal. Nothing is accepted automatically; the root proposal can be accepted only after every child is accepted and the complete catalog validates.
637
+
525
638
  ## Generator Plugins
526
639
 
527
640
  Generator plugins are configured in `okf.project.yaml` and run with `generate`.
@@ -535,7 +648,8 @@ Generated output is regular Markdown/YAML OKF and is validated by the same index
535
648
 
536
649
  ## Limitations
537
650
 
538
- - The MCP server implements the stdio JSON-RPC methods needed for resources and tools directly instead of using an SDK, so advanced SDK conveniences are out of scope.
539
- - MCP initialization negotiates an explicit supported version and falls back to `2025-11-25` for well-formed unsupported versions.
651
+ - MCP transport is stdio only. The separate HTTP authoring API is not MCP over HTTP.
652
+ - MCP protocol compatibility follows the pinned official SDK v2 dependency.
540
653
  - There is no file watcher. Restart the server after external file changes. Concepts accepted through MCP authoring refresh the MCP server index immediately.
541
654
  - The HTTP API is a lightweight built-in server, not a full hosted multi-tenant service.
655
+ - OKF v0.2 computation support is static inspection and preflight only; no computation or attester is executed.
@@ -37,10 +37,10 @@ Consumers that need reproducibility should replace `main` with a release tag. Re
37
37
 
38
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`.
39
39
 
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, negotiates MCP `2025-11-25`, checks fallback negotiation and notification silence, pings the server, discovers tools, and retrieves a concept over stdio.
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.
41
41
 
42
42
  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
43
 
44
- Concept ids use the stable `okf://okf-mcp/...` namespace. Internal relations target those stable ids, while `repo://` references connect durable concepts to their current implementation sources without turning source files into concepts.
44
+ Portable Concept IDs are extensionless paths inside this root. `okf://okf-mcp/...` remains a deterministic MCP/workspace locator, while `repo://` references connect durable concepts to implementation sources without turning source files into concepts.
45
45
 
46
46
  The bundle deliberately documents product contracts, runtime boundaries, workflows, and policies rather than mirroring every source file.
@@ -1,3 +1,7 @@
1
+ ---
2
+ okf_version: "0.2"
3
+ ---
4
+
1
5
  # okf-mcp Reference Bundle
2
6
 
3
7
  This bundle is the canonical machine-readable reference for the `okf-mcp` runtime, interfaces, workflows, policies, and distribution contract.
@@ -6,6 +10,8 @@ This bundle is the canonical machine-readable reference for the `okf-mcp` runtim
6
10
 
7
11
  - [okf-mcp Overview](overview/okf-mcp.md)
8
12
  - [OKF Concept Format](specs/concept-format.md)
13
+ - [Attested Computation Support](specs/attested-computation.md)
14
+ - [Pinned Git Sources](specs/git-sources.md)
9
15
  - [MCP Stdio Server](runtime/mcp-server.md)
10
16
  - [OKF Indexer](runtime/indexer.md)
11
17
  - [File Concept Store](runtime/file-concept-store.md)
@@ -13,5 +19,6 @@ This bundle is the canonical machine-readable reference for the `okf-mcp` runtim
13
19
  - [HTTP Authoring API](interfaces/http-authoring-api.md)
14
20
  - [Concept Authoring](workflows/concept-authoring.md)
15
21
  - [Concept Update](workflows/concept-update.md)
22
+ - [OKF v0.2 Migration](workflows/v02-migration.md)
16
23
  - [Authoring Safety](policies/authoring-safety.md)
17
24
  - [Published Reference Bundle](distribution/reference-bundle.md)
@@ -19,8 +19,8 @@ relations:
19
19
 
20
20
  The optional HTTP server exposes health, bundle discovery, candidate validation, path suggestion, proposal inspection, proposal creation, proposal update, acceptance, and rejection.
21
21
 
22
- Mutation endpoints require an exact bearer token supplied through `OKF_WRITE_TOKEN` or the CLI option. Validation and read endpoints do not mutate concept files.
22
+ Proposal inspection and mutation endpoints require an exact bearer token supplied through `OKF_WRITE_TOKEN` or the CLI option because pending proposal records can contain complete candidate Markdown or computation code. Health, bundle discovery, and candidate validation remain unauthenticated and do not mutate concept files.
23
23
 
24
- The API delegates all authoring behavior to the same service and file store used by MCP project mode. Proposal acceptance therefore uses the same validation, identity, revision, and path safeguards described by the [authoring safety policy](../policies/authoring-safety.md).
24
+ 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
25
 
26
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.