Guide#

AI-generated

Drawn from the README, written with Claude Opus 5.5 and Claude Sonnet 5.5, under human review.

Run#

Requires uv. Install on the fly from PyPI, nothing to clone; this is the form to use (pip install bowerbird-mcp works too):

uvx bowerbird-mcp help

In the examples below, uv run bowerbird_mcp.py ... means the same command run from a checkout of this repository (or beside a saved copy of that one file). To run the latest unreleased code instead of the PyPI release, give uv the repository: uvx --from git+https://github.com/dfoulks1/bowerbird-mcp bowerbird-mcp help.

Settings: kbmcp.yaml#

A kbmcp.yaml is the knowledgebase's configuration, and any folder that holds one is a knowledgebase: its base, with its index, archive and bundles. Commit it. It sits at the root, not in a bundle. The tool finds the nearest one from the current directory up, or you name it with --config, so a server needs no env block. A folder inside a knowledgebase with its own kbmcp.yaml is another knowledgebase, and the outer one skips it. init writes a mostly filled-in one (see below); config apply=true writes the all-commented example, and neither overwrites a file. The old KB_ROOT variable is gone and is refused: the base is wherever kbmcp.yaml is.

about: Engineering runbooks.   # shown to the agent; tells knowledgebases apart
user: your-id         # your id in confirmation prompts: personal, prefer KB_USER in .env
ai_producers: [zed]   # extra AI names for the provenance check (KB_AI_PRODUCERS)
passages: true        # false removes the passages and reindex tools
format: okf           # okf | adr | markdown | skos: what the folder holds (see Formats)
hubs: true            # concepts many others link to rank a little higher
semantic: false       # also match by meaning (see Reading the knowledgebase)
semantic_model: BAAI/bge-small-en-v1.5
min_similarity: 0.6   # how close in meaning a passage must be
vector_index: scan    # scan | sqlite-vec | hnsw: how semantic search finds neighbours
index: .kbmcp/index.db   # one SQLite file: passages, BM25, links, vectors; "" = memory
build: auto           # auto: passages keeps the index current; manual: only `reindex`
roles: [read, write, structure, lifecycle]   # roles the server may offer (see Register)
seal: {require: ["**"], exempt_status: [proposed, draft]}   # who must have reviewed what (see Sealing)

Overrides: .env and the environment#

kbmcp.yaml is shared, so what is yours alone does not go in it. env.example lists every override as a KB_<KEY> variable (KB_USER, KB_ABOUT, KB_SEMANTIC, KB_VECTOR_INDEX, KB_BUILD, and so on; lists are comma separated). Copy it to .env beside kbmcp.yaml and uncomment what you change: .env is not committed (init and config list it in .gitignore). Precedence, last wins: kbmcp.yaml, then .env, then real environment variables. format is the knowledgebase's own and no override touches it. KB_ROLE (singular) is the same as --role.

init fills in what it can: format is guessed from the folder (thesaurus files mean skos, Markdown with no OKF types means markdown, else okf), and it asks for what it cannot know: about, your user id (kept in .env) and holds (the format, to confirm). Over MCP it asks the human with a prompt; at a terminal it asks on the command line; or pass them (init about="Runbooks." holds=markdown user=you apply=true). Only an okf folder gets a first bundle.

The index#

With no kbmcp.yaml the defaults apply. The index is a cache derived from the concepts: safe to delete, never committed (a new .kbmcp/ folder ignores itself). To build it apart from the server, run reindex (incremental: only changed files are read) and set build: manual, so passages only reads it:

uvx bowerbird-mcp reindex format=text     # first semantic run embeds everything: minutes, once
# .pre-commit-config.yaml: refresh after you commit and after pulls
repos:
  - repo: local
    hooks:
      - id: kbmcp-reindex
        name: Bowerbird reindex
        entry: uvx bowerbird-mcp reindex
        language: system
        pass_filenames: false
        always_run: true
        verbose: true
        stages: [pre-commit, post-merge, post-checkout]

Where tools look#

A knowledgebase is where its kbmcp.yaml is: the tool looks for one from the current directory up (or takes --config path/to/kbmcp.yaml) and treats that file's folder as the base. With none, it uses the current directory. It is one bundle at its root, or a set of sibling bundles. A directory whose index.md declares okf_version is a bundle root; bundles do not nest. An index.md at the knowledgebase root lists its bundles (index apply=true there writes it), and tools find the root from inside a bundle through it. bundles lists them, split makes a directory its own bundle, rename moves or renames one, migrate moves a concept between bundles, archive and unarchive retire and restore a concept or a whole bundle, ingest keep_okf=true merges one in, and upgrade converts OKF v0.1.

Tools follow where you are: in a bundle, that bundle; at the knowledgebase root, every bundle (lint, fix, baseline, status, list, search, recheck_plan). Name files or directories to lint just those (lint notes/a.md docs/). Files are named the OKF way: a bundle and the path within it (bundle=eng file=runbooks/deploy.md), in every input and output. On the command line, without bundle=, paths are relative to where you are. Write tools act in the bundle the file belongs to. In a git work tree, files git ignores are skipped.

Running a tool#

wget https://raw.githubusercontent.com/dfoulks1/bowerbird-mcp/main/bowerbird_mcp.py
uv run bowerbird_mcp.py help                 # every tool, one line each
uv run bowerbird_mcp.py help move            # one tool: what it does, its arguments
uv run bowerbird_mcp.py lint format=text
uv run bowerbird_mcp.py init apply=true       # start a new bundle

Any tool runs as <name> name=value ... or <name> '<json object>'. Bare arguments fill the required ones in order (move a.md b.md); on set, any other key=value is frontmatter (set a.md status=deprecated tags=[x,y]). Write tools that touch many files default to apply=false and show a diff.

--attest records you, as human:<KB_USER> (else your git user.email), on create and provenance (generated), seal and recheck_apply (verified). It exists only on the command line: no MCP call can pass it.

Output is JSON; format=text prints one key per line and diffs as is.

Exit codes: 0 ok, 1 findings, 2 usage error.

Layout#

kb/                          the knowledgebase (kbmcp.yaml sits here)
  index.md                   lists the bundles; no frontmatter
  .gitattributes             log.md and index.md merge=union
  eng/                       a bundle
    index.md                 okf_version, then the list of its concepts
    log.md                   its history (§9)
    runbooks/
      index.md               optional: this directory's concepts
      deploy.md              a concept
  archive/                   the archive: a knowledgebase of its own, set apart
    index.md                 lists the archived bundles
    eng/old-runbook.md       archived from eng (archive/eng is a bundle)

index.md#

OKF §8: an index lists what is in its directory, for progressive disclosure. Every index has the same body shape, sections under headings with one entry per item:

# Engineering

Hand-written text is kept.

<!-- kb-index:start (generated by KnowledgeBaseMCP index; do not edit between the markers) -->

### runbooks

* [Deploy](./runbooks/deploy.md) - How we deploy.

<!-- kb-index:end -->
  • The tool owns what is between the markers and rebuilds it from frontmatter (title, else first heading, else file name; description, else the first sentence). Write anything else around them.
  • Knowledgebase root: no frontmatter (it is not a bundle). The list has one entry per bundle, titled by that bundle's first heading. Tools find the knowledgebase by walking up from a bundle to the nearest index.md that links to it.
  • Bundle root: frontmatter holds only okf_version: "0.2", which is what makes the directory a bundle (§12). The list covers every concept, a section per top-level folder.
  • Any other directory: no frontmatter. The list covers that directory's concepts and subdirectories (index dirs=true writes one everywhere).
  • Being listed counts as being linked, so a listed concept is not an orphan.
  • get synthesizes a missing index from frontmatter (§8 allows this).

log.md#

OKF §9: date headings, newest first, one entry per line. Each tool write adds an entry to the nearest log.md above the change, with a hidden unix-time stamp:

## 2026-10-27

* <!-- 1761588000 --> **Update**: Moved deploy.md to [ship.md](/runbooks/ship.md).

record "note" writes one by hand (link the concept it is about). log file=x.md reads a concept's history: the entries linking to it in every log.md above it, and the git commits that changed it. log alone shows the bundle's recent entries.

init adds log.md merge=union and index.md merge=union to the knowledgebase's .gitattributes, so git keeps both sides when parallel branches log or index. After such a merge, fix merges duplicate log date sections, orders stamped entries by time, and rebuilds the generated index lists. A section with a hand-written, unstamped entry keeps its order.

The archive#

archive/ is a knowledgebase within the knowledgebase, and a special one. Its index.md lists its bundles, like the knowledgebase root's. archive file=x.md bundle=eng moves a concept to archive/eng/x.md (starting archive/eng as a bundle); archive bundle=eng moves the whole bundle to archive/eng/, still a bundle. unarchive eng/x.md or unarchive eng puts them back. Links follow both ways.

The live knowledgebase does not see the archive: lint, list, search, status and web leave it out, nothing in it counts as nesting, and lint warns on links into it (archived_link). Editing tools refuse archived concepts. That is the only enforcement: the files are plain files, so an editor or a commit can still change them. It works whether the knowledgebase root is a set of bundles or a bundle itself.

Register with an MCP client#

init writes a .mcp.json at the root of the knowledgebase: commit it, and whoever clones the repository has the tools with nothing to register on their own machine (Claude Code asks once to approve a project's server). For another client, or a folder without one, add this to the client's servers file: .mcp.json in the project for Claude Code, claude_desktop_config.json for Claude Desktop, .cursor/mcp.json for Cursor. VS Code's .vscode/mcp.json takes the same entry under "servers".

{
  "mcpServers": {
    "bowerbird": {
      "command": "uvx",
      "args": ["bowerbird-mcp"]
    }
  }
}

The server runs in the project folder, so it finds the kbmcp.yaml there (your id is user: in it). To point at one elsewhere, add "--config", "/path/to/kb/kbmcp.yaml" to args. Or, in Claude Code:

claude mcp add bowerbird -- uvx bowerbird-mcp --config /path/to/kb/kbmcp.yaml

Several knowledgebases at once: one entry each, with its own --config. The client prefixes tool names with the entry name, and each file's about: tells the agent what that knowledgebase holds. Each keeps its own index.

The client loads the tool list at start. After editing the script, restart the client or reconnect the server (/mcp in Claude Code).

Roles: a smaller tool list per agent#

All 35 tools cost an agent about 7,250 tokens of schema (an estimate: each tool's name, description and argument schema as the client receives them, in characters divided by four); each role is about a quarter of that. Register the same script more than once, each with a role (--role, or KB_ROLE; several with commas), and each server offers only that role's tools:

Role Tools Schema
read find and read, nothing written: dirs get heatmap links list log passages search status vocab 10, ~1,750 tokens
structure shape, repair and reorganization: archive bundles dirs fix ingest migrate move rename split unarchive web 11, ~1,900 tokens
write write a concept and check it: cite create lint record seal set 6, ~1,850 tokens
lifecycle keep it current: baseline config index init provenance recheck_apply recheck_plan reindex upgrade 9, ~1,800 tokens
{
  "mcpServers": {
    "kb-read":  { "command": "uvx", "args": ["bowerbird-mcp", "--role", "read"] },
    "kb-write": { "command": "uvx", "args": ["bowerbird-mcp", "--role", "write"] }
  }
}

The read server is read-only, so a client can approve it without asking; the other three change files. A tool can belong to more than one role (dirs is in read and structure), and a server with no --role offers them all. With no --role the server offers every role that roles: in kbmcp.yaml leaves on; naming a role that is off refuses to start. The CLI always has every tool.

Sealing: who reviewed what#

seal is the one function for a human's review, in every format. It shows the human the exact file in a prompt, asks for their id, and records who reviewed that version and when. Over MCP the human types their own id; at a terminal --attest records you; an assistant can only seal as itself (by=process:<id>), never as a human. verify (the OKF word) and ratify (the ADR word) are its command-line names too.

  • okf: a verified: {by, at, sha256} entry in the concept's own frontmatter.
  • markdown and skos: an entry in verifications.yaml at the knowledgebase root (commit it): file, sha256, who, when, and decision=accepted|rejected for an ADR. The file itself is never edited, so Nygard ADRs, MADR and thesauri all work.

The sha256 covers the file's exact bytes (line endings normalized; for okf, without the verified key). Edit the file after sealing and the seal is broken: passages shows the hit unverified and stale. A ledger decision becomes the hit's status.

seal check=true changes nothing and exits 1 on findings, for a pre-commit hook and for CI (since=origin/main limits it to a pull request's files):

  • unsigned: a file the policy requires has no review by a human.
  • stale_signature: reviewed, then edited.
  • claims_accepted: its own status says accepted, but no human reviewed it.
  • orphan_signature: a ledger entry for a file that is gone (a warning).

The policy is the seal key in the committed kbmcp.yaml (nothing local can loosen it); by default every file needs a review, except those whose status is proposed or draft:

seal: {require: ["**"], exempt_status: [proposed, draft]}
# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: bowerbird-seal
        name: Bowerbird seal check
        entry: uvx bowerbird-mcp seal check=true format=text
        language: system
        pass_filenames: false
        always_run: true

Limits: a hook can be skipped (--no-verify), so run the same command in CI. seal proves a ledger entry exists for these bytes, not who typed it: protect verifications.yaml and kbmcp.yaml with CODEOWNERS or branch protection so changes to them need a named reviewer. A SKOS file is sealed whole, not per concept.

Before you push#

uv run bowerbird_mcp.py lint format=text      # what's wrong, each with a fix
uv run bowerbird_mcp.py fix apply=true        # mechanical repairs, then re-lint
uv run bowerbird_mcp.py lint format=text      # what's left needs you

scope=okf limits the check to the spec; scope=house to hygiene (links, anchors, orphans, islands, stubs, duplicate titles, reference links, filenames, tags, generated indexes). only= and ignore= keep or drop finding kinds: lint only=stub,island.

CI#

Vendor bowerbird_mcp.py into the bundle's repo, then:

# .github/workflows/okf.yml
name: okf
on: [push, pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0          # provenance needs full history
      - uses: astral-sh/setup-uv@v6
      - run: uv run bowerbird_mcp.py lint scope=okf format=github

Findings show as annotations on the PR. format=sarif suits code scanning. On PRs, since=origin/${{ github.base_ref }} limits findings to the files the PR changed. On a large existing collection, commit a baseline apply=true snapshot and run lint baseline=.okf-baseline.json, so only new findings fail. The snapshot sits at the knowledgebase root and matches from any directory. CI lints; it does not push fixes (fork PRs get a read-only token anyway).

To skip files outright, list them in a kbmcp.nolint file. It works like .gitignore: it may sit in any directory, patterns are relative to it, the last match wins and ! re-includes. At the knowledgebase root it covers every bundle. Skipped files are still read, so links to them resolve. One file can skip itself with the line <!-- kbmcp-nolint -->.

# kbmcp.nolint: agent instructions are not concepts
AGENTS*
CLAUDE.md
.kiro/

pre-commit, lint only (a hook that edits files leaves the commit unstaged). lint always ends with a verdict line, such as bowerbird-mcp lint: ok: 214 concept(s) in 3 bundle(s) checked, 0 finding(s), conformant: True, so you can see it ran. pre-commit prints a passing hook's output only with verbose: true:

repos:
  - repo: local
    hooks:
      - id: okf-lint
        name: OKF lint
        entry: uv run bowerbird_mcp.py lint format=text
        language: system
        pass_filenames: false
        verbose: true

Reading the knowledgebase#

  • Find things in three steps, each small: dirs maps the bundle (each directory and how many concepts it holds); search ranks concepts by where every word matches (title, then id, tags, type, description, body), with type=, tag= and dir= filters; get reads only the top hit. vocab lists the tags and types in use, the words those filters take.
uv run bowerbird_mcp.py dirs format=text
uv run bowerbird_mcp.py search deploy rollback dir=runbooks format=text
uv run bowerbird_mcp.py get runbooks/deploy.md format=text
  • passages answers a question. It cuts concepts at headings (a long section is cut again at blank lines, each piece repeating the last short paragraph of the one before) and returns the best sections, each with file, line, heading, trust tier and staleness, so the answer can cite and qualify its sources. Ranking is BM25 (rarer words count more; any one word may match; no stemming), with title, tags, type and description counting too, and concepts many others link to a little higher (hubs). With semantic on, passages are also matched by meaning and the two rankings are fused. vector_index picks how: scan (exact, in Python; fine to a few thousand passages), sqlite-vec (exact, in C; pip install sqlite-vec) or hnsw (approximate, for 100K+; pip install hnswlib; it keeps the top 500 before the type, tag and dir filters). No hit returns gap: true: say the knowledgebase has nothing, don't guess. Passages are indexed in one SQLite file (index in kbmcp.yaml), updated from the files that changed. reindex builds it ahead of time, for a hook, and with build: manual passages only reads it; reindex info=true reports what it holds and how far behind it is, drop=true deletes it. passages: false removes both tools.
uv run bowerbird_mcp.py reindex format=text
uv run bowerbird_mcp.py passages 'how do we roll back a deploy' format=text
  • web maps links and citations: bundles at the knowledgebase root, concepts in a bundle. format=text for the terminal, format=mermaid for anything that draws Mermaid (GitHub, GitLab).
  • heatmap days=30 ranks concepts by how many commits changed them (the ones most likely to collide across branches) and by how many people did; who changes the most; and concepts only one person has ever touched. index.md and log.md are left out.
  • status lists what needs a person next: longest since review, oldest drafts, concepts without sources, the longest concepts, and what goes stale within due_days; the most linked-to concepts (hubs); and the pages links want that do not exist yet (wanted), most wanted first.
  • log file=x.md is a concept's history.

Known limits#

  • A human seal over MCP needs a client that supports elicitation (confirmation prompts); otherwise the human runs it from the CLI.
  • move, migrate, split, rename, archive and unarchive rewrite links (code blocks included; read the diff) and §6.2 path fields (resource, computation, executor/attester, sources[].resource). A value naming an existing file is a path; one naming nothing is a path only if it has a file extension or a leading /, ./ or ../, else a scope description.
  • OKF makes okf_version optional; here it is how a bundle is found. An undeclared bundle is any folder until you pass it as bundle=.
  • ingest does not convert other formats or check licenses. Its plan says so.
  • With format: skos, links between concepts are not counted, so hubs does nothing, and a file that does not parse is skipped without an error.
  • passages has no stemming ("rolling" will not match "roll"), and with build: manual it does not notice files changed since the last reindex. Semantic search downloads its model (~65 MB) once into ~/.cache/bowerbird-mcp/models. fastembed and its dependencies (about 150 MB) come with the installed package (uvx bowerbird-mcp) but not with the bare script, which needs uv run --with fastembed for semantic: true. The index lives in the file index names and is safe to delete; nothing in the knowledgebase changes.