okf-knowledge-mcp

# okf-knowledge-mcp [](https://www.npmjs.com/package/okf-knowledge-mcp) [](https://opensource.org/licenses/MIT) 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`: ```bash npx -y okf-knowledge-mcp ``` ### 1. Claude Desktop Configuration Add the following to your `claude_desktop_config.json`: ```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: ```bash 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