okf-mcp

okf-mcp is a local-first consumer, validator, graph index, CLI, and MCP server for Open Knowledge Format v0.2.

It consumes an OKF bundle directory of Markdown files with YAML frontmatter. An optional workspace mode can federate several bundles. Concepts are exposed through CLI commands and MCP resources and tools for validation, structured search, graph navigation, provenance inspection, and proposal-based authoring.

The core intentionally has no database, embeddings, build step, or hosted-service dependency. It uses js-yaml for safe YAML, CommonMark for Markdown structure, MiniSearch for in-memory BM25+ text retrieval, and the official Model Context Protocol TypeScript SDK v2 for stdio MCP. Local root mode makes no network calls. Optional remote loading fetches public Markdown concepts and only their explicitly referenced inert assets from GitHub. Nothing in the v0.2 computation support executes code or attests a receipt.

OKF v0.2 Support And Extensions

OKF v0.2 intentionally specifies a portable file format, not a serving or query runtime. okf-mcp keeps that boundary explicit:

The following are okf-mcp extensions rather than requirements of the format:

• CLI, MCP, and HTTP interfaces; in-memory search and graph views
• optional multi-bundle okf.project.yaml workspaces and typed relations
• compatibility id, aliases, and okf:// locators
• proposal-backed authoring with explicit acceptance
• bounded GitHub remote loading and explicitly mapped pinned Git sources
• generator plugins and stricter opt-in project policies such as strictLinks

Install And Run

Node 22 or newer is required.

Install from the GitHub release:

git clone --branch v0.8.0 https://github.com/mfdaves/okf-mcp.git
cd okf-mcp
npm ci
node bin/okf-mcp.js --root ./path/to/okf validate

Pin the published version for reproducible use:

npx -y @mfdaves/okf-mcp@0.8.0 --version
npx -y @mfdaves/okf-mcp@0.8.0 --root ./path/to/okf validate

For a persistent installation:

npm install --global @mfdaves/okf-mcp@0.8.0

okf --version
okf --root ./path/to/okf validate
okf-mcp --root ./path/to/okf mcp

To work from the current source branch:

git clone https://github.com/mfdaves/okf-mcp.git
cd okf-mcp
npm ci
npm test
node bin/okf-mcp.js --version

--root accepts one local OKF bundle directory and is the recommended okf-mcp interface for a single bundle. The portable identity of each concept is its extensionless path inside that root.

--bundle accepts either a path or id=path. Multiple flags remain supported for compatibility. --project and its bundles: list are an optional okf-mcp federation/authoring extension, not part of OKF v0.2.

--remote-bundle accepts id=https://github.com/<owner>/<repo>/tree/<ref>/<path>. It fetches public Markdown first, then only bundle-local files explicitly named by standard v0.2 resource fields. Remote content remains read-only and inert.

--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. Without an explicit source, the CLI first discovers the nearest root index.md declaring okf_version; nearest-project discovery remains a compatibility fallback.

CLI exit statuses are 0 for success, 1 for validation or operational failure, and 2 for invalid usage. Unknown options are rejected.

Included OKF Reference

This repository publishes a self-describing OKF bundle for the product, its runtime boundaries, interfaces, authoring workflows, and safety policy. Its portable entry Concept ID is overview/okf-mcp; okf://okf-mcp/overview/okf-mcp remains the workspace/MCP resource locator.

Validate and query the bundled reference from a checkout or installed package:

okf --root okf/bundles/okf-mcp validate
okf --root okf/bundles/okf-mcp search "proposal"
okf --root okf/bundles/okf-mcp concept overview/okf-mcp

Load the reference bundle directly from this release:

okf --remote-bundle okf-mcp=https://github.com/mfdaves/okf-mcp/tree/v0.8.0/okf/bundles/okf-mcp --inspect

The @mfdaves/okf-mcp npm package includes both okf.project.yaml and the complete reference bundle.

Optional Multi-Bundle Project Config

Use okf.project.yaml only when one process must federate multiple roots, configure generators, or enforce a project-wide relation vocabulary:

project: Example
strictLinks: false
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:

• mcp
• validate
• graph [json|dot|mermaid]
• search <query>
• concept <concept-id-or-locator>
• neighbors <concept-id-or-locator>
• paths <from> <to>
• provenance <uri>
• edge-kinds
• computation inspect|prepare|check-receipt
• asset <okf-asset-uri>
• source <concept-id-or-locator> <source-id>
• migrate check|preview
• generate
• serve

serve 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 selected local root or project

MCP Client Config

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.

Example client configuration:

{
  "mcpServers": {
    "okf": {
      "command": "npx",
      "args": [
        "-y",
        "@mfdaves/okf-mcp@0.8.0",
        "--root",
        "/absolute/path/to/okf",
        "mcp"
      ]
    }
  }
}

Project config mode, with read-only project helpers but without proposal mutations:

{
  "mcpServers": {
    "okf": {
      "command": "npx",
      "args": [
        "-y",
        "@mfdaves/okf-mcp@0.8.0",
        "--project",
        "/absolute/path/to/repo/okf.project.yaml",
        "mcp"
      ]
    }
  }
}

Add --authoring to enable proposal creation, acceptance, and rejection. For a smaller direct-write surface, add --write --actor <actor> to expose read-only okf_validate_changes and validated-batch okf_apply_changes; add --git-commit to commit each successful batch when the catalog is in a clean Git worktree. Add --allow-remote-tool to let MCP clients load arbitrary supported public remote bundles at runtime. Configured remote bundles remain readable without that runtime-loading flag.

The stdio server uses @modelcontextprotocol/server v2. It serves the modern 2026-07-28 MCP revision and the SDK's compatibility path for 2025-era clients, including 2025-11-25. The SDK owns protocol negotiation, framing, resource dispatch, tool dispatch, and advertised-schema validation.

Expected failures from a known tool, such as a missing concept, a read-only bundle, a failed remote fetch, invalid arguments, or a proposal conflict, are returned as MCP tool results with isError: true. Calls to tools that are not enabled are rejected by SDK dispatch. Unexpected implementation errors are masked instead of exposing internal details.

MCP Registry Metadata

server.json describes the npm package as the stdio server io.github.mfdaves/okf-mcp. Registry-aware clients should prompt for an absolute OKF root path, pass it through --root, and append the fixed mcp command.