@mfdaves/okf-mcp 0.7.0 → 0.9.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/README.md +79 -18
- package/okf/{bundles/okf-mcp → okf-mcp}/distribution/reference-bundle.md +1 -1
- package/okf/{bundles/okf-mcp → okf-mcp}/index.md +3 -0
- package/okf/{bundles/okf-mcp → okf-mcp}/interfaces/mcp-tools.md +13 -5
- package/okf/{bundles/okf-mcp → okf-mcp}/overview/okf-mcp.md +5 -3
- package/okf/{bundles/okf-mcp → okf-mcp}/policies/authoring-safety.md +9 -1
- package/okf/{bundles/okf-mcp → okf-mcp}/runtime/file-concept-store.md +1 -1
- package/okf/{bundles/okf-mcp → okf-mcp}/runtime/mcp-server.md +6 -2
- package/okf/okf-mcp/runtime/producer-host.md +28 -0
- package/okf/{bundles/okf-mcp → okf-mcp}/specs/concept-format.md +1 -1
- package/okf/okf-mcp/specs/producer-api.md +26 -0
- package/okf/{bundles/okf-mcp → okf-mcp}/workflows/concept-authoring.md +1 -1
- package/okf/okf-mcp/workflows/producer-publication.md +28 -0
- package/okf.project.yaml +1 -1
- package/package.json +2 -2
- package/server.json +11 -3
- package/src/authoring.js +47 -11
- package/src/cli.js +46 -4
- package/src/graph.js +2 -2
- package/src/index.js +2 -0
- package/src/indexer.js +166 -8
- package/src/live-authoring.js +132 -50
- package/src/mcp-server.js +189 -13
- package/src/producer-publisher.js +462 -0
- package/src/producers.js +507 -0
- package/src/project.js +65 -0
- package/src/search.js +19 -0
- package/src/store.js +1 -0
- /package/okf/{bundles/okf-mcp → okf-mcp}/interfaces/http-authoring-api.md +0 -0
- /package/okf/{bundles/okf-mcp → okf-mcp}/runtime/indexer.md +0 -0
- /package/okf/{bundles/okf-mcp → okf-mcp}/specs/attested-computation.md +0 -0
- /package/okf/{bundles/okf-mcp → okf-mcp}/specs/git-sources.md +0 -0
- /package/okf/{bundles/okf-mcp → okf-mcp}/workflows/concept-update.md +0 -0
- /package/okf/{bundles/okf-mcp → okf-mcp}/workflows/v02-migration.md +0 -0
package/README.md
CHANGED
|
@@ -35,7 +35,7 @@ Node 22 or newer is required.
|
|
|
35
35
|
Install from the GitHub release:
|
|
36
36
|
|
|
37
37
|
```bash
|
|
38
|
-
git clone --branch v0.
|
|
38
|
+
git clone --branch v0.9.0 https://github.com/mfdaves/okf-mcp.git
|
|
39
39
|
cd okf-mcp
|
|
40
40
|
npm ci
|
|
41
41
|
node bin/okf-mcp.js --root ./path/to/okf validate
|
|
@@ -44,14 +44,14 @@ node bin/okf-mcp.js --root ./path/to/okf validate
|
|
|
44
44
|
Pin the published version for reproducible use:
|
|
45
45
|
|
|
46
46
|
```bash
|
|
47
|
-
npx -y @mfdaves/okf-mcp@0.
|
|
48
|
-
npx -y @mfdaves/okf-mcp@0.
|
|
47
|
+
npx -y @mfdaves/okf-mcp@0.9.0 --version
|
|
48
|
+
npx -y @mfdaves/okf-mcp@0.9.0 --root ./path/to/okf validate
|
|
49
49
|
```
|
|
50
50
|
|
|
51
51
|
For a persistent installation:
|
|
52
52
|
|
|
53
53
|
```bash
|
|
54
|
-
npm install --global @mfdaves/okf-mcp@0.
|
|
54
|
+
npm install --global @mfdaves/okf-mcp@0.9.0
|
|
55
55
|
|
|
56
56
|
okf --version
|
|
57
57
|
okf --root ./path/to/okf validate
|
|
@@ -87,23 +87,28 @@ This repository publishes a self-describing OKF bundle for the product, its runt
|
|
|
87
87
|
Validate and query the bundled reference from a checkout or installed package:
|
|
88
88
|
|
|
89
89
|
```bash
|
|
90
|
-
okf --root okf/
|
|
91
|
-
okf --root okf/
|
|
92
|
-
okf --root okf/
|
|
90
|
+
okf --root okf/okf-mcp validate
|
|
91
|
+
okf --root okf/okf-mcp search "proposal"
|
|
92
|
+
okf --root okf/okf-mcp concept overview/okf-mcp
|
|
93
93
|
```
|
|
94
94
|
|
|
95
|
-
Load the reference bundle directly from
|
|
95
|
+
Load the reference bundle directly from the current source branch:
|
|
96
96
|
|
|
97
97
|
```bash
|
|
98
|
-
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/main/okf/okf-mcp --inspect
|
|
99
99
|
```
|
|
100
100
|
|
|
101
|
+
The published `v0.8.0` tag retains its original
|
|
102
|
+
`okf/bundles/okf-mcp` path. The shorter `okf/okf-mcp` path was prepared in the
|
|
103
|
+
unpublished `0.8.1` maintenance checkpoint and ships with `v0.9.0`; the
|
|
104
|
+
immutable `v0.8.0` release remains unchanged.
|
|
105
|
+
|
|
101
106
|
The `@mfdaves/okf-mcp` npm package includes both `okf.project.yaml` and the
|
|
102
107
|
complete reference bundle.
|
|
103
108
|
|
|
104
109
|
## Optional Multi-Bundle Project Config
|
|
105
110
|
|
|
106
|
-
Use `okf.project.yaml` only when one process must federate multiple roots, configure generators, or enforce a project-wide relation vocabulary:
|
|
111
|
+
Use `okf.project.yaml` only when one process must federate multiple roots, configure generators or external metadata producers, or enforce a project-wide relation vocabulary:
|
|
107
112
|
|
|
108
113
|
```yaml
|
|
109
114
|
project: Example
|
|
@@ -115,6 +120,8 @@ bundles:
|
|
|
115
120
|
exclude: ["archive/**"]
|
|
116
121
|
- id: data
|
|
117
122
|
root: okf/bundles/data
|
|
123
|
+
- id: company-database
|
|
124
|
+
root: okf/company-database
|
|
118
125
|
relationTypes:
|
|
119
126
|
- deployed_by
|
|
120
127
|
remoteBundles:
|
|
@@ -128,6 +135,16 @@ plugins:
|
|
|
128
135
|
root: docs
|
|
129
136
|
output: okf/bundles/app/generated/docs
|
|
130
137
|
bundle: app
|
|
138
|
+
producers:
|
|
139
|
+
- name: main-database
|
|
140
|
+
type: postgresql
|
|
141
|
+
package: "@mfdaves/okf-postgres"
|
|
142
|
+
bundle: company-database
|
|
143
|
+
config:
|
|
144
|
+
connectionEnv: DATABASE_URL
|
|
145
|
+
source: company-db
|
|
146
|
+
schemas: [public]
|
|
147
|
+
includeIndexes: true
|
|
131
148
|
```
|
|
132
149
|
|
|
133
150
|
Run project commands:
|
|
@@ -137,6 +154,9 @@ okf --project okf.project.yaml validate
|
|
|
137
154
|
okf --project okf.project.yaml search "orders"
|
|
138
155
|
okf --project okf.project.yaml graph mermaid
|
|
139
156
|
okf --project okf.project.yaml generate
|
|
157
|
+
okf --project okf.project.yaml producer list
|
|
158
|
+
okf --project okf.project.yaml producer preview main-database
|
|
159
|
+
okf --project okf.project.yaml producer run main-database --write --actor process:nightly-refresh
|
|
140
160
|
okf --project okf.project.yaml mcp
|
|
141
161
|
okf --project okf.project.yaml mcp --authoring
|
|
142
162
|
okf --project okf.project.yaml mcp --allow-remote-tool
|
|
@@ -160,8 +180,43 @@ Commands:
|
|
|
160
180
|
- `source <concept-id-or-locator> <source-id>`
|
|
161
181
|
- `migrate check|preview`
|
|
162
182
|
- `generate`
|
|
183
|
+
- `producer list|preview|run`
|
|
163
184
|
- `serve`
|
|
164
185
|
|
|
186
|
+
### External metadata producers
|
|
187
|
+
|
|
188
|
+
Producers are separate from the built-in `plugins:` generators. A producer reads metadata from an external source and returns an in-memory candidate OKF bundle; `okf-mcp` validates and publishes that candidate. Install each producer package alongside the project, then allowlist its exact bare package name in the trusted project configuration. MCP callers can select a configured producer but cannot replace its package, configuration, credentials, queries, bundle, or output paths.
|
|
189
|
+
|
|
190
|
+
The package must be installed under a `node_modules` directory belonging to the project, resolved by its exact bare name. Ordinary registry installs, npm workspaces, `npm link`, and store-backed layouts such as pnpm all satisfy this; a path in configuration never does.
|
|
191
|
+
|
|
192
|
+
The package must export the versioned `okfProducer` API. Producer API v1 targets OKF v0.2 and separates `validateConfig()` from side-effect-free destination generation. Candidate concepts require native `generated` and non-empty `sources` provenance. The host rejects unsafe paths, malformed concepts, unresolved links or typed relations, unowned file collisions, locally modified managed files, secret values in output, and any candidate that would leave the complete project invalid.
|
|
193
|
+
|
|
194
|
+
Both interfaces run the same host. Use the CLI for scheduled refreshes:
|
|
195
|
+
|
|
196
|
+
```bash
|
|
197
|
+
okf --project okf.project.yaml producer preview main-database
|
|
198
|
+
okf --project okf.project.yaml producer run main-database --write --actor process:nightly-refresh
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
`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.
|
|
202
|
+
|
|
203
|
+
For a configured project, MCP exposes:
|
|
204
|
+
|
|
205
|
+
- `okf_list_producers`: list configuration without loading package code or reading the source
|
|
206
|
+
- `okf_preview_producer`: read source metadata and return a validated, non-writing diff
|
|
207
|
+
- `okf_run_producer`: regenerate under the shared writer queue and publish with revision checks and rollback; available only with `--write` plus a truthful `--actor` using `human:<id>`, `process:<id>`, or `provider/model` syntax
|
|
208
|
+
|
|
209
|
+
Preview and run accept only the configured producer name plus optional receipt detail. Receipts include bounded numeric source-object summaries and publication-diff counts. Publication records owned relative paths and SHA-256 digests in the bundle-local `.okf-producer.json`. Only unchanged paths owned by the prior manifest can be updated or removed; hand-authored content is never adopted implicitly. The manifest contains no producer configuration, credentials, or connection details.
|
|
210
|
+
|
|
211
|
+
Two rules keep a managed bundle stable across repeated runs:
|
|
212
|
+
|
|
213
|
+
- 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.
|
|
214
|
+
- 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.
|
|
215
|
+
|
|
216
|
+
Directories emptied by a stale deletion are removed with their last managed file.
|
|
217
|
+
|
|
218
|
+
`@mfdaves/okf-postgres` is the PostgreSQL implementation. Its average-use v1 covers database, schema, table/view, column, key, check, enum, index, and description metadata without reading table rows. Keep connection strings in an environment variable named by `connectionEnv`; do not place a connection string in YAML.
|
|
219
|
+
|
|
165
220
|
`serve` options:
|
|
166
221
|
|
|
167
222
|
- `--host <host>`: bind host, default `127.0.0.1`
|
|
@@ -182,7 +237,7 @@ Example client configuration:
|
|
|
182
237
|
"command": "npx",
|
|
183
238
|
"args": [
|
|
184
239
|
"-y",
|
|
185
|
-
"@mfdaves/okf-mcp@0.
|
|
240
|
+
"@mfdaves/okf-mcp@0.9.0",
|
|
186
241
|
"--root",
|
|
187
242
|
"/absolute/path/to/okf",
|
|
188
243
|
"mcp"
|
|
@@ -201,7 +256,7 @@ Project config mode, with read-only project helpers but without proposal mutatio
|
|
|
201
256
|
"command": "npx",
|
|
202
257
|
"args": [
|
|
203
258
|
"-y",
|
|
204
|
-
"@mfdaves/okf-mcp@0.
|
|
259
|
+
"@mfdaves/okf-mcp@0.9.0",
|
|
205
260
|
"--project",
|
|
206
261
|
"/absolute/path/to/repo/okf.project.yaml",
|
|
207
262
|
"mcp"
|
|
@@ -239,7 +294,7 @@ Concept IDs are their bundle-relative Markdown paths with `.md` removed. This ex
|
|
|
239
294
|
okf://<bundle-id>/<extensionless-concept-id>
|
|
240
295
|
```
|
|
241
296
|
|
|
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
|
|
297
|
+
The former `.md` URI and a valid custom `id` remain compatibility lookup aliases. A bare Concept ID resolves only when unique across loaded bundles. For standalone aggregate catalogs, a URI-shaped portable path such as `okf://services/queue.md` also resolves when `services/queue` is globally unique and `services` is not a loaded bundle id. Exact canonical URIs always win; a known-bundle miss or ambiguous portable path stays unresolved. Reserved `index.md` and `log.md` resources retain their filenames because they are not concepts.
|
|
243
298
|
|
|
244
299
|
The `id`, `aliases`, and typed `relations` fields below are `okf-mcp` extensions. The standard v0.2 identity remains path-derived:
|
|
245
300
|
|
|
@@ -318,6 +373,9 @@ okf --root /path/to/catalog \
|
|
|
318
373
|
- `okf_reject_proposal`
|
|
319
374
|
- `okf_validate_changes`
|
|
320
375
|
- `okf_apply_changes`
|
|
376
|
+
- `okf_list_producers`
|
|
377
|
+
- `okf_preview_producer`
|
|
378
|
+
- `okf_run_producer`
|
|
321
379
|
- `get_graph`
|
|
322
380
|
- `get_neighbors`
|
|
323
381
|
- `get_subgraph`
|
|
@@ -327,7 +385,7 @@ okf --root /path/to/catalog \
|
|
|
327
385
|
- `validate_project`
|
|
328
386
|
- `export_graph`
|
|
329
387
|
|
|
330
|
-
Most MCP tools are read-only over the current index. `load_remote_bundle` mutates only the server's in-memory index by fetching a public GitHub tree; it does not write files.
|
|
388
|
+
Most MCP tools are read-only over the current index. `load_remote_bundle` mutates only the server's in-memory index by fetching a public GitHub tree; it does not write files. Concept listing and search default to compact summaries; pass `detail: "full"` when navigation metadata, signals, ranking, or snippets are required. Relationship paths are deduplicated by node sequence even when parallel edge kinds connect the same concepts.
|
|
331
389
|
|
|
332
390
|
Every MCP tool includes a purpose-specific description, descriptions for its input parameters, and standard annotations covering read-only behavior, destructive behavior, idempotency, and external access.
|
|
333
391
|
|
|
@@ -382,9 +440,9 @@ The agent sees one read-only batch validator and one destructive apply tool. It
|
|
|
382
440
|
}
|
|
383
441
|
```
|
|
384
442
|
|
|
385
|
-
Create paths are optional. The server first uses a strong dominant directory convention from existing concepts
|
|
443
|
+
Create paths are optional. The server first uses a strong dominant directory convention from existing same-type concepts within the requested prefix, then falls back to deterministic type/title slugs. `okf_suggest_concept_path` reports the strategy, evidence, path availability, and same-type/title matches so an available filename is not mistaken for a safe duplicate. Updates identify an existing `uri`; stale locators return bounded likely replacements, while scalar fields replace existing values and `tags`, `sources`, and `relations` use explicit `add`/`remove` patches. `metadata` carries extension frontmatter but cannot override identity, generation, collection, or computation fields. Paths and URIs are immutable during update: moving a concept changes its portable identity and remains a separate, intentionally unsupported operation.
|
|
386
444
|
|
|
387
|
-
Every 1–100 item batch is validated as one future graph, so concepts created together can reference one another. Call `okf_validate_changes` with the complete intended batch to receive a time-of-check preview without writing files. Validation and apply share the same planner; apply repeats every check under the writer queue because revisions and Git state can change after a preview.
|
|
445
|
+
Every 1–100 item batch is validated as one future graph, so concepts created together can reference one another and same-type/title conflicts are detected across creates and updates. Call `okf_validate_changes` with the complete intended batch to receive a time-of-check preview without writing files. Validation and apply share the same planner; apply repeats every check under the writer queue because revisions and Git state can change after a preview. Compact receipts are the v0.8 default; pass `detail: "full"` for the v0.7 planning layout. Effects expose structured relations and keep server-managed generation provenance separate from substantive `changedFields`.
|
|
388
446
|
|
|
389
447
|
The server writes nothing unless every candidate is valid, revision checks still match, and every target stays inside one writable bundle. Process-generated documents, generator output directories, hidden/control-plane paths such as `.git/**`, reserved files, and Attested Computation contracts are not live-write targets. Rollback checks revisions immediately before each restore and reports detected replacements as a partial `rollback_conflict`. That protection is best effort under the documented single-external-writer requirement; it is not a cross-process compare-and-swap guarantee.
|
|
390
448
|
|
|
@@ -543,6 +601,7 @@ Use `list_remote_bundles` to inspect what was loaded.
|
|
|
543
601
|
- `hasSources`
|
|
544
602
|
- `runtime` and `attestationReady`
|
|
545
603
|
- `generatedBy` and `verifiedBy`
|
|
604
|
+
- `detail` (`compact` by default, or `full`)
|
|
546
605
|
- `limit`
|
|
547
606
|
- `offset`
|
|
548
607
|
|
|
@@ -551,7 +610,7 @@ listing filters. Text search tokenizes case-insensitively and requires every
|
|
|
551
610
|
query term, regardless of order. BM25+ ranks title, type, tags, aliases,
|
|
552
611
|
description, path, and body matches; frontmatter remains available through
|
|
553
612
|
exact structured filters but is not copied into the text index. Scores are
|
|
554
|
-
relative within a result set and are not a stable cross-version scale.
|
|
613
|
+
relative within a result set and are not a stable cross-version scale. Compact results contain only `uri`, `title`, `type`, and `description`; title, type, and description are bounded, while full results remain lossless.
|
|
555
614
|
|
|
556
615
|
Queries are bounded to 512 characters and 16 terms. Prefix expansion, fuzzy
|
|
557
616
|
matching, stemming, and stop-word removal are intentionally disabled so code
|
|
@@ -561,6 +620,8 @@ frontmatter filters support exact scalar matching and array-contains
|
|
|
561
620
|
matching. `relationType` selects concepts with an outgoing relation of that
|
|
562
621
|
type.
|
|
563
622
|
|
|
623
|
+
The SDK regression suite also budgets a neutral four-step research path from actual serialized MCP text. It uses UTF-8 bytes divided by four as a deterministic estimate, not an exact model tokenizer or billing count, and guards both an absolute compact budget and a compact/full ratio.
|
|
624
|
+
|
|
564
625
|
Example:
|
|
565
626
|
|
|
566
627
|
```json
|
|
@@ -595,7 +656,7 @@ For navigation convenience, okf-mcp resolves links to a nested bundle directory
|
|
|
595
656
|
`index.md` when there is no exact document target. This applies to local and
|
|
596
657
|
remote bundles and to candidate validation during proposal authoring.
|
|
597
658
|
|
|
598
|
-
Graph tools return
|
|
659
|
+
Graph tools return bounded JSON:
|
|
599
660
|
|
|
600
661
|
```json
|
|
601
662
|
{
|
|
@@ -31,7 +31,7 @@ This directory is the canonical machine-readable architectural reference for `ok
|
|
|
31
31
|
|
|
32
32
|
The latest public bundle can be loaded from:
|
|
33
33
|
|
|
34
|
-
`https://github.com/mfdaves/okf-mcp/tree/main/okf/
|
|
34
|
+
`https://github.com/mfdaves/okf-mcp/tree/main/okf/okf-mcp`
|
|
35
35
|
|
|
36
36
|
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
37
|
|
|
@@ -12,13 +12,16 @@ This bundle is the canonical machine-readable reference for the `okf-mcp` runtim
|
|
|
12
12
|
- [OKF Concept Format](specs/concept-format.md)
|
|
13
13
|
- [Attested Computation Support](specs/attested-computation.md)
|
|
14
14
|
- [Pinned Git Sources](specs/git-sources.md)
|
|
15
|
+
- [Producer API](specs/producer-api.md)
|
|
15
16
|
- [MCP Stdio Server](runtime/mcp-server.md)
|
|
16
17
|
- [OKF Indexer](runtime/indexer.md)
|
|
17
18
|
- [File Concept Store](runtime/file-concept-store.md)
|
|
19
|
+
- [Producer Host](runtime/producer-host.md)
|
|
18
20
|
- [MCP Tool Catalog](interfaces/mcp-tools.md)
|
|
19
21
|
- [HTTP Authoring API](interfaces/http-authoring-api.md)
|
|
20
22
|
- [Concept Authoring](workflows/concept-authoring.md)
|
|
21
23
|
- [Concept Update](workflows/concept-update.md)
|
|
22
24
|
- [OKF v0.2 Migration](workflows/v02-migration.md)
|
|
25
|
+
- [Producer Publication](workflows/producer-publication.md)
|
|
23
26
|
- [Authoring Safety](policies/authoring-safety.md)
|
|
24
27
|
- [Published Reference Bundle](distribution/reference-bundle.md)
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
id: okf://okf-mcp/interfaces/mcp-tools
|
|
3
3
|
type: OKF Interface
|
|
4
4
|
title: MCP Tool Catalog
|
|
5
|
-
description: Agent-facing tool contract for discovery, graph navigation, validation, remote loading, and authoring.
|
|
5
|
+
description: Agent-facing tool contract for discovery, graph navigation, validation, producer execution, remote loading, and authoring.
|
|
6
6
|
tags: [mcp, tools, interface, agents]
|
|
7
7
|
relations:
|
|
8
8
|
- type: depends_on
|
|
@@ -11,6 +11,8 @@ relations:
|
|
|
11
11
|
target: okf://okf-mcp/runtime/indexer
|
|
12
12
|
- type: related_to
|
|
13
13
|
target: okf://okf-mcp/workflows/concept-authoring
|
|
14
|
+
- type: related_to
|
|
15
|
+
target: okf://okf-mcp/workflows/producer-publication
|
|
14
16
|
- type: configured_by
|
|
15
17
|
target: repo://src/mcp-server.js
|
|
16
18
|
- type: checked_by
|
|
@@ -23,15 +25,17 @@ relations:
|
|
|
23
25
|
target: repo://test/live-mcp-contract.test.js
|
|
24
26
|
- type: checked_by
|
|
25
27
|
target: repo://test/live-agent-workflow.test.js
|
|
28
|
+
- type: checked_by
|
|
29
|
+
target: repo://test/producer.test.js
|
|
26
30
|
---
|
|
27
31
|
|
|
28
32
|
# MCP Tool Catalog
|
|
29
33
|
|
|
30
34
|
The MCP interface groups tools by intent.
|
|
31
35
|
|
|
32
|
-
Discovery tools list bundles, concepts, types, tags, custom relation types, standard edge kinds, and loaded remote bundles. `get_concept` accepts a portable Concept ID or compatibility locator and returns raw frontmatter and body plus normalized v0.2 signals, referenced-asset metadata, and declared Git-source availability. Search uses a process-local MiniSearch BM25+ index and filters lifecycle, trust, freshness at a deterministic date, source presence, generator or verifier actors, runtime, and static attestation readiness.
|
|
36
|
+
Discovery tools list bundles, concepts, types, tags, custom relation types, standard edge kinds, and loaded remote bundles. `get_concept` accepts a canonical URI, unique portable Concept ID, or URI-shaped portable compatibility locator and returns raw frontmatter and body plus normalized v0.2 signals, referenced-asset metadata, and declared Git-source availability. Missing stale locators return bounded likely replacements without silently following them. Search uses a process-local MiniSearch BM25+ index and filters lifecycle, trust, freshness at a deterministic date, source presence, generator or verifier actors, runtime, and static attestation readiness.
|
|
33
37
|
|
|
34
|
-
Graph tools return bounded graphs, neighbors, subgraphs, paths, summaries, provenance traces, and rendered exports. They can filter semantic edge kinds and optionally include inert asset nodes or unfetched external leaves.
|
|
38
|
+
Graph tools return bounded graphs, neighbors, subgraphs, paths, summaries, provenance traces, and rendered exports. They can filter semantic edge kinds and optionally include inert asset nodes or unfetched external leaves. Identical node paths from parallel edge kinds are returned once.
|
|
35
39
|
|
|
36
40
|
Validation tools inspect bundles, projects, and candidate concepts without writing. They report OKF conformance separately from project validity. Remote loading fetches a public GitHub tree into the in-memory index.
|
|
37
41
|
|
|
@@ -41,7 +45,11 @@ Static computation tools inspect contracts, read indexed assets, prepare paramet
|
|
|
41
45
|
|
|
42
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`.
|
|
43
47
|
|
|
44
|
-
`
|
|
48
|
+
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
|
+
|
|
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.
|
|
51
|
+
|
|
52
|
+
`okf_validate_changes` and `okf_apply_changes` plan 1–100 operations as one future graph, including cross-batch and loaded-remote references plus same-type/title conflicts. Validation returns a non-durable time-of-check receipt. Apply repeats planning under the process-local writer queue, stamps one server-owned `generated.at` with the configured `generated.by`, publishes the complete local batch, validates persisted state, and refreshes the index. Compact receipts are the default; `detail: "full"` retains the richer planning layout. Relation effects are structured, and generated provenance is separate from substantive changed fields.
|
|
45
53
|
|
|
46
54
|
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.
|
|
47
55
|
|
|
@@ -49,4 +57,4 @@ Every tool supplies a purpose-specific description, descriptions for all input p
|
|
|
49
57
|
|
|
50
58
|
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.
|
|
51
59
|
|
|
52
|
-
`search_concepts` and the optional text query on `list_concepts` require every case-insensitive query term, regardless of order. They rank title, type, tags, aliases, description, path, and body while keeping arbitrary frontmatter as an exact structured filter. Queries are bounded to 512 characters and 16 terms; fuzzy, prefix, stemming, and stop-word expansion are not applied. Scores are relative retrieval scores rather than a stable public scale. Relation-type filtering selects concepts with an outgoing relation of the requested type.
|
|
60
|
+
`search_concepts` and the optional text query on `list_concepts` require every case-insensitive query term, regardless of order. They rank title, type, tags, aliases, description, path, and body while keeping arbitrary frontmatter as an exact structured filter. Compact MCP results expose the URI plus bounded title, type, and description; `detail: "full"` returns navigation metadata, signals, ranking, and snippets. Queries are bounded to 512 characters and 16 terms; fuzzy, prefix, stemming, and stop-word expansion are not applied. Scores are relative retrieval scores rather than a stable public scale. Relation-type filtering selects concepts with an outgoing relation of the requested type.
|
|
@@ -2,13 +2,15 @@
|
|
|
2
2
|
id: okf://okf-mcp/overview/okf-mcp
|
|
3
3
|
type: OKF Product
|
|
4
4
|
title: okf-mcp
|
|
5
|
-
description: Project-agnostic OKF CLI, graph index, MCP stdio server, and
|
|
5
|
+
description: Project-agnostic OKF CLI, graph index, MCP stdio server, validated producer host, and authoring runtime.
|
|
6
6
|
tags: [okf, mcp, runtime, knowledge-graph]
|
|
7
7
|
relations:
|
|
8
8
|
- type: depends_on
|
|
9
9
|
target: okf://okf-mcp/runtime/mcp-server
|
|
10
10
|
- type: depends_on
|
|
11
11
|
target: okf://okf-mcp/runtime/indexer
|
|
12
|
+
- type: depends_on
|
|
13
|
+
target: okf://okf-mcp/runtime/producer-host
|
|
12
14
|
- type: related_to
|
|
13
15
|
target: okf://okf-mcp/interfaces/http-authoring-api
|
|
14
16
|
- type: produces
|
|
@@ -19,10 +21,10 @@ relations:
|
|
|
19
21
|
|
|
20
22
|
# okf-mcp
|
|
21
23
|
|
|
22
|
-
`okf-mcp` turns one OKF v0.2 root and its explicitly referenced inert assets into a searchable in-memory knowledge graph. It provides a CLI, SDK-backed stdio MCP server, pinned Git-source reads, optional workspace federation, generator plugins, remote GitHub bundles, and an HTTP authoring API.
|
|
24
|
+
`okf-mcp` turns one OKF v0.2 root and its explicitly referenced inert assets into a searchable in-memory knowledge graph. It provides a CLI, SDK-backed stdio MCP server, pinned Git-source reads, optional workspace federation, built-in generator plugins, configured external producers, remote GitHub bundles, and an HTTP authoring API.
|
|
23
25
|
|
|
24
26
|
The runtime uses `js-yaml`, CommonMark, and a process-local MiniSearch BM25+ text index. It has no database, embedding service, computation executor, attester runtime, or build step. `--root` is the normal single-catalog interface and performs no network calls. The optional project manifest federates multiple roots and generator configuration; it is an okf-mcp extension rather than part of OKF v0.2.
|
|
25
27
|
|
|
26
|
-
The primary runtime entry is the [MCP stdio server](../runtime/mcp-server.md). Concept interpretation and graph construction belong to the [indexer](../runtime/indexer.md). Durable knowledge changes follow the [concept authoring workflow](../workflows/concept-authoring.md) and [authoring safety policy](../policies/authoring-safety.md).
|
|
28
|
+
The primary runtime entry is the [MCP stdio server](../runtime/mcp-server.md). Concept interpretation and graph construction belong to the [indexer](../runtime/indexer.md). Configured metadata sources run through the [producer host](../runtime/producer-host.md) and its [publication workflow](../workflows/producer-publication.md). Durable knowledge changes follow the [concept authoring workflow](../workflows/concept-authoring.md) and [authoring safety policy](../policies/authoring-safety.md).
|
|
27
29
|
|
|
28
30
|
The HTTP server is an authoring API rather than a remotely hosted MCP transport. The canonical public architectural reference is this [published reference bundle](../distribution/reference-bundle.md), shipped with the npm package and described for discovery by the MCP Registry metadata.
|
|
@@ -11,6 +11,8 @@ relations:
|
|
|
11
11
|
target: okf://okf-mcp/workflows/concept-authoring
|
|
12
12
|
- type: related_to
|
|
13
13
|
target: okf://okf-mcp/workflows/concept-update
|
|
14
|
+
- type: related_to
|
|
15
|
+
target: okf://okf-mcp/workflows/producer-publication
|
|
14
16
|
- type: configured_by
|
|
15
17
|
target: repo://src/authoring.js
|
|
16
18
|
- type: configured_by
|
|
@@ -27,6 +29,8 @@ relations:
|
|
|
27
29
|
target: repo://test/live-authoring-correctness.test.js
|
|
28
30
|
- type: checked_by
|
|
29
31
|
target: repo://test/live-agent-workflow.test.js
|
|
32
|
+
- type: checked_by
|
|
33
|
+
target: repo://test/producer.test.js
|
|
30
34
|
---
|
|
31
35
|
|
|
32
36
|
# Authoring Safety
|
|
@@ -35,7 +39,7 @@ Authoring is allowed for an explicit local `--root` or local roots declared by `
|
|
|
35
39
|
|
|
36
40
|
Concept paths must be safe relative `.md` paths inside the selected bundle. Absolute paths, parent traversal, hidden/control-plane segments such as `.git`, case-insensitive reserved `index.md` and `log.md` targets, Markdown-file ancestor segments, symbolic-link traversal, and non-directory parents are rejected.
|
|
37
41
|
|
|
38
|
-
New concepts cannot reuse a canonical Concept ID or compatibility alias. Updates are bound to the existing bundle and path and cannot change the custom-id alias.
|
|
42
|
+
New concepts cannot reuse a canonical Concept ID or compatibility alias, and a batch cannot increase same-type/title ambiguity. Updates are bound to the existing bundle and path and cannot change the custom-id alias. Move/rename remains unsupported because it changes portable identity and requires a future graph tombstone plus lossless inbound-reference rewriting.
|
|
39
43
|
|
|
40
44
|
Candidates must satisfy the concept format, configured relation vocabulary, and internal target integrity. External schemes such as `repo://` are allowed as opaque references.
|
|
41
45
|
|
|
@@ -43,6 +47,10 @@ Proposal creation never writes a concept file. Acceptance repeats validation. Up
|
|
|
43
47
|
|
|
44
48
|
Direct authoring exposes a read-only batch validator and one destructive apply tool with the same structured grammar. They share the combined-future-graph planner, while apply repeats the plan under one process-local writer lock, stamps generation metadata at the server boundary, stages every file before publication, and validates persisted state. It rejects generated-file flags, `process:*` generation owners, configured generator outputs, and computation contracts.
|
|
45
49
|
|
|
50
|
+
Configured producer bundle roots are also protected from direct authoring. A producer candidate must declare and emit OKF v0.2, carry valid native generation and source provenance on every concept, contain no producer-owned graph failures, and leave the complete future project conformant and valid. Secret values requested through the host are rejected if they appear in generated bytes. Invalid previews remain inspectable but are never publishable.
|
|
51
|
+
|
|
52
|
+
Producer ownership is recorded in `.okf-producer.json` with relative paths and content digests. New unowned path collisions, modified owned files, corrupt or foreign manifests, path traversal, and symbolic-link traversal block publication. Only unchanged paths owned by the previous manifest may be removed. The manifest is written last after staged publication, and persisted validation failures trigger revision-aware rollback.
|
|
53
|
+
|
|
46
54
|
Rollback revision-checks a published target immediately before restoring it. Detected external replacements are preserved and reported as rollback conflicts, but this is best-effort detection rather than a cross-process compare-and-swap primitive. Optional Git commits require a clean worktree before publication, reject active filter attributes and hidden `assume-unchanged`/`skip-worktree` index flags, and disable replace-object resolution. They build an isolated index directly from validated Markdown bytes, create the exact tree without mutating the shared index, publish it through a compare-and-swap ref update, synchronize only affected ordinary-index paths afterward, and never push. Commit, target, index, and durability states remain explicit when a timeout or concurrent replacement cannot be classified safely.
|
|
47
55
|
|
|
48
56
|
Computation, executor, and attester artifacts are always inert. Inspection and preflight never execute them, fetch external contract URIs, echo parameter or receipt values, persist receipts, or claim attestation. Migration adds no unverifiable provenance or trust claims and never accepts its own proposals.
|
|
@@ -27,7 +27,7 @@ New concepts use exclusive creation. Updates retain a SHA256 revision and check
|
|
|
27
27
|
|
|
28
28
|
The store rolls back published files when an ordinary acceptance call fails, but a multi-file acceptance is not crash-transactional across process or power loss. Operators must inspect and repair an interrupted acceptance before restarting authoring; the store does not claim database transaction semantics.
|
|
29
29
|
|
|
30
|
-
Proposal acceptance
|
|
30
|
+
Proposal acceptance, direct live planning/apply, and producer publication share one process-local writer queue. Read-only validation returns a time-of-check preview without staging. Apply stages every candidate, checks revisions immediately before publication, validates the persisted graph, and revision-checks each published target immediately before restoring it after a failure. Ordinary failures remain all-or-none when the published bytes still belong to the operation; detected concurrent replacements are preserved and surfaced as rollback conflicts. The revision check and filesystem restore are not a cross-process compare-and-swap, so external single-writer coordination remains required. This is not crash durability or distributed coordination.
|
|
31
31
|
|
|
32
32
|
Write paths remain bundle-relative, bundle boundaries are enforced, and symbolic-link traversal is blocked. Generic tools cannot alter computation contracts. Migration manifests live under `.okf-proposals/migrations`; their child proposals are never auto-accepted, and the reserved version proposal depends on accepted Stage-A children.
|
|
33
33
|
|
|
@@ -11,6 +11,8 @@ relations:
|
|
|
11
11
|
target: okf://okf-mcp/interfaces/mcp-tools
|
|
12
12
|
- type: depends_on
|
|
13
13
|
target: okf://okf-mcp/workflows/concept-authoring
|
|
14
|
+
- type: depends_on
|
|
15
|
+
target: okf://okf-mcp/runtime/producer-host
|
|
14
16
|
- type: configured_by
|
|
15
17
|
target: repo://src/mcp-server.js
|
|
16
18
|
- type: checked_by
|
|
@@ -19,6 +21,8 @@ relations:
|
|
|
19
21
|
target: repo://test/mcp-hardening.test.js
|
|
20
22
|
- type: checked_by
|
|
21
23
|
target: repo://test/mcp-sdk.test.js
|
|
24
|
+
- type: checked_by
|
|
25
|
+
target: repo://test/producer.test.js
|
|
22
26
|
---
|
|
23
27
|
|
|
24
28
|
# MCP Stdio Server
|
|
@@ -29,9 +33,9 @@ The SDK serves the modern `2026-07-28` revision and its compatibility path for 2
|
|
|
29
33
|
|
|
30
34
|
The SDK validates protocol messages and tool arguments before application dispatch. Expected application failures return tool results with `isError: true`; unexpected implementation failures are masked. Stdout remains reserved for protocol messages.
|
|
31
35
|
|
|
32
|
-
Each indexed Markdown document is exposed as a `text/markdown` resource. The [MCP tool catalog](../interfaces/mcp-tools.md) exposes discovery, search, graph navigation, validation, remote loading, proposal-based authoring, and explicitly gated live batch validation/apply.
|
|
36
|
+
Each indexed Markdown document is exposed as a `text/markdown` resource. The [MCP tool catalog](../interfaces/mcp-tools.md) exposes discovery, search, graph navigation, validation, remote loading, configured producer preview/run, proposal-based authoring, and explicitly gated live batch validation/apply.
|
|
33
37
|
|
|
34
|
-
Root mode is the normal single-catalog interface and can supply the local store used by the [authoring workflow](../workflows/concept-authoring.md). Project mode remains an optional federation/configuration extension.
|
|
38
|
+
Root mode is the normal single-catalog interface and can supply the local store used by the [authoring workflow](../workflows/concept-authoring.md). Project mode remains an optional federation/configuration extension and is required for producer instances. Configured projects expose static producer discovery and read-only preview; producer run and live batch tools remain disabled unless the server starts with `--write --actor <actor>`. Proposal mutation tools remain disabled unless it starts with `--authoring`; runtime remote loading remains disabled unless it starts with `--allow-remote-tool`.
|
|
35
39
|
|
|
36
40
|
Remote GitHub bundles are fetched as Markdown and added to the in-memory index. They remain read only and never execute remote code. After an accepted local proposal, one reconstruction path rebuilds the index from configured local bundles, configured remote bundles, and runtime-loaded remote bundles, preserving remote concepts and relationships. The lexical search index is cached against that reconstructed OKF index, so the next query builds a fresh per-server BM25+ view without global or persisted state.
|
|
37
41
|
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: okf://okf-mcp/runtime/producer-host
|
|
3
|
+
type: OKF Runtime Component
|
|
4
|
+
title: Producer Host
|
|
5
|
+
description: Project-scoped runtime that loads allowlisted producers, validates strict OKF v0.2 candidates, and delegates safe publication.
|
|
6
|
+
tags: [producer, runtime, validation, project]
|
|
7
|
+
relations:
|
|
8
|
+
- type: consumes
|
|
9
|
+
target: okf://okf-mcp/specs/producer-api
|
|
10
|
+
- type: depends_on
|
|
11
|
+
target: okf://okf-mcp/runtime/indexer
|
|
12
|
+
- type: depends_on
|
|
13
|
+
target: okf://okf-mcp/runtime/file-concept-store
|
|
14
|
+
- type: related_to
|
|
15
|
+
target: okf://okf-mcp/workflows/producer-publication
|
|
16
|
+
- type: configured_by
|
|
17
|
+
target: repo://src/producers.js
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
# Producer Host
|
|
21
|
+
|
|
22
|
+
The producer host is available only for instances declared by a trusted local project. Static listing does not execute packages. Preview and run resolve the selected bare npm package from the project root, require its `okfProducer` export, validate API and OKF versions plus producer identity, and then validate its configuration before generation.
|
|
23
|
+
|
|
24
|
+
The managed-producer profile is deliberately stricter than permissive OKF consumption. The root index must declare exactly OKF v0.2. Every concept must have a type, title, description, native valid generation metadata, and native non-empty sources. Producer-owned v0.2 diagnostics, broken internal references, invalid relation types or targets, unsafe paths, duplicate paths, and leaked resolved secrets block readiness.
|
|
25
|
+
|
|
26
|
+
Preview overlays candidate writes and manifest-owned stale deletions onto the current catalog and validates the complete future project. Run repeats generation and validation under the shared writer queue; a prior preview is never treated as authority. Invalid output changes no destination bytes.
|
|
27
|
+
|
|
28
|
+
The host publishes through the [producer publication workflow](../workflows/producer-publication.md), validates persisted state, and refreshes the MCP index. Candidate validation runs against the bytes publication will actually leave on disk, which for an unchanged source is the file already published. Compact receipts expose counts; full receipts add bounded relative paths. Neither receipt exposes generated content, secret values, source connection details, producer configuration, or absolute filesystem paths.
|
|
@@ -21,7 +21,7 @@ relations:
|
|
|
21
21
|
|
|
22
22
|
An OKF concept is a UTF-8 Markdown file with YAML frontmatter. A non-empty string `type` is required. Standard v0.2 metadata families include `resource`, `sources`, `usage_window`, `generated`, `verified`, `status`, `stale_after`, and the Attested Computation contract. The Markdown body carries the durable explanation.
|
|
23
23
|
|
|
24
|
-
The standard Concept ID is the bundle-relative path with `.md` removed. okf-mcp also creates the workspace-scoped locator `okf://<bundle>/<concept-id>` for MCP resources and federated lookup; it is not the portable OKF identity. The former `.md` URI remains a compatibility alias. The optional `id`, `aliases`, and typed `relations` fields are `okf-mcp` extensions; a valid custom `id` is an additional alias rather than a replacement for the standard identity.
|
|
24
|
+
The standard Concept ID is the bundle-relative path with `.md` removed. okf-mcp also creates the workspace-scoped locator `okf://<bundle>/<concept-id>` for MCP resources and federated lookup; it is not the portable OKF identity. The former `.md` URI remains a compatibility alias. A URI-shaped portable path is accepted only when its apparent authority is not a loaded bundle and the complete portable ID is globally unique; canonical identity always takes precedence. The optional `id`, `aliases`, and typed `relations` fields are `okf-mcp` extensions; a valid custom `id` is an additional alias rather than a replacement for the standard identity.
|
|
25
25
|
|
|
26
26
|
Frontmatter is parsed as a YAML mapping with the safe core schema. Nested mappings, arrays, block scalars, and unknown extension keys are preserved. Duplicate mapping keys and unsupported custom tags are rejected. Unknown concept type values do not fail OKF conformance.
|
|
27
27
|
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: okf://okf-mcp/specs/producer-api
|
|
3
|
+
type: OKF Extension Contract
|
|
4
|
+
title: Producer API
|
|
5
|
+
description: Versioned Node.js contract for configured metadata producers that return candidate OKF v0.2 documents without publishing them.
|
|
6
|
+
tags: [okf, producer, extension, api]
|
|
7
|
+
relations:
|
|
8
|
+
- type: depends_on
|
|
9
|
+
target: okf://okf-mcp/specs/concept-format
|
|
10
|
+
- type: related_to
|
|
11
|
+
target: okf://okf-mcp/runtime/producer-host
|
|
12
|
+
- type: configured_by
|
|
13
|
+
target: repo://src/producers.js
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
# Producer API
|
|
17
|
+
|
|
18
|
+
A producer package exports `okfProducer`. The descriptor declares producer API version `1`, target OKF version `0.2`, stable identity, package version, relation vocabulary, configuration validation, and one asynchronous `generate` function.
|
|
19
|
+
|
|
20
|
+
The host supplies a configured bundle ID, normalized trusted configuration, one generation timestamp, cancellation signal, and a bounded secret resolver. Generation may read source metadata but must not write destination files. It returns sorted bundle-relative Markdown candidates plus a numeric summary. It receives no destination path and has no preview or apply authority.
|
|
21
|
+
|
|
22
|
+
Producer configuration comes only from `okf.project.yaml`. MCP callers select one configured instance and cannot replace its package, bundle, configuration, credentials, queries, or output location. Packages are already installed and are resolved from the trusted project root; okf-mcp never installs or fetches producer code.
|
|
23
|
+
|
|
24
|
+
Resolution requires the exact bare package name to be installed under a project `node_modules` directory, and the entry node resolves must belong to that installed package. Registry installs, workspaces, links, and store-backed layouts all qualify, because a symbolic link inside `node_modules` is an install-tool detail rather than a trust boundary. A path written into configuration never resolves.
|
|
25
|
+
|
|
26
|
+
The producer declaration is not proof of conformance. The [producer host](../runtime/producer-host.md) independently parses and validates every candidate and the complete future project before publication.
|
|
@@ -29,7 +29,7 @@ A reviewer then inspects the proposal and either accepts or rejects it. Acceptan
|
|
|
29
29
|
|
|
30
30
|
Invalid candidates never become proposals. A proposal that becomes invalid before acceptance remains inspectable and returns the current validation result.
|
|
31
31
|
|
|
32
|
-
For a trusted client approval boundary, `--write --actor <actor>` exposes read-only `okf_validate_changes` and destructive `okf_apply_changes`. Agents submit structured concept fields rather than YAML. The server derives optional paths from strong same-type
|
|
32
|
+
For a trusted client approval boundary, `--write --actor <actor>` exposes read-only `okf_validate_changes` and destructive `okf_apply_changes`. Agents submit structured concept fields rather than YAML. The server derives optional paths from strong prefix-scoped same-type conventions or deterministic slugs, rejects future same-type/title conflicts, patches tags/sources/relations, stamps one generation actor and time, and validates the complete future graph. A validation receipt is a non-durable time-of-check preview; apply repeats the checks before publication. Compact receipts are the default and full receipts remain available explicitly. Optional Git policy pins the checked-out symbolic branch, builds one exact isolated tree from validated bytes, and compare-and-swap publishes it without pushing.
|
|
33
33
|
|
|
34
34
|
Direct writes do not replace generator ownership or computation review. Process-generated concepts, configured generator outputs, and Attested Computation contracts remain outside this workflow.
|
|
35
35
|
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: okf://okf-mcp/workflows/producer-publication
|
|
3
|
+
type: OKF Workflow
|
|
4
|
+
title: Producer Publication
|
|
5
|
+
description: Preview and apply workflow for publishing validated producer-owned OKF v0.2 files without overwriting user-owned content.
|
|
6
|
+
tags: [producer, publication, workflow, safety]
|
|
7
|
+
relations:
|
|
8
|
+
- type: depends_on
|
|
9
|
+
target: okf://okf-mcp/runtime/producer-host
|
|
10
|
+
- type: checked_by
|
|
11
|
+
target: okf://okf-mcp/policies/authoring-safety
|
|
12
|
+
- type: configured_by
|
|
13
|
+
target: repo://src/producer-publisher.js
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
# Producer Publication
|
|
17
|
+
|
|
18
|
+
One configured producer owns generated paths in one local bundle. The host records that ownership in `.okf-producer.json` with the producer identity, version, bundle, sorted relative paths, and SHA-256 content digests.
|
|
19
|
+
|
|
20
|
+
Preview reads the prior manifest, rejects foreign or corrupt ownership, computes created, updated, unchanged, and stale-owned paths, and constructs the complete future graph. An existing path not owned by the manifest is a collision rather than an implicit adoption. An owned file whose current digest differs from the manifest is a manual-edit conflict. Stale removal is allowed only when the current digest still matches the previous manifest.
|
|
21
|
+
|
|
22
|
+
A producer restamps its generation time on every run, so a digest comparison alone would report the whole bundle as updated. The host compares each candidate against the published file with that stamp excluded. A source that did not change reports `unchanged`, keeps the published bytes, and leaves the manifest identical, which keeps the publication diff a statement about the source rather than about the run.
|
|
23
|
+
|
|
24
|
+
Ownership is necessary but not sufficient to destroy work. A file the host would rewrite or remove must itself carry native generation provenance, so a corrupt, hand-merged, or forged manifest cannot direct a producer at hand-authored content.
|
|
25
|
+
|
|
26
|
+
Run regenerates under the process-local writer queue. It stages candidate bytes, rechecks revisions immediately before publication, applies owned changes, removes eligible stale files, writes the next manifest last, and validates persisted state. A normal failure rolls matching operation-owned bytes back to their prior state. Concurrent replacement is preserved and reported rather than overwritten during rollback.
|
|
27
|
+
|
|
28
|
+
Directories emptied by a stale deletion are removed with their last managed file. Successful publication refreshes the server index. It does not commit or push Git state, mutate the metadata source, sample application rows, or claim that generated knowledge has been independently verified.
|
package/okf.project.yaml
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mfdaves/okf-mcp",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.9.0",
|
|
4
4
|
"description": "Local-first Open Knowledge Format validator, graph index, CLI, and MCP stdio server.",
|
|
5
5
|
"homepage": "https://github.com/mfdaves/okf-mcp#readme",
|
|
6
6
|
"repository": {
|
|
@@ -20,7 +20,7 @@
|
|
|
20
20
|
"scripts": {
|
|
21
21
|
"test": "node --test",
|
|
22
22
|
"check": "node --test",
|
|
23
|
-
"self:validate": "node bin/okf-mcp.js --root okf/
|
|
23
|
+
"self:validate": "node bin/okf-mcp.js --root okf/okf-mcp validate",
|
|
24
24
|
"pack:check": "npm pack --dry-run",
|
|
25
25
|
"package:smoke": "node scripts/package-smoke.js",
|
|
26
26
|
"prepublishOnly": "npm run check && npm run self:validate",
|
package/server.json
CHANGED
|
@@ -8,12 +8,12 @@
|
|
|
8
8
|
"source": "github"
|
|
9
9
|
},
|
|
10
10
|
"websiteUrl": "https://github.com/mfdaves/okf-mcp#readme",
|
|
11
|
-
"version": "0.
|
|
11
|
+
"version": "0.9.0",
|
|
12
12
|
"packages": [
|
|
13
13
|
{
|
|
14
14
|
"registryType": "npm",
|
|
15
15
|
"identifier": "@mfdaves/okf-mcp",
|
|
16
|
-
"version": "0.
|
|
16
|
+
"version": "0.9.0",
|
|
17
17
|
"transport": {
|
|
18
18
|
"type": "stdio"
|
|
19
19
|
},
|
|
@@ -22,10 +22,18 @@
|
|
|
22
22
|
"type": "named",
|
|
23
23
|
"name": "--root",
|
|
24
24
|
"description": "Absolute path to one OKF bundle root.",
|
|
25
|
-
"isRequired":
|
|
25
|
+
"isRequired": false,
|
|
26
26
|
"format": "filepath",
|
|
27
27
|
"placeholder": "/absolute/path/to/okf-root"
|
|
28
28
|
},
|
|
29
|
+
{
|
|
30
|
+
"type": "named",
|
|
31
|
+
"name": "--project",
|
|
32
|
+
"description": "Absolute path to an optional federated OKF project, including configured producers.",
|
|
33
|
+
"isRequired": false,
|
|
34
|
+
"format": "filepath",
|
|
35
|
+
"placeholder": "/absolute/path/to/okf.project.yaml"
|
|
36
|
+
},
|
|
29
37
|
{
|
|
30
38
|
"type": "positional",
|
|
31
39
|
"value": "mcp"
|