@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 +86 -20
- package/okf/bundles/okf-mcp/interfaces/mcp-tools.md +7 -3
- package/okf/bundles/okf-mcp/overview/okf-mcp.md +1 -1
- package/okf/bundles/okf-mcp/policies/authoring-safety.md +7 -1
- package/okf/bundles/okf-mcp/runtime/file-concept-store.md +4 -2
- package/okf/bundles/okf-mcp/runtime/mcp-server.md +1 -1
- package/okf/bundles/okf-mcp/workflows/concept-authoring.md +9 -3
- package/package.json +3 -2
- package/server.json +2 -2
- package/src/cli.js +63 -1
- package/src/index.js +1 -0
- package/src/indexer.js +40 -6
- package/src/live-authoring.js +945 -0
- package/src/mcp-server.js +171 -2
- package/src/search-index.js +83 -0
- package/src/search.js +35 -42
- package/src/store.js +10 -1
- package/src/v02.js +1 -0
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.
|
|
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
|
-
|
|
44
|
+
Pin the published version for reproducible use:
|
|
45
45
|
|
|
46
46
|
```bash
|
|
47
|
-
npx -y @mfdaves/okf-mcp@0.
|
|
48
|
-
npx -y @mfdaves/okf-mcp@0.
|
|
47
|
+
npx -y @mfdaves/okf-mcp@0.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.
|
|
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.
|
|
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
|
|
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.
|
|
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.
|
|
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
|
-
| `--
|
|
344
|
-
| `--allow-
|
|
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.
|
|
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
|
-
|
|
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.
|
|
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
|
-
`
|
|
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
|
|
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:
|
|
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
|
|
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.
|
|
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.
|
|
11
|
+
"version": "0.6.0",
|
|
12
12
|
"packages": [
|
|
13
13
|
{
|
|
14
14
|
"registryType": "npm",
|
|
15
15
|
"identifier": "@mfdaves/okf-mcp",
|
|
16
|
-
"version": "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] [--
|
|
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
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
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
return;
|
|
385
|
-
}
|
|
388
|
+
const indexedPaths = new Set();
|
|
389
|
+
const indexLocalDocument = (relativePath, text, source) => {
|
|
390
|
+
indexedPaths.add(relativePath);
|
|
386
391
|
try {
|
|
387
|
-
const doc =
|
|
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
|
|