@mfdaves/okf-mcp 0.5.0 → 0.6.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 CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  It consumes an OKF bundle directory of Markdown files with YAML frontmatter. An optional workspace mode can federate several bundles. Concepts are exposed through CLI commands and MCP resources and tools for validation, structured search, graph navigation, provenance inspection, and proposal-based authoring.
6
6
 
7
- The core intentionally has no database, embeddings, build step, or hosted-service dependency. It uses `js-yaml` for safe YAML, CommonMark for Markdown structure, and the official Model Context Protocol TypeScript SDK v2 for stdio MCP. Local root mode makes no network calls. Optional remote loading fetches public Markdown concepts and only their explicitly referenced inert assets from GitHub. Nothing in the v0.2 computation support executes code or attests a receipt.
7
+ The core intentionally has no database, embeddings, build step, or hosted-service dependency. It uses `js-yaml` for safe YAML, CommonMark for Markdown structure, 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
8
 
9
9
  ## OKF v0.2 Support And Extensions
10
10
 
@@ -35,23 +35,23 @@ Node 22 or newer is required.
35
35
  Install from the GitHub release:
36
36
 
37
37
  ```bash
38
- git clone --branch v0.5.0 https://github.com/mfdaves/okf-mcp.git
38
+ git clone --branch v0.6.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
42
42
  ```
43
43
 
44
- After version `0.5.0` is published on npm, pin it for reproducible use:
44
+ Pin the published version for reproducible use:
45
45
 
46
46
  ```bash
47
- npx -y @mfdaves/okf-mcp@0.5.0 --version
48
- npx -y @mfdaves/okf-mcp@0.5.0 --root ./path/to/okf validate
47
+ npx -y @mfdaves/okf-mcp@0.6.0 --version
48
+ npx -y @mfdaves/okf-mcp@0.6.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.5.0
54
+ npm install --global @mfdaves/okf-mcp@0.6.0
55
55
 
56
56
  okf --version
57
57
  okf --root ./path/to/okf validate
@@ -95,7 +95,7 @@ okf --root okf/bundles/okf-mcp concept overview/okf-mcp
95
95
  Load the reference bundle directly from this release:
96
96
 
97
97
  ```bash
98
- okf --remote-bundle okf-mcp=https://github.com/mfdaves/okf-mcp/tree/v0.5.0/okf/bundles/okf-mcp --inspect
98
+ okf --remote-bundle okf-mcp=https://github.com/mfdaves/okf-mcp/tree/v0.6.0/okf/bundles/okf-mcp --inspect
99
99
  ```
100
100
 
101
101
  The `@mfdaves/okf-mcp` npm package includes both `okf.project.yaml` and the
@@ -171,7 +171,7 @@ Commands:
171
171
 
172
172
  ## MCP Client Config
173
173
 
174
- The npm-based examples below apply after version `0.5.0` is published there. A source checkout can invoke its executable `bin/okf-mcp.js` with the same arguments.
174
+ The npm-based examples below use the current published release. A source checkout can invoke its executable `bin/okf-mcp.js` with the same arguments.
175
175
 
176
176
  Example client configuration:
177
177
 
@@ -182,7 +182,7 @@ Example client configuration:
182
182
  "command": "npx",
183
183
  "args": [
184
184
  "-y",
185
- "@mfdaves/okf-mcp@0.5.0",
185
+ "@mfdaves/okf-mcp@0.6.0",
186
186
  "--root",
187
187
  "/absolute/path/to/okf",
188
188
  "mcp"
@@ -201,7 +201,7 @@ Project config mode, with read-only project helpers but without proposal mutatio
201
201
  "command": "npx",
202
202
  "args": [
203
203
  "-y",
204
- "@mfdaves/okf-mcp@0.5.0",
204
+ "@mfdaves/okf-mcp@0.6.0",
205
205
  "--project",
206
206
  "/absolute/path/to/repo/okf.project.yaml",
207
207
  "mcp"
@@ -211,7 +211,7 @@ Project config mode, with read-only project helpers but without proposal mutatio
211
211
  }
212
212
  ```
213
213
 
214
- Add `--authoring` to enable proposal creation, acceptance, and rejection. Add `--allow-remote-tool` to let MCP clients load arbitrary supported public remote bundles at runtime. Configured remote bundles remain readable without that runtime-loading flag.
214
+ Add `--authoring` to enable proposal creation, acceptance, and rejection. For a smaller direct-write surface, add `--write --actor <actor>` to expose one transactional `okf_apply_changes` tool; add `--git-commit` to commit each successful batch when the catalog is in a clean Git worktree. Add `--allow-remote-tool` to let MCP clients load arbitrary supported public remote bundles at runtime. Configured remote bundles remain readable without that runtime-loading flag.
215
215
 
216
216
  The stdio server uses `@modelcontextprotocol/server` v2. It serves the modern
217
217
  `2026-07-28` MCP revision and the SDK's compatibility path for 2025-era
@@ -316,6 +316,7 @@ okf --root /path/to/catalog \
316
316
  - `okf_get_proposal`
317
317
  - `okf_accept_proposal`
318
318
  - `okf_reject_proposal`
319
+ - `okf_apply_changes`
319
320
  - `get_graph`
320
321
  - `get_neighbors`
321
322
  - `get_subgraph`
@@ -336,20 +337,59 @@ disabled tool names remain protocol-level invalid-parameter errors.
336
337
 
337
338
  Tool discovery and direct invocation use the same capability checks:
338
339
 
339
- | Mode | Normal proposals | Computation proposal | Runtime remote load |
340
- | --- | --- | --- | --- |
341
- | default | disabled | disabled | disabled |
342
- | `--authoring` | enabled | disabled | disabled |
343
- | `--authoring --allow-computation-authoring` | enabled | enabled | disabled |
344
- | `--allow-remote-tool` | disabled | disabled | enabled |
340
+ | Mode | Normal proposals | Direct live write | Computation proposal | Runtime remote load |
341
+ | --- | --- | --- | --- | --- |
342
+ | default | disabled | disabled | disabled | disabled |
343
+ | `--authoring` | enabled | disabled | disabled | disabled |
344
+ | `--write --actor openai/gpt-5.6` | disabled | enabled | disabled | disabled |
345
+ | `--authoring --allow-computation-authoring` | enabled | disabled | enabled | disabled |
346
+ | `--allow-remote-tool` | disabled | disabled | disabled | enabled |
345
347
 
346
- An explicit local root or project workspace exposes concept validation, path suggestion, and proposal inspection helpers. The `okf_*` mutation tools are proposal-first and require `--authoring`. In normal single-root mode, callers omit `bundle`; it is required only to select among multiple project roots. Proposing a concept or update writes only a proposal record. Acceptance writes Markdown inside the selected local root and rebuilds the index; remote roots remain read only.
348
+ An explicit local root or project workspace exposes concept validation, path suggestion, and proposal inspection helpers. Proposal mutation tools require `--authoring`. The direct live tool instead requires `--write` plus a truthful actor using `human:<id>`, `process:<id>`, or `provider/model` syntax. In normal single-root mode, callers omit `bundle`; it is required only to select among multiple project roots. Remote roots remain read only.
347
349
 
348
350
  Generic concept tools cannot create or change an Attested Computation contract. `okf_propose_attested_computation` additionally requires `--allow-computation-authoring` and creates one coordinated review proposal for the concept plus an optional external computation file.
349
351
 
352
+ ## Live Concept Authoring
353
+
354
+ Start the server with the direct-write capability only when the MCP client/user approval boundary is sufficient review:
355
+
356
+ ```bash
357
+ okf --root /path/to/catalog --write --actor openai/gpt-5.6 mcp
358
+ ```
359
+
360
+ The agent sees one destructive tool. It supplies structured concept fields rather than YAML; OKF serializes compatible Markdown frontmatter and stamps the configured `generated.by` plus one `generated.at` timestamp for the whole batch.
361
+
362
+ ```json
363
+ {
364
+ "name": "okf_apply_changes",
365
+ "arguments": {
366
+ "message": "docs(okf): document order creation",
367
+ "changes": [
368
+ {
369
+ "op": "create",
370
+ "type": "MCP Tool",
371
+ "title": "Create Order",
372
+ "body": "# Create Order\n\nCreates a validated order.",
373
+ "tags": ["orders", "mcp"],
374
+ "sources": ["/repositories/orders-service.md"],
375
+ "relations": [
376
+ { "type": "related_to", "target": "/workflows/order-creation.md" }
377
+ ]
378
+ }
379
+ ]
380
+ }
381
+ }
382
+ ```
383
+
384
+ Create paths are optional and derive deterministically from type and title. Updates identify an existing `uri`; scalar fields replace existing values, while `tags`, `sources`, and `relations` use explicit `add`/`remove` patches. `metadata` carries extension frontmatter but cannot override identity, generation, collection, or computation fields.
385
+
386
+ Every 1–100 item batch is validated as one future graph, so concepts created together can reference one another. 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, reserved files, and Attested Computation contracts are not live-write targets.
387
+
388
+ Add `--git-commit` as server policy to create one commit per successful batch. A detected Git worktree must be completely clean and have a configured identity before any file is staged. The tool never pushes. Non-Git catalogs are written normally; if staging or commit fails after valid files were written, the result is `applied_uncommitted` and includes the Git error so the work remains recoverable.
389
+
350
390
  ## Authoring Concepts
351
391
 
352
- Concept authoring is available through MCP tools started with `--authoring` and through the HTTP API. Clients never need direct local file access.
392
+ The reviewable proposal workflow remains available through MCP tools started with `--authoring` and through the HTTP API. Clients never need direct local file access.
353
393
 
354
394
  MCP proposal flow:
355
395
 
@@ -405,6 +445,8 @@ Safety rules:
405
445
  - updates cannot change concept identity and reject detected changes made after proposal creation
406
446
  - invalid IDs, invalid relation types, and broken internal OKF relations fail validation
407
447
  - external relation targets such as `repo://...` are allowed
448
+ - direct batches are serialized within one process and validate the combined future graph before publication
449
+ - independent processes still require external single-writer coordination
408
450
 
409
451
  ## HTTP API
410
452
 
@@ -502,7 +544,16 @@ Use `list_remote_bundles` to inspect what was loaded.
502
544
  - `offset`
503
545
 
504
546
  `list_concepts` also accepts a text `query` and applies it together with its
505
- listing filters. Tags and types are matched case-insensitively. Arbitrary
547
+ listing filters. Text search tokenizes case-insensitively and requires every
548
+ query term, regardless of order. BM25+ ranks title, type, tags, aliases,
549
+ description, path, and body matches; frontmatter remains available through
550
+ exact structured filters but is not copied into the text index. Scores are
551
+ relative within a result set and are not a stable cross-version scale.
552
+
553
+ Queries are bounded to 512 characters and 16 terms. Prefix expansion, fuzzy
554
+ matching, stemming, and stop-word removal are intentionally disabled so code
555
+ identifiers and domain terminology remain literal. Punctuation-only queries
556
+ return no matches. Tags and types are matched case-insensitively. Arbitrary
506
557
  frontmatter filters support exact scalar matching and array-contains
507
558
  matching. `relationType` selects concepts with an outgoing relation of that
508
559
  type.
@@ -518,6 +569,21 @@ Example:
518
569
  }
519
570
  ```
520
571
 
572
+ For local relevance and performance checks, run the non-packaged development
573
+ benchmark with a bundle root and an optional JSON array of `{ "query": "...",
574
+ "expected": "path/or/concept-id" }` judgments:
575
+
576
+ ```bash
577
+ node --expose-gc scripts/search-benchmark.js \
578
+ --root /path/to/okf \
579
+ --qrels /path/to/qrels.json
580
+ ```
581
+
582
+ It reports OKF and search-index build time, retained heap/RSS, p50/p95 query
583
+ latency, Recall@10, MRR@10, and representative rankings. Search indexes are
584
+ process-local and keyed to the parsed OKF index, so remote loads and accepted
585
+ proposals receive a fresh index automatically.
586
+
521
587
  ## Graph Behavior
522
588
 
523
589
  As an okf-mcp graph projection, Markdown links become `markdown_link` edges, extension `relations` become typed `relation` edges, and standard v0.2 path-valued fields become `resource`, `source`, `computation`, `executor`, and `attester` edges. Internal concept references resolve to canonical nodes; explicitly referenced non-Markdown files resolve to okf-mcp `okf-asset://` nodes; URLs and scope descriptors remain unfetched external or opaque leaves.
@@ -17,13 +17,15 @@ relations:
17
17
  target: repo://test/okf-mcp.test.js
18
18
  - type: checked_by
19
19
  target: repo://test/mcp-hardening.test.js
20
+ - type: checked_by
21
+ target: repo://test/live-authoring.test.js
20
22
  ---
21
23
 
22
24
  # MCP Tool Catalog
23
25
 
24
26
  The MCP interface groups tools by intent.
25
27
 
26
- 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 filters lifecycle, trust, freshness at a deterministic date, source presence, generator or verifier actors, runtime, and static attestation readiness.
28
+ 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.
27
29
 
28
30
  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. Extensionless canonical, `.md`, and custom-id aliases are accepted for lookup.
29
31
 
@@ -33,10 +35,12 @@ Static computation tools inspect contracts, read indexed assets, prepare paramet
33
35
 
34
36
  `read_git_source` reads one pinned `sources[].git` entry from a checkout or bare repository explicitly mapped by the MCP host. It reads the Git object database rather than the working tree and never fetches.
35
37
 
36
- 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`. Runtime calls to `load_remote_bundle` require `--allow-remote-tool`.
38
+ 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 only `okf_apply_changes`, which accepts structured create/update batches without requiring agents to compose YAML. Runtime calls to `load_remote_bundle` require `--allow-remote-tool`.
39
+
40
+ `okf_apply_changes` validates 1–100 operations as one future graph, stamps one server-owned `generated.at` with the configured `generated.by`, then publishes the complete local batch and refreshes the index. Optional `--git-commit` policy creates one scoped commit from a clean worktree. Commit failure leaves valid files applied and reports `applied_uncommitted`; the tool never pushes.
37
41
 
38
42
  Every tool supplies a purpose-specific description, descriptions for all input parameters, and MCP annotations for read behavior, destructive behavior, idempotency, and external access. Tool discovery and direct invocation use the same capability checks, so a hidden tool also fails when called by name. Annotations remain hints to clients; server-side validation is authoritative.
39
43
 
40
44
  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.
41
45
 
42
- `list_concepts` applies its optional text query together with its structured filters. Relation-type filtering selects concepts with an outgoing relation of the requested type.
46
+ `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.
@@ -21,7 +21,7 @@ relations:
21
21
 
22
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.
23
23
 
24
- The runtime uses `js-yaml` and CommonMark and 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.
24
+ 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
25
 
26
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).
27
27
 
@@ -15,15 +15,19 @@ relations:
15
15
  target: repo://src/authoring.js
16
16
  - type: configured_by
17
17
  target: repo://src/store.js
18
+ - type: configured_by
19
+ target: repo://src/live-authoring.js
18
20
  - type: checked_by
19
21
  target: repo://test/okf-mcp.test.js
20
22
  - type: checked_by
21
23
  target: repo://test/mcp-hardening.test.js
24
+ - type: checked_by
25
+ target: repo://test/live-authoring.test.js
22
26
  ---
23
27
 
24
28
  # Authoring Safety
25
29
 
26
- Authoring is allowed for an explicit local `--root` or local roots declared by `okf.project.yaml`. MCP proposal mutations require `--authoring`; coordinated computation proposals also require `--allow-computation-authoring`. Remote roots are read only.
30
+ Authoring is allowed for an explicit local `--root` or local roots declared by `okf.project.yaml`. MCP proposal mutations require `--authoring`; coordinated computation proposals also require `--allow-computation-authoring`. Direct authoring requires `--write` and a configured actor. Remote roots are read only.
27
31
 
28
32
  Concept paths must be safe relative `.md` paths inside the selected bundle. Absolute paths, parent traversal, reserved `index.md` and `log.md` targets, symbolic-link traversal, and non-directory parents are rejected.
29
33
 
@@ -33,6 +37,8 @@ Candidates must satisfy the concept format, configured relation vocabulary, and
33
37
 
34
38
  Proposal creation never writes a concept file. Acceptance repeats validation. Updates also compare the source revision immediately before replacement and return conflicts for detected concurrent changes. After acceptance, the MCP index is rebuilt without discarding configured or runtime-loaded remote bundle state.
35
39
 
40
+ Direct authoring exposes one destructive batch tool. It validates the combined future graph, stamps generation metadata at the server boundary, serializes batches under one process-local writer lock, stages every file before publication, and rolls back its published files on write or post-write validation failure. It rejects generated-file flags, `process:*` generation owners, configured generator outputs, and computation contracts. Optional Git commits require a clean worktree before any write and never push; a commit failure leaves the valid batch visible as applied but uncommitted.
41
+
36
42
  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.
37
43
 
38
44
  HTTP mutations require bearer authorization. Filesystem safeguards still apply after authentication.
@@ -2,8 +2,8 @@
2
2
  id: okf://okf-mcp/runtime/file-concept-store
3
3
  type: OKF Runtime Component
4
4
  title: File Concept Store
5
- description: Local proposal and concept persistence boundary used by root and project authoring.
6
- tags: [storage, proposals, authoring, filesystem]
5
+ description: Local proposal, direct-batch, and concept persistence boundary used by root and project authoring.
6
+ tags: [storage, proposals, authoring, filesystem, batch]
7
7
  relations:
8
8
  - type: consumes
9
9
  target: okf://okf-mcp/specs/concept-format
@@ -27,6 +27,8 @@ 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 batches share one process-local writer queue. A direct batch stages every candidate, checks revisions immediately before publication, validates the persisted graph, and restores its own changed files when publication or validation fails. This provides all-or-nothing behavior for ordinary process errors, not crash durability or distributed coordination.
31
+
30
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.
31
33
 
32
34
  This is a local file-backed store intended for a trusted root or project workspace. It is not a distributed transaction system or multi-writer database. Its invariants are defined by the [authoring safety policy](../policies/authoring-safety.md).
@@ -33,6 +33,6 @@ Each indexed Markdown document is exposed as a `text/markdown` resource. The [MC
33
33
 
34
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`; runtime remote loading remains disabled unless it starts with `--allow-remote-tool`.
35
35
 
36
- 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.
36
+ 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
37
 
38
38
  This component is a stdio MCP transport. The separate [HTTP authoring API](../interfaces/http-authoring-api.md) does not implement MCP over HTTP.
@@ -2,8 +2,8 @@
2
2
  id: okf://okf-mcp/workflows/concept-authoring
3
3
  type: OKF Workflow
4
4
  title: Concept Authoring
5
- description: Proposal-first workflow for validating, reviewing, and accepting new OKF concepts.
6
- tags: [workflow, authoring, proposals, review]
5
+ description: Reviewable and direct workflows for validating and persisting structured OKF concept changes.
6
+ tags: [workflow, authoring, proposals, review, batch]
7
7
  relations:
8
8
  - type: depends_on
9
9
  target: okf://okf-mcp/runtime/file-concept-store
@@ -15,11 +15,13 @@ relations:
15
15
  target: okf://okf-mcp/workflows/concept-update
16
16
  - type: configured_by
17
17
  target: repo://src/authoring.js
18
+ - type: configured_by
19
+ target: repo://src/live-authoring.js
18
20
  ---
19
21
 
20
22
  # Concept Authoring
21
23
 
22
- Concept authoring separates proposal from persistence.
24
+ Concept authoring has two explicitly gated persistence paths.
23
25
 
24
26
  First, the candidate bundle, path, frontmatter, body, links, relations, and identity are validated. A valid proposal stores the candidate Markdown and its validation result as a proposal record. It does not create the concept file.
25
27
 
@@ -27,4 +29,8 @@ A reviewer then inspects the proposal and either accepts or rejects it. Acceptan
27
29
 
28
30
  Invalid candidates never become proposals. A proposal that becomes invalid before acceptance remains inspectable and returns the current validation result.
29
31
 
32
+ For a trusted client approval boundary, `--write --actor <actor>` exposes one direct `okf_apply_changes` tool. Agents submit structured concept fields rather than YAML. The server derives optional paths, patches tags/sources/relations, stamps one generation actor and time, validates the complete future graph, and publishes all files or none. Optional Git policy creates one commit for the batch without pushing.
33
+
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
+
30
36
  Corrections to existing concepts follow the related [concept update workflow](concept-update.md). Both paths are governed by the [authoring safety policy](../policies/authoring-safety.md) and persist through the [file concept store](../runtime/file-concept-store.md).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mfdaves/okf-mcp",
3
- "version": "0.5.0",
3
+ "version": "0.6.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": {
@@ -55,7 +55,8 @@
55
55
  "dependencies": {
56
56
  "@modelcontextprotocol/server": "2.0.0",
57
57
  "commonmark": "^0.31.2",
58
- "js-yaml": "^5.2.3"
58
+ "js-yaml": "^5.2.3",
59
+ "minisearch": "7.2.0"
59
60
  },
60
61
  "devDependencies": {
61
62
  "@modelcontextprotocol/client": "2.0.0"
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.5.0",
11
+ "version": "0.6.0",
12
12
  "packages": [
13
13
  {
14
14
  "registryType": "npm",
15
15
  "identifier": "@mfdaves/okf-mcp",
16
- "version": "0.5.0",
16
+ "version": "0.6.0",
17
17
  "transport": {
18
18
  "type": "stdio"
19
19
  },
package/src/cli.js CHANGED
@@ -27,6 +27,7 @@ const {
27
27
  } = require("./computation");
28
28
  const { buildV02MigrationPlan, checkV02Migration } = require("./migration");
29
29
  const { describeConceptGitSources, readConceptGitSource } = require("./git-source");
30
+ const { validActor } = require("./v02");
30
31
  const packageMetadata = require("../package.json");
31
32
 
32
33
  const COMMANDS = new Set([
@@ -90,6 +91,9 @@ function parseArgs(argv) {
90
91
  let proposalRoot = "";
91
92
  let version = false;
92
93
  let authoring = false;
94
+ let write = false;
95
+ let actor = "";
96
+ let gitCommit = false;
93
97
  let allowRemoteTool = false;
94
98
  let strictLinks = false;
95
99
  let allowComputationAuthoring = false;
@@ -201,6 +205,35 @@ function parseArgs(argv) {
201
205
  authoring = true;
202
206
  continue;
203
207
  }
208
+ if (arg === "--write") {
209
+ write = true;
210
+ continue;
211
+ }
212
+ if (arg === "--actor") {
213
+ if (actor) {
214
+ throw usageError("--actor may be supplied only once.");
215
+ }
216
+ if (!argv[index + 1] || String(argv[index + 1]).startsWith("-")) {
217
+ throw usageError("--actor requires a value.");
218
+ }
219
+ actor = argv[index + 1];
220
+ index += 1;
221
+ continue;
222
+ }
223
+ if (arg.startsWith("--actor=")) {
224
+ if (actor) {
225
+ throw usageError("--actor may be supplied only once.");
226
+ }
227
+ actor = arg.slice("--actor=".length);
228
+ if (!actor) {
229
+ throw usageError("--actor requires a value.");
230
+ }
231
+ continue;
232
+ }
233
+ if (arg === "--git-commit") {
234
+ gitCommit = true;
235
+ continue;
236
+ }
204
237
  if (arg === "--allow-remote-tool") {
205
238
  allowRemoteTool = true;
206
239
  continue;
@@ -371,6 +404,18 @@ function parseArgs(argv) {
371
404
  positional.push(arg);
372
405
  }
373
406
  }
407
+ if (write && !actor) {
408
+ throw usageError("--write requires --actor <human:id|process:id|provider/model>.");
409
+ }
410
+ if (write && !validActor(actor)) {
411
+ throw usageError("--actor must use human:<id>, process:<id>, or provider/model syntax.");
412
+ }
413
+ if (actor && !write) {
414
+ throw usageError("--actor requires --write.");
415
+ }
416
+ if (gitCommit && !write) {
417
+ throw usageError("--git-commit requires --write.");
418
+ }
374
419
  return {
375
420
  bundles,
376
421
  remoteBundles,
@@ -382,6 +427,9 @@ function parseArgs(argv) {
382
427
  help,
383
428
  version,
384
429
  authoring,
430
+ write,
431
+ actor,
432
+ gitCommit,
385
433
  allowRemoteTool,
386
434
  allowComputationAuthoring,
387
435
  strictLinks,
@@ -409,7 +457,7 @@ function usage() {
409
457
  " okf-mcp --bundle <path-or-id=path> [--bundle <path>] [--inspect]",
410
458
  " okf-mcp --remote-bundle <id=github-tree-url> [--inspect]",
411
459
  " okf-mcp --project <okf.project.yaml> <command>",
412
- " okf-mcp [--project <okf.project.yaml>] [--authoring] [--allow-computation-authoring] [--allow-remote-tool] mcp",
460
+ " okf-mcp [--project <okf.project.yaml>] [--authoring] [--write --actor <actor>] [--git-commit] mcp",
413
461
  " okf-mcp --project <okf.project.yaml> serve [--host 127.0.0.1] [--port 8765]",
414
462
  " okf-mcp <command> --bundle <path-or-id=path>",
415
463
  "",
@@ -437,6 +485,9 @@ function usage() {
437
485
  " --root, -r <directory> Load one official OKF bundle root.",
438
486
  " --repo <concept-id=path> Map a Git Repository concept to a checkout or bare repo; repeatable.",
439
487
  " --authoring Enable MCP proposal authoring tools.",
488
+ " --write Enable direct atomic MCP concept writes (requires --actor).",
489
+ " --actor <actor> Stamp live writes with human:id, process:id, or provider/model.",
490
+ " --git-commit Commit each live write batch when the catalog is in a clean Git repo.",
440
491
  " --allow-remote-tool Enable runtime remote-bundle loading over MCP.",
441
492
  " --allow-computation-authoring Enable coordinated computation proposals (also requires --authoring).",
442
493
  " --strict-links Treat broken internal Markdown links as project-invalid.",
@@ -448,6 +499,7 @@ function usage() {
448
499
  " --max-content-bytes <n> Bound asset reads to 1..1048576 bytes (default 65536).",
449
500
  " Search filters: --status, --trust-tier, --freshness, --as-of, --has-sources,",
450
501
  " --runtime, --attestation-ready, --frontmatter key=value.",
502
+ " Text search requires all terms and accepts at most 512 characters and 16 terms.",
451
503
  " --version, -v Print the package version.",
452
504
  " --help, -h Print this help.",
453
505
  " --debug Include stack traces in error output.",
@@ -533,6 +585,13 @@ function stdioServerOptions(args) {
533
585
  if (args.authoring && args.allowComputationAuthoring) {
534
586
  options.allowComputationAuthoring = true;
535
587
  }
588
+ if (args.write) {
589
+ options.allowWrite = true;
590
+ options.actor = args.actor;
591
+ if (args.gitCommit) {
592
+ options.gitCommit = true;
593
+ }
594
+ }
536
595
  if (args.strictLinks) {
537
596
  options.strictLinks = true;
538
597
  }
@@ -609,6 +668,9 @@ async function main(argv, runtime) {
609
668
  if (!COMMANDS.has(command)) {
610
669
  throw usageError(`Unknown OKF command: ${command}`);
611
670
  }
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.");
673
+ }
612
674
  if (command === "mcp") {
613
675
  const bundles = resolveLegacyBundles(args);
614
676
  if (args.project) {
package/src/index.js CHANGED
@@ -14,6 +14,7 @@ module.exports = {
14
14
  ...require("./git-source"),
15
15
  ...require("./migration"),
16
16
  ...require("./authoring"),
17
+ ...require("./live-authoring"),
17
18
  ...require("./store"),
18
19
  ...require("./http-server"),
19
20
  ...require("./mcp-server"),
package/src/indexer.js CHANGED
@@ -47,6 +47,10 @@ function parseBundleArg(arg, index) {
47
47
  };
48
48
  }
49
49
 
50
+ function documentOverrideKey(bundleId, relativePath) {
51
+ return `${bundleId}\u0000${normalizeSlashes(relativePath)}`;
52
+ }
53
+
50
54
  function uniqueBundleIds(bundles) {
51
55
  return bundles.map((bundle) => {
52
56
  const base = sanitizeBundleId(bundle.id);
@@ -319,6 +323,9 @@ function semanticReferences(doc) {
319
323
 
320
324
  function buildIndex(bundleArgs, options) {
321
325
  const config = options || {};
326
+ const documentOverrides = config.documentOverrides instanceof Map
327
+ ? config.documentOverrides
328
+ : new Map();
322
329
  const strictLinks = Boolean(config.strictLinks);
323
330
  const requestedBundles = uniqueBundleIds((bundleArgs || []).map(parseBundleArg));
324
331
  const allowedRelationTypes = new Set((config.relationTypes || DEFAULT_RELATION_TYPES).map(String));
@@ -378,13 +385,13 @@ function buildIndex(bundleArgs, options) {
378
385
  errors.push({ code: "missing_bundle_root", bundle: bundle.id, path: bundle.root, message: "Bundle root does not exist." });
379
386
  return;
380
387
  }
381
- walkMarkdown(bundle.root).forEach((filePath) => {
382
- const relativePath = safeRelativePath(bundle.root, filePath) || normalizeSlashes(filePath);
383
- if (!bundleAllowsPath(bundle, relativePath)) {
384
- return;
385
- }
388
+ const indexedPaths = new Set();
389
+ const indexLocalDocument = (relativePath, text, source) => {
390
+ indexedPaths.add(relativePath);
386
391
  try {
387
- const doc = parseMarkdownFile(bundle, filePath, { asOf: config.asOf });
392
+ const doc = text === undefined
393
+ ? parseMarkdownFile(bundle, source, { asOf: config.asOf })
394
+ : parseMarkdownText(bundle, relativePath, text, source, { asOf: config.asOf });
388
395
  documents.push(doc);
389
396
  if (doc.reserved) {
390
397
  reserved.push(doc);
@@ -400,6 +407,33 @@ function buildIndex(bundleArgs, options) {
400
407
  message: error.message,
401
408
  });
402
409
  }
410
+ };
411
+ walkMarkdown(bundle.root).forEach((filePath) => {
412
+ const relativePath = safeRelativePath(bundle.root, filePath) || normalizeSlashes(filePath);
413
+ if (!bundleAllowsPath(bundle, relativePath)) {
414
+ return;
415
+ }
416
+ const key = documentOverrideKey(bundle.id, relativePath);
417
+ indexLocalDocument(
418
+ relativePath,
419
+ documentOverrides.has(key) ? String(documentOverrides.get(key)) : undefined,
420
+ filePath,
421
+ );
422
+ });
423
+ const prefix = `${bundle.id}\u0000`;
424
+ documentOverrides.forEach((text, key) => {
425
+ if (!String(key).startsWith(prefix)) {
426
+ return;
427
+ }
428
+ const relativePath = normalizeSlashes(String(key).slice(prefix.length));
429
+ if (indexedPaths.has(relativePath) || !bundleAllowsPath(bundle, relativePath)) {
430
+ return;
431
+ }
432
+ indexLocalDocument(
433
+ relativePath,
434
+ String(text),
435
+ path.join(bundle.root, ...relativePath.split("/")),
436
+ );
403
437
  });
404
438
  });
405
439