okf-mcp

Semantic search and CRUD tooling for OKF knowledge bundles. Runs locally, entirely offline.

OKF is a vendor-neutral format (published by Google Cloud Platform) for persisting team knowledge as markdown with YAML frontmatter. okf-mcp indexes those files and makes them searchable via hybrid BM25 + vector cosine similarity. It exposes the same functionality through both a CLI and an MCP server, so humans and AI agents can query the same bundle.

Quick Start

# requires Python 3.10+
git clone https://github.com/hdean-ssp/okf-mcp.git
cd okf-mcp
source activate.sh

# 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 (downloads ~30MB embedding model on first run)
okf reindex

# search
okf fetch "how to handle network failures"

After that:

• okf fetch "your question" searches with natural language

• okf list browses all concepts

• okf show <concept-id> prints full content

• okf stats reports bundle health

• Use Cases & Examples has real-world workflows

• Getting Started is the full walkthrough

Related MCP server: RAG In A Box MCP Server

Commands

All commands accept --format json|text|brief. Piped output defaults to JSON; interactive defaults to text.

How It Works

The markdown files in your bundle are the source of truth. The vector index is a derived sidecar (gitignored, rebuildable from scratch with okf reindex --full).

Search combines BM25 keyword matching and vector cosine similarity at a 60/40 weighting. Embeddings come from fastembed using BAAI/bge-small-en-v1.5 (384 dimensions), stored in SQLite via sqlite-vec. Everything runs locally.

Reindexing is incremental by default (mtime-based change detection). Embedding is chunked in small batches to keep memory usage under 500MB even on a 2GB VPS.

MCP Server

The MCP server lets any MCP-compatible client (Kiro, Claude Desktop, etc.) interact with your bundle over stdio JSON-RPC.

# from within your bundle directory
okf-mcp

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

You typically don't run it by hand. 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-mcp": {
      "command": "/path/to/okf-mcp/.venv/bin/okf-mcp",
      "args": [
        "--bundle-path",
        "/path/to/your/team-bundle"
      ],
      "autoApprove": [
        "commit_concept", "delete_concept", "fetch_concepts",
        "get_stats", "init_bundle", "list_concepts",
        "move_concept", "reindex", "show_concept", "update_concept"
      ]
    }
  }
}

Kiro via Remote-SSH (Kiro connects to server, MCP runs on server):

{
  "mcpServers": {
    "okf-mcp": {
      "command": "/path/to/okf-mcp/.venv/bin/okf-mcp",
      "args": ["--bundle-path", "/path/to/your/bundle"],
      "autoApprove": [
        "fetch_concepts", "list_concepts", "show_concept",
        "get_stats", "reindex"
      ]
    }
  }
}

Local setup (Kiro and bundle on the same machine):

{
  "mcpServers": {
    "okf-mcp": {
      "command": "okf-mcp",
      "args": ["--bundle-path", "/path/to/your/bundle"],
      "autoApprove": [
        "fetch_concepts", "list_concepts", "show_concept",
        "get_stats", "reindex"
      ]
    }
  }
}

See MCP Setup Guide for individual installation or Team Setup Guide for shared deployments.

Available Tools

The server can start without a bundle configured. Pass --bundle-path or call init_bundle from the client. All tools except init_bundle require a configured bundle. Errors come back as structured MCP tool errors. Logging goes to stderr (stdout is the JSON-RPC channel).

Agent Integration

Agents interact through the MCP tools directly (fetch_concepts, commit_concept, etc.). See agent/AGENT.md for the usage guide: when to query, when to commit, workflow patterns.

Documentation

• Team Setup Guide - shared deployment onboarding

• MCP Setup Guide - individual installation and troubleshooting

• Getting Started - CLI walkthrough

• CLI Reference

• Use Cases & Examples

• Metrics & Impact Measurement

• Validation Checklist

Development

git clone https://github.com/hdean-ssp/okf-mcp.git
cd okf-mcp
source activate.sh
pip install -e ".[dev]"
pytest

190 tests across CLI, MCP server, bundle operations, search, sync, and move/rename. Dev dependencies: pytest, hypothesis, pytest-asyncio.

Roadmap

See ROADMAP.md for the production readiness plan — input hardening, data integrity, deployment tooling, and the path to a stable 1.0 release.

License

Apache 2.0