@mfdaves/okf-mcp
Advanced tools
Local-first Open Knowledge Format validator, graph index, CLI, and MCP stdio server.
okf-mcp is a project-agnostic Open Knowledge Format CLI, graph index, generator runner, MCP stdio server, and optional HTTP authoring API.
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.
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.
The current stable release is 0.3.3, published under npm's latest tag.
Pin the exact version for reproducible use:
npx -y @mfdaves/okf-mcp@0.3.3 --version
npx -y @mfdaves/okf-mcp@0.3.3 --project ./okf.project.yaml validate
For a persistent installation:
npm install --global @mfdaves/okf-mcp@0.3.3
okf --version
okf --project ./okf.project.yaml validate
okf-mcp --project ./okf.project.yaml mcp
To work from the source repository:
git clone https://github.com/mfdaves/okf-mcp.git
cd okf-mcp
npm ci
npm test
node bin/okf-mcp.js --version
Node 22 or newer is required.
--bundle accepts either a path or id=path. Multiple --bundle flags are allowed.
--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.
--inspect prints a compact graph summary and exits. Without --inspect and without an explicit command, the process starts a stdio MCP server.
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.
CLI exit statuses are 0 for success, 1 for validation or operational failure, and 2 for invalid usage. Unknown options are rejected.
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.
Validate and query the bundled reference from a checkout or installed package:
okf --project okf.project.yaml validate
okf --project okf.project.yaml search "proposal"
okf --project okf.project.yaml concept okf://okf-mcp/overview/okf-mcp
Load the latest published reference directly from GitHub:
okf --remote-bundle okf-mcp=https://github.com/mfdaves/okf-mcp/tree/main/okf/bundles/okf-mcp --inspect
For reproducible consumption, replace main with a release tag. The
@mfdaves/okf-mcp npm package includes both okf.project.yaml and the
complete reference bundle.
For project-agnostic use, create an okf.project.yaml at a repository root:
project: Example
bundles:
- id: app
root: okf/bundles/app
include: ["**/*.md"]
exclude: ["archive/**"]
- id: data
root: okf/bundles/data
relationTypes:
- deployed_by
remoteBundles:
- id: shared
url: https://github.com/example/okf-atlas/tree/main/bundles/shared
include: ["public/**"]
exclude: ["drafts/**"]
plugins:
- name: docs
type: filesystem
root: docs
output: okf/bundles/app/generated/docs
bundle: app
Run project commands:
okf --project okf.project.yaml validate
okf --project okf.project.yaml search "orders"
okf --project okf.project.yaml graph mermaid
okf --project okf.project.yaml generate
okf --project okf.project.yaml mcp
okf --project okf.project.yaml mcp --authoring
okf --project okf.project.yaml mcp --allow-remote-tool
OKF_WRITE_TOKEN=change-me okf --project okf.project.yaml serve
okf --remote-bundle shared=https://github.com/example/okf-atlas/tree/main/bundles/shared --inspect
Commands:
mcpvalidategraph [json|dot|mermaid]search <query>concept <uri>neighbors <uri>paths <from> <to>generateserveserve options:
--host <host>: bind host, default 127.0.0.1--port <port>: bind port, default 8765--write-token <token>: bearer token for write endpoints; defaults to OKF_WRITE_TOKEN--proposal-root <path>: proposal JSON directory; defaults to .okf-proposals under the project rootExample client configuration:
{
"mcpServers": {
"okf": {
"command": "npx",
"args": [
"-y",
"@mfdaves/okf-mcp@0.3.3",
"--bundle",
"app=/absolute/path/to/repo/okf/bundles/app",
"mcp"
]
}
}
}
Project config mode, with read-only project helpers but without proposal mutations:
{
"mcpServers": {
"okf": {
"command": "npx",
"args": [
"-y",
"@mfdaves/okf-mcp@0.3.3",
"--project",
"/absolute/path/to/repo/okf.project.yaml",
"mcp"
]
}
}
}
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.
The stdio server supports MCP protocol versions 2025-11-25, 2025-06-18,
2025-03-26, and 2024-11-05. It returns a requested supported version.
For a well-formed unsupported version, it returns its preferred supported
version, 2025-11-25, so the client can continue or disconnect.
The transport uses standard JSON-RPC error codes for malformed messages,
invalid requests, unknown methods, invalid method parameters, missing
resources, and internal failures. Notifications never receive responses.
Expected failures from a known tool, such as a missing concept, a read-only
bundle, a failed remote fetch, or a proposal conflict, are returned as MCP
tool results with isError: true.
server.json describes the npm package as the stdio server
io.github.mfdaves/okf-mcp. Registry-aware clients should prompt for an
absolute okf.project.yaml path, pass it through --project, and append the
fixed mcp command.
The package, lockfile, CLI, MCP serverInfo, package.json mcpName, and
both versions in server.json are kept synchronized by the package smoke
gate. Release candidates remain available through npm's next tag; only a
verified stable version is published to the official MCP Registry.
The server exposes one resource per Markdown document:
okf://<bundle-id>/<relative-path>
Resources use text/markdown. Reserved index.md and log.md files are resources, but they are not concept documents.
Concept files may use a path-derived URI or set a stable id:
---
id: okf://app/routes/order-status
type: API Route
title: Order Status Route
description: Serves order status state.
aliases: [order-status]
tags: [api, orders]
relations:
- type: consumes
target: okf://data/tables/order_status
- type: configured_by
target: repo://src/routes/order-status.js
---
# Order Status Route
okf:// relation targets must resolve to a known concept. Non-OKF targets such as repo:// are treated as external opaque references.
list_bundleslist_conceptsget_conceptsearch_conceptslist_typeslist_tagslist_relation_typesload_remote_bundlelist_remote_bundlesokf_validate_conceptokf_suggest_concept_pathokf_propose_conceptokf_propose_updateokf_list_proposalsokf_get_proposalokf_accept_proposalokf_reject_proposalget_graphget_neighborsget_subgraphfind_pathsgraph_summaryvalidate_bundlevalidate_projectexport_graphMost 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.
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.
Tool arguments are validated against the advertised input schemas before execution. Unsupported fields, missing required values, incorrect primitive types, and out-of-range integers are rejected without coercion. Unknown or disabled tool names remain protocol-level invalid-parameter errors.
Tool discovery and direct invocation use the same capability checks:
| Mode | Proposal mutations | Runtime remote load | Configured remote reads |
|---|---|---|---|
| default | disabled | disabled | enabled |
--authoring | enabled | disabled | enabled |
--allow-remote-tool | disabled | enabled | enabled |
| both flags | enabled | enabled | enabled |
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.
Concept authoring is available through MCP tools started with --authoring and through the HTTP API. Clients never need direct local file access.
MCP proposal flow:
{
"name": "okf_propose_concept",
"arguments": {
"bundle": "app",
"path": "tools/create-order.md",
"frontmatter": {
"type": "MCP Tool",
"title": "Create Order",
"relations": [
{
"type": "related_to",
"target": "okf://app/workflows/order-creation"
}
]
},
"body": "# Create Order\n\nCreates an order through the application MCP tool.",
"message": "Document create_order for agents."
}
}
Then call okf_accept_proposal with the returned proposal.id.
To correct an existing concept, read it with get_concept, then propose only the fields that need to change:
{
"name": "okf_propose_update",
"arguments": {
"uri": "okf://app/tools/create-order",
"frontmatter": {
"title": "Create Order Tool",
"description": "Creates a validated order."
},
"removeFrontmatterKeys": ["deprecatedField"],
"message": "Correct outdated tool metadata."
}
}
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.
Safety rules:
.md paths inside a writable bundleindex.md and log.md cannot be authored as conceptsokf:// IDs are rejectedrepo://... are allowedStart the HTTP server:
OKF_WRITE_TOKEN=change-me okf --project okf.project.yaml serve --host 127.0.0.1 --port 8765
Read/validation endpoints:
GET /healthGET /v1/bundlesPOST /v1/concepts/validatePOST /v1/concepts/suggest-pathGET /v1/proposalsGET /v1/proposals/:idMutation endpoints require Authorization: Bearer <OKF_WRITE_TOKEN>:
POST /v1/proposalsPOST /v1/proposals/updatePOST /v1/proposals/:id/acceptPOST /v1/proposals/:id/rejectThe 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.
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.
Remote bundles let one project consume concepts published by another repository without cloning or vendoring them locally.
Supported source:
https://github.com/<owner>/<repo>/tree/<ref>/<path>Remote loading:
.md filesinclude and exclude filtersCLI examples:
okf --remote-bundle shared=https://github.com/example/okf-atlas/tree/main/bundles/shared --inspect
okf --project okf.project.yaml --remote-bundle vendor=https://github.com/example/vendor-okf/tree/main/bundles/catalog validate
MCP runtime loading:
Start the MCP server with --allow-remote-tool before calling load_remote_bundle.
{
"name": "load_remote_bundle",
"arguments": {
"id": "shared",
"url": "https://github.com/example/okf-atlas/tree/main/bundles/shared",
"include": ["public/**"]
}
}
Use list_remote_bundles to inspect what was loaded.
search_concepts accepts:
querybundletypestagsAnytagsAllpathPrefixfrontmatterlinkedTolinkedFromrelationTypeorphanOnlylimitoffsetlist_concepts also accepts a text query and applies it together with its
listing filters. Tags and types are matched case-insensitively. Arbitrary
frontmatter filters support exact scalar matching and array-contains
matching. relationType selects concepts with an outgoing relation of that
type.
Example:
{
"query": "catalog",
"types": ["API Route"],
"tagsAll": ["api", "orders"],
"limit": 10
}
Markdown links between OKF documents become markdown_link edges. Frontmatter relations become typed relation edges.
Links to a nested bundle directory resolve to that directory's reserved
index.md when there is no exact document target. This applies to local and
remote bundles and to candidate validation during proposal authoring.
Graph tools return compact JSON:
{
"nodes": [
{
"id": "okf://app/routes/order-status",
"bundle": "app",
"path": "routes/order-status.md",
"type": "API Route",
"title": "Order Status Route",
"tags": ["api", "orders"],
"description": "Serves order status state."
}
],
"edges": [],
"warnings": []
}
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.
Default relation types:
depends_onproducesconsumespersists_tomaterializes_toconfigured_bychecked_byowned_bysupersedesrelated_toAdd project-specific relation types with relationTypes in okf.project.yaml.
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.
Bundle include and exclude filters use simple path patterns:
services/order-status.mdarchive/* for one path segment** for any nested pathvalidate, validate_bundle, and validate_project return separate conformant and validForProject fields plus structured diagnostics. valid remains a compatibility alias for validForProject.
OKF conformance covers:
typeindex.md and log.mdUnknown 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.
Project validity additionally reports:
okf:// relation targetsThe server keeps serving valid concepts from partial bundles.
Generator plugins are configured in okf.project.yaml and run with generate.
Built-in plugins:
filesystem: creates one concept per matching source file. Defaults to Markdown files.json-spec: creates one concept per JSON file and can emit persists_to relations when a destination table is present.Generated output is regular Markdown/YAML OKF and is validated by the same indexer as hand-authored concepts.
2025-11-25 for well-formed unsupported versions.FAQs
Local-first Open Knowledge Format validator, graph index, CLI, and MCP stdio server.
We found that @mfdaves/okf-mcp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Company News
Open source maintainers are under more pressure than ever. We're raising our open source program from the Team plan to the Business plan, free.
Security News
The supply chain control that delays freshly published gems now covers lockfile generation and gem vendoring in Ruby projects.
Security News
During a UK cyber test, a Mythos 5 agent used sockpuppets, social engineering, and prompt injection to try to get a maintainer to merge malware.