okf-retrieve 0.1.0

MCP-first agent retrieval over Open Knowledge Format (OKF) bundles.

okf

Mount any Open Knowledge Format bundle as a retrievable knowledge source for LLM agents — over MCP.

OKF (announced by Google Cloud, June 2026) represents organizational knowledge as a directory of markdown files with YAML frontmatter. The format was designed for agent progressive disclosure: index.md listings, structured type/tags frontmatter, and a resolvable cross-document link graph.

okf turns a bundle into agent-ready retrieval. Point an MCP-capable agent (Claude Code, Claude Desktop, or the Messages API) at a bundle and it searches for stubs, fetches bodies, and walks the link graph on demand — instead of you flattening every doc into the context window.

pip install "okf-retrieve[mcp]"
okf serve-mcp ./sales          # serve the bundle to any agent over MCP (stdio)

Why MCP-first

The OKF link graph and frontmatter are exactly what an agent needs to navigate knowledge rather than be handed a wall of text. okf exposes that as four tools:

Tool	Returns
search(query, type?, tags?, limit?)	ranked document stubs (path, type, title, description) — not full bodies
get(path)	one document's full content
neighbors(path, hops?)	documents linked from/to a document (graph expansion)
list_types() / list_by_type(type)	structured browse

search deliberately returns stubs so the agent decides what to read — the progressive-disclosure pattern OKF was built for.

Use it from Claude Code / Desktop

Add to your MCP config (claude_desktop_config.json or .mcp.json):

{
  "mcpServers": {
    "okf-sales": {
      "command": "okf",
      "args": ["serve-mcp", "/abs/path/to/sales"]
    }
  }
}

Use it from the Messages API

Run okf serve-mcp ./sales --transport streamable-http, then reference it with mcp_servers + mcp_toolset (beta mcp-client-2025-11-20) on client.beta.messages.create(...).

Library

The same retrieval is available directly in Python:

from okf import Bundle, StructuredRetriever, GraphExpandedRetriever, pack

bundle = Bundle.load("./sales")

doc = bundle["tables/orders.md"]
doc.type                       # "BigQuery Table"
doc.links                      # resolved internal links -> [Doc(customers), ...]
bundle.neighbors(doc, hops=2)  # graph expansion

# Keyword (BM25) retrieval with frontmatter filtering — no embeddings needed
hits = StructuredRetriever(bundle).search("weekly active users", type="Metric")

# Graph-expanded retrieval: surface structurally-related docs the query missed
graph = GraphExpandedRetriever(StructuredRetriever(bundle), bundle, hops=1)
hits = graph.search("weekly active users")

# Token-budgeted, citable context block, ready to drop into a prompt
ctx = pack(hits, max_tokens=4000)
ctx.text          # assembled markdown
ctx.citations     # ["metrics/weekly_active_users.md", ...]

Semantic (vector) retrieval

from okf import Bundle, SemanticRetriever
from okf.retrieve import VoyageEmbedder      # or SentenceTransformerEmbedder

bundle = Bundle.load("./sales")
retriever = SemanticRetriever(bundle, VoyageEmbedder())  # set VOYAGE_API_KEY
hits = retriever.search("which table has revenue per order")

Anthropic's Claude API has no embeddings endpoint, so the embedder is pluggable. The [semantic] extra ships Voyage AI (Anthropic's recommended embedding partner) and sentence-transformers (offline, no API key). Any object with embed_documents / embed_query works. Wrap a SemanticRetriever in GraphExpandedRetriever for vector + graph retrieval.

CLI

okf validate ./sales                 # lint against the OKF spec (exit 1 on errors)
okf search ./sales "orders"          # keyword (BM25) search
okf search ./sales "orders" --graph  # + graph expansion
okf search ./sales "orders" --semantic  # vector search (OKF_EMBEDDER=voyage|local)
okf graph ./sales --json             # emit the resolved link graph
okf serve-mcp ./sales                # serve the bundle as an MCP tool server

Install

pip install okf-retrieve              # core: model + graph + BM25 retrieval + CLI (PyYAML only)
pip install "okf-retrieve[mcp]"       # + MCP server
pip install "okf-retrieve[semantic]"  # + vector retrieval (numpy, Voyage, sentence-transformers)

Requires Python 3.10+. The distribution is okf-retrieve; you still import okf.

Status

0.1.0, early alpha. Implemented: bundle model + link graph, validation, BM25 / semantic / graph-expanded retrieval, context packing, the MCP server, and the CLI. Roadmap: a reference Claude agent, pluggable vector stores, and bundle generators.

Related projects

The OKF tooling space is young. okf-toolkit covers init/validate/search as a CLI; py-okf generates bundles from Python code; hermes-okf is an agent-memory layer. okf focuses specifically on the agent-native retrieval surface (MCP).

License

MIT