Atlas / MCP servers / xrieros / okf-cli

okf-cliSAFE

Name: okf-cli
Author: xrieros

mcp/xrieros/okf-cli

MCP server by xrieros · ai agents · bm25 · claude code · Audited 2026-10-13

CLI + MCP server for Open Knowledge Format (OKF) v0.2 catalogues: hybrid BM25/semantic search, link-safe rename, validation. Python stdlib only.

Verdict

SAFE

Grade

Trust score

89 /100

Exposed tools

21 14r · 7w · 0d

Transport

—

License

Apache-2.0

Stars

Overview

From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.

Search, navigate, validate and refactor a catalogue of [Open Knowledge Format (OKF) v0.2](https://github.com/GoogleCloudPlatform/open-knowledge-format/blob/main/SPEC.md) bundles — markdown files with YAML frontmatter, built for humans and AI agents.

Agent-ready. read returns one section, or a page together with the pages it links to, in one call; one command registers an MCP server and an agent skill with Claude Code, Codex, opencode, omp, Kimi Code, OpenClaw and Hermes; prime onboards a fresh agent session in one call.
Predictable. Every command answers --json with one envelope, and every failure has an exit code that names its class.
Hybrid search. Local SQLite FTS5/BM25 plus optional semantic arm (Voyage embeddings), narrowed by one --where filter language.
Safe refactoring. rename and archive move a concept and rewrite every inbound and outbound link. Every mutating command previews a unified diff before --apply writes it.
Trust and freshness. OKF v0.2 provenance (generated, sources, verified, stale_after) is checked by check, recorded by verify and queried by --where.
Catalogue-aware. Works across many bundles at once, not only one.

Keywords: Open Knowledge Format, OKF v0.2, knowledge base CLI, markdown frontmatter, MCP server, Claude Code, agent memory, Obsidian, BM25, link checker, wikilinks.

Install

okf is a single-file script with inline dependencies (PEP 723): Python 3.11 or newer, ruamel.yaml and argcomplete. `uv` reads that header and installs the packages on first use, so install uv first. Run it from a clone, or install it as a tool. Both end in the same step, okf install: it wires okf into your coding agents and shells, and previews before it writes anything.

# From a clone: runs in place, `git pull` updates it
git c

Read from source at commit 8efaf9619671OBSERVED · 2026-10-13

Connect

Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control. Replace the environment placeholders with a token scoped to the least it needs.

claude-code

claude mcp add okf-cli --env VOYAGE_API_KEY=${VOYAGE_API_KEY} -- uvx okf-cli

claude-desktop

{
  "mcpServers": {
    "okf-cli": {
      "command": "uvx",
      "args": [
        "okf-cli"
      ],
      "env": {
        "VOYAGE_API_KEY": "${VOYAGE_API_KEY}"
      }
    }
  }
}

Exposed tools (21)

14 read · 7 write · 0 destructive.

Tool	Risk	Description
`okf_build_index`	read	(Re)build the FTS5 lexical index at <root>/.fts/fts.sqlite. Local
`okf_build_semantic_index`	read	Fill <root>/.tagvec/tag_vectors.sqlite
`okf_check`	read	§9 conformance scan (config-aware TYPES). Returns {findings}: a list of
`okf_ctx_list`	read	Curated ctx bundles (_ctx/<slug>.md): slug, description, entry counts.
`okf_ctx_show`	write	One ctx bundle in reading order: entries with live title, type,
`okf_find`	read	Ranked search across a catalogue/repo root, narrowed by a `where`
`okf_index`	read	Catalogue/bundle TOC. Without `bundle`, defaults to one entry per
`okf_info`	read	The catalogue
`okf_list`	write	The complete, unranked set of concepts a `where` expression selects;
`okf_prime`	read	One-shot onboarding for a fresh session: what the store is, how to
`okf_read`	read	Print one concept page (bundle/concept-id). At most one of `section`,
`okf_refs`	read	Inbound and outbound markdown references of a file (reference-integrity step a).
`okf_reindex`	read	Regenerate marker-bounded index listings for a bundle/subdir.
`okf_rename`	write	Move a concept and keep every reference intact: rewrites inbound links
`okf_sync_export`	write	Print one canonical block
`okf_sync_insert`	write	Materialise a canonical block inside a consumer concept, so the
`okf_sync_status`	write	Drift report for every materialised canon block: returns
`okf_sync_update`	write	Re-materialise every outdated consumer block from its canon owner.
`okf_tags`	read	List all tags with usage counts (query omitted), or fuzzy-search a
`okf_toc`	read	Section headings of a concept.
`okf_wikilinks`	read	Obsidian wikilinks ([[...]]) in a catalogue, with the resolution status

Trust audit

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

Layer	What it checks	Result
L0	Provenance & inventory	PASS
L1	Static analysis of the code	PASS
L2	Instruction surface (what it tells the agent)	PASS
L3	Class-specific surface	PASS
L4	Behavioural (sandbox)	SKIPPED

What the source does

Filesystem: declared (5 observation(s))
Network: declared (5 observation(s))
Shell: none-observed
Dependencies: pinned
Secrets in source: none-found

Findings (10)

LOWInventory / provenance · inv.hidden_file · CWE-1104

.beans.yml

.beans.yml

Why it matters. hidden member outside the usual dotfiles

Fix. review its purpose

LOWInventory / provenance · inv.hidden_file · CWE-1104

tests/golden/catalogue/.okf.toml

.okf.toml

Why it matters. hidden member outside the usual dotfiles

Fix. review its purpose