Serve#
AI Generated, Human Reviewed at: 2026-11-18T15:57:43Z
serve is Bowerbird in a browser, for a person. It browses a collection, searches it, edits it and seals it, with no AI
involved: it makes no model calls, and nothing it writes is stamped as machine-written. It runs on your machine, on
127.0.0.1, and rereads the files on every request, so a change on disk shows when you refresh.
Start it#
It needs one extra package (markdown):
pip install 'bowerbird-mcp[serve]'
# or, with no install:
uvx --from 'bowerbird-mcp[serve]' bowerbird-mcp serve start
Run it from inside a collection (the folder holding kbmcp.yaml, or below it):
bowerbird-mcp serve start # in the background, at http://127.0.0.1:26937/
bowerbird-mcp serve start -f # in the foreground; ctrl-c stops it
bowerbird-mcp serve start 8080 # another port
bowerbird-mcp serve status # information only (exit 0 if running, 1 if not); a bare `serve` does this
bowerbird-mcp serve stop # end it; nothing running is not an error
bowerbird-mcp serve restart # stop what is found, then start
Code highlighting is optional: add the syntax extra (pip install 'bowerbird-mcp[serve,syntax]') and serve colours
code files by their file name, in a light and a dark set that follow the theme. Without it they show as plain numbered text.
status and stop take the port if it is not 26937. The port (26937) spells BOWER on a phone keypad.
A different repository. Run it from there, or name its config from anywhere:
bowerbird-mcp --config /path/to/repo/kbmcp.yaml serve. To serve several at once, give each its own port and use the same
port with status and stop.
Stopping. serve stop, or the ⏻ button at the right of the top bar. If you lose your shell, the button ends the
server, so you never have to hunt for the process.
Restarting. Refresh the page to see changed files. Run serve restart after you change
kbmcp.yaml or update Bowerbird, because both are read once at start.
What you see#
- Left: the folder tree of the whole collection, with a dot on each page for its seal state (green sealed, amber unsealed, red broken by an edit, grey derived from the code and so never sealed). Every folder ends in + New file. Under the root are Lint all and Tags.
- Middle: the page, with a badge saying who sealed it and when, or that it is unsealed or edited since review.
- Right: a pencil (edit) and a gear (Move, Delete, Seal), then the page's outline, the pages that link to it and the pages it links to.
- Top: back and forward, a path, the search box with its type menu, a theme button (system, light, dark) and ⏻.
Seal-only collections. A file that seal.require names (code, YAML, config) is a page here: read-only, as numbered
text, with a badge and the same Seal button. It has no editor, no tags and no outline. A file that is not UTF-8 text, or is
over 512 KB, is not listed or shown; the command line still seals it. With no root index.md, / shows the empty shell
(tree and search) rather than a directory listing.
Keys: / search, n and p next and previous unsealed page, j and k next and previous page, t theme, [ and ]
history.
Search#
The menu beside the search box chooses what kind of search to run, and remembers your choice.
| Type | What it searches | Notes |
|---|---|---|
| Passages | Ranked sections of pages, by keyword | The same passages an agent gets. Each hit shows its file and line, its trust tier and whether it is stale. |
| Concepts | Whole pages | The same as the search tool: a title match counts for more than a body match. |
| Meaning | Passages, matched by meaning as well as keyword | Offered only when kbmcp.yaml sets semantic: true (it needs fastembed). |
| Tags | Pages with a tag containing your text | Click a tag on the Tags page to jump here. |
Press Enter for a full results page, with the other types a click away.
Change things#
Every change goes through the same tools the command line runs. Where a tool can preview, you see its diff first and nothing is written until you confirm.
- Edit (the pencil). The page's own text in a box, with Save, Lint and Cancel. Lint checks the text as you
have typed it, without saving. Save refuses to overwrite a page that changed on disk while you were editing, so you
never silently lose someone's work. Only
.mdfiles inside the collection can be edited here. - New file (the link at the foot of each folder). The folder is fixed; type a name in the heading (
.mdis added), write the page, and Save. A name ending in/makes a folder instead. Git keeps a folder once it holds a file. - Move (the gear). Moves or renames a page and rewrites every link to it, with a diff to confirm.
- Delete (the gear). Removes the file and its seal entry, and refuses while another page links to it. Git is your
undo. For a reversible removal, use
archive(the refusal page links to it). - Tags. A tag is a word in a page's frontmatter:
tags: [deploy, runbook]. Any page with frontmatter has a tags field under it (comma separated). The Tags page lists every tag in use, and renames, merges or removes one across all pages, with a diff first. A tag renamed to an existing tag merges them. - Lint all lists every finding in the collection, with what to do about each, and previews
fixfor the ones it can clear.
Seal from the browser#
Seal (the gear) opens a dialog that shows what the MCP prompt shows: the file, its word count, how it opens and the
first characters of its sha256. You tick that you reviewed it, type your id, and Bowerbird records human:<your id> for
exactly that text. A draft concept can be promoted to stable in the same step, and a decision record can be marked accepted
or rejected. If the page changed while the dialog was open, nothing is written and you review it again.
The server never seals by itself. Editing a sealed page afterwards breaks its seal, and the badge says so until you review it again. See Sealing for what a seal means.
Safety#
serve listens on 127.0.0.1 only, and refuses requests whose Host is not that address (a web page on another site
cannot reach it through your browser). Every change needs a token that is made fresh each time the server starts and
carries only in pages serve sends you. Paths are held inside the collection. Any path with a part that starts with a dot (.env, .git/,
.waxseals.yaml, sub/.hidden) is a 404, and so is any path through a symbolic link; listings leave both out.
Hidden files stay sealable from the command line.
It trusts the person at the machine, as the command line's --attest does: a program running as you could submit the
seal form too. A hardware key (FIDO2) is the planned way to close that. Do not put serve behind a public proxy: it has
no logins.
If something goes wrong#
serve needs the markdown package. Install the extra:pip install 'bowerbird-mcp[serve]'.port 26937: Address already in use. It is already running (serve status), or something else has the port. Useserve stop, or pick a port:serve start 8080.- Meaning is not in the search menu.
semanticis off inkbmcp.yaml. Turn it on, then restartserve. - A page you edited is not what you expected. Check
git diff. Edits are plain file writes, and Git has the history. - Not in the tools here.
provenance,initand the rest of the tools are the command line's:bowerbird-mcp help.