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., "@knowledge-base search for refund policy"
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.
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.
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.
Related MCP server: 50 First Tapes MCP Server
Tool | Arguments | Result |
|
| Pages ranked by full-text relevance with title, score and up to three |
|
| The page or line range, with the total line count |
|
| Every page under |
|
| 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.
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:
| Meaning |
| Published to the tracked branch |
| The checkout has no git remote |
| The current branch does not track a remote branch |
| The checkout is on a detached HEAD |
| The remote refused the push or the rebase conflicted |
| 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.
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 neededA 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.jsThe 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).
MIT
Create or change one markdown page under content/, then commit it and push it to the tracked branch so it is published. Pass either content (the whole new page) or edit ({ find, replace }, where find must match exactly once). The message becomes the commit title. Pages are never deleted.
| Name | Required | Description | Default |
|---|---|---|---|
| edit | No | A targeted change: find is replaced by replace. find must occur exactly once in the page. | |
| path | Yes | Page path under content/, ending in .md. | |
| content | No | The complete new text of the page. Use for new pages or full rewrites. | |
| message | Yes | Commit title describing the change, for example 'Expenses: raise meal limit to 60 EUR'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only signal non-read-only, non-idempotent, non-destructive. The description adds substantial behavioral context beyond that: it commits and pushes to the tracked branch to publish, the message becomes the commit title, and pages are never deleted. This fully discloses the side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences, each earning its place: the core action plus commit/publish behavior, then the two call modes and the non-deletion guarantee. No filler and no repetition of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a side-effecting tool with no output schema, the description covers the main outcomes (commit, push, publish) and the non-destructive guarantee. It leaves some gaps — such as error behavior when find does not match or when a path is missing — but the essentials an agent needs to call it correctly are present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and each parameter already has a description. The description adds value by making the either/or relationship between content and edit explicit and by clarifying that find must match exactly once, which is not fully conveyed by the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Create or change one markdown page under content/') and covers the two modes (content vs edit). It is clearly distinguishable from the read-only siblings kb_search, kb_read, and kb_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for use: it is the write/publish tool among read siblings, and it explains when to pass content vs edit. However, it never explicitly names alternatives or states when not to use the tool, so it stops short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List knowledge base pages with their titles, optionally only those under one folder.
| Name | Required | Description | Default |
|---|---|---|---|
| folder | No | Folder under content/ to list, for example policies. Defaults to everything. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds that results contain titles and that listing can be scoped to a folder, but it does not disclose behaviors like pagination, ordering, or whether subfolders are included. This is acceptable but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no filler, front-loaded with the action and resource, and the optional behavior placed at the end. Every word contributes to understanding the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one optional parameter, the description sufficiently states what is returned (titles) and the optional folder scope. The schema covers the folder default. It could add details about pagination or recursive folder behavior, but nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the folder parameter is already fully documented in the input schema. The description's mention of listing 'under one folder' adds no meaning beyond the schema's definition. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource: it lists knowledge base pages and returns their titles. It also adds the folder-scoping option, which makes the tool's purpose clear. It does not explicitly name or contrast sibling tools, so it stops just short of full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage context is implied: use this tool to enumerate knowledge base pages, optionally within a single folder. However, the description does not explicitly say when to choose kb_list over kb_search or kb_read, nor does it note exclusion criteria such as searching vs browsing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a knowledge base page, whole or a line range. Paths are relative to content/ or start with content/.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Page path, for example policies/expenses.md or content/policies/expenses.md. | |
| endLine | No | Last line to return, inclusive. Defaults to the end of the page. | |
| startLine | No | First line to return, 1-based. Defaults to 1. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, covering non-destructiveness. The description adds that the tool can return the whole page or a line range and clarifies path resolution, which is useful context. It does not discuss error behavior or output format, but with annotations covering the safety profile, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, front-loaded sentences that state the core purpose and a key path convention without waste. No redundant information; every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool, the description covers the main behavioral aspects: whole-page or partial access and path format. There is no output schema, but the return content is implied by 'Read'. Annotations cover safety, making the description nearly complete for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are well documented. The description's statement about paths relative to content/ and line ranges is already reflected in the schema examples and default descriptions. It adds minimal meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Read') and resource ('knowledge base page'), clearly distinguishing from siblings kb_search, kb_amend, and kb_list. The qualifier 'whole or a line range' adds precision about the scope of the read operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a path convention (relative to content/ or start with content/) that aids invocation, but does not explicitly mention when to use this tool versus alternatives like kb_search or kb_list. The intended use case is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ranked full-text search over every page in the knowledge base. Returns page paths, titles and matching lines with line numbers to cite or open with kb_read.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Most results to return. Defaults to 10. | |
| query | Yes | Words to look for. Pages matching more of them rank higher. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description need not re-cover safety. It adds useful behavior: the scope is 'every page,' results are ranked, and the return shape includes page paths, titles, and matching lines with line numbers. This exceeds the structured annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with no filler. The core action and scope appear first, followed by the return-value summary and the sibling pointer, all in efficient prose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only search tool with full schema coverage and no output schema, this description fully equips an agent to call it correctly, interpret results, and take the obvious next step with kb_read. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents both parameters at 100% coverage, including defaults and ranking behavior. The description adds no parameter-level detail beyond what the schema provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action ('ranked full-text search'), a clear resource ('every page in the knowledge base'), and distinguishes itself from likely alternatives like kb_read and kb_list. An agent can immediately understand what this tool does and how it differs from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the intended downstream action: use the returned line numbers and page paths to cite or open with kb_read. It does not explicitly discuss when not to use the tool versus kb_list or kb_amend, but the search-versus-read contrast is clearly implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0kb_amendkb_listkb_readkb_searchScored across 4 tools
Each tool covers a distinct operation: search, amend (create/edit), read, and list. No two tools could be confused, with search returning matches and read retrieving page content.
All four tools share the kb_ prefix and use a consistent verb_noun pattern: kb_search, kb_amend, kb_read, kb_list. The naming is uniform and predictable.
Four tools is well-scoped for a knowledge base server, covering the core needs without unnecessary bloat. Each tool earns its place.
The surface provides list, read, search, and amend (covering create and edit). Deletion is explicitly not supported, which is an intentional policy rather than a gap. The domain is fully covered.
Team knowledge base for snippets, API calls and docs. Agents search and file items; humans review.
Runnable, versioned lists agents can search, read, create and update. Git under the hood.
Git-backed platform for skills, tools, and context for AI agents
Read and write KukGit repositories, files, issues and pull requests from an AI assistant.
