@mfdaves/okf-mcp 0.6.0 → 0.8.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
@@ -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.6.0 https://github.com/mfdaves/okf-mcp.git
38
+ git clone --branch v0.8.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.6.0 --version
48
- npx -y @mfdaves/okf-mcp@0.6.0 --root ./path/to/okf validate
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
49
  ```
50
50
 
51
51
  For a persistent installation:
52
52
 
53
53
  ```bash
54
- npm install --global @mfdaves/okf-mcp@0.6.0
54
+ npm install --global @mfdaves/okf-mcp@0.8.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.6.0/okf/bundles/okf-mcp --inspect
98
+ okf --remote-bundle okf-mcp=https://github.com/mfdaves/okf-mcp/tree/v0.8.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
@@ -182,7 +182,7 @@ Example client configuration:
182
182
  "command": "npx",
183
183
  "args": [
184
184
  "-y",
185
- "@mfdaves/okf-mcp@0.6.0",
185
+ "@mfdaves/okf-mcp@0.8.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.6.0",
204
+ "@mfdaves/okf-mcp@0.8.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. 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.
214
+ Add `--authoring` to enable proposal creation, acceptance, and rejection. For a smaller direct-write surface, add `--write --actor <actor>` to expose read-only `okf_validate_changes` and validated-batch `okf_apply_changes`; 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
@@ -239,7 +239,7 @@ Concept IDs are their bundle-relative Markdown paths with `.md` removed. This ex
239
239
  okf://<bundle-id>/<extensionless-concept-id>
240
240
  ```
241
241
 
242
- The former `.md` URI and a valid custom `id` remain compatibility lookup aliases. A bare Concept ID resolves only when unique across loaded bundles; `okf://` remains deterministic for federated workspaces. Reserved `index.md` and `log.md` resources retain their filenames because they are not concepts.
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. 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
243
 
244
244
  The `id`, `aliases`, and typed `relations` fields below are `okf-mcp` extensions. The standard v0.2 identity remains path-derived:
245
245
 
@@ -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_validate_changes`
319
320
  - `okf_apply_changes`
320
321
  - `get_graph`
321
322
  - `get_neighbors`
@@ -326,7 +327,7 @@ okf --root /path/to/catalog \
326
327
  - `validate_project`
327
328
  - `export_graph`
328
329
 
329
- 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.
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. 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.
330
331
 
331
332
  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.
332
333
 
@@ -345,7 +346,7 @@ Tool discovery and direct invocation use the same capability checks:
345
346
  | `--authoring --allow-computation-authoring` | enabled | disabled | enabled | disabled |
346
347
  | `--allow-remote-tool` | disabled | disabled | disabled | enabled |
347
348
 
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.
349
+ An explicit local root or project workspace exposes concept validation, path suggestion, and proposal inspection helpers. Proposal mutation tools require `--authoring`. The direct live tools instead require `--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.
349
350
 
350
351
  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.
351
352
 
@@ -357,7 +358,7 @@ Start the server with the direct-write capability only when the MCP client/user
357
358
  okf --root /path/to/catalog --write --actor openai/gpt-5.6 mcp
358
359
  ```
359
360
 
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
+ The agent sees one read-only batch validator and one destructive apply 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
 
362
363
  ```json
363
364
  {
@@ -381,11 +382,13 @@ The agent sees one destructive tool. It supplies structured concept fields rathe
381
382
  }
382
383
  ```
383
384
 
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
+ 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.
385
386
 
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
+ 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`.
387
388
 
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
+ 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
+
391
+ 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 publication. Active Git filter attributes and `assume-unchanged`/`skip-worktree` index flags block the operation so validation cannot execute configured filters or overlook hidden user changes; replace-object resolution is disabled so hidden replacement history cannot alter the parent tree. The server builds an isolated index from the validated Markdown bytes, creates that exact tree with `commit-tree`, publishes it with a compare-and-swap ref update, synchronizes only the affected ordinary-index paths afterward, and never pushes. Concurrent unrelated staged entries cannot enter the commit. A determinate commit failure leaves matching valid files as working-tree-only; an ambiguous ref-update timeout is reported as unknown unless the resulting commit tree can be proven. Non-Git catalogs are written normally. Every response makes the repository root, commit state, index state, target-byte state, and persistence boundary explicit.
389
392
 
390
393
  ## Authoring Concepts
391
394
 
@@ -437,7 +440,7 @@ Omitted frontmatter fields and an omitted body are preserved. The concept URI ca
437
440
 
438
441
  Safety rules:
439
442
 
440
- - concept paths must be safe relative `.md` paths inside a writable bundle
443
+ - concept paths must be safe, non-hidden relative `.md` paths inside a writable bundle
441
444
  - concept writes cannot traverse symbolic links under a writable bundle
442
445
  - missing subdirectories are created only when a proposal is accepted
443
446
  - `index.md` and `log.md` cannot be authored as concepts
@@ -540,6 +543,7 @@ Use `list_remote_bundles` to inspect what was loaded.
540
543
  - `hasSources`
541
544
  - `runtime` and `attestationReady`
542
545
  - `generatedBy` and `verifiedBy`
546
+ - `detail` (`compact` by default, or `full`)
543
547
  - `limit`
544
548
  - `offset`
545
549
 
@@ -548,7 +552,7 @@ listing filters. Text search tokenizes case-insensitively and requires every
548
552
  query term, regardless of order. BM25+ ranks title, type, tags, aliases,
549
553
  description, path, and body matches; frontmatter remains available through
550
554
  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.
555
+ 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.
552
556
 
553
557
  Queries are bounded to 512 characters and 16 terms. Prefix expansion, fuzzy
554
558
  matching, stemming, and stop-word removal are intentionally disabled so code
@@ -558,6 +562,8 @@ frontmatter filters support exact scalar matching and array-contains
558
562
  matching. `relationType` selects concepts with an outgoing relation of that
559
563
  type.
560
564
 
565
+ 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.
566
+
561
567
  Example:
562
568
 
563
569
  ```json
@@ -592,7 +598,7 @@ For navigation convenience, okf-mcp resolves links to a nested bundle directory
592
598
  `index.md` when there is no exact document target. This applies to local and
593
599
  remote bundles and to candidate validation during proposal authoring.
594
600
 
595
- Graph tools return compact JSON:
601
+ Graph tools return bounded JSON:
596
602
 
597
603
  ```json
598
604
  {
@@ -19,28 +19,34 @@ relations:
19
19
  target: repo://test/mcp-hardening.test.js
20
20
  - type: checked_by
21
21
  target: repo://test/live-authoring.test.js
22
+ - type: checked_by
23
+ target: repo://test/live-mcp-contract.test.js
24
+ - type: checked_by
25
+ target: repo://test/live-agent-workflow.test.js
22
26
  ---
23
27
 
24
28
  # MCP Tool Catalog
25
29
 
26
30
  The MCP interface groups tools by intent.
27
31
 
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.
32
+ 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.
29
33
 
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.
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. Identical node paths from parallel edge kinds are returned once.
31
35
 
32
36
  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.
33
37
 
34
38
  Static computation tools inspect contracts, read indexed assets, prepare parameter digests, and check receipt field names without execution, attestation, value echo, or persistence. Migration tools check or preview Stage A without writes.
35
39
 
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.
40
+ `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. Oversized content errors include the observed size, active limit, maximum supported limit, and whether a bounded retry can succeed.
41
+
42
+ 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`.
37
43
 
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`.
44
+ `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.
39
45
 
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.
46
+ 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.
41
47
 
42
48
  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.
43
49
 
44
50
  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.
45
51
 
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.
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. 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.
@@ -23,21 +23,27 @@ relations:
23
23
  target: repo://test/mcp-hardening.test.js
24
24
  - type: checked_by
25
25
  target: repo://test/live-authoring.test.js
26
+ - type: checked_by
27
+ target: repo://test/live-authoring-correctness.test.js
28
+ - type: checked_by
29
+ target: repo://test/live-agent-workflow.test.js
26
30
  ---
27
31
 
28
32
  # Authoring Safety
29
33
 
30
34
  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.
31
35
 
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.
36
+ 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.
33
37
 
34
- 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.
38
+ 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.
35
39
 
36
40
  Candidates must satisfy the concept format, configured relation vocabulary, and internal target integrity. External schemes such as `repo://` are allowed as opaque references.
37
41
 
38
42
  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.
39
43
 
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.
44
+ 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
+
46
+ 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.
41
47
 
42
48
  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.
43
49
 
@@ -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 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.
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.
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
 
@@ -29,9 +29,9 @@ The SDK serves the modern `2026-07-28` revision and its compatibility path for 2
29
29
 
30
30
  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
31
 
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, and proposal-based authoring.
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.
33
33
 
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`.
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`.
35
35
 
36
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
 
@@ -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
 
@@ -18,6 +18,6 @@ A standard `sources` entry may point at a bundle-local concept of type `Git Repo
18
18
 
19
19
  The OKF content contains the repository's transport URL but never a machine-local checkout path or credential. The MCP host maps the repository Concept ID to an explicit checkout, bare repository, or mounted object store with `--repo <concept-id>=<path>`.
20
20
 
21
- `read_git_source` resolves only declared source entries. It reads a regular blob from the pinned commit, verifies its Git object ID and SHA-256, enforces UTF-8 and byte limits, and rejects traversal, symbolic links, and submodules. It disables lazy fetches and never consults dirty working-tree bytes.
21
+ `read_git_source` resolves only declared source entries. It reads a regular blob from the pinned commit, verifies its Git object ID and SHA-256, enforces UTF-8 and byte limits, and rejects traversal, symbolic links, and submodules. It disables lazy fetches and never consults dirty working-tree bytes. When a blob exceeds the active limit, the structured error reports the actual size, the active and maximum limits, and whether retrying with a larger bounded request can succeed; line selection never bypasses the full-blob safety limit.
22
22
 
23
23
  An unpinned source or missing host mapping remains discoverable but unavailable. No indexing, search, graph, or provenance operation triggers Git network access.
@@ -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 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.
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
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mfdaves/okf-mcp",
3
- "version": "0.6.0",
3
+ "version": "0.8.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": {
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.6.0",
11
+ "version": "0.8.0",
12
12
  "packages": [
13
13
  {
14
14
  "registryType": "npm",
15
15
  "identifier": "@mfdaves/okf-mcp",
16
- "version": "0.6.0",
16
+ "version": "0.8.0",
17
17
  "transport": {
18
18
  "type": "stdio"
19
19
  },
package/src/authoring.js CHANGED
@@ -7,6 +7,8 @@ const yaml = require("js-yaml");
7
7
  const { parseMarkdownText, normalizeSlashes } = require("./parser");
8
8
  const {
9
9
  bundleExcludesPath,
10
+ conceptMatchSummary,
11
+ findConceptMatches,
10
12
  resolveLinkPath,
11
13
  semanticReferences,
12
14
  } = require("./indexer");
@@ -27,14 +29,29 @@ function slug(value, fallback) {
27
29
  .replace(/^-+|-+$/g, "") || String(fallback || "concept");
28
30
  }
29
31
 
32
+ function isConfiguredGeneratorOutput(project, absolutePath) {
33
+ return Boolean(project && project.root && absolutePath && (project.plugins || []).some((plugin) => {
34
+ if (!plugin || !plugin.output) return false;
35
+ const relative = path.relative(path.resolve(project.root, String(plugin.output)), absolutePath);
36
+ return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
37
+ }));
38
+ }
39
+
30
40
  function normalizeConceptPath(value) {
31
41
  const raw = normalizeSlashes(String(value || "").trim());
32
42
  if (!raw) {
33
43
  throw new Error("Concept path is required.");
34
44
  }
35
- if (raw.startsWith("/") || raw.includes("\0")) {
45
+ if (raw.startsWith("/") || /^[A-Za-z]:\//.test(raw) || /[\u0000-\u001f\u007f]/.test(raw)) {
36
46
  throw new Error("Concept path must be a safe relative path.");
37
47
  }
48
+ const rawParts = raw.split("/");
49
+ if (rawParts.some((part) => !part || part === "." || part === ".." || part.startsWith("."))) {
50
+ throw new Error("Concept path must be a safe relative path without empty, hidden, dot, or parent segments.");
51
+ }
52
+ if (rawParts.slice(0, -1).some((part) => part.toLowerCase().endsWith(".md"))) {
53
+ throw new Error("Concept path cannot place a Markdown file inside another Markdown path.");
54
+ }
38
55
  const normalized = path.posix.normalize(raw);
39
56
  if (!normalized || normalized === "." || normalized.startsWith("../") || normalized === "..") {
40
57
  throw new Error("Concept path must stay inside the bundle.");
@@ -45,13 +62,69 @@ function normalizeConceptPath(value) {
45
62
  if (!normalized.toLowerCase().endsWith(".md")) {
46
63
  throw new Error("Concept path must end with .md.");
47
64
  }
48
- const base = path.posix.basename(normalized);
65
+ const base = path.posix.basename(normalized).toLowerCase();
49
66
  if (base === "index.md" || base === "log.md") {
50
67
  throw new Error("Concept path cannot be a reserved index.md or log.md file.");
51
68
  }
52
69
  return normalized;
53
70
  }
54
71
 
72
+ function deriveConceptPathSuggestion(index, bundle, input) {
73
+ const rawPrefix = input && input.prefix
74
+ ? normalizeSlashes(String(input.prefix).trim())
75
+ : "";
76
+ if (rawPrefix.startsWith("/") || /^[A-Za-z]:\//.test(rawPrefix)) {
77
+ throw new Error("Path prefix must be a safe relative path inside the bundle.");
78
+ }
79
+ const prefix = rawPrefix.replace(/\/+$/g, "");
80
+ if (prefix) {
81
+ normalizeConceptPath(`${prefix}/placeholder.md`);
82
+ }
83
+ const type = String((input && input.type) || "").trim();
84
+ const typePart = type === "Attested Computation"
85
+ ? "computations"
86
+ : slug(type, "concept");
87
+ const titlePart = slug(input && input.title, typePart);
88
+ let parent = prefix ? `${prefix}/${typePart}` : typePart;
89
+ let strategy = prefix ? "explicit_prefix" : "type_slug";
90
+ let evidence = { matchingConcepts: 0, dominantDirectoryCount: 0, dominantDirectoryRatio: 0 };
91
+
92
+ if (type !== "Attested Computation" && index) {
93
+ const matching = findConceptMatches(index, {
94
+ bundle: bundle.id,
95
+ type,
96
+ pathPrefix: prefix,
97
+ });
98
+ const counts = new Map();
99
+ matching.forEach((document) => {
100
+ const directory = path.posix.dirname(document.path);
101
+ const normalizedDirectory = directory === "." ? "" : directory;
102
+ counts.set(normalizedDirectory, (counts.get(normalizedDirectory) || 0) + 1);
103
+ });
104
+ const dominant = Array.from(counts.entries()).sort((left, right) => (
105
+ right[1] - left[1] || left[0].localeCompare(right[0])
106
+ ))[0];
107
+ const dominantCount = dominant ? dominant[1] : 0;
108
+ const ratio = matching.length ? dominantCount / matching.length : 0;
109
+ evidence = {
110
+ matchingConcepts: matching.length,
111
+ dominantDirectoryCount: dominantCount,
112
+ dominantDirectoryRatio: Number(ratio.toFixed(3)),
113
+ };
114
+ if (dominant && dominantCount >= 2 && ratio >= 0.6) {
115
+ parent = dominant[0];
116
+ strategy = "dominant_same_type_directory";
117
+ evidence.dominantDirectory = dominant[0] || ".";
118
+ }
119
+ }
120
+
121
+ return {
122
+ path: normalizeConceptPath([parent, `${titlePart}.md`].filter(Boolean).join("/")),
123
+ strategy,
124
+ evidence,
125
+ };
126
+ }
127
+
55
128
  function renderFrontmatter(frontmatter) {
56
129
  const values = Object.fromEntries(
57
130
  Object.entries(frontmatter || {}).filter((entry) => entry[1] !== undefined),
@@ -119,17 +192,36 @@ class ConceptAuthoringService {
119
192
 
120
193
  suggestConceptPath(input) {
121
194
  const bundle = this.getBundle(input && input.bundle);
122
- const prefix = input && input.prefix ? normalizeSlashes(String(input.prefix)).replace(/^\/+|\/+$/g, "") : "";
123
- if (prefix && (prefix === "." || prefix.startsWith("../") || prefix.includes("/../"))) {
124
- throw new Error("Path prefix must stay inside the bundle.");
125
- }
126
- const typePart = input && input.type === "Attested Computation"
127
- ? "computations"
128
- : slug(input && input.type, "concept");
129
- const titlePart = slug(input && input.title, typePart);
195
+ const index = this.store.getIndex();
196
+ const suggestion = deriveConceptPathSuggestion(index, bundle, input || {});
197
+ const target = this.store.resolveConceptFile(bundle.id, suggestion.path);
198
+ const titleMatches = findConceptMatches(index, {
199
+ bundle: bundle.id,
200
+ type: input && input.type,
201
+ title: input && input.title,
202
+ });
203
+ const matches = titleMatches.slice(0, 5).map((doc) => conceptMatchSummary(doc));
204
+ const available = !fs.existsSync(target.absolutePath);
205
+ const only = matches.length === 1 && matches[0];
206
+ const generatorOwned = only && (only.generatedFile
207
+ || only.generatedBy && only.generatedBy.startsWith("process:")
208
+ || isConfiguredGeneratorOutput(this.store.project, titleMatches[0].absolutePath));
130
209
  return {
131
210
  bundle: bundle.id,
132
- path: normalizeConceptPath([prefix, typePart, `${titlePart}.md`].filter(Boolean).join("/")),
211
+ path: suggestion.path,
212
+ uri: `okf://${bundle.id}/${suggestion.path.replace(/\.md$/i, "")}`,
213
+ absolutePath: target.absolutePath,
214
+ available,
215
+ creatable: available && titleMatches.length === 0,
216
+ titleMatches: matches,
217
+ titleMatchesOmitted: Math.max(0, titleMatches.length - matches.length),
218
+ ...(matches.length === 1 ? { existingConcept: matches[0] } : {}),
219
+ recommendedOperation: titleMatches.length
220
+ ? titleMatches.length > 1 ? "review_matches"
221
+ : generatorOwned ? "change_generator" : "update"
222
+ : available ? "create" : "inspect_existing",
223
+ strategy: suggestion.strategy,
224
+ evidence: suggestion.evidence,
133
225
  };
134
226
  }
135
227
 
@@ -802,6 +894,8 @@ class ConceptAuthoringService {
802
894
 
803
895
  module.exports = {
804
896
  ConceptAuthoringService,
897
+ deriveConceptPathSuggestion,
898
+ isConfiguredGeneratorOutput,
805
899
  normalizeConceptPath,
806
900
  renderConceptMarkdown,
807
901
  renderFrontmatter,
package/src/cli.js CHANGED
@@ -485,7 +485,7 @@ function usage() {
485
485
  " --root, -r <directory> Load one official OKF bundle root.",
486
486
  " --repo <concept-id=path> Map a Git Repository concept to a checkout or bare repo; repeatable.",
487
487
  " --authoring Enable MCP proposal authoring tools.",
488
- " --write Enable direct atomic MCP concept writes (requires --actor).",
488
+ " --write Enable direct validated-batch MCP concept writes (requires --actor).",
489
489
  " --actor <actor> Stamp live writes with human:id, process:id, or provider/model.",
490
490
  " --git-commit Commit each live write batch when the catalog is in a clean Git repo.",
491
491
  " --allow-remote-tool Enable runtime remote-bundle loading over MCP.",
package/src/git-source.js CHANGED
@@ -12,10 +12,13 @@ const DEFAULT_GIT_TIMEOUT_MS = 10000;
12
12
  const MAX_GIT_TIMEOUT_MS = 60000;
13
13
 
14
14
  class GitSourceError extends Error {
15
- constructor(code, message) {
15
+ constructor(code, message, details) {
16
16
  super(message);
17
17
  this.name = "GitSourceError";
18
18
  this.code = code;
19
+ if (details !== undefined) {
20
+ this.details = details;
21
+ }
19
22
  }
20
23
  }
21
24
 
@@ -27,8 +30,8 @@ function isPlainObject(value) {
27
30
  return prototype === Object.prototype || prototype === null;
28
31
  }
29
32
 
30
- function sourceError(code, message) {
31
- return new GitSourceError(code, message);
33
+ function sourceError(code, message, details) {
34
+ return new GitSourceError(code, message, details);
32
35
  }
33
36
 
34
37
  function normalizeLines(value) {
@@ -392,7 +395,13 @@ function readGitSource(source, repositoryMappings, options) {
392
395
  if (size > maxBytes) {
393
396
  throw sourceError(
394
397
  "git_source_too_large",
395
- `Git source exceeds the configured ${maxBytes} byte limit.`,
398
+ `Git source is ${size} bytes and exceeds the configured ${maxBytes} byte limit.`,
399
+ {
400
+ actualBytes: size,
401
+ limitBytes: maxBytes,
402
+ maxAllowedBytes: MAX_GIT_SOURCE_BYTES,
403
+ retryable: size <= MAX_GIT_SOURCE_BYTES,
404
+ },
396
405
  );
397
406
  }
398
407
 
package/src/graph.js CHANGED
@@ -180,9 +180,9 @@ function findPaths(index, source, target, maxPaths, options) {
180
180
  const adjacency = new Map();
181
181
  index.edges.filter((edge) => !edge.broken && edgeAllowed(edge, options)).forEach((edge) => {
182
182
  if (!adjacency.has(edge.source)) {
183
- adjacency.set(edge.source, []);
183
+ adjacency.set(edge.source, new Set());
184
184
  }
185
- adjacency.get(edge.source).push(edge.target);
185
+ adjacency.get(edge.source).add(edge.target);
186
186
  });
187
187
  const queue = [[canonicalSource]];
188
188
  const paths = [];