KnowledgeBaseMCP
A local MCP server for maintaining a folder of OKF v0.2 Markdown concepts (a knowledge base of bundles): check, edit, reorganize, and trace where facts came from.
Read and explore:
searchtext,getfiles (synthesizes missingindex.md),listconcepts by type/tag/status/tier/stale,statussummary and upkeep queues,bundles,links(in/out edges),log(history plus git commits),web(link graph, Mermaid),heatmap(hot concepts/authors from git).Write concepts:
createvalid frontmatter + body,setfrontmatter fields,recorda log.md entry,citea source with retrieval time and re-check recipe,verifyaverifiedentry (human confirmation prompt or agent self-check, optional draft→stable promotion).Check and repair:
lint(spec + hygiene findings,since/baseline/scopefilters),fixmechanical repairs,indexrebuild generated lists,baselinesnapshot existing findings,upgradev0.1→v0.2,provenanceinfergeneratedfrom git history.Reorganize:
inita new bundle,move/renamewithin a bundle,migratebetween bundles,splita directory into its own bundle,archive/unarchive,ingestmarkdown or another OKF bundle — all rewriting links.Keep facts current:
recheck_planlists sources due a re-check with replayable calls,recheck_applyrecords the re-check.Safe by default: write tools use
apply=falseto show a diff first, files are named asbundle+ path, and everything stays local (no network, never writes to git).
Reads local Git work-tree state and history: skips Git-ignored files, infers provenance from commits, includes commit history in concept logs, and ranks concepts by commit activity for heatmaps. It never writes to Git.
Integrates with GitHub Actions CI by producing GitHub annotations (format=github) and SARIF for code scanning, and supports PR-scoped linting via since; CI linting does not push fixes.
Checks, maintains, and imports OKF concepts stored as Markdown files, including links, generated indexes, and index sections.
Generates Mermaid diagrams for web link and citation maps via format=mermaid.
Provides a pre-commit hook configuration to run OKF lint on commits; the hook is lint-only.
Parses and validates YAML frontmatter in OKF concept files, including okf_version, metadata, sources, and path fields.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@KnowledgeBaseMCP lint the eng bundle and show me any problems"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 helpIn 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 bundleAny 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 (exceptREADME.mdandindex.md), whatever its name or folder, and no frontmatter is needed. A hit gets typeadrand itsstatus, read from MADR frontmatter, a## Statussection (Nygard) or a* Status:line (MADR 2).markdown: any other folder of Markdown, no frontmatter needed;index.mdandlog.mdare ordinary files. A numbered file name (0007-use-queue.md) or a path throughadr,adrsordecisionsstill counts as an ADR.asciidoc: AsciiDoc (*.adoc,*.asciidoc), no frontmatter needed. One passage per section; the document header's:name: valueattributes (or YAML front matter) are the metadata, andxref:,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; needspip 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 inseal.require; the one tool isseal, andkb seal check=truefails 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 anokfcollection keeps its concepts in order. Amarkdown,adr,skos,asciidocorseal-onlyfolder needs only akbmcp.yamland 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.mdthat 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=truewrites one everywhere).Being listed counts as being linked, so a listed concept is not an orphan.
getsynthesizes 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 folderA 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.yamlSeveral 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 |
| find and read, nothing written: | 10, ~1,750 tokens |
| shape, repair and reorganization: | 10, ~1,700 tokens |
| write a concept and check it: | 6, ~1,600 tokens |
| keep it current: | 9, ~1,800 tokens |
| a human's review of a file, and the check for it: | 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: averified: {by, at, sha256}entry in the concept's own frontmatter.markdown,adr,skos,asciidocandseal-only: one dense line per file in.waxseals.yamlat the collection root (commit it), holding only the latest review: file, sha256, who, when,bowerbird(the version that wrote it), anddecision=accepted|rejectedfor 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: trueLimits: 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 youscope=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=githubFindings 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: trueReading the collection
Find things in three steps, each small:
dirsmaps the bundle (each directory and how many concepts it holds);searchranks concepts by where every word matches (title, then id, tags, type, description, body), withtype=,tag=anddir=filters;getreads only the top hit.vocablists 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=textpassagesanswers 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). Withsemanticon, passages are also matched by meaning and the two rankings are fused.vector_indexpicks how:scan(exact, in Python; fine to a few thousand passages),sqlite-vec(exact, in C;pip install sqlite-vec) orhnsw(approximate, for 100K+;pip install hnswlib; it keeps the top 500 before the type, tag and dir filters). No hit returnsgap: true: say the collection has nothing, don't guess. Passages are indexed in one SQLite file (indexinkbmcp.yaml), updated from the files that changed.reindexbuilds it ahead of time, for a hook, and withbuild: manualpassagesonly reads it;reindex info=truereports what it holds and how far behind it is,drop=truedeletes it.passages: falseremoves both tools.uv run bowerbird_mcp.py reindex output=text uv run bowerbird_mcp.py passages 'how do we roll back a deploy' output=textwebmaps links and citations: bundles at the collection root, concepts in a bundle.output=textfor the terminal,output=mermaidfor anything that draws Mermaid (GitHub, GitLab).heatmap days=30ranks 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.adocand.asciidoc).statuslists what needs a person next: longest since review, oldest drafts, concepts without sources, the longest concepts, and what goes stale withindue_days; the most linked-to concepts (hubs); and the pages links want that do not exist yet (wanted), most wanted first. Inmarkdownandadrit 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=proposedis the unreviewed worklist.log file=x.mdis a concept's history.
Known limits
A human
sealover MCP needs a client that supports elicitation (confirmation prompts); otherwise the human runs it from the CLI.move,migrate,split,rename,archiveandunarchiverewrite 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_versionoptional; here it is how a bundle is found. An undeclared bundle is any folder until you pass it asbundle=.ingestdoes not convert other formats or check licenses. Its plan says so.With
format: skos, links between concepts are not counted, sohubsdoes nothing, and a file that does not parse is skipped without an error. Withformat: asciidoc,include::is not followed, andmoveis not offered.passageshas no stemming ("rolling" will not match "roll"), and withbuild: manualit does not notice files changed since the lastreindex. Semantic search downloads its model (~65 MB) once into~/.cache/bowerbird-mcp/models.fastembedand its dependencies (about 150 MB) come with the installed package (uvx bowerbird-mcp) but not with the bare script, which needsuv run --with fastembedforsemantic: true. The index lives in the fileindexnames and is safe to delete; nothing in the collection changes.
Self-check
uv run test_bowerbird_mcp.pySpec
SPEC.md is OKF v0.2, copied unchanged from
GoogleCloudPlatform/knowledge-catalog at commit bad9bdb,
Apache-2.0.
Available Tools
30 toolsarchiveADestructive
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.
baselineAIdempotent
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.
bundlesCRead-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.
fixAIdempotent
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.
getARead-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.
heatmapBRead-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.
indexAIdempotent
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.
ingestADestructiveIdempotent
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.
initAIdempotent
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.
linksBRead-onlyIdempotent
Edges of one concept (§6): out = its links, and its §6.2 path fields as field entries (sources are
lineage, §5.1); exists false = broken; target names the bundle and file. in = concepts in its bundle
that link to it or cite it. Check in before moving, renaming or deprecating a concept.
Inputs: file (required), bundle.
lintARead-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.
listARead-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.
logARead-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.
migrateADestructive
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.
moveADestructive
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.
provenanceAIdempotent
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_planARead-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.
renameADestructive
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.
searchCRead-onlyIdempotent
Case-insensitive text search over concepts; each hit is {bundle, file, line, text}.
Inputs: query (required), limit, bundle, offset.
setAIdempotent
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.
statusARead-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.
unarchiveADestructive
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.
upgradeAIdempotent
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.
webARead-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
Scored across 30 tools
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.
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.
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.
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
Related MCP Connectors
MCP Spec Compliance MCP — audits any MCP server.json against the official Model Context Protocol
KnowMan MCP server: search, ask, save and read your Knowledge Base from any MCP client.
Verified component catalog over remote MCP: agents pick component ids and get a stamped project repo that builds. Connect at https://www.botkelp.com/mcp. Auth: MCP OAuth 2.1, or a Bearer bk_live_ API key; initialize and tools/list are open.
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
Related MCP Servers
- AlicenseAqualityCmaintenanceMCP 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.109MIT
- AlicenseBqualityBmaintenanceA 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.28836 npm8MIT
- AlicenseNot gradedqualityBmaintenanceMCP 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.4MIT
- AlicenseNot gradedqualityAmaintenanceAn 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