okf-knowledge-mcp

Model Context Protocol (MCP) server for querying, reading, writing, and automatically syncing an OKF (Open Knowledge Format) markdown knowledge base.

It acts as a secure, fast, and automated "shared brain" bridge for AI agents (like Claude Code, Cursor, and Cline) working in public or private repositories, letting them query or document architectural decisions and rules on the fly.

Features

• TF-IDF Keyword Search: Highly relevance-ranked deterministic search over titles, descriptions, and file bodies, utilizing synonym expansion and kebab/underscore token parsing.
• Auto-Discovery of Knowledge Root: Walks up ancestor directories to find a knowledge/ directory, falls back to a home directory config ~/.okf-knowledge-mcp.json or custom environment variable.
• Write and Sync: Create or edit concept files with strict OKF v0.2 frontmatter compliance (type, title, description, tags, etc.).
• Automatic Git Sync (Git-Ops): If your knowledge base is in a Git repo, writing or deleting concepts will automatically execute git add, git commit, and git push to keep your remote repository in sync.
• Path Sanitization: Secure boundaries prevent directory traversal attacks.

Installation

You can run it directly via npx:

npx -y okf-knowledge-mcp

1. Claude Desktop Configuration

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "okf-knowledge": {
      "command": "npx",
      "args": ["-y", "okf-knowledge-mcp"],
      "env": {
        "KNOWLEDGE_ROOT": "C:/g/knowledge"
      }
    }
  }
}

2. Claude Code or OpenCode Configuration

Register it directly:

claude mcp add okf-knowledge npx -y okf-knowledge-mcp --env KNOWLEDGE_ROOT="C:/g/knowledge"

Tools Exposed

search_knowledge

Search the knowledge base using keyword TF-IDF relevance scoring.

• query (string, required): Search terms
• limit (number, optional): Max results (default 5)
• minScore (number, optional): Min score threshold (default 0.15)

read_concept

Read a specific OKF concept file's parsed YAML frontmatter and body.

• relativePath (string, required): Relative path under the knowledge root (e.g. rules/agent/afk-vs-hitl-tasks.md)

write_concept

Create or update a concept file with compliant frontmatter and body.

• relativePath (string, required): Relative path under the knowledge root
• type (enum, required): decision | rule | runbook | service | glossary | index
• title (string, required): Document title
• description (string, required): One-line summary
• tags (string[], required): Category tags
• body (string, required): Markdown body text
• confidence (enum, optional): high | medium | low
• durability (enum, optional): durable | volatile
• status (enum, optional): active | deprecated | superseded | draft
• customFrontmatter (object, optional): Additional key/value frontmatter fields

delete_concept

Delete a concept file and run a Git sync.

• relativePath (string, required): Relative path under the knowledge root

list_concepts

List all concepts in the knowledge base, optionally filtered by type or tag.

• type (string, optional)
• tag (string, optional)

Configuration Options

The server looks for paths in the following priority order:

1. KNOWLEDGE_ROOT environment variable.
2. An automatically discovered knowledge/ directory in CWD or any of its parents.
3. The home folder config file: ~/.okf-knowledge-mcp.json.

If the Git auto-sync is not desired, set OKF_GIT_AUTO_SYNC=false in the environment.

License

MIT