@mfdaves/okf-mcp 0.8.0 → 0.9.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (31) hide show
  1. package/README.md +74 -14
  2. package/okf/{bundles/okf-mcp → okf-mcp}/distribution/reference-bundle.md +1 -1
  3. package/okf/{bundles/okf-mcp → okf-mcp}/index.md +3 -0
  4. package/okf/{bundles/okf-mcp → okf-mcp}/interfaces/mcp-tools.md +9 -1
  5. package/okf/{bundles/okf-mcp → okf-mcp}/overview/okf-mcp.md +5 -3
  6. package/okf/{bundles/okf-mcp → okf-mcp}/policies/authoring-safety.md +8 -0
  7. package/okf/{bundles/okf-mcp → okf-mcp}/runtime/file-concept-store.md +1 -1
  8. package/okf/{bundles/okf-mcp → okf-mcp}/runtime/mcp-server.md +6 -2
  9. package/okf/okf-mcp/runtime/producer-host.md +28 -0
  10. package/okf/okf-mcp/specs/producer-api.md +26 -0
  11. package/okf/okf-mcp/workflows/producer-publication.md +28 -0
  12. package/okf.project.yaml +1 -1
  13. package/package.json +2 -2
  14. package/server.json +11 -3
  15. package/src/authoring.js +10 -2
  16. package/src/cli.js +46 -4
  17. package/src/index.js +2 -0
  18. package/src/indexer.js +8 -1
  19. package/src/mcp-server.js +95 -0
  20. package/src/producer-publisher.js +462 -0
  21. package/src/producers.js +507 -0
  22. package/src/project.js +65 -0
  23. package/src/store.js +1 -0
  24. /package/okf/{bundles/okf-mcp → okf-mcp}/interfaces/http-authoring-api.md +0 -0
  25. /package/okf/{bundles/okf-mcp → okf-mcp}/runtime/indexer.md +0 -0
  26. /package/okf/{bundles/okf-mcp → okf-mcp}/specs/attested-computation.md +0 -0
  27. /package/okf/{bundles/okf-mcp → okf-mcp}/specs/concept-format.md +0 -0
  28. /package/okf/{bundles/okf-mcp → okf-mcp}/specs/git-sources.md +0 -0
  29. /package/okf/{bundles/okf-mcp → okf-mcp}/workflows/concept-authoring.md +0 -0
  30. /package/okf/{bundles/okf-mcp → okf-mcp}/workflows/concept-update.md +0 -0
  31. /package/okf/{bundles/okf-mcp → okf-mcp}/workflows/v02-migration.md +0 -0
package/README.md CHANGED
@@ -1,8 +1,10 @@
1
1
  # okf-mcp
2
2
 
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).
3
+ `okf-mcp` publishes [Open Knowledge Format v0.2](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) from the systems that already hold the knowledge, and serves the result to agents. It is a local-first consumer, validator, graph index, CLI, and MCP server.
4
4
 
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.
5
+ The part that is hard is writing to a catalog safely. A configured producer reads an external source and returns a candidate bundle; okf-mcp validates it, then publishes it under an ownership manifest that records exactly which files it owns. Hand-authored content is never adopted, a source that did not change rewrites nothing, and no producer output escapes its bundle. [`@mfdaves/okf-postgres`](https://github.com/mfdaves/okf-postgres) reads PostgreSQL catalogs this way without reading a single table row.
6
+
7
+ Reading is the ordinary half. It consumes an OKF bundle directory of Markdown files with YAML frontmatter. An optional workspace mode can federate several bundles. Concepts are exposed through CLI commands and MCP resources and tools for validation, structured search, graph navigation, provenance inspection, and proposal-based authoring.
6
8
 
7
9
  The core intentionally has no database, embeddings, build step, or hosted-service dependency. It uses `js-yaml` for safe YAML, CommonMark for Markdown structure, MiniSearch for in-memory BM25+ text retrieval, and the official Model Context Protocol TypeScript SDK v2 for stdio MCP. Local root mode makes no network calls. Optional remote loading fetches public Markdown concepts and only their explicitly referenced inert assets from GitHub. Nothing in the v0.2 computation support executes code or attests a receipt.
8
10
 
@@ -35,7 +37,7 @@ Node 22 or newer is required.
35
37
  Install from the GitHub release:
36
38
 
37
39
  ```bash
38
- git clone --branch v0.8.0 https://github.com/mfdaves/okf-mcp.git
40
+ git clone --branch v0.9.1 https://github.com/mfdaves/okf-mcp.git
39
41
  cd okf-mcp
40
42
  npm ci
41
43
  node bin/okf-mcp.js --root ./path/to/okf validate
@@ -44,14 +46,14 @@ node bin/okf-mcp.js --root ./path/to/okf validate
44
46
  Pin the published version for reproducible use:
45
47
 
46
48
  ```bash
47
- npx -y @mfdaves/okf-mcp@0.8.0 --version
48
- npx -y @mfdaves/okf-mcp@0.8.0 --root ./path/to/okf validate
49
+ npx -y @mfdaves/okf-mcp@0.9.1 --version
50
+ npx -y @mfdaves/okf-mcp@0.9.1 --root ./path/to/okf validate
49
51
  ```
50
52
 
51
53
  For a persistent installation:
52
54
 
53
55
  ```bash
54
- npm install --global @mfdaves/okf-mcp@0.8.0
56
+ npm install --global @mfdaves/okf-mcp@0.9.1
55
57
 
56
58
  okf --version
57
59
  okf --root ./path/to/okf validate
@@ -87,23 +89,28 @@ This repository publishes a self-describing OKF bundle for the product, its runt
87
89
  Validate and query the bundled reference from a checkout or installed package:
88
90
 
89
91
  ```bash
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
92
+ okf --root okf/okf-mcp validate
93
+ okf --root okf/okf-mcp search "proposal"
94
+ okf --root okf/okf-mcp concept overview/okf-mcp
93
95
  ```
94
96
 
95
- Load the reference bundle directly from this release:
97
+ Load the reference bundle directly from the current source branch:
96
98
 
97
99
  ```bash
98
- okf --remote-bundle okf-mcp=https://github.com/mfdaves/okf-mcp/tree/v0.8.0/okf/bundles/okf-mcp --inspect
100
+ okf --remote-bundle okf-mcp=https://github.com/mfdaves/okf-mcp/tree/main/okf/okf-mcp --inspect
99
101
  ```
100
102
 
103
+ The published `v0.8.0` tag retains its original
104
+ `okf/bundles/okf-mcp` path. The shorter `okf/okf-mcp` path was prepared in the
105
+ unpublished `0.8.1` maintenance checkpoint and ships with `v0.9.0`; the
106
+ immutable `v0.8.0` release remains unchanged.
107
+
101
108
  The `@mfdaves/okf-mcp` npm package includes both `okf.project.yaml` and the
102
109
  complete reference bundle.
103
110
 
104
111
  ## Optional Multi-Bundle Project Config
105
112
 
106
- Use `okf.project.yaml` only when one process must federate multiple roots, configure generators, or enforce a project-wide relation vocabulary:
113
+ 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
114
 
108
115
  ```yaml
109
116
  project: Example
@@ -115,6 +122,8 @@ bundles:
115
122
  exclude: ["archive/**"]
116
123
  - id: data
117
124
  root: okf/bundles/data
125
+ - id: company-database
126
+ root: okf/company-database
118
127
  relationTypes:
119
128
  - deployed_by
120
129
  remoteBundles:
@@ -128,6 +137,16 @@ plugins:
128
137
  root: docs
129
138
  output: okf/bundles/app/generated/docs
130
139
  bundle: app
140
+ producers:
141
+ - name: main-database
142
+ type: postgresql
143
+ package: "@mfdaves/okf-postgres"
144
+ bundle: company-database
145
+ config:
146
+ connectionEnv: DATABASE_URL
147
+ source: company-db
148
+ schemas: [public]
149
+ includeIndexes: true
131
150
  ```
132
151
 
133
152
  Run project commands:
@@ -137,6 +156,9 @@ okf --project okf.project.yaml validate
137
156
  okf --project okf.project.yaml search "orders"
138
157
  okf --project okf.project.yaml graph mermaid
139
158
  okf --project okf.project.yaml generate
159
+ okf --project okf.project.yaml producer list
160
+ okf --project okf.project.yaml producer preview main-database
161
+ okf --project okf.project.yaml producer run main-database --write --actor process:nightly-refresh
140
162
  okf --project okf.project.yaml mcp
141
163
  okf --project okf.project.yaml mcp --authoring
142
164
  okf --project okf.project.yaml mcp --allow-remote-tool
@@ -160,8 +182,43 @@ Commands:
160
182
  - `source <concept-id-or-locator> <source-id>`
161
183
  - `migrate check|preview`
162
184
  - `generate`
185
+ - `producer list|preview|run`
163
186
  - `serve`
164
187
 
188
+ ### External metadata producers
189
+
190
+ 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.
191
+
192
+ 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.
193
+
194
+ 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.
195
+
196
+ Both interfaces run the same host. Use the CLI for scheduled refreshes:
197
+
198
+ ```bash
199
+ okf --project okf.project.yaml producer preview main-database
200
+ okf --project okf.project.yaml producer run main-database --write --actor process:nightly-refresh
201
+ ```
202
+
203
+ `producer preview` exits `1` when the candidate is invalid; `producer run` exits `1` when nothing was published. Both print the same receipt the MCP tools return.
204
+
205
+ For a configured project, MCP exposes:
206
+
207
+ - `okf_list_producers`: list configuration without loading package code or reading the source
208
+ - `okf_preview_producer`: read source metadata and return a validated, non-writing diff
209
+ - `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
210
+
211
+ 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.
212
+
213
+ Two rules keep a managed bundle stable across repeated runs:
214
+
215
+ - A producer restamps `generated.at` on every run. The host compares each candidate against the published file ignoring that stamp, so a source that did not change reports `unchanged` and leaves the bytes, the timestamps, and the manifest untouched. Publication-diff counts therefore describe the source, not the run.
216
+ - A manifest entry alone is not authority to destroy work. Any file the host would rewrite or remove must itself carry `generated` provenance, so a damaged, hand-merged, or forged manifest cannot make a producer delete hand-authored content.
217
+
218
+ Directories emptied by a stale deletion are removed with their last managed file.
219
+
220
+ `@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.
221
+
165
222
  `serve` options:
166
223
 
167
224
  - `--host <host>`: bind host, default `127.0.0.1`
@@ -182,7 +239,7 @@ Example client configuration:
182
239
  "command": "npx",
183
240
  "args": [
184
241
  "-y",
185
- "@mfdaves/okf-mcp@0.8.0",
242
+ "@mfdaves/okf-mcp@0.9.1",
186
243
  "--root",
187
244
  "/absolute/path/to/okf",
188
245
  "mcp"
@@ -201,7 +258,7 @@ Project config mode, with read-only project helpers but without proposal mutatio
201
258
  "command": "npx",
202
259
  "args": [
203
260
  "-y",
204
- "@mfdaves/okf-mcp@0.8.0",
261
+ "@mfdaves/okf-mcp@0.9.1",
205
262
  "--project",
206
263
  "/absolute/path/to/repo/okf.project.yaml",
207
264
  "mcp"
@@ -318,6 +375,9 @@ okf --root /path/to/catalog \
318
375
  - `okf_reject_proposal`
319
376
  - `okf_validate_changes`
320
377
  - `okf_apply_changes`
378
+ - `okf_list_producers`
379
+ - `okf_preview_producer`
380
+ - `okf_run_producer`
321
381
  - `get_graph`
322
382
  - `get_neighbors`
323
383
  - `get_subgraph`
@@ -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/bundles/okf-mcp`
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,6 +25,8 @@ 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
@@ -41,6 +45,10 @@ 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
 
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
+
44
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.
@@ -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 proposal-based authoring runtime.
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
@@ -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 and direct live planning/apply share one process-local writer queue. Read-only batch 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 batch; 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.
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. Proposal mutation tools remain disabled unless the server starts with `--authoring`; live batch tools remain disabled unless it starts with `--write --actor <actor>`; runtime remote loading remains disabled unless it starts with `--allow-remote-tool`.
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.
@@ -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.
@@ -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
@@ -1,5 +1,5 @@
1
1
  project: okf-mcp
2
2
  bundles:
3
3
  - id: okf-mcp
4
- root: okf/bundles/okf-mcp
4
+ root: okf/okf-mcp
5
5
  include: ["*.md", "**/*.md"]
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mfdaves/okf-mcp",
3
- "version": "0.8.0",
3
+ "version": "0.9.1",
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/bundles/okf-mcp validate",
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.8.0",
11
+ "version": "0.9.1",
12
12
  "packages": [
13
13
  {
14
14
  "registryType": "npm",
15
15
  "identifier": "@mfdaves/okf-mcp",
16
- "version": "0.8.0",
16
+ "version": "0.9.1",
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": true,
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"
package/src/authoring.js CHANGED
@@ -30,11 +30,19 @@ function slug(value, fallback) {
30
30
  }
31
31
 
32
32
  function isConfiguredGeneratorOutput(project, absolutePath) {
33
- return Boolean(project && project.root && absolutePath && (project.plugins || []).some((plugin) => {
33
+ if (!project || !project.root || !absolutePath) return false;
34
+ const pluginOutput = (project.plugins || []).some((plugin) => {
34
35
  if (!plugin || !plugin.output) return false;
35
36
  const relative = path.relative(path.resolve(project.root, String(plugin.output)), absolutePath);
36
37
  return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
37
- }));
38
+ });
39
+ if (pluginOutput) return true;
40
+ const managedBundles = new Set((project.producers || []).map((producer) => producer && producer.bundle));
41
+ return (project.bundles || []).some((bundle) => {
42
+ if (!bundle || !managedBundles.has(bundle.id)) return false;
43
+ const relative = path.relative(path.resolve(bundle.root), absolutePath);
44
+ return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
45
+ });
38
46
  }
39
47
 
40
48
  function normalizeConceptPath(value) {
package/src/cli.js CHANGED
@@ -15,6 +15,8 @@ const { searchConcepts } = require("./search");
15
15
  const { conceptSummary } = require("./indexer");
16
16
  const { findOkfRoot, findProjectConfig, loadProjectConfig } = require("./project");
17
17
  const { generateProject } = require("./plugins");
18
+ const { ProducerService, producerReceipt } = require("./producers");
19
+ const { FileConceptStore } = require("./store");
18
20
  const { runStdioServer } = require("./mcp-server");
19
21
  const { fetchRemoteBundles } = require("./remote");
20
22
  const { runHttpServer } = require("./http-server");
@@ -32,8 +34,10 @@ const packageMetadata = require("../package.json");
32
34
 
33
35
  const COMMANDS = new Set([
34
36
  "mcp", "validate", "graph", "search", "concept", "neighbors", "paths", "generate", "serve",
35
- "provenance", "edge-kinds", "computation", "asset", "source", "migrate",
37
+ "provenance", "edge-kinds", "computation", "asset", "source", "migrate", "producer",
36
38
  ]);
39
+ const PRODUCER_ACTIONS = new Set(["list", "preview", "run"]);
40
+ const WRITE_COMMANDS = new Set(["mcp", "producer"]);
37
41
 
38
42
  class UsageError extends Error {
39
43
  constructor(message) {
@@ -459,6 +463,7 @@ function usage() {
459
463
  " okf-mcp --project <okf.project.yaml> <command>",
460
464
  " okf-mcp [--project <okf.project.yaml>] [--authoring] [--write --actor <actor>] [--git-commit] mcp",
461
465
  " okf-mcp --project <okf.project.yaml> serve [--host 127.0.0.1] [--port 8765]",
466
+ " okf-mcp --project <okf.project.yaml> producer run <name> --write --actor <actor>",
462
467
  " okf-mcp <command> --bundle <path-or-id=path>",
463
468
  "",
464
469
  "Commands:",
@@ -479,6 +484,9 @@ function usage() {
479
484
  " migrate check [bundle] Check staged v0.2 migration readiness.",
480
485
  " migrate preview [bundle] [actor-mappings-json]",
481
486
  " generate Run configured generator plugins.",
487
+ " producer list List configured external metadata producers.",
488
+ " producer preview <name> Validate one producer's candidate bundle without writing.",
489
+ " producer run <name> Publish one producer (requires --write --actor).",
482
490
  " serve Start the HTTP OKF API server.",
483
491
  "",
484
492
  "Options:",
@@ -486,7 +494,7 @@ function usage() {
486
494
  " --repo <concept-id=path> Map a Git Repository concept to a checkout or bare repo; repeatable.",
487
495
  " --authoring Enable MCP proposal authoring tools.",
488
496
  " --write Enable direct validated-batch MCP concept writes (requires --actor).",
489
- " --actor <actor> Stamp live writes with human:id, process:id, or provider/model.",
497
+ " --actor <actor> Stamp live writes and producer runs with human:id, process:id, or provider/model.",
490
498
  " --git-commit Commit each live write batch when the catalog is in a clean Git repo.",
491
499
  " --allow-remote-tool Enable runtime remote-bundle loading over MCP.",
492
500
  " --allow-computation-authoring Enable coordinated computation proposals (also requires --authoring).",
@@ -668,8 +676,11 @@ async function main(argv, runtime) {
668
676
  if (!COMMANDS.has(command)) {
669
677
  throw usageError(`Unknown OKF command: ${command}`);
670
678
  }
671
- if (command !== "mcp" && (args.write || args.actor || args.gitCommit)) {
672
- throw usageError("--write, --actor, and --git-commit are available only with the mcp command.");
679
+ if (!WRITE_COMMANDS.has(command) && (args.write || args.actor || args.gitCommit)) {
680
+ throw usageError("--write, --actor, and --git-commit are available only with the mcp and producer commands.");
681
+ }
682
+ if (command === "producer" && args.gitCommit) {
683
+ throw usageError("--git-commit is available only with the mcp command.");
673
684
  }
674
685
  if (command === "mcp") {
675
686
  const bundles = resolveLegacyBundles(args);
@@ -716,6 +727,37 @@ async function main(argv, runtime) {
716
727
  printJson(generateProject(project));
717
728
  return;
718
729
  }
730
+ if (command === "producer") {
731
+ if (!args.project) {
732
+ throw usageError("producer requires --project.");
733
+ }
734
+ const action = args.positional[1] || "list";
735
+ if (!PRODUCER_ACTIONS.has(action)) {
736
+ throw usageError("producer action must be list, preview, or run.");
737
+ }
738
+ const loaded = await loadProjectBundles(args.project);
739
+ const service = new ProducerService({
740
+ project: loaded.project,
741
+ store: FileConceptStore.fromProject(args.project, { proposalRoot: args.proposalRoot || "" }),
742
+ bundles: (loaded.bundles || []).filter((bundle) => !bundle.remote),
743
+ });
744
+ if (action === "list") {
745
+ printJson(service.list());
746
+ return;
747
+ }
748
+ const name = args.positional[2];
749
+ if (!name) {
750
+ throw usageError(`producer ${action} requires a configured producer name.`);
751
+ }
752
+ if (action === "run" && !args.write) {
753
+ throw usageError("producer run requires --write --actor <human:id|process:id|provider/model>.");
754
+ }
755
+ const receipt = action === "run" ? await service.run(name) : await service.preview(name);
756
+ printJson(producerReceipt(receipt, "full"));
757
+ const succeeded = action === "run" ? receipt.applied === true : receipt.valid === true;
758
+ process.exitCode = succeeded ? 0 : 1;
759
+ return;
760
+ }
719
761
  const index = await loadIndex(args);
720
762
  const repositoryMappings = parseRepositoryMappings(args.repositories);
721
763
  if (command === "validate") {