@mfdaves/okf-mcp 0.9.1 → 0.12.0-rc.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +69 -0
- package/README.md +172 -17
- package/bin/okf-mcp.js +6 -1
- package/okf/okf-mcp/policies/authoring-safety.md +11 -1
- package/package.json +17 -5
- package/server.json +2 -2
- package/src/assets.js +165 -73
- package/src/authoring/candidates.js +391 -0
- package/src/authoring/git-preflight.js +225 -0
- package/src/authoring/git-publish.js +776 -0
- package/src/authoring/live.js +789 -0
- package/src/authoring/paths.js +112 -0
- package/src/authoring/policy-hook.js +221 -0
- package/src/authoring/proposal-policy.js +137 -0
- package/src/authoring/receipts.js +329 -0
- package/src/authoring/render.js +38 -0
- package/src/authoring/shared.js +75 -0
- package/src/authoring/staging.js +216 -0
- package/src/authoring.js +386 -287
- package/src/cache/files.js +147 -0
- package/src/cache/lock.js +201 -0
- package/src/cache/paths.js +197 -0
- package/src/cache/store.js +703 -0
- package/src/catalog-text.js +19 -0
- package/src/cli.js +184 -151
- package/src/computation.js +99 -61
- package/src/context/assemble.js +567 -0
- package/src/context/cli-options.js +88 -0
- package/src/context/score.js +234 -0
- package/src/context/sections.js +274 -0
- package/src/embed/interface.js +160 -0
- package/src/embed/openai.js +715 -0
- package/src/embed/prepare.js +182 -0
- package/src/embed/units.js +96 -0
- package/src/git-source.js +112 -52
- package/src/graph.js +95 -37
- package/src/http-server.js +36 -17
- package/src/index.js +15 -0
- package/src/indexer/assemble.js +566 -0
- package/src/indexer/build.js +290 -0
- package/src/indexer/cache.js +81 -0
- package/src/indexer/edges.js +430 -0
- package/src/indexer/index.js +44 -0
- package/src/indexer/paths.js +178 -0
- package/src/indexer/resolve.js +282 -0
- package/src/indexer/update.js +720 -0
- package/src/indexer.js +3 -1068
- package/src/live-authoring.js +4 -2329
- package/src/markdown.js +21 -16
- package/src/mcp/registry.js +328 -0
- package/src/mcp/resources.js +45 -0
- package/src/mcp/server.js +472 -0
- package/src/mcp/tools/catalog.js +244 -0
- package/src/mcp/tools/computation.js +83 -0
- package/src/mcp/tools/context.js +133 -0
- package/src/mcp/tools/graph.js +167 -0
- package/src/mcp/tools/live-authoring.js +316 -0
- package/src/mcp/tools/migration.js +86 -0
- package/src/mcp/tools/producers.js +79 -0
- package/src/mcp/tools/proposals.js +213 -0
- package/src/mcp/tools/provenance.js +87 -0
- package/src/mcp/tools/remote.js +79 -0
- package/src/mcp/tools/search.js +242 -0
- package/src/mcp-server.js +3 -1611
- package/src/migration.js +431 -253
- package/src/parser.js +245 -130
- package/src/plugins.js +71 -48
- package/src/policy/write-policy.js +713 -0
- package/src/producer-publisher.js +195 -77
- package/src/producers.js +265 -101
- package/src/project.js +277 -93
- package/src/remote.js +96 -61
- package/src/search/cli-options.js +107 -0
- package/src/search/confidence.js +61 -0
- package/src/search/dense.js +304 -0
- package/src/search/embedding-cli.js +57 -0
- package/src/search/embedding-config.js +217 -0
- package/src/search/fusion.js +249 -0
- package/src/search/hybrid.js +526 -0
- package/src/search/languages.js +200 -0
- package/src/search/lexical.js +695 -0
- package/src/search/query.js +620 -0
- package/src/search/stem/among.js +43 -0
- package/src/search/stem/base-stemmer.js +311 -0
- package/src/search/stem/en-regions.js +456 -0
- package/src/search/stem/en-suffixes.js +664 -0
- package/src/search/stem/en-tables.js +176 -0
- package/src/search/stem/en.js +238 -0
- package/src/search/stem/it-regions.js +459 -0
- package/src/search/stem/it-suffixes.js +471 -0
- package/src/search/stem/it-tables.js +257 -0
- package/src/search/stem/it.js +155 -0
- package/src/search-index.js +2 -81
- package/src/search.js +2 -252
- package/src/store.js +134 -81
- package/src/v02.js +301 -105
- package/src/validation.js +24 -20
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to `@mfdaves/okf-mcp`. The format follows Keep a Changelog; versions follow SemVer. Until 1.0, minor versions may change defaults where this file says so.
|
|
4
|
+
|
|
5
|
+
## 0.12.0-rc.1 — 2026-10-25
|
|
6
|
+
|
|
7
|
+
Retrieval level-up (WP3c-2): an adaptive fusion weight, contextual embedding units and a confidence block with opt-in abstention, each measured against pre-registered targets on both fixtures and on a real 560-concept catalog (`test/fixtures/retrieval/reports/hybrid-0.12-2026-10-25.md`, `context-0.12-2026-10-25.md`). No default ranking changes: the fixed fusion weight 0.4 and concept units stay the defaults because the new options did not meet their conditions for becoming defaults.
|
|
8
|
+
|
|
9
|
+
### Added
|
|
10
|
+
|
|
11
|
+
- `fusion.alpha: adaptive`: the weight of the semantic side is decided once per query from the lexical pass, `fusion.adaptive.low` when quoted or identifier-like terms are matched by every-term hits, `mid` when at least `autoFill` concepts match every term, `high` when nothing matches every term and no concept matches half of them, linear in between. The weights default to the development-split choice `{ low: 0.1, mid: 0.5, high: 0.9 }`. Hybrid responses report `alphaUsed` and `alphaReason`; `embedding_status` reports the setting. Opt-in: on the fixtures it raised alpinaria Recall@5 0.830 → 0.838 (synonyms 0.542 → 0.604, target 0.70) but lowered atlas 0.882 → 0.870; overhead 0.3 ms p95 at 20,000 vectors. On the real catalog it lifted paraphrase queries from 0.10 to 0.27 (informative only).
|
|
12
|
+
- `embedUnits: contextual-sections` and `contextual-concepts`: each section, or each concept, is embedded after a one-line prefix naming its concept (`title · type · path`, at most 160 characters; `type · path` for concepts). Plain unit hashes are unchanged; switching unit sets re-embeds once and the receipts name the unit set (`embedUnits`). On the fixtures neither beat concept units (mean dev Recall@5 0.841 and 0.843 against 0.844) and the prefix costs 56% more prompt tokens for sections (6.6% for concepts).
|
|
13
|
+
- `confidence: { coverage, topSimilarity, lowConfidence, reasons }` on every `search_concepts` and `get_context` response to a query. With an embedder, `lowConfidence` is also true when the top result matched fewer than half of the terms and no candidate reaches `confidence.minSimilarity` (project or `--embedder-config` key; default 0). Lexical-only responses keep the 0.10 rule.
|
|
14
|
+
- `get_context` `abstainOnLowConfidence`: a low-confidence query returns no sections, with the confidence block, the candidate concepts and `abstained: true`.
|
|
15
|
+
- Evaluation harness: `--alpha adaptive`, `--adaptive`, the dev-only `--adaptive-grid` with its pre-registered choice rule, and `--baseline <report>` for a per-category paired bootstrap of the Recall@5 difference; hybrid per-query rows carry `alphaUsed`, `alphaReason` and `topSimilarity`.
|
|
16
|
+
|
|
17
|
+
### Changed
|
|
18
|
+
|
|
19
|
+
- With an embedder, the top-level `lowConfidence` of a search follows the confidence rule above; at the default threshold it flags the same queries as before.
|
|
20
|
+
- The confidence block counts against a `get_context` budget (about 18 tokens). Atlas section-anchor hit at 1,200 tokens: 0.721 → 0.698 (one query); alpinaria unchanged.
|
|
21
|
+
|
|
22
|
+
### Known issues
|
|
23
|
+
|
|
24
|
+
- Synonym Recall@5 on the SEO fixture stays at 0.542 by default (0.604 with the adaptive weight; target 0.70).
|
|
25
|
+
- Abstention: the similarity clause shares the coverage bound of the lexical one, so on the fixtures no threshold flags an extra unanswerable query; no-answer recall is 0.545 on alpinaria (target 0.70) and 0.70 on atlas, and 4 of 7 on the real catalog (target 5), whose unflagged questions have a top coverage of 0.60–0.67.
|
|
26
|
+
- `get_context` candidates are lexical; contextual embeddings do not reach it yet.
|
|
27
|
+
|
|
28
|
+
## 0.11.0-rc.2 — 2026-10-25
|
|
29
|
+
|
|
30
|
+
Three defects found by running 0.11.0-rc.1 against a real 560-concept catalog, fixed.
|
|
31
|
+
|
|
32
|
+
### Fixed
|
|
33
|
+
|
|
34
|
+
- One oversized document no longer turns hybrid search off for a whole catalog. A generated contract dense with identifiers was longer than the embedding model accepts; the whole request failed and the server fell back to lexical-only search for every document. The client now plans requests with a cautious estimate (one token per 3 characters) and truncates at 24,000 characters by default instead of 32,000. If the provider still refuses a request, the client splits the batch until the refused document stands alone, retries it once at half its length (never below 2,000 characters), and skips it only if it is refused again. A skipped document is listed in the preparation receipt as `skipped: [{ id, reason: "input_rejected" }]` and in `embedding_status` and the startup receipt as `skipped: { count, ids }`. Every other document is embedded and search stays hybrid. On the real catalog: 560 of 560 embedded, none skipped, one retried at half length. The default change gives a new embedder id, so existing vector caches made with the default are rebuilt once.
|
|
35
|
+
- Search mode `auto` is no longer stopped by one long document that happens to contain every word of the query. It used to fall back to any-word matches only when no document matched every word. Now the documents that match every word come first, in their usual order, and documents that match some of the words follow them whenever fewer than `autoFill` documents match every word (default 3). In that case `mode` is `auto`; `allTermsTotal`, `coverage` and `lowConfidence` mean what they meant before. Set `autoFill` as a library search option or in `okf.project.yaml`; `autoFill: 0` restores the old rule. It is not a tool argument. Lexical Recall@5 on the fixtures: 0.742 → 0.823 and 0.760 → 0.827. Hybrid results on the fixtures are unchanged.
|
|
36
|
+
- `get_context` now stays within its token budget. Only the text of the sections used to be counted, so a response was 1.6 to 1.7 times the budget. `usedTokens` now measures the whole JSON response: the candidate concepts, query terms, counters and every section field. Sections are packed into what is left. When even the other fields do not fit, the candidate list is shortened from the end, and the new `omittedConcepts` field counts what was dropped. The tool returns compact JSON, so the text an agent receives is exactly what was measured. A section's `tokens` field now counts the whole section object. Because the old overhead is now charged to the budget, fewer sections fit: the fixtures' section-anchor hit at 1,200 tokens went from 1.000 to 0.900 and from 0.791 to 0.721.
|
|
37
|
+
|
|
38
|
+
## 0.11.0-rc.1 — 2026-10-24
|
|
39
|
+
|
|
40
|
+
The first usable version of the "knowledge runtime for autonomous agents" direction described in `docs/plan-1.0.md`. Measured on the two committed retrieval fixtures (`test/fixtures/retrieval/`, 297 pre-registered queries, Italian and English); numbers are in the committed reports under `test/fixtures/retrieval/reports/`.
|
|
41
|
+
|
|
42
|
+
### Added
|
|
43
|
+
|
|
44
|
+
- Task-shaped lexical search (0.10): query mode `auto` (all terms, then any-term fallback), Italian and English stemming with per-bundle language detection (`languages` in project config or `--languages`), diacritic folding, stop words, literal matching for quoted and identifier-like terms, per-result `matchedTerms`, `coverage`, `relevance`, top-level `allTermsTotal` and an advisory `lowConfidence` flag, opt-in `minCoverage`/`minRelevance` floors and `freshnessPrior`. Recall@5 on the fixtures rose from 0.29/0.25 to 0.74/0.76 with a zero-result rate of 0.
|
|
45
|
+
- Functional incremental index: writes update the index instead of rebuilding it (about 0.04× a full build), with `refreshIndex` over Markdown and referenced assets and a property test proving equivalence with a fresh build.
|
|
46
|
+
- Embeddings (opt-in): a zero-dependency OpenAI-compatible embeddings client (`embedder: { type: openai, ... }`), a rebuildable vector cache outside the bundle (XDG directory, content-hash keyed, locked, digest-verified), incremental embedding after each write, and `embedding_status`.
|
|
47
|
+
- Hybrid retrieval: convex-combination fusion (`fusion: { alpha, normalization }`, default `tmm` and 0.4) of lexical and dense rankings when an embedder is configured; lexical-only fallback with `embedder.degraded`. Recall@5 0.74/0.76 → 0.83/0.88 with `text-embedding-3-small` at 512 dimensions (`embedUnits: concepts` by default; `sections` configurable).
|
|
48
|
+
- Budgeted context: `get_context` tool and `context` CLI command returning deduplicated sections with stable `uri#heading-slug` anchors and provenance, packed to a token budget (default 1,200, compact provenance).
|
|
49
|
+
- Write policy: `writePolicy` in project config or `--policy` for `--root`; per-actor rules over bundles, paths, types, required fields, default status and batch size; enforced read-only by `okf_validate_changes`, as a refusal before staging by `okf_apply_changes`, at proposal creation and acceptance over MCP and HTTP, and opt-in for producers.
|
|
50
|
+
- Evaluation and benchmarks: `npm run eval:search`, `eval:context`, `bench:index`, `bench:write`, with pre-registered thresholds gated by `npm test`.
|
|
51
|
+
- Code structure and gates: `src/mcp/*`, `src/authoring/*`, `src/indexer/*`, `src/search/*` modules with shims at the old paths; MCP contract and tool-order snapshots; Biome lint and format; Windows CI job; content-boundary test asserting catalog text never reaches instruction surfaces.
|
|
52
|
+
|
|
53
|
+
### Changed
|
|
54
|
+
|
|
55
|
+
- Default search semantics are `auto` instead of all-terms-must-match (`mode: "all"` restores the old behaviour); `score` magnitudes changed with stemming (use ordering and `relevance`).
|
|
56
|
+
- Error messages reference URIs and paths instead of concept titles; YAML frontmatter errors name a fixed category and position instead of echoing source text; undeclared relation types and duplicated computation parameter names are reported by ordinal, never echoed.
|
|
57
|
+
- `LiveAuthoringService` no longer carries git helper methods; they live on `GitPublisher` (`service.git`). Exported names in `src/index.js` are unchanged.
|
|
58
|
+
|
|
59
|
+
### Known issues
|
|
60
|
+
|
|
61
|
+
- Synonym-category Recall@5 on the SEO fixture stays near 0.54 against a 0.70 target (0.59 with `embedUnits: sections`); a per-query adaptive fusion weight is the planned follow-up.
|
|
62
|
+
- Section-anchor hit on the architecture fixture is 0.79 at the default budget (target 0.80); the causes are recorded in the context report.
|
|
63
|
+
- A write batch with `--git-commit` takes about 630–730 ms at 5,000 concepts against a 500 ms budget; the git preflight dominates.
|
|
64
|
+
- At 20,000 concepts search p95 and memory exceed the stretch targets.
|
|
65
|
+
- The vector cache is machine-local; export/import is planned.
|
|
66
|
+
|
|
67
|
+
## 0.9.1
|
|
68
|
+
|
|
69
|
+
Last release before this plan; see the git history.
|
package/README.md
CHANGED
|
@@ -37,7 +37,7 @@ Node 22 or newer is required.
|
|
|
37
37
|
Install from the GitHub release:
|
|
38
38
|
|
|
39
39
|
```bash
|
|
40
|
-
git clone --branch v0.
|
|
40
|
+
git clone --branch v0.12.0-rc.1 https://github.com/mfdaves/okf-mcp.git
|
|
41
41
|
cd okf-mcp
|
|
42
42
|
npm ci
|
|
43
43
|
node bin/okf-mcp.js --root ./path/to/okf validate
|
|
@@ -46,14 +46,14 @@ node bin/okf-mcp.js --root ./path/to/okf validate
|
|
|
46
46
|
Pin the published version for reproducible use:
|
|
47
47
|
|
|
48
48
|
```bash
|
|
49
|
-
npx -y @mfdaves/okf-mcp@0.
|
|
50
|
-
npx -y @mfdaves/okf-mcp@0.
|
|
49
|
+
npx -y @mfdaves/okf-mcp@0.12.0-rc.1 --version
|
|
50
|
+
npx -y @mfdaves/okf-mcp@0.12.0-rc.1 --root ./path/to/okf validate
|
|
51
51
|
```
|
|
52
52
|
|
|
53
53
|
For a persistent installation:
|
|
54
54
|
|
|
55
55
|
```bash
|
|
56
|
-
npm install --global @mfdaves/okf-mcp@0.
|
|
56
|
+
npm install --global @mfdaves/okf-mcp@0.12.0-rc.1
|
|
57
57
|
|
|
58
58
|
okf --version
|
|
59
59
|
okf --root ./path/to/okf validate
|
|
@@ -226,6 +226,8 @@ Directories emptied by a stale deletion are removed with their last managed file
|
|
|
226
226
|
- `--write-token <token>`: bearer token for write endpoints; defaults to `OKF_WRITE_TOKEN`
|
|
227
227
|
- `--proposal-root <path>`: proposal JSON directory; defaults to `.okf-proposals` under the selected local root or project
|
|
228
228
|
|
|
229
|
+
Proposals are stored state, not a derived cache, so the proposal directory is never cleaned up automatically. A server started with `--git-commit` refuses to publish while the worktree has untracked files, so that directory must be ignored by Git: add `.okf-proposals/` to `.gitignore` (as this repository does), or pass `--proposal-root` with a directory Git already ignores. In project mode the proposal root must stay inside the project root.
|
|
230
|
+
|
|
229
231
|
## MCP Client Config
|
|
230
232
|
|
|
231
233
|
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.
|
|
@@ -239,7 +241,7 @@ Example client configuration:
|
|
|
239
241
|
"command": "npx",
|
|
240
242
|
"args": [
|
|
241
243
|
"-y",
|
|
242
|
-
"@mfdaves/okf-mcp@0.
|
|
244
|
+
"@mfdaves/okf-mcp@0.12.0-rc.1",
|
|
243
245
|
"--root",
|
|
244
246
|
"/absolute/path/to/okf",
|
|
245
247
|
"mcp"
|
|
@@ -258,7 +260,7 @@ Project config mode, with read-only project helpers but without proposal mutatio
|
|
|
258
260
|
"command": "npx",
|
|
259
261
|
"args": [
|
|
260
262
|
"-y",
|
|
261
|
-
"@mfdaves/okf-mcp@0.
|
|
263
|
+
"@mfdaves/okf-mcp@0.12.0-rc.1",
|
|
262
264
|
"--project",
|
|
263
265
|
"/absolute/path/to/repo/okf.project.yaml",
|
|
264
266
|
"mcp"
|
|
@@ -450,6 +452,37 @@ The server writes nothing unless every candidate is valid, revision checks still
|
|
|
450
452
|
|
|
451
453
|
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.
|
|
452
454
|
|
|
455
|
+
### Write policy
|
|
456
|
+
|
|
457
|
+
A write policy narrows what each actor may write through live batches and proposals. It is trusted configuration: declare it as `writePolicy` in `okf.project.yaml`, or pass `--policy <file>` (the same mapping as a YAML file) with `--root` and `--write` or `--authoring`. Tool and HTTP arguments cannot name, replace, or relax it.
|
|
458
|
+
|
|
459
|
+
```yaml
|
|
460
|
+
writePolicy:
|
|
461
|
+
defaultEffect: deny # allow (default) or deny when no rule decides
|
|
462
|
+
rules:
|
|
463
|
+
- name: humans
|
|
464
|
+
actors: ["human:*"]
|
|
465
|
+
- name: nightly-seo
|
|
466
|
+
actors: ["process:nightly-*", "openai/*"]
|
|
467
|
+
bundles: ["customers-*"]
|
|
468
|
+
paths: ["findings/**"]
|
|
469
|
+
types: ["SEO Finding"]
|
|
470
|
+
requiredFields: ["sources", "stale_after"]
|
|
471
|
+
defaultStatus: draft # stamped on creates that set no status
|
|
472
|
+
maxConceptsPerBatch: 20
|
|
473
|
+
- name: no-drafts
|
|
474
|
+
actors: ["**"]
|
|
475
|
+
paths: ["drafts/**"]
|
|
476
|
+
effect: deny
|
|
477
|
+
applyToProducers: false # true also judges producer runs
|
|
478
|
+
```
|
|
479
|
+
|
|
480
|
+
For each concept in a batch, the first rule whose `actors` match the configured `--actor` and whose other selectors (when present) match decides. `effect` is `allow` by default; `requiredFields`, `defaultStatus`, and `maxConceptsPerBatch` apply to allow rules. Patterns use a fixed glob subset: `*` within one segment, `**` as a whole segment for any depth, and literal segments. They are never compiled to regular expressions, and absolute, empty, `.` and `..` segments are rejected when the policy loads. A malformed policy is a project error, so no writable server starts on it. The policy judges only the concepts a batch creates or updates; existing content is never retro-validated.
|
|
481
|
+
|
|
482
|
+
Violations are structured: `{ code: "policy_violation", rule, reason, field?, path?, bundleId?, uri?, limit?, count? }`, where `rule` is the rule's `name`, else its index, and `null` when `defaultEffect` decided. `reason` is one of `actor_denied`, `bundle_denied`, `path_denied`, `type_denied`, `missing_required_field`, or `batch_too_large`. `okf_validate_changes` reports them read-only in `policyViolations` and as `layer: "policy"` diagnostics; `okf_apply_changes` refuses such a batch with status `rejected` before staging or touching any file. Receipts carry `policyViolations` only when a policy is configured; messages name rules, paths, and URIs, never catalog text.
|
|
483
|
+
|
|
484
|
+
Scope. Live batches (`okf_validate_changes`, `okf_apply_changes`) are judged against `--actor`. Proposals are judged twice. When `okf_propose_concept`, `okf_propose_update`, `okf_propose_attested_computation`, `okf_propose_v02_migration` (every child update and the `index.md` version declaration, before any is stored) or their HTTP equivalents would store one, it is judged against the proposing actor (`--actor`, which `--authoring` also accepts); a refused proposal returns `created: false` with `policyViolations` and is not stored. When `okf_accept_proposal` or `POST /v1/proposals/<id>/accept` would write it, it is judged against the actor recorded on the proposal (`proposedBy`), else the accepting actor; a refusal returns `accepted: false` before any file is written, and an accepted create the matching rule gives a `defaultStatus` is published with that status. A write with no actor (an HTTP call, or a proposal stored before an actor or a policy was configured) is judged as the literal actor `unknown`: `*` and `**` match it and a rule can name it, so legacy proposals are judged as `unknown` at acceptance unless the accepting server has an actor. `okf serve` takes the policy from `okf.project.yaml`, or from `--policy <file>` with `--root` and `--authoring`. Producers publish under `process:<producer name>` and are exempt unless `applyToProducers: true`, in which case `okf_preview_producer` reports the violations of the created and updated concept files read-only and `okf_run_producer` / `producer run` refuse before publication. Producer output is never rewritten, so `defaultStatus` does not apply to it: a required `status` must be in the produced file, or the run is refused with `missing_required_field`. The reserved `index.md` and `log.md` files of a producer bundle are not judged.
|
|
485
|
+
|
|
453
486
|
## Authoring Concepts
|
|
454
487
|
|
|
455
488
|
The reviewable proposal workflow remains available through MCP tools started with `--authoring` and through the HTTP API. Clients never need direct local file access.
|
|
@@ -607,17 +640,48 @@ Use `list_remote_bundles` to inspect what was loaded.
|
|
|
607
640
|
- `limit`
|
|
608
641
|
- `offset`
|
|
609
642
|
|
|
610
|
-
`list_concepts` also accepts a text `query` and applies it
|
|
611
|
-
listing filters. Text search tokenizes case-insensitively
|
|
612
|
-
|
|
613
|
-
|
|
614
|
-
|
|
615
|
-
|
|
616
|
-
|
|
617
|
-
|
|
618
|
-
|
|
619
|
-
|
|
620
|
-
|
|
643
|
+
`list_concepts` also accepts a text `query` (and `mode`) and applies it
|
|
644
|
+
together with its listing filters. Text search tokenizes case-insensitively,
|
|
645
|
+
folds diacritics, drops stop words and single letters, and stems every term
|
|
646
|
+
with the catalog's languages (English and Italian at 1.0). `mode` is `auto`
|
|
647
|
+
by default since 0.10: the concepts matching every term come first, in their
|
|
648
|
+
own order, and when fewer than `autoFill` of them exist (default 3) the
|
|
649
|
+
concepts matching only some of the terms follow them (the response's `mode`
|
|
650
|
+
is then `auto`; it is `any` when nothing matches every term and `all` when
|
|
651
|
+
nothing was appended). This keeps one long document that happens to contain
|
|
652
|
+
every term from hiding the shorter documents that match most of them.
|
|
653
|
+
`autoFill` is a library search option and an `okf.project.yaml` key
|
|
654
|
+
(`autoFill: 0` restores the 0.10 rule: fall back only when nothing matches
|
|
655
|
+
every term), never a tool argument. `all` restores the pre-0.10
|
|
656
|
+
behaviour and `any` ranks anything matching one term. BM25+ ranks title,
|
|
657
|
+
type, tags, aliases, description, path, body, and an exact field (ids,
|
|
658
|
+
paths, aliases, raw title tokens) that is never stemmed, so identifiers and
|
|
659
|
+
SKUs still match literally. Double-quoted text is matched literally (no
|
|
660
|
+
stemming or accent folding, stop words and single letters kept) against ids,
|
|
661
|
+
paths, aliases, titles and raw tokens, and unquoted tokens containing digits
|
|
662
|
+
or hyphens stay literal as well; stems only ever reach the text fields.
|
|
663
|
+
Frontmatter remains available through exact structured filters but is not
|
|
664
|
+
copied into the text index. Scores are
|
|
665
|
+
relative within a result set and are not a stable cross-version scale; use
|
|
666
|
+
ordering and `relevance` instead.
|
|
667
|
+
|
|
668
|
+
Query responses report `mode` (the one that ran), `queryTerms`,
|
|
669
|
+
`droppedTerms`, `allTermsTotal` (concepts matching every term, also under
|
|
670
|
+
`any`) and `lowConfidence`, true when `mode` is `any` (the any-term ranking produced the page)
|
|
671
|
+
and its top result matched fewer than half of the terms. Each result carries
|
|
672
|
+
`coverage` (share of query terms matched), `relevance` (score over the top
|
|
673
|
+
score) and, in full detail, `matchedTerms`. Opt-in floors `minCoverage` and
|
|
674
|
+
`minRelevance` drop weaker results; `freshnessPrior` down-weights deprecated
|
|
675
|
+
(0.5), stale (0.7), and draft (0.85) concepts. Compact results contain
|
|
676
|
+
`uri`, `title`, `type`, `description`, `coverage`, and `relevance`; title,
|
|
677
|
+
type, and description are bounded, while full results remain lossless.
|
|
678
|
+
|
|
679
|
+
Queries are bounded to 512 characters and 16 terms after stop words. Prefix
|
|
680
|
+
expansion and fuzzy matching are intentionally disabled. The stemming
|
|
681
|
+
languages come from the project config key `languages` (`auto`, `none`, or
|
|
682
|
+
codes such as `[it, en]`) or `--languages` in `--root` mode; `auto` detects
|
|
683
|
+
each bundle's languages from its documents. Punctuation-only queries return
|
|
684
|
+
no matches. Tags and types are matched case-insensitively. Arbitrary
|
|
621
685
|
frontmatter filters support exact scalar matching and array-contains
|
|
622
686
|
matching. `relationType` selects concepts with an outgoing relation of that
|
|
623
687
|
type.
|
|
@@ -650,6 +714,97 @@ latency, Recall@10, MRR@10, and representative rankings. Search indexes are
|
|
|
650
714
|
process-local and keyed to the parsed OKF index, so remote loads and accepted
|
|
651
715
|
proposals receive a fresh index automatically.
|
|
652
716
|
|
|
717
|
+
### Budgeted context and section anchors (0.11)
|
|
718
|
+
|
|
719
|
+
`get_context` (MCP, read-only) and `okf context <query> [--budget <tokens>]
|
|
720
|
+
[--limit <n>] [--provenance compact|full|none]` (CLI, JSON) answer a question
|
|
721
|
+
with the sections that matter instead of whole concepts. Candidates come from
|
|
722
|
+
the same search as `search_concepts` (same filters, `mode`, `minCoverage`,
|
|
723
|
+
`minRelevance`, `lowConfidence`, `queryTerms`). Their sections are scored on
|
|
724
|
+
their own text (BM25; the concept's type, tags and path add at most 20%) and
|
|
725
|
+
ordered by the candidate concept rank; within a concept, sections whose text
|
|
726
|
+
matches the query come before sections found only through that metadata, and
|
|
727
|
+
a strongly matching section may move ahead of up to four weaker concepts.
|
|
728
|
+
Sections are deduplicated and packed in that order while they fit
|
|
729
|
+
`budgetTokens` (default 1,200, never exceeded). The budget covers the whole
|
|
730
|
+
response as delivered: `usedTokens` is `ceil(characters / 4)` of the entire
|
|
731
|
+
JSON result, every field included (the candidate `concepts`, `queryTerms`,
|
|
732
|
+
the counters and every section field, scoring fields too), and `get_context`
|
|
733
|
+
returns that JSON compact, so the text an agent receives is what was
|
|
734
|
+
measured. Sections are packed into what the rest of the response leaves;
|
|
735
|
+
when even the fields around them do not fit, the candidate concept list is
|
|
736
|
+
shortened from its tail (`omittedConcepts`), and only a budget smaller than
|
|
737
|
+
the query echo and the field names can be exceeded (then no section and no
|
|
738
|
+
concept is returned). Each section's `tokens` is the same estimate for that
|
|
739
|
+
section, and the estimator is named in the response. Before 0.11.0-rc.2 only
|
|
740
|
+
the sections' content fields were counted, so responses ran at 1.6-1.7 times
|
|
741
|
+
the budget. Provenance is
|
|
742
|
+
`compact` by default (`status`, `freshness`, `verified` as a boolean,
|
|
743
|
+
`sourceCount`); `provenance: "full"` returns `status`, `staleAfter`,
|
|
744
|
+
`freshness`, `trustTier`, `verified`, `generated` and `sources`, and
|
|
745
|
+
`provenance: "none"` (or `includeProvenance: false`) spends the whole budget
|
|
746
|
+
on the sections. The library exposes
|
|
747
|
+
`assembleContext(index, options)`, `conceptSections(doc)` and
|
|
748
|
+
`sectionUnits(index)`.
|
|
749
|
+
|
|
750
|
+
Section anchors are an okf-mcp extension; OKF v0.2 defines none and nothing
|
|
751
|
+
in a bundle needs them. A concept is cut at its document-level headings: the
|
|
752
|
+
text before the first heading (with the title and description) is addressed
|
|
753
|
+
by the concept URI alone, every other section by `uri#slug`. The heading
|
|
754
|
+
text is first normalised (the line breaks of a setext or wrapped heading and
|
|
755
|
+
every whitespace run become one space, then trimmed); the slug then follows
|
|
756
|
+
GitHub's rule: lower-cased, every character other than a letter, a combining
|
|
757
|
+
mark, a digit, an underscore, a hyphen or a space removed, and each space
|
|
758
|
+
turned into a hyphen (so `## Consentito / Allowed` gives
|
|
759
|
+
`consentito--allowed`, as on GitHub). A repeated heading takes `-1`, `-2`,
|
|
760
|
+
... in document order. A reader that drops the fragment still lands on the
|
|
761
|
+
concept. An anchor depends only on the heading texts up to its own: edits to
|
|
762
|
+
any section body, whitespace-only edits and edits to later sections leave it
|
|
763
|
+
unchanged, while renaming the heading, or adding a heading with the same text
|
|
764
|
+
before it, changes it.
|
|
765
|
+
|
|
766
|
+
## Embeddings (0.11, opt-in)
|
|
767
|
+
|
|
768
|
+
Dense retrieval is off unless configured, and the default install makes no network calls. 0.11 ships the embedder interface, a zero-dependency client for the OpenAI embeddings API and compatible servers (Ollama, vLLM, LM Studio), a vector cache kept outside the bundle under `$XDG_CACHE_HOME/okf-mcp/<sha256 of the root>/` (`~/.cache/okf-mcp/` or `%LOCALAPPDATA%\okf-mcp\`), so a populated cache never dirties a Git worktree and can be deleted at any time, and hybrid search over it.
|
|
769
|
+
|
|
770
|
+
Enable it in `okf.project.yaml` (or, for `--root` mode, in a JSON or YAML file passed with `--embedder-config <file>`, which may also be a bare embedder block; `--cache-dir <dir>` overrides the cache location):
|
|
771
|
+
|
|
772
|
+
```yaml
|
|
773
|
+
embedder:
|
|
774
|
+
type: openai
|
|
775
|
+
baseUrl: https://api.openai.com # or a local OpenAI-compatible server
|
|
776
|
+
model: text-embedding-3-small
|
|
777
|
+
apiKeyEnv: OPENAI_API_KEY # the key is read only from this variable
|
|
778
|
+
dimensions: 512
|
|
779
|
+
# optional: batchSize, timeoutMs, maxRetries, concurrency, maxInputChars
|
|
780
|
+
cacheDir: ../okf-vectors # optional; relative to the project root, never inside it
|
|
781
|
+
fusion:
|
|
782
|
+
alpha: 0.4 # weight of the dense side (default 0.4, chosen on the development queries)
|
|
783
|
+
normalization: tmm # tmm (default), lexical-tmm or minmax
|
|
784
|
+
embedUnits: concepts # concepts (default) or sections (one vector per section; better on synonym queries)
|
|
785
|
+
```
|
|
786
|
+
|
|
787
|
+
Embedder settings are never accepted as tool arguments. At startup the server validates the embedder, discovers the dimension when it is not configured, opens the cache and embeds the missing units in the background; it never fails to start because of the embedder. `search_concepts` then fuses the lexical ranking with cosine similarity over the cache by convex combination of normalised scores: each side is scaled by its best score above a lower bound: by default the theoretical minimum of its scoring function (0 for the lexical score, -1 for cosine; `tmm`); `lexical-tmm` uses the theoretical minimum on the lexical side only and `minmax` the observed minimum on both, as in Bruch et al., arXiv:2210.11934 (`hybrid: false` per call keeps it lexical and makes no request). Remote bundles stay lexical-only: their text is never embedded. `mode`, `coverage`, `allTermsTotal` and the `minCoverage`/`minRelevance` floors keep their lexical meaning (an explicit `mode: "all"` only re-ranks the all-term matches): the lexical hits are fused with the 200 nearest concepts by cosine, a fixed candidate set so every page of a query paginates the same ranking, and each candidate carries its own lexical evidence (matched terms, coverage, score), which the floors and `lowConfidence` (computed on the displayed top result) read. When the all-term pass ran and the query holds quoted or identifier-like terms, the all-term matches stay ahead of every semantic neighbour. `relevance` and `score` become fused and each result adds `lexicalScore`, `denseScore` (cosine) and `fusedScore`. The response adds `hybrid`, `alpha`, `normalization`, `embedder: { id, remote, dimension, degraded, code?, serverCode? }`, `cache: { rows, dir? }` (`dir` only on a `--write` server), `usage: { promptTokens, requests }` for the query encoding, and `timings: { queryEncodingMs, searchMs, totalMs }`. Whenever the embedder is missing, failing or the cache is empty, search runs lexical-only with `embedder.degraded: true`, a fixed `code` and, for HTTP failures, the enumerated `serverCode`; no server-supplied text is ever returned. After a failed query encoding the server stays lexical for 30 seconds before trying again. After each successful `okf_apply_changes` batch only the changed units are embedded (one request when the batch fits) and the receipt carries `embedding: { units, embedded, skipped, embedder, cache, usage, durationMs }`. The read-only `embedding_status` tool, listed only when an embedder is configured, reports the embedder, the cache, the startup and last preparation receipts and the token usage. Receipts report `embedder.remote: true` whenever text leaves the machine. The cache is keyed by the embedder identity `openai:<endpoint>:<model>:<dimension>:<maxInputChars>`, so a change of endpoint, model, dimension or truncation length rebuilds it. The library exposes `createOpenAiEmbedder`, `openVectorCache`, `resolveCacheDir`, `prepareEmbeddings`, `openEmbeddingRuntime`, `denseSearch` and `fuseRankings`; `node scripts/eval-search.js --embedder <file>` scores hybrid runs on the retrieval fixtures.
|
|
788
|
+
|
|
789
|
+
Long or identifier-dense documents: the client truncates every input at `maxInputChars` (default 24,000 characters) and plans requests with a conservative estimate of one token per 3 characters, because generated contracts and column lists run at about 2.6 characters per token and overflow the provider's 8,192-token input limit at the old 32,000-character default (the default change rebuilds caches keyed with 32000). If the provider still refuses a request as `invalid_request`, the client splits the batch in halves until the refused inputs stand alone (a bounded number of extra requests), retries each refused input once at half its length (never below 2,000 characters) and, if it is refused again, skips that unit: the preparation receipt lists it under `skipped: [{ id, reason: "input_rejected" }]`, every other unit is embedded and search stays hybrid. `embedding_status` reports `skipped: { count, ids }` (the first five ids) for the last preparation, and the startup receipt carries the same field; a skipped unit is retried by the next preparation and is found by its lexical score meanwhile. A request whose every input is refused is a configuration problem and still fails as before.
|
|
790
|
+
|
|
791
|
+
Adaptive fusion weight (0.12): `fusion.alpha: adaptive` decides the weight of the semantic side once per query, from what the lexical pass already knows, so every page of a query uses the same weight: `fusion.adaptive.low` when the query holds quoted or identifier-like terms and some concept matches every term (the all-term matches still stay ahead of every semantic neighbour), `mid` when at least `autoFill` concepts match every term, `high` when no concept matches every term and none matches even half of them, and in between linear in the best lexical coverage, from `high` at 0.5 to `mid` at 1. The weights default to the development-split choice `{ low: 0.1, mid: 0.5, high: 0.9 }`; `high` may not be below `mid`. Hybrid responses report `alphaUsed` and `alphaReason` (`fixed`, `literal_terms`, `all_terms`, `weak_lexical` or `interpolated`) and `embedding_status` reports the setting and its weights. The default stays the fixed 0.4, which ranks exactly as 0.11 did: on the fixtures the adaptive weight raised alpinaria Recall@5 from 0.830 to 0.838 (synonyms 0.542 to 0.604) but lowered atlas from 0.882 to 0.870, so it missed its pre-registered conditions (`test/fixtures/retrieval/reports/hybrid-0.12-2026-10-25.md`).
|
|
792
|
+
|
|
793
|
+
```yaml
|
|
794
|
+
fusion:
|
|
795
|
+
alpha: adaptive # or a number between 0 and 1 (default 0.4)
|
|
796
|
+
adaptive: { low: 0.1, mid: 0.5, high: 0.9 }
|
|
797
|
+
```
|
|
798
|
+
|
|
799
|
+
Contextual units (0.12): `embedUnits: contextual-sections` embeds each section after a one-line prefix naming its concept, `title · type · path` (at most 160 characters; a long title is shortened first), so a bare "Limits" or "Steps" section carries the system it belongs to; `contextual-concepts` puts `type · path` before the concept text. Anchors are those of `sections`. The prefixed texts have their own hashes, so switching unit sets re-embeds every unit once (the preparation receipt, the startup receipt and `embedding_status` name the unit set; `embedded` and `pruned` count the switch), and afterwards a body edit re-embeds only its section (a title, type or path edit re-embeds every section of that concept). `concepts` stays the default: on the development queries no other unit set beat it by the pre-registered rule (mean dev Recall@5 0.844 for concepts, 0.843 contextual-concepts, 0.841 contextual-sections, 0.834 sections), and on the fixtures' short sections the prefix costs 56% more prompt tokens (6.6% for contextual-concepts).
|
|
800
|
+
|
|
801
|
+
Confidence (0.12): every `search_concepts` and `get_context` response to a query carries `confidence: { coverage, topSimilarity, lowConfidence, reasons }`. `coverage` is the share of query terms the top result matched; `topSimilarity` is the best cosine similarity between the query and any candidate's units when the semantic side ran (`null` otherwise); `lowConfidence` (also the top-level field) is true when the any-term fallback produced the results and the top result matched fewer than half of the terms (reason `weak_lexical_match`), or when the top result matched fewer than half of the terms and `topSimilarity` is below `confidence.minSimilarity` (reason `low_similarity`). Lexical-only responses have no similarity and keep the 0.10 rule. `get_context` takes `abstainOnLowConfidence: true` to return no sections for a low-confidence query (the response keeps the confidence block and the candidate concepts and says `abstained: true`). The similarity threshold depends on the embedding model; the default, 0, was chosen on the development queries for `text-embedding-3-small`: no threshold up to 0.8 flagged a single extra unanswerable query there, because every unanswerable query whose top result matched fewer than half of the terms was already an any-term fallback. A deployment can set its own:
|
|
802
|
+
|
|
803
|
+
```yaml
|
|
804
|
+
confidence:
|
|
805
|
+
minSimilarity: 0.3 # cosine below which a weakly matched top result is flagged
|
|
806
|
+
```
|
|
807
|
+
|
|
653
808
|
## Graph Behavior
|
|
654
809
|
|
|
655
810
|
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.
|
package/bin/okf-mcp.js
CHANGED
|
@@ -7,7 +7,12 @@ const debug = process.argv.includes("--debug");
|
|
|
7
7
|
const args = process.argv.slice(2).filter((arg) => arg !== "--debug");
|
|
8
8
|
|
|
9
9
|
main(args).catch((error) => {
|
|
10
|
-
const message =
|
|
10
|
+
const message =
|
|
11
|
+
debug && error && error.stack
|
|
12
|
+
? error.stack
|
|
13
|
+
: error && error.message
|
|
14
|
+
? error.message
|
|
15
|
+
: String(error);
|
|
11
16
|
process.stderr.write(message + "\n");
|
|
12
17
|
process.exitCode = exitCodeForError(error);
|
|
13
18
|
});
|
|
@@ -19,6 +19,8 @@ relations:
|
|
|
19
19
|
target: repo://src/store.js
|
|
20
20
|
- type: configured_by
|
|
21
21
|
target: repo://src/live-authoring.js
|
|
22
|
+
- type: configured_by
|
|
23
|
+
target: repo://src/policy/write-policy.js
|
|
22
24
|
- type: checked_by
|
|
23
25
|
target: repo://test/okf-mcp.test.js
|
|
24
26
|
- type: checked_by
|
|
@@ -31,6 +33,12 @@ relations:
|
|
|
31
33
|
target: repo://test/live-agent-workflow.test.js
|
|
32
34
|
- type: checked_by
|
|
33
35
|
target: repo://test/producer.test.js
|
|
36
|
+
- type: checked_by
|
|
37
|
+
target: repo://test/write-policy.test.js
|
|
38
|
+
- type: checked_by
|
|
39
|
+
target: repo://test/write-policy-enforcement.test.js
|
|
40
|
+
- type: checked_by
|
|
41
|
+
target: repo://test/content-boundary.test.js
|
|
34
42
|
---
|
|
35
43
|
|
|
36
44
|
# Authoring Safety
|
|
@@ -47,11 +55,13 @@ Proposal creation never writes a concept file. Acceptance repeats validation. Up
|
|
|
47
55
|
|
|
48
56
|
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.
|
|
49
57
|
|
|
58
|
+
An optional write policy narrows direct authoring and proposals per actor. It is trusted configuration only (`writePolicy` in `okf.project.yaml`, or `--policy <file>` with `--root`), never a tool or HTTP argument. Proposals are judged when stored, against the proposing actor, and again before acceptance writes them, against the recorded actor (else the accepting one), which publishes a create with the default status it was judged with; a write without an actor is judged as the literal actor `unknown`. Producers are judged under `process:<name>` only when the policy sets `applyToProducers: true`, and their output, which is never rewritten, must carry any required status itself. An ordered list of rules matches the configured actor and, optionally, bundle ids, concept paths (a fixed glob subset of `*`, `**`, and literal segments, never compiled to a regular expression, with traversal and absolute patterns rejected at load), and concept types. The first matching rule decides; otherwise `defaultEffect` (`allow` unless set to `deny`) does. Allow rules may require frontmatter fields, stamp a `defaultStatus` on creates that set none, and cap the concepts per batch. Only the concepts a batch creates or updates are judged; existing content is never retro-validated. Violations are structured `policy_violation` records carrying the deciding rule id, a reason (`actor_denied`, `bundle_denied`, `path_denied`, `type_denied`, `missing_required_field`, `batch_too_large`), and the path, bundle, URI, or field involved. The batch validator reports them read-only, and apply rejects the batch before staging or writing any file. Their messages, like every error message, name rules, paths, and URIs, never catalog text.
|
|
59
|
+
|
|
50
60
|
Configured producer bundle roots are also protected from direct authoring. A producer candidate must declare and emit OKF v0.2, carry valid native generation and source provenance on every concept, contain no producer-owned graph failures, and leave the complete future project conformant and valid. Secret values requested through the host are rejected if they appear in generated bytes. Invalid previews remain inspectable but are never publishable.
|
|
51
61
|
|
|
52
62
|
Producer ownership is recorded in `.okf-producer.json` with relative paths and content digests. New unowned path collisions, modified owned files, corrupt or foreign manifests, path traversal, and symbolic-link traversal block publication. Only unchanged paths owned by the previous manifest may be removed. The manifest is written last after staged publication, and persisted validation failures trigger revision-aware rollback.
|
|
53
63
|
|
|
54
|
-
Rollback revision-checks a published target immediately before restoring it. Detected external replacements are preserved and reported as rollback conflicts, but this is best-effort detection rather than a cross-process compare-and-swap primitive. Optional Git commits require a clean worktree before publication, reject active filter attributes and hidden `assume-unchanged`/`skip-worktree` index flags, and disable replace-object resolution. They build an isolated index directly from validated Markdown bytes, create the exact tree without mutating the shared index, publish it through a compare-and-swap ref update, synchronize only affected ordinary-index paths afterward, and never push. Commit, target, index, and durability states remain explicit when a timeout or concurrent replacement cannot be classified safely.
|
|
64
|
+
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. Untracked files count as a dirty worktree, so with `--git-commit` the proposal directory (`.okf-proposals/` by default, or the `--proposal-root` location) must be ignored by Git. 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.
|
|
55
65
|
|
|
56
66
|
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.
|
|
57
67
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mfdaves/okf-mcp",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.12.0-rc.1",
|
|
4
4
|
"description": "Local-first Open Knowledge Format validator, graph index, CLI, and MCP stdio server.",
|
|
5
5
|
"homepage": "https://github.com/mfdaves/okf-mcp#readme",
|
|
6
6
|
"repository": {
|
|
@@ -18,14 +18,22 @@
|
|
|
18
18
|
"okf-mcp": "bin/okf-mcp.js"
|
|
19
19
|
},
|
|
20
20
|
"scripts": {
|
|
21
|
-
"test": "node --test",
|
|
22
|
-
"check": "node --test",
|
|
21
|
+
"test": "node --test \"test/*.test.js\"",
|
|
22
|
+
"check": "node --test \"test/*.test.js\"",
|
|
23
|
+
"lint": "biome lint",
|
|
24
|
+
"format": "biome format --write",
|
|
25
|
+
"format:check": "biome format",
|
|
23
26
|
"self:validate": "node bin/okf-mcp.js --root okf/okf-mcp validate",
|
|
24
27
|
"pack:check": "npm pack --dry-run",
|
|
25
28
|
"package:smoke": "node scripts/package-smoke.js",
|
|
26
29
|
"prepublishOnly": "npm run check && npm run self:validate",
|
|
27
30
|
"inspect": "node bin/okf-mcp.js --help",
|
|
28
|
-
"start": "node bin/okf-mcp.js"
|
|
31
|
+
"start": "node bin/okf-mcp.js",
|
|
32
|
+
"eval:search": "node scripts/eval-search.js --fixture alpinaria --fixture atlas --split all",
|
|
33
|
+
"bench:search": "node --expose-gc scripts/search-benchmark.js --root test/fixtures/retrieval/alpinaria/bundles/alpinaria --qrels test/fixtures/retrieval/alpinaria/queries.json --rounds 20",
|
|
34
|
+
"bench:index": "node --expose-gc scripts/index-benchmark.js --rounds 10",
|
|
35
|
+
"bench:write": "node scripts/write-benchmark.js",
|
|
36
|
+
"eval:context": "node scripts/eval-context.js --fixture alpinaria --fixture atlas"
|
|
29
37
|
},
|
|
30
38
|
"keywords": [
|
|
31
39
|
"mcp",
|
|
@@ -44,6 +52,7 @@
|
|
|
44
52
|
"okf.project.yaml",
|
|
45
53
|
"server.json",
|
|
46
54
|
"README.md",
|
|
55
|
+
"CHANGELOG.md",
|
|
47
56
|
"LICENSE"
|
|
48
57
|
],
|
|
49
58
|
"engines": {
|
|
@@ -59,6 +68,9 @@
|
|
|
59
68
|
"minisearch": "7.2.0"
|
|
60
69
|
},
|
|
61
70
|
"devDependencies": {
|
|
62
|
-
"@
|
|
71
|
+
"@biomejs/biome": "2.5.15",
|
|
72
|
+
"@modelcontextprotocol/client": "2.0.0",
|
|
73
|
+
"@nlpjs/lang-en-min": "4.26.1",
|
|
74
|
+
"@nlpjs/lang-it": "4.26.1"
|
|
63
75
|
}
|
|
64
76
|
}
|
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.12.0-rc.1",
|
|
12
12
|
"packages": [
|
|
13
13
|
{
|
|
14
14
|
"registryType": "npm",
|
|
15
15
|
"identifier": "@mfdaves/okf-mcp",
|
|
16
|
-
"version": "0.
|
|
16
|
+
"version": "0.12.0-rc.1",
|
|
17
17
|
"transport": {
|
|
18
18
|
"type": "stdio"
|
|
19
19
|
},
|