Knowledge base plugin

A team knowledge base that lives in this repository as markdown under content/, packaged as an Agent Plugins 1.0 plugin for atmOS. Agents search it, cite it by path and line, and publish small amendments back to it through git.

The plugin carries:

mcp.json: one stdio MCP server, knowledge-base, run with node ./server/index.js from a checkout of this repository. Plain ESM JavaScript, no dependencies, Node 20 or newer, nothing to install.
skills/knowledge-base: when and how to search and read, and how to cite.
skills/amend-knowledge: how to make small, well-titled amendments.
content/: the knowledge base itself. The pages shipped here describe a fictional company, Tidewater Labs; replace them with your own.

Use it in atmOS

New knowledge base creates a copy of this template repository for you and installs it.
Or install it directly: Add plugin, then paste the repository URL (this one, or your own copy).

atmOS runs the MCP server from a checkout of the repository and keeps self-authored plugins up to date from their tracked branch.

Tools

Tool	Arguments	Result
`kb_search`	`query`, `limit` (default 10, max 50)	Pages ranked by full-text relevance with title, score and up to three `path:line` snippets
`kb_read`	`path`, `startLine`, `endLine` (inclusive, 1-based)	The page or line range, with the total line count
`kb_list`	`folder` (optional)	Every page under `content/` or the folder, with its title
`kb_amend`	`path`, `content` or `edit: { find, replace }`, `message`	Writes the page, commits it and pushes it; reports the commit and whether it was published

Paths are relative to content/ (policies/expenses.md) or start with it (content/policies/expenses.md). Results always use the content/... form. Every tool returns readable text plus the same data as structuredContent.

kb_amend only writes .md files inside content/. It refuses absolute paths, .., hidden files and symlinks that lead outside content/, refuses empty content, and an edit.find must match exactly once. It never deletes pages.

How amendments publish

Each kb_amend call:

Writes the page.
Runs git add and git commit for that page only, with message as the commit title.
Pushes HEAD to the branch the checkout tracks. If the remote moved on, it rebases onto it and pushes again. It never force-pushes.

Git runs with GIT_TERMINAL_PROMPT=0 and SSH in batch mode, so it never waits for a password. When the commit cannot be published the result says why, and the commit stays in the checkout:

`push.status`	Meaning
`pushed`	Published to the tracked branch
`not_configured`	The checkout has no git remote
`no_upstream`	The current branch does not track a remote branch
`detached`	The checkout is on a detached HEAD
`rejected`	The remote refused the push or the rebase conflicted
`failed`	Anything else, usually missing credentials; git's message is included

The machine running the server needs git credentials that can push to the repository. Without a configured user.name and user.email it commits as Knowledge base <knowledge-base@localhost>; set KB_GIT_AUTHOR_NAME and KB_GIT_AUTHOR_EMAIL to change that.

Local development

node server/index.js          # serve this checkout over stdio
KB_ROOT=/path/to/other/checkout node server/index.js
npm test                      # node:test, no install needed

A quick session by hand:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"cli","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"kb_search","arguments":{"query":"refund"}}}' \
  | node server/index.js

The server speaks MCP protocol versions 2025-06-18, 2025-11-25 and 2026-07-28, and echoes the client's version when it is one of them.

scripts/render-assets.py regenerates the icon, logo and screenshot in assets/ (Python 3 with Pillow, macOS system fonts).

License

MIT