okft

Lint and serve Open Knowledge Format (OKF) bundles.

OKF is Google's open spec for representing organizational knowledge as a directory of markdown files with YAML frontmatter — a knowledge graph that both humans and AI agents can read natively. okft covers the two sides of keeping a bundle healthy and useful:

• okft lint — validate a bundle against the OKF v0.1 spec, plus hygiene checks (broken links, orphaned concepts, malformed timestamps). Wire it into CI so your knowledge bundle can't rot silently.
• okft serve — expose a bundle to any MCP-capable AI agent (Claude, Gemini CLI, Cursor, …) as a set of navigation tools: overview, read, search, list. Deterministic graph traversal, no embeddings, no database.

Install

pip install okft          # lint only
pip install 'okft[serve]' # lint + MCP server

Lint

okft lint path/to/bundle

analytics/tables/orders.md:1 error E003 frontmatter must include a non-empty `type` field
analytics/metrics/churn.md:24 warning W001 link target does not resolve in bundle: /analytics/tables/order
engineering/runbook.md:1 warning W004 concept is never linked from any other document

12 concepts checked: 1 error(s), 2 warning(s)

Exit code is 1 on errors (or on warnings with --strict), so it drops straight into CI. --format json emits machine-readable findings.

Rules

Code	Severity	Check
E001	error	concept file has no YAML frontmatter block
E002	error	frontmatter is not parseable YAML
E003	error	missing or empty type field
E004	error	reserved file (index.md / log.md) has frontmatter
W001	warning	link target does not resolve inside the bundle¹
W002	warning	timestamp is not ISO 8601
W003	warning	tags is not a list of strings
W004	warning	orphan concept — nothing links to it (--no-orphans to skip)
W005	warning	bundle root has no index.md
W006	warning	log.md headings are not ISO 8601 dates
W007	warning	concept has no title

¹ The spec requires consumers to tolerate broken links, so they are warnings, never conformance errors.

Both standard markdown links (/analytics/tables/customers.md, relative paths) and [[wiki-style]] links are resolved.

Serve to an AI agent

okft serve path/to/bundle

Runs an MCP server (stdio) with four tools:

Tool	Purpose
okf_overview	root index + every concept grouped by type
okf_read	one concept: frontmatter, body, outbound & inbound links
okf_search	ranked full-text search with snippets
okf_list	filter concepts by type and/or tag

Register it with Claude Code:

claude mcp add acme-brain -- okft serve /path/to/bundle

or in any MCP client config:

{
  "mcpServers": {
    "acme-brain": { "command": "okft", "args": ["serve", "/path/to/bundle"] }
  }
}

Try it

A small example bundle ships in examples/acme_brain:

okft lint examples/acme_brain
okft serve examples/acme_brain

CI example (GitHub Actions)

- uses: actions/setup-python@v5
  with: { python-version: "3.12" }
- run: pip install okft
- run: okft lint knowledge/ --strict

Status

Tracks OKF v0.1. The spec is young and so is this tool — issues and PRs welcome, especially reports of real-world bundles that lint incorrectly.

License

Apache-2.0