@mfdaves/okf-mcp 0.5.1 → 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 +58 -16
- package/okf/bundles/okf-mcp/interfaces/mcp-tools.md +5 -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/workflows/concept-authoring.md +9 -3
- package/package.json +1 -1
- package/server.json +2 -2
- package/src/cli.js +62 -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 +168 -0
- package/src/store.js +10 -1
- package/src/v02.js +1 -0
package/README.md
CHANGED
|
@@ -35,7 +35,7 @@ Node 22 or newer is required.
|
|
|
35
35
|
Install from the GitHub release:
|
|
36
36
|
|
|
37
37
|
```bash
|
|
38
|
-
git clone --branch v0.
|
|
38
|
+
git clone --branch v0.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
|
|
@@ -44,14 +44,14 @@ node bin/okf-mcp.js --root ./path/to/okf validate
|
|
|
44
44
|
Pin the published version for reproducible use:
|
|
45
45
|
|
|
46
46
|
```bash
|
|
47
|
-
npx -y @mfdaves/okf-mcp@0.
|
|
48
|
-
npx -y @mfdaves/okf-mcp@0.
|
|
47
|
+
npx -y @mfdaves/okf-mcp@0.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
|
|
@@ -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
|
|
|
@@ -17,6 +17,8 @@ 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
|
|
@@ -33,7 +35,9 @@ 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
|
|
|
@@ -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).
|
|
@@ -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
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.",
|
|
@@ -534,6 +585,13 @@ function stdioServerOptions(args) {
|
|
|
534
585
|
if (args.authoring && args.allowComputationAuthoring) {
|
|
535
586
|
options.allowComputationAuthoring = true;
|
|
536
587
|
}
|
|
588
|
+
if (args.write) {
|
|
589
|
+
options.allowWrite = true;
|
|
590
|
+
options.actor = args.actor;
|
|
591
|
+
if (args.gitCommit) {
|
|
592
|
+
options.gitCommit = true;
|
|
593
|
+
}
|
|
594
|
+
}
|
|
537
595
|
if (args.strictLinks) {
|
|
538
596
|
options.strictLinks = true;
|
|
539
597
|
}
|
|
@@ -610,6 +668,9 @@ async function main(argv, runtime) {
|
|
|
610
668
|
if (!COMMANDS.has(command)) {
|
|
611
669
|
throw usageError(`Unknown OKF command: ${command}`);
|
|
612
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
|
+
}
|
|
613
674
|
if (command === "mcp") {
|
|
614
675
|
const bundles = resolveLegacyBundles(args);
|
|
615
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
|
|