BowerbirdMCP
Curate a collection of files, and know a human looked at them.
Dokümantasyon
Curate a collection of files, and know a human looked at them. Bowerbird keeps notes, decisions, vocabularies or code searchable and in order, for agents and people alike. Guarantee integrity across formats with one tool.
An agent, over MCP
Every tool, with a diff before each write and a confirmation prompt before anything records a person.
CI
lint as GitHub annotations or SARIF, a baseline for old findings, since= for pull requests, and seal check=true to fail a commit that has no human review.
A person at a terminal
No AI needed: help, ranked search, passages for questions, readable text output, and --attest to sign your own reviews.
Local files only. No network, except the one-time model download if you turn on semantic search. Never writes to git. One Python file, installed or run with uv. These pages were written with Claude Opus 5.5 and Claude Sonnet 5.5 and are sealed with Bowerbird.
Pick the format that fits
A format: line in kbmcp.yaml says what a folder holds. Each exists for a reason:
- Markdown: notes, runbooks, wikis, docs. Nothing to write but Markdown.
- ADR: decision records (ADR or MADR), with each record's status.
- OKF: knowledge that says where it came from, who checked it and when it expires, with the full toolset.
- SKOS: glossaries, vocabularies and thesauri.
- Seal-only: code and other files, with nothing searched: just a guaranteed human review of each one.
Formats shows what each one looks like, side by side.
Use whatever type is right for you: plain Markdown needs no header and no conversion, ADR reads decision records, OKF adds sources and trust, SKOS holds vocabularies, and seal-only does no searching at all, just a guaranteed human review of each file you name.
Quickstart
Nothing to clone. uv installs it from PyPI, with its dependencies, on the fly:
uvx bowerbird-mcp help
No uv yet? curl -LsSf https://astral.sh/uv/install.sh | sh
Then add it to your MCP client's servers file (.mcp.json for Claude Code; other clients):
{
"mcpServers": {
"bowerbird": {
"command": "uvx",
"args": ["bowerbird-mcp"]
}
}
}
Or work from the terminal, no AI needed. In any folder, with the format that fits what you keep (Markdown here, as an example):
# make it a collection: settings files only, your files are not touched
# holds= is markdown, adr, okf, skos or seal-only
uvx bowerbird-mcp init holds=markdown about="Team notes." apply=true
# ask a question: the best sections, each with the file and line to cite
uvx bowerbird-mcp passages 'how do we deploy' output=text
# any tool: what it does, its arguments
uvx bowerbird-mcp help passages
Next: getting started for a ten-minute walkthrough, formats for what each kind of collection looks like, the guide for settings and workflows, the tools for every command, and OKF for the richest format, with its specification.