@mfdaves/okf-mcp 0.3.2-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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 OKF contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,504 @@
1
+ # okf-mcp
2
+
3
+ `okf-mcp` is a project-agnostic Open Knowledge Format CLI, graph index, generator runner, MCP stdio server, and optional HTTP authoring API.
4
+
5
+ It consumes one or more directories of Markdown files with YAML frontmatter, treats non-reserved Markdown files as OKF concepts, and exposes those concepts through CLI commands plus MCP resources and tools for structured search, validation, graph navigation, and proposal-based authoring.
6
+
7
+ The core intentionally has no database, embeddings, build step, or hosted-service dependency. It uses `js-yaml` for standards-oriented YAML parsing. Local bundle mode makes no network calls. Optional remote bundles can fetch public Markdown concepts from GitHub when configured. Generator plugins and accepted authoring proposals are the write paths, and both write only under configured project directories.
8
+
9
+ ## Install And Run
10
+
11
+ The current release candidate is published under npm's `next` tag. Pin the
12
+ exact version for unattended MCP clients:
13
+
14
+ ```bash
15
+ npx -y @mfdaves/okf-mcp@0.3.2-rc.1 --version
16
+ npx -y @mfdaves/okf-mcp@0.3.2-rc.1 --project ./okf.project.yaml validate
17
+ ```
18
+
19
+ For a persistent installation:
20
+
21
+ ```bash
22
+ npm install --global @mfdaves/okf-mcp@0.3.2-rc.1
23
+
24
+ okf --version
25
+ okf --project ./okf.project.yaml validate
26
+ okf-mcp --project ./okf.project.yaml mcp
27
+ ```
28
+
29
+ To work from the source repository:
30
+
31
+ ```bash
32
+ git clone https://github.com/mfdaves/okf-mcp.git
33
+ cd okf-mcp
34
+ npm ci
35
+ npm test
36
+ node bin/okf-mcp.js --version
37
+ ```
38
+
39
+ Node 22 or newer is required.
40
+
41
+ `--bundle` accepts either a path or `id=path`. Multiple `--bundle` flags are allowed.
42
+
43
+ `--remote-bundle` accepts `id=https://github.com/<owner>/<repo>/tree/<ref>/<path>`. It fetches public Markdown files from that GitHub tree and indexes them as a read-only bundle.
44
+
45
+ `--inspect` prints a compact graph summary and exits. Without `--inspect` and without an explicit command, the process starts a stdio MCP server.
46
+
47
+ The package exposes both `okf` and `okf-mcp` binaries when installed. If neither `--project` nor a bundle source is passed, the CLI discovers the nearest `okf.project.yaml` or `okf.project.json` from the current directory.
48
+
49
+ CLI exit statuses are `0` for success, `1` for validation or operational failure, and `2` for invalid usage. Unknown options are rejected.
50
+
51
+ ## Published OKF Reference
52
+
53
+ This repository publishes a self-describing OKF bundle for the product, its runtime boundaries, interfaces, authoring workflows, and safety policy. The canonical entry point is `okf://okf-mcp/overview/okf-mcp`.
54
+
55
+ Validate and query the bundled reference from a checkout or installed package:
56
+
57
+ ```bash
58
+ okf --project okf.project.yaml validate
59
+ okf --project okf.project.yaml search "proposal"
60
+ okf --project okf.project.yaml concept okf://okf-mcp/overview/okf-mcp
61
+ ```
62
+
63
+ Load the latest published reference directly from GitHub:
64
+
65
+ ```bash
66
+ okf --remote-bundle okf-mcp=https://github.com/mfdaves/okf-mcp/tree/main/okf/bundles/okf-mcp --inspect
67
+ ```
68
+
69
+ For reproducible consumption, replace `main` with a release tag. The
70
+ `@mfdaves/okf-mcp` npm package includes both `okf.project.yaml` and the
71
+ complete reference bundle.
72
+
73
+ ## Project Config
74
+
75
+ For project-agnostic use, create an `okf.project.yaml` at a repository root:
76
+
77
+ ```yaml
78
+ project: Example
79
+ bundles:
80
+ - id: app
81
+ root: okf/bundles/app
82
+ include: ["**/*.md"]
83
+ exclude: ["archive/**"]
84
+ - id: data
85
+ root: okf/bundles/data
86
+ relationTypes:
87
+ - deployed_by
88
+ remoteBundles:
89
+ - id: shared
90
+ url: https://github.com/example/okf-atlas/tree/main/bundles/shared
91
+ include: ["public/**"]
92
+ exclude: ["drafts/**"]
93
+ plugins:
94
+ - name: docs
95
+ type: filesystem
96
+ root: docs
97
+ output: okf/bundles/app/generated/docs
98
+ bundle: app
99
+ ```
100
+
101
+ Run project commands:
102
+
103
+ ```bash
104
+ okf --project okf.project.yaml validate
105
+ okf --project okf.project.yaml search "orders"
106
+ okf --project okf.project.yaml graph mermaid
107
+ okf --project okf.project.yaml generate
108
+ okf --project okf.project.yaml mcp
109
+ okf --project okf.project.yaml mcp --authoring
110
+ okf --project okf.project.yaml mcp --allow-remote-tool
111
+ OKF_WRITE_TOKEN=change-me okf --project okf.project.yaml serve
112
+ okf --remote-bundle shared=https://github.com/example/okf-atlas/tree/main/bundles/shared --inspect
113
+ ```
114
+
115
+ Commands:
116
+
117
+ - `mcp`
118
+ - `validate`
119
+ - `graph [json|dot|mermaid]`
120
+ - `search <query>`
121
+ - `concept <uri>`
122
+ - `neighbors <uri>`
123
+ - `paths <from> <to>`
124
+ - `generate`
125
+ - `serve`
126
+
127
+ `serve` options:
128
+
129
+ - `--host <host>`: bind host, default `127.0.0.1`
130
+ - `--port <port>`: bind port, default `8765`
131
+ - `--write-token <token>`: bearer token for write endpoints; defaults to `OKF_WRITE_TOKEN`
132
+ - `--proposal-root <path>`: proposal JSON directory; defaults to `.okf-proposals` under the project root
133
+
134
+ ## MCP Client Config
135
+
136
+ Example client configuration:
137
+
138
+ ```json
139
+ {
140
+ "mcpServers": {
141
+ "okf": {
142
+ "command": "npx",
143
+ "args": [
144
+ "-y",
145
+ "@mfdaves/okf-mcp@0.3.2-rc.1",
146
+ "--bundle",
147
+ "app=/absolute/path/to/repo/okf/bundles/app",
148
+ "mcp"
149
+ ]
150
+ }
151
+ }
152
+ }
153
+ ```
154
+
155
+ Project config mode, with read-only project helpers but without proposal mutations:
156
+
157
+ ```json
158
+ {
159
+ "mcpServers": {
160
+ "okf": {
161
+ "command": "npx",
162
+ "args": [
163
+ "-y",
164
+ "@mfdaves/okf-mcp@0.3.2-rc.1",
165
+ "--project",
166
+ "/absolute/path/to/repo/okf.project.yaml",
167
+ "mcp"
168
+ ]
169
+ }
170
+ }
171
+ }
172
+ ```
173
+
174
+ 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.
175
+
176
+ ## Concept Format
177
+
178
+ The server exposes one resource per Markdown document:
179
+
180
+ ```text
181
+ okf://<bundle-id>/<relative-path>
182
+ ```
183
+
184
+ Resources use `text/markdown`. Reserved `index.md` and `log.md` files are resources, but they are not concept documents.
185
+
186
+ Concept files may use a path-derived URI or set a stable `id`:
187
+
188
+ ```markdown
189
+ ---
190
+ id: okf://app/routes/order-status
191
+ type: API Route
192
+ title: Order Status Route
193
+ description: Serves order status state.
194
+ aliases: [order-status]
195
+ tags: [api, orders]
196
+ relations:
197
+ - type: consumes
198
+ target: okf://data/tables/order_status
199
+ - type: configured_by
200
+ target: repo://src/routes/order-status.js
201
+ ---
202
+
203
+ # Order Status Route
204
+ ```
205
+
206
+ `okf://` relation targets must resolve to a known concept. Non-OKF targets such as `repo://` are treated as external opaque references.
207
+
208
+ ## Tools
209
+
210
+ - `list_bundles`
211
+ - `list_concepts`
212
+ - `get_concept`
213
+ - `search_concepts`
214
+ - `list_types`
215
+ - `list_tags`
216
+ - `list_relation_types`
217
+ - `load_remote_bundle`
218
+ - `list_remote_bundles`
219
+ - `okf_validate_concept`
220
+ - `okf_suggest_concept_path`
221
+ - `okf_propose_concept`
222
+ - `okf_propose_update`
223
+ - `okf_list_proposals`
224
+ - `okf_get_proposal`
225
+ - `okf_accept_proposal`
226
+ - `okf_reject_proposal`
227
+ - `get_graph`
228
+ - `get_neighbors`
229
+ - `get_subgraph`
230
+ - `find_paths`
231
+ - `graph_summary`
232
+ - `validate_bundle`
233
+ - `validate_project`
234
+ - `export_graph`
235
+
236
+ Most MCP tools are read-only over the current index. `load_remote_bundle` mutates only the server's in-memory index by fetching a public GitHub tree; it does not write files.
237
+
238
+ Every MCP tool includes a purpose-specific description, descriptions for its input parameters, and standard annotations covering read-only behavior, destructive behavior, idempotency, and external access.
239
+
240
+ Tool discovery and direct invocation use the same capability checks:
241
+
242
+ | Mode | Proposal mutations | Runtime remote load | Configured remote reads |
243
+ | --- | --- | --- | --- |
244
+ | default | disabled | disabled | enabled |
245
+ | `--authoring` | enabled | disabled | enabled |
246
+ | `--allow-remote-tool` | disabled | enabled | enabled |
247
+ | both flags | enabled | enabled | enabled |
248
+
249
+ Project mode may expose read-only concept validation, path suggestion, and proposal inspection helpers. The `okf_*` mutation tools are proposal-first and require both project mode and `--authoring`. Proposing a concept or update writes only a proposal record. Accepting a proposal writes the Markdown concept into the configured bundle root and rebuilds the complete index from configured local bundles, configured remote bundles, and runtime-loaded remote bundles.
250
+
251
+ ## Authoring Concepts
252
+
253
+ Concept authoring is available through MCP tools started with `--authoring` and through the HTTP API. Clients never need direct local file access.
254
+
255
+ MCP proposal flow:
256
+
257
+ ```json
258
+ {
259
+ "name": "okf_propose_concept",
260
+ "arguments": {
261
+ "bundle": "app",
262
+ "path": "tools/create-order.md",
263
+ "frontmatter": {
264
+ "type": "MCP Tool",
265
+ "title": "Create Order",
266
+ "relations": [
267
+ {
268
+ "type": "related_to",
269
+ "target": "okf://app/workflows/order-creation"
270
+ }
271
+ ]
272
+ },
273
+ "body": "# Create Order\n\nCreates an order through the application MCP tool.",
274
+ "message": "Document create_order for agents."
275
+ }
276
+ }
277
+ ```
278
+
279
+ Then call `okf_accept_proposal` with the returned `proposal.id`.
280
+
281
+ To correct an existing concept, read it with `get_concept`, then propose only the fields that need to change:
282
+
283
+ ```json
284
+ {
285
+ "name": "okf_propose_update",
286
+ "arguments": {
287
+ "uri": "okf://app/tools/create-order",
288
+ "frontmatter": {
289
+ "title": "Create Order Tool",
290
+ "description": "Creates a validated order."
291
+ },
292
+ "removeFrontmatterKeys": ["deprecatedField"],
293
+ "message": "Correct outdated tool metadata."
294
+ }
295
+ }
296
+ ```
297
+
298
+ Omitted frontmatter fields and an omitted body are preserved. The concept URI cannot change through an update. Each update proposal records the source file revision, and acceptance checks it again immediately before replacing the file so detected concurrent changes are rejected.
299
+
300
+ Safety rules:
301
+
302
+ - concept paths must be safe relative `.md` paths inside a writable bundle
303
+ - concept writes cannot traverse symbolic links under a writable bundle
304
+ - missing subdirectories are created only when a proposal is accepted
305
+ - `index.md` and `log.md` cannot be authored as concepts
306
+ - duplicate paths and duplicate `okf://` IDs are rejected
307
+ - updates cannot change concept identity and reject detected changes made after proposal creation
308
+ - invalid IDs, invalid relation types, and broken internal OKF relations fail validation
309
+ - external relation targets such as `repo://...` are allowed
310
+
311
+ ## HTTP API
312
+
313
+ Start the HTTP server:
314
+
315
+ ```bash
316
+ OKF_WRITE_TOKEN=change-me okf --project okf.project.yaml serve --host 127.0.0.1 --port 8765
317
+ ```
318
+
319
+ Read/validation endpoints:
320
+
321
+ - `GET /health`
322
+ - `GET /v1/bundles`
323
+ - `POST /v1/concepts/validate`
324
+ - `POST /v1/concepts/suggest-path`
325
+ - `GET /v1/proposals`
326
+ - `GET /v1/proposals/:id`
327
+
328
+ Mutation endpoints require `Authorization: Bearer <OKF_WRITE_TOKEN>`:
329
+
330
+ - `POST /v1/proposals`
331
+ - `POST /v1/proposals/update`
332
+ - `POST /v1/proposals/:id/accept`
333
+ - `POST /v1/proposals/:id/reject`
334
+
335
+ The default file-backed proposal store writes proposal JSON under `.okf-proposals` in the project root. Accepted proposals write Markdown concepts into the configured bundle root.
336
+
337
+ `POST /v1/concepts/validate` and `POST /v1/concepts/suggest-path` do not persist anything. `POST /v1/proposals` persists only a proposal record. Only `POST /v1/proposals/:id/accept` writes a concept Markdown file.
338
+
339
+ ## Remote Bundles
340
+
341
+ Remote bundles let one project consume concepts published by another repository without cloning or vendoring them locally.
342
+
343
+ Supported source:
344
+
345
+ - Public GitHub repository tree URLs: `https://github.com/<owner>/<repo>/tree/<ref>/<path>`
346
+
347
+ Remote loading:
348
+
349
+ - indexes only `.md` files
350
+ - ignores non-Markdown files
351
+ - keeps each remote bundle under its configured bundle id
352
+ - supports `include` and `exclude` filters
353
+ - resolves Markdown links inside the remote bundle path
354
+ - enforces file count and byte limits
355
+ - does not execute code from the remote repository
356
+
357
+ CLI examples:
358
+
359
+ ```bash
360
+ okf --remote-bundle shared=https://github.com/example/okf-atlas/tree/main/bundles/shared --inspect
361
+ okf --project okf.project.yaml --remote-bundle vendor=https://github.com/example/vendor-okf/tree/main/bundles/catalog validate
362
+ ```
363
+
364
+ MCP runtime loading:
365
+
366
+ Start the MCP server with `--allow-remote-tool` before calling `load_remote_bundle`.
367
+
368
+ ```json
369
+ {
370
+ "name": "load_remote_bundle",
371
+ "arguments": {
372
+ "id": "shared",
373
+ "url": "https://github.com/example/okf-atlas/tree/main/bundles/shared",
374
+ "include": ["public/**"]
375
+ }
376
+ }
377
+ ```
378
+
379
+ Use `list_remote_bundles` to inspect what was loaded.
380
+
381
+ ## Structured Search
382
+
383
+ `search_concepts` accepts:
384
+
385
+ - `query`
386
+ - `bundle`
387
+ - `types`
388
+ - `tagsAny`
389
+ - `tagsAll`
390
+ - `pathPrefix`
391
+ - `frontmatter`
392
+ - `linkedTo`
393
+ - `linkedFrom`
394
+ - `relationType`
395
+ - `orphanOnly`
396
+ - `limit`
397
+ - `offset`
398
+
399
+ Tags and types are matched case-insensitively. Arbitrary frontmatter filters support exact scalar matching and array-contains matching.
400
+
401
+ Example:
402
+
403
+ ```json
404
+ {
405
+ "query": "catalog",
406
+ "types": ["API Route"],
407
+ "tagsAll": ["api", "orders"],
408
+ "limit": 10
409
+ }
410
+ ```
411
+
412
+ ## Graph Behavior
413
+
414
+ Markdown links between OKF documents become `markdown_link` edges. Frontmatter `relations` become typed `relation` edges.
415
+
416
+ Graph tools return compact JSON:
417
+
418
+ ```json
419
+ {
420
+ "nodes": [
421
+ {
422
+ "id": "okf://app/routes/order-status",
423
+ "bundle": "app",
424
+ "path": "routes/order-status.md",
425
+ "type": "API Route",
426
+ "title": "Order Status Route",
427
+ "tags": ["api", "orders"],
428
+ "description": "Serves order status state."
429
+ }
430
+ ],
431
+ "edges": [],
432
+ "warnings": []
433
+ }
434
+ ```
435
+
436
+ Use `graph_summary` first for a compact overview, `get_neighbors` for local traversal, and `get_subgraph` for bounded expansion around seed concepts. `export_graph` supports `json`, `dot`, and `mermaid`. Pass `includeExternal: true` to graph tools when opaque external targets should appear as graph nodes.
437
+
438
+ Default relation types:
439
+
440
+ - `depends_on`
441
+ - `produces`
442
+ - `consumes`
443
+ - `persists_to`
444
+ - `materializes_to`
445
+ - `configured_by`
446
+ - `checked_by`
447
+ - `owned_by`
448
+ - `supersedes`
449
+ - `related_to`
450
+
451
+ Add project-specific relation types with `relationTypes` in `okf.project.yaml`.
452
+
453
+ Project paths in `bundles` and `plugins` must be relative paths that stay inside the directory containing `okf.project.yaml`. Absolute paths and `../` escapes are rejected.
454
+
455
+ Bundle `include` and `exclude` filters use simple path patterns:
456
+
457
+ - exact file paths, such as `services/order-status.md`
458
+ - directory prefixes, such as `archive/`
459
+ - `*` for one path segment
460
+ - `**` for any nested path
461
+
462
+ ## Validation
463
+
464
+ `validate`, `validate_bundle`, and `validate_project` return separate `conformant` and `validForProject` fields plus structured diagnostics. `valid` remains a compatibility alias for `validForProject`.
465
+
466
+ OKF conformance covers:
467
+
468
+ - parseable YAML mapping frontmatter on non-reserved concept documents
469
+ - a non-empty `type`
470
+ - the reserved structure of `index.md` and `log.md`
471
+
472
+ Unknown frontmatter keys and unknown concept type values do not fail conformance. The YAML parser supports nested mappings, arrays, block scalars, and other structures accepted by its safe YAML core schema; duplicate keys and unsupported custom tags are rejected.
473
+
474
+ Project validity additionally reports:
475
+
476
+ - duplicate OKF URIs
477
+ - broken internal Markdown links
478
+ - invalid relation types
479
+ - missing relation targets
480
+ - broken `okf://` relation targets
481
+ - duplicate bundle IDs
482
+ - invalid or escaping project paths
483
+ - links that resolve outside the configured bundle root
484
+ - missing bundle roots
485
+
486
+ The server keeps serving valid concepts from partial bundles.
487
+
488
+ ## Generator Plugins
489
+
490
+ Generator plugins are configured in `okf.project.yaml` and run with `generate`.
491
+
492
+ Built-in plugins:
493
+
494
+ - `filesystem`: creates one concept per matching source file. Defaults to Markdown files.
495
+ - `json-spec`: creates one concept per JSON file and can emit `persists_to` relations when a destination table is present.
496
+
497
+ Generated output is regular Markdown/YAML OKF and is validated by the same indexer as hand-authored concepts.
498
+
499
+ ## Limitations
500
+
501
+ - The MCP server implements the stdio JSON-RPC methods needed for resources and tools directly instead of using an SDK, so advanced SDK conveniences are out of scope.
502
+ - MCP initialization accepts only the explicitly supported protocol versions and rejects unsupported versions.
503
+ - There is no file watcher. Restart the server after external file changes. Concepts accepted through MCP authoring refresh the MCP server index immediately.
504
+ - The HTTP API is a lightweight built-in server, not a full hosted multi-tenant service.
package/bin/okf-mcp.js ADDED
@@ -0,0 +1,13 @@
1
+ #!/usr/bin/env node
2
+ "use strict";
3
+
4
+ const { exitCodeForError, main } = require("../src/cli");
5
+
6
+ const debug = process.argv.includes("--debug");
7
+ const args = process.argv.slice(2).filter((arg) => arg !== "--debug");
8
+
9
+ main(args).catch((error) => {
10
+ const message = debug && error && error.stack ? error.stack : (error && error.message ? error.message : String(error));
11
+ process.stderr.write(message + "\n");
12
+ process.exitCode = exitCodeForError(error);
13
+ });
@@ -0,0 +1,42 @@
1
+ ---
2
+ id: okf://okf-mcp/distribution/reference-bundle
3
+ type: OKF Distribution
4
+ title: Published okf-mcp Reference Bundle
5
+ description: Canonical public OKF bundle describing the okf-mcp product and its durable contracts.
6
+ tags: [distribution, reference, remote-bundle, dogfooding]
7
+ relations:
8
+ - type: consumes
9
+ target: okf://okf-mcp/specs/concept-format
10
+ - type: related_to
11
+ target: okf://okf-mcp/overview/okf-mcp
12
+ - type: checked_by
13
+ target: repo://test/okf-mcp.test.js
14
+ - type: checked_by
15
+ target: repo://scripts/package-smoke.js
16
+ - type: configured_by
17
+ target: repo://okf.project.yaml
18
+ - type: configured_by
19
+ target: repo://package.json
20
+ - type: configured_by
21
+ target: repo://.github/workflows/release.yml
22
+ - type: configured_by
23
+ target: repo://.agents/skills/okf-mcp-release/SKILL.md
24
+ ---
25
+
26
+ # Published okf-mcp Reference Bundle
27
+
28
+ This directory is the canonical machine-readable architectural reference for `okf-mcp`. It is maintained with the source repository and validated by the same runtime it documents.
29
+
30
+ The latest public bundle can be loaded from:
31
+
32
+ `https://github.com/mfdaves/okf-mcp/tree/main/okf/bundles/okf-mcp`
33
+
34
+ Consumers that need reproducibility should replace `main` with a release tag. Remote loading indexes only the Markdown tree and does not execute repository code.
35
+
36
+ The public npm package is `@mfdaves/okf-mcp`. Its allowlist includes `okf.project.yaml` and the `okf` directory so installed artifacts carry the same reference bundle. The package smoke gate installs the generated tarball into a clean temporary project, executes both binaries, validates this bundle, and exercises MCP initialization, tool discovery, and concept retrieval over stdio.
37
+
38
+ The repository release skill defines the package identity, capability matrix, self-validation, tarball, clean-install, prerelease, and registry synchronization gates. The trusted-publishing workflow repeats those checks against an exact Git release tag before publishing.
39
+
40
+ Concept ids use the stable `okf://okf-mcp/...` namespace. Internal relations target those stable ids, while `repo://` references connect durable concepts to their current implementation sources without turning source files into concepts.
41
+
42
+ The bundle deliberately documents product contracts, runtime boundaries, workflows, and policies rather than mirroring every source file.
@@ -0,0 +1,17 @@
1
+ # okf-mcp Reference Bundle
2
+
3
+ This bundle is the canonical machine-readable reference for the `okf-mcp` runtime, interfaces, workflows, policies, and distribution contract.
4
+
5
+ ## Start Here
6
+
7
+ - [okf-mcp Overview](overview/okf-mcp.md)
8
+ - [OKF Concept Format](specs/concept-format.md)
9
+ - [MCP Stdio Server](runtime/mcp-server.md)
10
+ - [OKF Indexer](runtime/indexer.md)
11
+ - [File Concept Store](runtime/file-concept-store.md)
12
+ - [MCP Tool Catalog](interfaces/mcp-tools.md)
13
+ - [HTTP Authoring API](interfaces/http-authoring-api.md)
14
+ - [Concept Authoring](workflows/concept-authoring.md)
15
+ - [Concept Update](workflows/concept-update.md)
16
+ - [Authoring Safety](policies/authoring-safety.md)
17
+ - [Published Reference Bundle](distribution/reference-bundle.md)
@@ -0,0 +1,26 @@
1
+ ---
2
+ id: okf://okf-mcp/interfaces/http-authoring-api
3
+ type: OKF Interface
4
+ title: HTTP Authoring API
5
+ description: Optional local HTTP interface for validation and proposal-based concept authoring.
6
+ tags: [http, api, authoring, interface]
7
+ relations:
8
+ - type: depends_on
9
+ target: okf://okf-mcp/workflows/concept-authoring
10
+ - type: checked_by
11
+ target: okf://okf-mcp/policies/authoring-safety
12
+ - type: configured_by
13
+ target: repo://src/http-server.js
14
+ - type: checked_by
15
+ target: repo://test/okf-mcp.test.js
16
+ ---
17
+
18
+ # HTTP Authoring API
19
+
20
+ The optional HTTP server exposes health, bundle discovery, candidate validation, path suggestion, proposal inspection, proposal creation, proposal update, acceptance, and rejection.
21
+
22
+ Mutation endpoints require an exact bearer token supplied through `OKF_WRITE_TOKEN` or the CLI option. Validation and read endpoints do not mutate concept files.
23
+
24
+ The API delegates all authoring behavior to the same service and file store used by MCP project mode. Proposal acceptance therefore uses the same validation, identity, revision, and path safeguards described by the [authoring safety policy](../policies/authoring-safety.md).
25
+
26
+ The default listener is local. This API is not an MCP Streamable HTTP transport, authentication service, hosted multi-tenant control plane, or distributed storage layer. Public deployment requires additional transport, identity, TLS, persistence, and concurrency design.
@@ -0,0 +1,34 @@
1
+ ---
2
+ id: okf://okf-mcp/interfaces/mcp-tools
3
+ type: OKF Interface
4
+ title: MCP Tool Catalog
5
+ description: Agent-facing tool contract for discovery, graph navigation, validation, remote loading, and authoring.
6
+ tags: [mcp, tools, interface, agents]
7
+ relations:
8
+ - type: depends_on
9
+ target: okf://okf-mcp/runtime/mcp-server
10
+ - type: consumes
11
+ target: okf://okf-mcp/runtime/indexer
12
+ - type: related_to
13
+ target: okf://okf-mcp/workflows/concept-authoring
14
+ - type: configured_by
15
+ target: repo://src/mcp-server.js
16
+ - type: checked_by
17
+ target: repo://test/okf-mcp.test.js
18
+ - type: checked_by
19
+ target: repo://test/mcp-hardening.test.js
20
+ ---
21
+
22
+ # MCP Tool Catalog
23
+
24
+ The MCP interface groups tools by intent.
25
+
26
+ Discovery tools list bundles, concepts, types, tags, relation types, and loaded remote bundles. `get_concept` returns the complete frontmatter and Markdown body for one concept. `search_concepts` combines text ranking with structured filters.
27
+
28
+ Graph tools return bounded graphs, neighbors, subgraphs, paths, summaries, and rendered exports. Canonical and path-derived concept URIs are accepted for direct graph traversal.
29
+
30
+ Validation tools inspect bundles, projects, and candidate concepts without writing. They report OKF conformance separately from project validity. Remote loading fetches a public GitHub tree into the in-memory index.
31
+
32
+ Project mode exposes read-only candidate validation, path suggestion, and proposal inspection helpers. Proposal creation, acceptance, and rejection additionally require `--authoring`. Runtime calls to `load_remote_bundle` require `--allow-remote-tool`; configured remote bundles remain readable without that flag.
33
+
34
+ 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.