# Knowledge base plugin

A team knowledge base that lives in this repository as markdown under `content/`, packaged as an [Agent Plugins 1.0](https://github.com/agentplugins/agent-plugins-spec/blob/main/spec/1.0.0.md) 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:

1. Writes the page.
2. Runs `git add` and `git commit` for that page only, with `message` as the commit title.
3. 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

```sh
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:

```sh
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