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

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).