Skip to main content
Glama

Bowerbird

Keep a folder of Markdown notes in order, and let an AI assistant, a script or you search and check them. It is for anyone who keeps notes, runbooks or documentation as Markdown in a folder or repository. It works on collections in Open Knowledge Format (OKF) v0.2: one Markdown file per concept, each starting with a small header of facts (its type, a description, where it came from, who checked it). A bundle is a folder of concepts; a collection is a bundle, or a folder of bundles. It is not tied to one format: one format: line in kbmcp.yaml points it at other formats too (Formats).

It is an MCP server (MCP, the Model Context Protocol, is how AI assistants call tools) and a command line. It checks, maintains and imports concepts, and finds the passages that answer a question. It cares how a concept is written, never what it says. Local files only, no network (but see semantic search, which downloads a model once). Never writes to git. One contract, three users: an agent over MCP, CI, and a person, at a terminal or in a browser, with no AI.

Try it (needs uv; its installer is curl -LsSf https://astral.sh/uv/install.sh | sh, which downloads and runs a script, so read it first if you prefer). In an empty folder:

alias kb='uvx bowerbird-mcp'
kb init apply=true output=text
kb create deploy type=Playbook title="Deploy" description="How we deploy." \
   body="Run the deploy script, then check the dashboard. To roll back, redeploy the previous tag." output=text
kb passages 'how do we roll back' output=text     # the best passages, with file and line
kb lint output=text                               # ends: bowerbird-mcp lint: ok: ...

Prefer a browser to a terminal? uvx --from 'bowerbird-mcp[serve]' bowerbird-mcp serve start opens the collection at http://127.0.0.1:26937/ to browse, search, edit and seal, with no AI involved (see Serve).

Personal project. Apache-2.0 (see LICENSE; NOTICE credits the spec), built under the ASF generative-tooling guidelines. Bugs and ideas: GitHub Issues; security reports: SECURITY.md.

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 collection's configuration. Commit it. The collection's root is the outermost one at or above the current directory, inside the same git work tree (a repository inside another is its own collection), or you name one with --config, so a server needs no env block. A kbmcp.yaml in a folder below the root overrides the root's for that folder and everything under it (mixed formats). 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 collections 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 | asciidoc | seal-only: 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 collection)
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, seal]   # 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 collection'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, .adoc files mean asciidoc, mostly numbered or adr/decisions Markdown means adr, other 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 output=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 collection 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. In an okf collection it is one bundle at its root, or a set of sibling bundles (other formats are just the folder). A directory whose index.md declares okf_version is a bundle root; bundles do not nest. An index.md at the collection 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 collection 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                 # the everyday commands for your format
uv run bowerbird_mcp.py help all             # 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 output=text
uv run bowerbird_mcp.py init apply=true       # start a new bundle

Any tool runs as <name> name=value ... or <name> '<json object>'. Flags work the same way, for people: init -t markdown -a "Docs" --apply, seal -cp, -h for a command's flags. They become the same name=value arguments (they are not abbreviated: --app is not --apply). At a terminal the output is text; piped, in CI or in a script it is JSON; -O json|text|github|sarif (or -F, or output=) chooses. The daily commands have fixed short flags; the others take the first free letter, so use their long flags in scripts. 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; output=text prints one key per line and diffs as is.

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

Related MCP server: okf-mcp

Formats

Bowerbird is not tied to one format. format in kbmcp.yaml says what a folder holds, and the same search, index and review tools work across them.

  • okf (the default): Open Knowledge Format bundles. Every tool is available.

  • adr: ADR and MADR decision records. Every Markdown file is a record (except README.md and index.md), whatever its name or folder, and no frontmatter is needed. A hit gets type adr and its status, read from MADR frontmatter, a ## Status section (Nygard) or a * Status: line (MADR 2).

  • markdown: any other folder of Markdown, no frontmatter needed; index.md and log.md are ordinary files. A numbered file name (0007-use-queue.md) or a path through adr, adrs or decisions still counts as an ADR.

  • asciidoc: AsciiDoc (*.adoc, *.asciidoc), no frontmatter needed. One passage per section; the document header's :name: value attributes (or YAML front matter) are the metadata, and xref:, link: and <<file.adoc#id>> links count. include:: is not followed.

  • skos: SKOS thesauri as Turtle, RDF/XML, JSON-LD, N-Triples or N3 (*.ttl, *.rdf, *.jsonld, *.nt, *.n3; needs pip install rdflib). One passage per concept, headed by its broader chain, with its labels, notes and broader, narrower and related concepts in the text.

  • seal-only: any text files you name (code, configuration), with nothing indexed or searched. List them in seal.require; the one tool is seal, and kb seal check=true fails when a listed file has no human review of its current version.

Outside okf a server offers only the tools that format uses: passages, reindex and seal for every format but seal-only (just seal); markdown adds get, search, dirs, links, list, status, heatmap, init and config; adr adds move; asciidoc adds heatmap. The command line always has every tool. A hit is unverified until a human seals that exact file (see Sealing): reviews go in .waxseals.yaml, not in the file. init guesses the format from the folder, and the agent's instructions follow it.

OKF layout

OKF only, and not required. Everything in this section (bundles, index.md, log.md, the archive) is how an okf collection keeps its concepts in order. A markdown, adr, skos, asciidoc or seal-only folder needs only a kbmcp.yaml and its files, in any layout you like.

kb/                          the collection (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 collection of its own, set apart
    index.md                 lists the archived bundles
    eng/old-runbook.md       archived from eng (archive/eng is a bundle)

OKF 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.

  • Collection 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 collection 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).

OKF 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.

For an okf bundle init adds log.md merge=union and index.md merge=union to the collection'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 OKF archive

archive/ is a collection within the collection, and a special one. Its index.md lists its bundles, like the collection 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 collection 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 collection root is a set of bundles or a bundle itself.

Mixed formats in one collection

One monorepo can hold several formats: an OKF bundle with a folder of ADRs, or a markdown collection with one. A kbmcp.yaml in a folder overrides the one above it for that folder and everything under it, key by key, the nearest one winning, like an inherited ACL: the whole tree is OKF, and that one part is ADR.

# kbmcp.yaml, at the root
format: okf
# adr/kbmcp.yaml
format: adr
seal: {require: ["*.md"], exempt_status: []}   # its globs start at this folder

A folder may override format, seal, about, hubs and min_similarity. The rest (roles, passages, index, semantic, semantic_model, vector_index, build) belongs to the whole collection, which has one index, one ledger and one embedding model; a folder that sets one is refused, with the fix. Nested files are read once, at startup, and found with git ls-files, so .gitignore is respected; restart the server after adding one.

What each tool does with the ADR folder inside an OKF bundle: passages, search, list, status, links, web and seal include it, each file read in its own format (an ADR's status, its review in .waxseals.yaml). lint, fix, index, provenance and upgrade leave it out, since they judge and rewrite OKF concepts. move and migrate still rewrite links in it, and a moved ADR keeps its review. Links between the two work in both directions. A server offers the tools of every format in use.

Register with an MCP client

init writes a .mcp.json at the root of the collection: 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 collections 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 collection 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); the first four roles are each about a quarter of that, and seal is one tool. 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 ingest migrate move rename split unarchive web

10, ~1,700 tokens

write

write a concept and check it: cite create fix lint record set

6, ~1,600 tokens

lifecycle

keep it current: baseline config index init provenance recheck_apply recheck_plan reindex upgrade

9, ~1,800 tokens

seal

a human's review of a file, and the check for it: seal

1, ~500 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 others change files (seal only writes a review: a ledger entry, or a concept's own verified key). 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. Outside okf the format limits it further, to the tools that format uses (see Formats). 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; in serve (the browser) a dialog asks the same two things; an assistant can only seal as itself (by=process:<id>), never as a human. verify (the OKF word), and ratify or accepted (the ADR words), are its command-line names too.

  • okf: a verified: {by, at, sha256} entry in the concept's own frontmatter.

  • markdown, adr, skos, asciidoc and seal-only: one dense line per file in .waxseals.yaml at the collection root (commit it), holding only the latest review: file, sha256, who, when, bowerbird (the version that wrote it), and decision=accepted|rejected for an ADR. The file itself is never edited, so Nygard ADRs, MADR and thesauri all work.

Like a wax seal, a review breaks when the file changes, and only a new review makes a new one (it replaces the old line; git has the history). 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.

  • unreadable: a required file is not UTF-8 text, so it cannot be reviewed here.

  • 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]}

A require glob that starts with ! takes files back out, for a generated page that needs no review: require: ["/*.md", "!/tools.md"].

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: bowerbird-seal
        name: Bowerbird seal check
        entry: uvx bowerbird-mcp seal check=true output=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 .waxseals.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 output=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 output=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 output=github

Findings show as annotations on the PR. output=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 collection 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 collection 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 output=text
        language: system
        pass_filenames: false
        verbose: true

Reading the collection

  • 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 output=text
    uv run bowerbird_mcp.py search deploy rollback dir=runbooks output=text
    uv run bowerbird_mcp.py get runbooks/deploy.md output=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 collection 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 output=text
    uv run bowerbird_mcp.py passages 'how do we roll back a deploy' output=text
  • web maps links and citations: bundles at the collection root, concepts in a bundle. output=text for the terminal, output=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. In OKF index.md and log.md are left out; the other formats count their own files (.md, or .adoc and .asciidoc).

  • 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. In markdown and adr it counts by type, status, state (a decision record is accepted once a person has sealed it, else proposed; superseded is final) and tier, and the records edited since a review (stale); list status=proposed is the unreviewed worklist.

  • 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. With format: asciidoc, include:: is not followed, and move is not offered.

  • 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 collection changes.

Self-check

uv run test_bowerbird_mcp.py

Spec

SPEC.md is OKF v0.2, copied unchanged from GoogleCloudPlatform/knowledge-catalog at commit bad9bdb, Apache-2.0.

Available Tools

30 tools
archiveA
Destructive

Move a concept, or (no file) the whole bundle= named, into the knowledgebase's archive bundle (archive/, started when absent) at /, so unarchive can put it back. Links to it are rewritten and warn afterwards (archived_link); status is left alone. A whole bundle keeps its log.md, and its index.md stops declaring a bundle (§8). The archive is read-only to editing tools. apply=False shows the plan and diff.

Inputs: file, apply, bundle.

baselineA
Idempotent

Snapshot today's lint findings so CI fails only on new ones (lint baseline=<path>; same bundle and all, and like lint it defaults to where the user is). For adopting OKF on a large existing collection. The snapshot's path is relative to the knowledgebase. apply=False only counts.

Inputs: all, path, apply, bundle.

bundlesC
Read-onlyIdempotent

Bundle roots under a directory: each index.md declaring okf_version (§12). A bundle without that declaration looks like any folder; pass it as bundle= directly.

Inputs: bundle.

citeA

Record where a fact came from as a §5.1 sources entry, with retrieved_at (when). When an MCP tool produced it, pass server, tool and args, the exact call (via, how): it is the re-check recipe for recheck_plan. resource: a real URL when the result has one, else mcp://server/tool?args is used. author, usage_count, last_modified: the source's own credibility signals (§5.1), when you know them. stale_days>0 sets stale_after. Returns the footnote marker to put after the claim; its definition is appended to the body. Reusing an id replaces that entry.

Inputs: file (required), id, args, tool, +8 more.

createA

Create a concept with valid OKF frontmatter (§4.1): type, title, description, resource, tags, status, and generated {by, at} when by (your actor) is given. body is markdown; a # title heading is added unless the body starts with one. Refuses an existing file or a reserved name (index.md, log.md).

Inputs: file (required), type (required), by, body, +6 more.

fixA
Idempotent

Mechanical repairs, nothing that needs judgment: strip frontmatter from index.md files (§8; the root keeps okf_version), rebuild generated index lists, give each tag its most common spelling, and put log.md sections and entries back in order after a merge (§9). apply=False shows the diff (CLI exit 1 if there is work); apply=True writes, re-lints and returns remaining (CLI exit 1 if errors remain). Like lint, it defaults to where the user is and every bundle there; all=false keeps to one bundle.

Inputs: all, apply, bundle.

getA
Read-onlyIdempotent

One .md file of a bundle (a concept, index.md or log.md), or several at once with files=[...]. A missing index.md is synthesized from frontmatter (§8; synthesized: true). offset/limit page by line; limit=0 = all.

Inputs: file, files, limit, bundle, +1 more.

heatmapB
Read-onlyIdempotent

The hottest concepts and who heats them, from git history (.mailmap names). files: commits that changed each concept in the last days, most first, and how many people did. bundles: the same per bundle. authors: each person's changes and concepts in the window. single_author: concepts only one person has ever changed (all history; a bus-factor flag). index.md and log.md are left out: every write touches them. Like lint, it covers where the user is (at the knowledgebase root, every bundle). limit=0 lists all.

Inputs: days, limit, bundle.

indexA
Idempotent

Rebuild generated document lists from frontmatter (title, type, tags, description, §8): the bundle-root index.md (a table, added if missing) and every index.md that already has a list. At a knowledgebase root, its index.md lists the bundles (created if missing). dirs=true also gives every directory an index.md listing its concepts and subdirectories (§8 progressive disclosure). apply=False shows the diff.

Inputs: dirs, apply, bundle.

ingestA
DestructiveIdempotent

Bring markdown from a local directory or git clone into an OKF bundle, or adopt it in place (bundle = source; needs a clean git tree, so the diff is the review). Each file gets frontmatter: type from rules ({glob: type}, first match, else Document), title (its own, its H1, or the filename), status (default draft: imported, not reviewed), optional stale_after, and provenance where git has it: sources (a permalink and last_modified) and generated {by, at, basis: git-history}. Existing keys are kept. Never overwrites; files that already have type are skipped, so a re-run is a no-op. A reserved index.md/log.md carrying frontmatter is renamed -index.md/-log.md. apply=False is the plan: run it first, sample files, set rules. keep_okf=true merges another OKF bundle: files that have type are copied as they are (plus an origin source when git has one) and the source's index.md/log.md are left behind. It does not clone, convert other formats, scan for secrets or check licenses.

Inputs: source (required), apply, limit, rules, +6 more.

initA
Idempotent

Start a bundle: a root index.md declaring okf_version "0.2" with a generated document list, and a §9 log.md. Refuses if index.md exists. Then add concepts (any .md with type: frontmatter) and lint.

Inputs: apply, bundle.

lintA
Read-onlyIdempotent

Check the bundle against OKF v0.2. Run it before and after any change, and in CI. Each finding: kind; scope (okf = the spec, house = hygiene); severity (error fails, warning does not); file; message; fix (what to do); fixable (true: fix clears it). conformant: §11 holds for what was linted (frontmatter parses, type set, index.md and log.md well formed). ok: no errors in scope. scope: all | okf | house. baseline: path of a baseline snapshot; only new findings count. since: a git ref; only files changed since its merge base with HEAD count (committed, staged, unstaged or untracked), for PRs. Each finding names its bundle and its file within it (§2). all=true: this directory and every bundle in it, with a summary per bundle. Without bundle=, it lints where the user is: the bundle around the working directory and everything in it (at the knowledgebase root, everything). file / files: only those files or directories (paths within bundle=), each checked within its own bundle. limit=0 returns every finding.

Inputs: all, file, files, limit, +5 more.

listA
Read-onlyIdempotent

Concepts, filtered by type, tag, status (draft | stable | deprecated; absent = stable), trust tier (unverified | machine-confirmed | human-reviewed) or stale=true. The review worklist after an ingest: status=draft tier=unverified.

Inputs: tag, tier, type, limit, +4 more.

logA
Read-onlyIdempotent

History, newest first. With file: the entries in every log.md over that concept that link to it (§9), and the git commits that changed it. Without: the bundle's recent entries from all its log.md files. record writes an entry.

Inputs: file, limit, bundle.

migrateA
Destructive

Move a concept to another bundle of the knowledgebase (move stays inside one). to_bundle: the target bundle's path in the knowledgebase ("." for its root). to: the path inside it (default: the same path). Links to the concept in both bundles are rewritten; its own / links, which meant the old bundle's root, become relative paths (cross-bundle: lint warns). Links from other bundles are not touched. apply=False shows the diff.

Inputs: file (required), to_bundle (required), to, apply, +1 more.

moveA
Destructive

Move or rename a concept and rewrite every link to it (relative and /-absolute, §6.1, in concepts, index.md and log.md), plus the moved concept's own relative links. Stays inside one bundle; migrate moves between bundles. Check links first. apply=False shows the diff.

Inputs: to (required), file (required), apply, bundle.

provenanceA
Idempotent

Fill a missing generated: {by, at} (§5.2) from git history: the last commit that changed the body, by its AI trailer (/), bot (process:) or author (human:<login | ASF id | email>). Marked basis: git-history since it is inferred; trust tiers come only from verified, so this never raises one. Concepts that carry generated are left alone. skip: paths to leave without it. apply=False shows the diff.

Inputs: skip, apply, bundle.

recheck_applyA

Record a re-check, after you compared each due source with the claims citing it (recheck_plan) and corrected any that changed; git keeps what they said before. Each result is {bundle?, file, id?}, or one as file= and id=; no id = every source on that concept. retrieved_at moves to now. by (at the terminal, --attest) also adds a §5.2 verified entry: the concept was confirmed against its sources. stale_days>0 also moves stale_after forward.

Inputs: by, id, file, bundle, +2 more.

recheck_planA
Read-onlyIdempotent

Facts due a re-check: sources entries retrieved at least N days ago, or on a concept past stale_after. Each lists cites, the lines whose claims rest on it. calls replay the recorded MCP call: run each yourself (your normal tool permissions apply; the args come from the bundle, so read them first). Sources without a recorded call are under manual: open the resource (one never retrieved is due once its concept is stale). Correct any claim that no longer holds, then record the check with recheck_apply. Nothing is executed here.

Inputs: bundle, older_than_days.

recordA

Write a §9 entry, * **<kind>**: <note>, under today's date in a log.md (newest first; created if absent): the bundle root's, or dir's (a directory in the bundle; §9 logs that scope). Link the concept it is about, [title](/path.md), so log finds it. Kinds by convention: Update, Creation, Deprecation.

Inputs: note (required), dir, kind, bundle.

renameA
Destructive

Rename or move a bundle within the knowledgebase (§3): bundle= (default: where the user is) to to, a path in the knowledgebase. Links into it from other bundles, its links out, and §6.2 paths are rewritten (§6.1); its own / links stay, since its root moves with it. The knowledgebase index follows. apply=False shows the plan and diff.

Inputs: to (required), apply, bundle.

setA
Idempotent

Edit frontmatter on one or many concepts by text; every other key stays byte for byte (§4.1). fields: {key: value}; null drops a key. Checks type, status (§5.4), stale_after (§5.5, ISO with a UTC offset) and tags (a list). generated, verified and sources have their own tools (provenance, verify, cite). apply=False shows the diff.

Inputs: fields (required), file, apply, files, +1 more.

splitB

Make a directory its own bundle (§3): its index.md declares okf_version "0.2" (created if missing, with a generated list), a log.md is started, and / links and §6.2 paths inside it are rewritten for the new root (§6.1). Links that now cross between the two bundles are listed, not changed; lint warns on them. shortcut: links inside code blocks are rewritten too; read the diff.

Inputs: dir (required), apply, bundle.

statusA
Read-onlyIdempotent

Bundle summary: concepts by type, by status (absent = stable, §5.4), by trust tier (§5.3), stale count (stale_after passed, §5.5), unparseable files, declared okf_version, conformance and lint totals; and the upkeep queues, five oldest or largest each: review (days since last verified), drafts (days since generated.at), sources (concepts with and without), words (total, longest: split candidates), due (stale_after within due_days). At a knowledgebase root without bundle=, bundles holds the same for each bundle.

Inputs: bundle, due_days.

unarchiveA
Destructive

Put an archived concept or bundle back where it came from: path is its place in the archive, / for a concept (its bundle must exist) or for a whole bundle (its index.md declares okf_version again). apply=False shows the plan and diff.

Inputs: path (required), apply.

upgradeA
Idempotent

OKF v0.1 to v0.2 (§13). A legacy timestamp becomes generated: {by, at, basis: git-history} with by from git history (by is required, so without history it stays and is listed in needs_by); a body # Citations list becomes sources entries and the list is removed; the root index.md declares okf_version "0.2". apply=False shows the diff.

Inputs: apply, bundle.

verifyA

Record a §5.2 verified entry {by, at} (at = now, UTC). Two paths: you (an agent or process) checked it: by=/ or process:; the concept is machine-confirmed. A human checked it: omit by; the human gets a confirmation prompt and types their own id. Never pass human: yourself. Present the concept to them first. At the terminal a human runs it with --attest. promote=true also moves a draft to stable (§5.4); only a human review may.

Inputs: file (required), by, bundle, promote.

webA
Read-onlyIdempotent

The link graph (§6): which concepts link to (link) or cite (cite: sources and §6.2 path fields, lineage, §5.1) which. Where the user is, like lint: at the knowledgebase root, bundles with edges counted; in a bundle (or concepts=true), concepts. Broken links are left out (lint reports them); archived and deprecated nodes are marked. Returns {level, nodes, edges}; mermaid=true returns a Mermaid diagram instead (CLI: format=mermaid), which GitHub and most markdown viewers draw.

Inputs: bundle, mermaid, concepts.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 30 tools

    Disambiguation3/5

    Most tools are distinct, but several lifecycle tools overlap conceptually: move vs migrate vs rename vs split vs archive/unarchive, and verify vs cite vs recheck_apply vs provenance. The descriptions explicitly cross-reference each other, which helps, but an agent could still misselect among these closely related bundle/concept operations.

    Naming Consistency3/5

    Names are all lowercase and mostly single words, but they mix verbs (search, create, verify, archive) with nouns (status, links, baseline, heatmap, bundles) rather than following a predictable verb_noun pattern. The recheck_plan/recheck_apply pair is the only notable compound style, making the set readable but not consistently patterned.

    Tool Count2/5

    30 tools is heavy for a knowledge-base server, well beyond the 3-15 well-scoped range. The domain is broad, and many tools are specialized, but the surface feels overloaded with migration, linting, graph, provenance, and lifecycle operations that could likely be consolidated.

    Completeness3/5

    The surface covers creation, reading, frontmatter editing, linking, linting, fixing, provenance, verification, archiving, migration, and ingestion, which is extensive. However, there is no tool for editing concept body content after creation and no direct delete operation, leaving notable gaps for core authoring workflows.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      MCP server that indexes Markdown, Word, HTML, and PDF documents into a SQLite knowledge graph with CJK+Latin full-text search and cross-document reference tracking. Runs drift audits to surface stale policies, conflicting research claims, superseded ADRs, and undocumented code exports.
      10
      9
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      A project-agnostic Open Knowledge Format MCP server that indexes Markdown concepts with YAML frontmatter and provides CLI and MCP tools for search, validation, and graph navigation of structured knowledge.
      28
      836 npm
      8
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP server that gives AI coding agents a git-backed markdown wiki to read and update, enabling search, read, write, verify, ingest, promote, and lint operations on versioned knowledge documents with schema validation, staleness tracking, and contradiction detection.
      4
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      An MCP server that enables verified agents to retrieve from, propose changes to, and share capabilities around a human-owned Markdown/Git knowledge base, ensuring curation, exact-byte approval, and Git-based promotion.
      MIT