Awesome-OKF

What is OKF

Open Knowledge Format (OKF) is an open specification by Google Cloud — define knowledge as a directory of Markdown files with YAML frontmatter and a small set of conventions. No runtime, no SDK.

What's Different Here

Awesome OKF keeps the entire OKF ecosystem in one validated YAML catalog, then turns it into a browsable list, a searchable CLI, and an MCP meta-server that AI agents can query directly:

                      catalog.yaml
                           │
          ┌────────────────┼────────────────┐
          ▼                ▼                 ▼
      README.md         CLI tools        MCP server
   (human-browsable)  (searchable)   (agent-searchable)

Edit one record. Regenerate the docs. Re-query from anywhere.

🌐 OKF Anything

Anything readable → OKF. Every format above — and any you invent — collapses into one intermediate shape, then bundles into OKF:

        ┌────────── EXTRACT ──────────┐   ┌── NORMALIZE ──┐   ┌──── BUNDLE ────┐
        │  Markdown · Typora · PDF    │   │  title         │   │  # title       │
        │  Obsidian · Notion · Feishu │ → │  url           │ → │  description   │
        │  GitHub · JSON · YAML       │   │  description   │   │  resource      │
        │  CSV · key-value · OCR      │   │  body / tags   │   │  myokf-ready   │
        └─────────────────────────────┘   └────────────────┘   └────────────────┘

1. Extract — pull readable text out of any source. Platform exports and local engines (pymupdf, PaddleOCR) do the lifting; nothing runs through our model.
2. Normalize — every format reduces to title / url / description (+ optional body, tags).
3. Bundle — render the intermediate shape into a myokf-validatable OKF directory.

--format anything is the programmatic form: feed it arbitrary text and it walks the parser chain (list → JSON → key-value → URLs → line-per-row) until one sticks:

python scripts/convert-to-okf.py whatever.txt --format anything -o kb/

The MCP tool convert_to_okf speaks the same idea — an agent hands it arbitrary text, it hands back OKF.

See It in Action

User (or Agent):
  "Find an OKF plugin for Obsidian vault conversion."

Agent calls:
  search_catalog({
    "query": "Obsidian",
    "kind": "plugin",
    "limit": 3
  })

Awesome-OKF responds:
  ┌──────────────────────────────────────────────────────────────┐
  │ obsidian-to-okf                                plugin        │
  │ Convert Obsidian vaults to OKF — wikilinks become OKF links. │
  │ Platform: python  ·  Tags: obsidian, wikilink, markdown      │
  └──────────────────────────────────────────────────────────────┘

The catalog speaks OKF.

Quick Start

Connect to Your Agent

Add Awesome OKF to any MCP client so your agent can discover OKF resources:

pipx install awesome-okf

{
  "mcpServers": {
    "awesome-okf": {
      "command": "awesome-okf-server"
    }
  }
}

CLI

awesome-okf stats
awesome-okf list --kind plugin
awesome-okf search obsidian
awesome-okf readme

🛠️ Our Tools

convert-to-okf 🔄

Zero-dependency CLI that converts content from your favorite platforms into OKF knowledge bundles:

# Every platform, one command
python scripts/convert-to-okf.py README.md -o kb/ -t concept
python scripts/convert-to-okf.py https://github.com/GoogleCloudPlatform/knowledge-catalog --format github -o kb/
python scripts/convert-to-okf.py my-vault/ --format obsidian -o kb/
python scripts/convert-to-okf.py notion-export/ --format notion -o kb/
python scripts/convert-to-okf.py feishu-doc.md --format feishu -o kb/

# Structured data
python scripts/convert-to-okf.py data.yaml --format yaml -o kb/   # needs: pip install pyyaml
python scripts/convert-to-okf.py table.csv --format csv -o kb/
python scripts/convert-to-okf.py notes.properties --format kv -o kb/

# Text-layer PDFs
pip install pymupdf
python scripts/convert-to-okf.py paper.pdf --format pdf -o kb/

# Scans / image-only PDFs → OKF: OCR first (your local engine, never our model), then convert
python scripts/convert-to-okf.py scan.png --format image    # prints the OCR recipe
pip install paddleocr paddlepaddle
paddleocr ppocr -i scans/ --type ocr --lang en -o ocr-text/
python scripts/convert-to-okf.py ocr-text/ --format notion -o kb/

# Output: kb/ with Markdown files, each with YAML frontmatter
# Ready for: myokf validate kb/

awesome-okf CLI 🎛️

The data-driven catalog CLI (same architecture as Awesome-MCP):

🔥 Popular Repositories

Catalog

29 curated entries · 4 tools · 7 plugins · 7 skills · 5 proposals · 6 docs Deliberately curated — not an exhaustive index.

🛠️ Tools & CLI

Cli

• myokf-cli cli — Unified CLI for OKF — pull from GitHub, validate, and package to single-file web. — cli, python, validation, packaging

Conversion

• binder cli — Go CLI that converts an existing plain-markdown corpus into a conformant OKF v0.2 bundle, resolving the corpus link web (markdown links and wikilinks) into OKF relationships — with validate, a stdio MCP server, and an agent plugin. — conversion, go, markdown, wikilink
• convert-to-okf cli — CLI tool to convert Markdown awesome-xx lists, JSON arrays, and URL lists into OKF knowledge bundles — zero dependencies, standard library only. — conversion, cli, markdown, json

Quality

• OKF Validator (myokf) cli — Built-in OKF schema validator — checks YAML frontmatter, link integrity, and spec compliance. — validation, quality, schema

SDK

• OKF Python SDK ✅ python — Official Python SDK for reading, validating, and writing OKF bundles — referenced by Google as the reference implementation. — sdk, python, official

🔌 Producer Plugins

Cli

• myokf-cli (plugin entry) python — Unified CLI entry point wrapping all seven producer plugins. — cli, aggregator, zero-dependency

Code

• github-to-okf python —