@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 +21 -0
- package/README.md +504 -0
- package/bin/okf-mcp.js +13 -0
- package/okf/bundles/okf-mcp/distribution/reference-bundle.md +42 -0
- package/okf/bundles/okf-mcp/index.md +17 -0
- package/okf/bundles/okf-mcp/interfaces/http-authoring-api.md +26 -0
- package/okf/bundles/okf-mcp/interfaces/mcp-tools.md +34 -0
- package/okf/bundles/okf-mcp/overview/okf-mcp.md +28 -0
- package/okf/bundles/okf-mcp/policies/authoring-safety.md +38 -0
- package/okf/bundles/okf-mcp/runtime/file-concept-store.md +30 -0
- package/okf/bundles/okf-mcp/runtime/indexer.md +34 -0
- package/okf/bundles/okf-mcp/runtime/mcp-server.md +32 -0
- package/okf/bundles/okf-mcp/specs/concept-format.md +32 -0
- package/okf/bundles/okf-mcp/workflows/concept-authoring.md +30 -0
- package/okf/bundles/okf-mcp/workflows/concept-update.md +30 -0
- package/okf.project.yaml +5 -0
- package/package.json +55 -0
- package/src/authoring.js +334 -0
- package/src/cli.js +427 -0
- package/src/graph.js +278 -0
- package/src/http-server.js +137 -0
- package/src/index.js +15 -0
- package/src/indexer.js +437 -0
- package/src/mcp-server.js +816 -0
- package/src/parser.js +364 -0
- package/src/plugins.js +209 -0
- package/src/project.js +235 -0
- package/src/remote.js +179 -0
- package/src/search.js +179 -0
- package/src/store.js +341 -0
- package/src/validation.js +117 -0
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.
|