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

¹ 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:

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