okf-mcp

okf-mcp

MCP server for Open Knowledge Format bundles — expose okf-ingest's deterministic consume verbs as tools any MCP client (Claude Code, Cursor, custom agents) can call.

Existing OKF MCP servers hand agents the markdown files. This one hands them the queryable catalog and concept graph: index-first context assembly, impact/backlink analysis, SQL over frontmatter, drift diffs, and health checks — all deterministic okf-ingest code, no model calls in the server.

Tools

Tool	What the agent gets
okf_list_bundles	which bundles this server exposes
okf_search	concepts whose title/body match a term
okf_get_concept	one concept's frontmatter + full body
okf_context	the flagship — index.md + a concept's most relevant neighborhood as one curated markdown blob, ranked by exact Personalized PageRank over the author's link graph (pass rank='bfs' for plain depth) — or pass query (a free-text question) instead of start for lexical-seeded multi-PPR retrieval
okf_related	the k concepts most relevant to a topic — exact PPR, no embeddings
okf_impact	inbound / outbound / transitive links — "what breaks if X changes"
okf_sql	read-only SELECT over the DuckDB catalog (okf_concept, okf_link, okf_validation)
okf_diff	what changed on disk since the server loaded the bundle — an agent's memory-refresh between looks
okf_refresh	re-ingest a directory bundle after okf_diff shows changes
okf_doctor	health score + per-rule findings before trusting a bundle
okf_computations	OKF v0.2 SPEC 10 — the bundle's Attested Computations: the sanctioned way to compute each value, its runtime, its typed parameters, the executor, the receipt fields a run must return, and the attester that checks it. Call before computing a number the bundle already defines
okf_trust	OKF v0.2 SPEC 5 — trust tier (unverified / machine-confirmed / human-reviewed), lifecycle status, and stale_after per concept: how much weight to give a concept, and what has gone stale

Install & run

Built on the official MCP Python SDK v2 (MCP spec 2026-07-28); v2 servers still answer the legacy initialize handshake, so pre-2026 clients keep working. For environments pinned to SDK v1, install okf-mcp==0.3.1.

pip install okf-mcp        # depends on okf-ingest >= 0.9.0 and mcp >= 2

# one or more bundles: directories and/or okf-ingest .duckdb catalogs,
# optionally named (first one is the default target)
okf-mcp ~/my-bundle
okf-mcp wiki=~/wiki notes=~/vault snapshot=./kb.duckdb

Register with Claude Code:

claude mcp add okf -- okf-mcp ~/my-bundle

Or in any MCP client config:

{ "mcpServers": { "okf": { "command": "okf-mcp", "args": ["wiki=/path/to/bundle"] } } }

Design notes

• Read-only. Directory bundles are ingested into disposable in-memory DuckDB catalogs at startup; .duckdb sources open read-only; okf_sql accepts SELECT/WITH only. The server never writes to your bundle.
• Deterministic. Every tool is plain okf-ingest code — same input, same answer; the only nondeterminism an agent sees is its own.
• Concepts resolve by name. okf_get_concept / okf_context / okf_impact accept a path or a wikilink-style name — id, alias, title, or filename stem, compared on alphanumerics ('agent memory architecture' finds ops/agent_memory_architecture.md). Ambiguous names return the candidate list instead of guessing.
• [[wikilinks]] work. Vault-style bundles (Obsidian/Logseq/Foam) resolve by id / alias / title / stem, same as okf-ingest 0.6.0+.

Apache-2.0. Sibling project: okf-ingest (the R + Python ingestion tool this wraps).