@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.
- package/.agents/skills/okf-v02-migration/SKILL.md +37 -0
- package/.agents/skills/okf-v02-migration/agents/openai.yaml +6 -0
- package/.agents/skills/okf-v02-migration/references/field-mapping.md +26 -0
- package/README.md +192 -78
- package/okf/bundles/okf-mcp/distribution/reference-bundle.md +2 -2
- package/okf/bundles/okf-mcp/index.md +7 -0
- package/okf/bundles/okf-mcp/interfaces/http-authoring-api.md +2 -2
- package/okf/bundles/okf-mcp/interfaces/mcp-tools.md +8 -4
- package/okf/bundles/okf-mcp/overview/okf-mcp.md +2 -2
- package/okf/bundles/okf-mcp/policies/authoring-safety.md +5 -3
- package/okf/bundles/okf-mcp/runtime/file-concept-store.md +7 -5
- package/okf/bundles/okf-mcp/runtime/indexer.md +6 -4
- package/okf/bundles/okf-mcp/runtime/mcp-server.md +6 -6
- package/okf/bundles/okf-mcp/specs/attested-computation.md +24 -0
- package/okf/bundles/okf-mcp/specs/concept-format.md +5 -3
- package/okf/bundles/okf-mcp/specs/git-sources.md +23 -0
- package/okf/bundles/okf-mcp/workflows/v02-migration.md +24 -0
- package/package.json +9 -3
- package/server.json +5 -5
- package/src/assets.js +469 -0
- package/src/authoring.js +492 -20
- package/src/cli.js +467 -37
- package/src/computation.js +366 -0
- package/src/git-source.js +551 -0
- package/src/graph.js +71 -18
- package/src/http-server.js +8 -1
- package/src/index.js +5 -0
- package/src/indexer.js +428 -24
- package/src/markdown.js +129 -0
- package/src/mcp-server.js +447 -313
- package/src/migration.js +687 -0
- package/src/parser.js +135 -54
- package/src/plugins.js +30 -50
- package/src/project.js +74 -17
- package/src/remote.js +232 -17
- package/src/search.js +69 -6
- package/src/store.js +421 -25
- package/src/v02.js +545 -0
- package/src/validation.js +13 -2
- 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,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
|
|
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
|
|
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
|
|
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
|
-
|
|
12
|
-
|
|
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.
|
|
16
|
-
npx -y @mfdaves/okf-mcp@0.
|
|
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.
|
|
54
|
+
npm install --global @mfdaves/okf-mcp@0.5.0
|
|
23
55
|
|
|
24
56
|
okf --version
|
|
25
|
-
okf --
|
|
26
|
-
okf-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
|
|
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
|
-
|
|
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 `--
|
|
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
|
|
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.
|
|
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
|
-
##
|
|
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.
|
|
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 --
|
|
59
|
-
okf --
|
|
60
|
-
okf --
|
|
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
|
|
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/
|
|
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
|
-
|
|
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
|
-
|
|
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 <
|
|
122
|
-
- `neighbors <
|
|
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
|
|
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.
|
|
146
|
-
"--
|
|
147
|
-
"
|
|
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.
|
|
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
|
|
177
|
-
`
|
|
178
|
-
|
|
179
|
-
|
|
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
|
|
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
|
|
193
|
-
|
|
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
|
|
234
|
+
## Concept Identity And Extensions
|
|
201
235
|
|
|
202
|
-
|
|
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>/<
|
|
239
|
+
okf://<bundle-id>/<extensionless-concept-id>
|
|
206
240
|
```
|
|
207
241
|
|
|
208
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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 |
|
|
339
|
+
| Mode | Normal proposals | Computation proposal | Runtime remote load |
|
|
272
340
|
| --- | --- | --- | --- |
|
|
273
|
-
| default | disabled | disabled |
|
|
274
|
-
| `--authoring` | enabled | disabled |
|
|
275
|
-
| `--allow-
|
|
276
|
-
|
|
|
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
|
-
|
|
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": "
|
|
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 --
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
-
-
|
|
379
|
-
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
-
|
|
539
|
-
- MCP
|
|
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,
|
|
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
|
|
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
|
-
|
|
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
|
|
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.
|