KnowledgeBaseMCP

Keep an Open Knowledge Format knowledgebase in order: checked, maintained and imported, by agents and people alike. It cares how a concept is written, never what it says.

Get started View on GitHub

Local files only. No network. Never writes to git. One Python file, run with uv. These pages were written with Claude Opus 5.5 and are under human review.

Quickstart#

One file. uv fetches its dependencies on the first run.

wget https://raw.githubusercontent.com/dfoulks1/KnowledgeBaseMCP/main/KnowledgeBaseMCP.py
uv run KnowledgeBaseMCP.py help

No uv yet? curl -LsSf https://astral.sh/uv/install.sh | sh

Then add it to your MCP client's servers file (.mcp.json for Claude Code; other clients):

{
  "mcpServers": {
    "knowledgebase": {
      "command": "uv",
      "args": ["run", "/path/to/KnowledgeBaseMCP.py"],
      "env": { "KB_ROOT": "/path/to/kb", "KB_USER": "your-id" }
    }
  }
}

Or work from the terminal, no AI needed:

# start a bundle
uv run KnowledgeBaseMCP.py init bundle=eng apply=true

# write a concept
uv run KnowledgeBaseMCP.py create eng/runbooks/deploy \
    type=Playbook description="How we deploy."

# find it: the map, then the best matches
uv run KnowledgeBaseMCP.py dirs format=text
uv run KnowledgeBaseMCP.py search deploy format=text

# what's wrong, each with a fix; then the mechanical repairs
uv run KnowledgeBaseMCP.py lint format=text
uv run KnowledgeBaseMCP.py fix apply=true

# any tool: what it does, its arguments
uv run KnowledgeBaseMCP.py help move

What a knowledgebase looks like#

A knowledgebase is a folder of bundles. A bundle is a folder of concepts, one Markdown file each. Two small bundles:

kb/
  index.md                 lists the bundles
  eng/                     a bundle: its index.md declares okf_version "0.2"
    index.md
    log.md                 what changed, newest first
    db.md
    runbooks/ship.md
    refs/pg.md
  mkt/
    index.md
    log.md
    launch.md

Each concept is frontmatter (what kind of thing it is, where its facts came from, who checked it) over an ordinary Markdown body. Here is eng/db.md:

---
type: Reference
title: Database
description: The PostgreSQL cluster behind every service.
sources:
  - id: pg
    resource: refs/pg.md
verified: { by: human:dfoulks, at: 2026-10-27T14:00:00Z }
---

We run PostgreSQL 16.4.[^pg] Deploys follow [the ship runbook](/runbooks/ship.md).

[^pg]: PostgreSQL release notes

Concepts point at each other in two ways: a Markdown link in the body, and a citation in sources, which records where a fact came from. web format=mermaid draws both for the whole knowledgebase:

graph LR
  subgraph eng
    db["db.md"]
    ship["runbooks/ship.md"]
    pg["refs/pg.md"]
  end
  subgraph mkt
    launch["launch.md"]
  end
  db -.->|cites| pg
  db -->|links| ship
  ship -->|links| db
  ship -->|links| launch
  launch -->|links| db

Solid arrows are links; dotted ones are citations. The boxes are bundles, so an arrow that leaves its box crosses into another bundle. That is allowed, but lint flags it because the link breaks if one bundle is published alone. From here, dirs and search find a concept, lint checks every file against the spec, status says what needs a person next (including the pages links want that nobody has written), and heatmap shows where the work is.

Next: the guide for layout and workflows, the tools for every command, and the OKF v0.2 specification it implements.