okf-tools

Local semantic search over OKF knowledge bundles. No API keys, no cloud services.

Why it exists: Engineers waste hours rediscovering knowledge that already exists — scattered across wikis, Slack, git history, and colleagues' heads. OKF defines a vendor-neutral format (published by Google Cloud Platform) for persisting that knowledge as markdown; okf-tools makes it queryable and useful in practice. OKF defines the format; okf-tools provides the tooling layer.

Write markdown files with YAML frontmatter → okf-tools makes them queryable via hybrid search (BM25 keyword + vector cosine similarity).

Quick Start

# Install (requires Python 3.9+)
git clone https://github.com/hdean-ssp/okf-tools.git
cd okf-tools
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

# Create a bundle
mkdir ~/my-knowledge && cd ~/my-knowledge
git init && okf init

# Add a concept
okf commit --check-duplicates --json '{
  "title": "Retry Pattern",
  "type": "Pattern",
  "content": "Use exponential backoff with jitter for transient failures.",
  "tags": ["reliability", "networking"]
}'

# Build search index (first run downloads ~30MB embedding model)
# Note: first run takes ~30 seconds to download the model. Subsequent runs are instant.
okf reindex

# Search
okf fetch "how to handle network failures"

Related MCP server: RAG In A Box MCP Server

What Next?

After completing the Quick Start above:

• okf fetch "your question" — search your bundle with natural language

• okf list — browse all concepts

• okf show <concept-id> — view full concept content

• okf stats — check bundle health

• See Use Cases & Examples for real-world workflows

• See Getting Started for the full guide

Commands

All commands support --format json|text|brief. Output is JSON when piped (agent-friendly), text when interactive.

How It Works

• Markdown files are the source of truth — the vector index is a derived sidecar, gitignored and rebuildable

• Hybrid search — combines BM25 keyword matching with vector semantic similarity. No external services.

• Local embeddings — fastembed + BAAI/bge-small-en-v1.5 (384 dimensions), no API keys

• Incremental indexing — only re-embeds changed files (mtime comparison)

MCP Server

okf-tools includes an MCP (Model Context Protocol) server, letting any MCP-compatible client (Kiro, Claude Desktop, etc.) use your knowledge bundle directly.

Quick Start — MCP Server

# Start the server (from within your bundle directory)
okf-mcp

# Or point to a specific bundle
okf-mcp --bundle-path ~/my-knowledge

The server communicates over stdio (JSON-RPC). You don't run it manually for normal use — instead, configure your MCP client to launch it.

Client Configuration

Team/Shared Deployment (recommended — see Team Setup Guide):

Create ~/.kiro/settings/mcp.json on the server:

{
  "mcpServers": {
    "okf-tools": {
      "command": "/home/electra/trunk/m3/castle_sdx/etc/okf-tools/.venv/bin/okf-mcp",
      "args": [
        "--bundle-path",
        "/home/electra/trunk/m3/castle_sdx/etc/team-okf"
      ],
      "autoApprove": [
        "commit_concept", "delete_concept", "fetch_concepts",
        "get_stats", "init_bundle", "list_concepts",
        "reindex", "show_concept", "update_concept"
      ]
    }
  }
}

Kiro via Remote-SSH (generic setup — Kiro connects to server, MCP runs locally on server):

{
  "mcpServers": {
    "okf-tools": {
      "command": "/path/to/okf-tools/.venv/bin/okf-mcp",
      "args": ["--bundle-path", "/path/to/your/bundle"]
    }
  }
}

Local setup (Kiro and bundle on same machine):

{
  "mcpServers": {
    "okf-tools": {
      "command": "okf-mcp",
      "args": ["--bundle-path", "/path/to/your/bundle"]
    }
  }
}

See MCP Setup Guide for individual installation or Team Setup Guide for onboarding to the shared deployment.

Available Tools

Notes

• The server starts without a bundle configured — use init_bundle to create one, or pass --bundle-path

• All tools except init_bundle require a configured bundle

• Errors are returned as structured MCP tool errors (no stack traces exposed)

• All logging goes to stderr (stdout is the JSON-RPC channel)

Agent Integration

The MCP server handles agent integration directly — no hooks or CLI wrappers needed.

• agent/AGENT.md — agent usage guide (when to use, MCP tools reference, workflow pattern)

Agents access the knowledge bundle through MCP tools (fetch_concepts, commit_concept, etc.) rather than shelling out to CLI commands.

Documentation

• Team Setup Guide — onboarding for the shared deployment

• MCP Setup Guide — individual installation and troubleshooting

• Getting Started — CLI quick start

• CLI Reference

• Use Cases & Examples

• Metrics & Impact Measurement

• Validation Checklist

• Proof Point Summary

Development

git clone https://github.com/hdean-ssp/okf-tools.git
cd okf-tools
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest

Dev dependencies include pytest, hypothesis (property-based testing), and pytest-asyncio.

Branches

• main — core CLI tool. Focused on the essential loop: init → commit → fetch → reindex.

• mcp — adds the MCP server (okf-mcp) for use with Kiro, Claude Desktop, and other MCP clients.

• ssp-full — extended version with multi-bundle support, link graph traversal, compliance linting, skills system, and Kiro-specific install script.

License

Apache 2.0