# okft

**Lint and serve [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) (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

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

## Lint

```sh
okft lint path/to/bundle
```

```text
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

```sh
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:

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

or in any MCP client config:

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

## Try it

A small example bundle ships in [`examples/acme_brain`](examples/acme_brain):

```sh
okft lint examples/acme_brain
okft serve examples/acme_brain
```

## CI example (GitHub Actions)

```yaml
- 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