@dikolab/kbdb 0.1.5 → 0.2.0

package/docs/details/mcp-server.md

@@ -0,0 +1,430 @@
+# MCP Server Guide
+
+The `kbdb mcp` command starts a long-lived MCP
+server that exposes the knowledge base to AI
+agents over stdio using JSON-RPC 2.0.
+
+## Setup
+
+Configure kbdb as an MCP server for your AI agent
+platform. The server requires a database path via
+`--db` or the `KBDB_DIR` environment variable.
+
+### Claude Code (CLI)
+
+Create `.mcp.json` in the project root:
+
+```json
+{
+   "mcpServers": {
+      "kbdb": {
+         "command": "npx",
+         "args": [
+            "-y", "@dikolab/kbdb", "mcp",
+            "--db", "/path/to/.kbdb"
+         ]
+      }
+   }
+}
+```
+
+Deno variant:
+
+```json
+{
+   "mcpServers": {
+      "kbdb": {
+         "command": "deno",
+         "args": [
+            "run", "-A",
+            "jsr:@dikolab/kbdb/cli", "mcp",
+            "--db", "/path/to/.kbdb"
+         ]
+      }
+   }
+}
+```
+
+### Claude for VS Code
+
+Create `.vscode/mcp.json`:
+
+```json
+{
+   "servers": {
+      "kbdb": {
+         "command": "npx",
+         "args": [
+            "-y", "@dikolab/kbdb", "mcp",
+            "--db", "/path/to/.kbdb"
+         ]
+      }
+   }
+}
+```
+
+Deno variant:
+
+```json
+{
+   "servers": {
+      "kbdb": {
+         "command": "deno",
+         "args": [
+            "run", "-A",
+            "jsr:@dikolab/kbdb/cli", "mcp",
+            "--db", "/path/to/.kbdb"
+         ]
+      }
+   }
+}
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+   "mcpServers": {
+      "kbdb": {
+         "command": "npx",
+         "args": [
+            "-y", "@dikolab/kbdb", "mcp",
+            "--db", "/path/to/.kbdb"
+         ]
+      }
+   }
+}
+```
+
+Deno variant:
+
+```json
+{
+   "mcpServers": {
+      "kbdb": {
+         "command": "deno",
+         "args": [
+            "run", "-A",
+            "jsr:@dikolab/kbdb/cli", "mcp",
+            "--db", "/path/to/.kbdb"
+         ]
+      }
+   }
+}
+```
+
+### Other AI Agents
+
+Any MCP-compatible agent can connect via stdio
+transport. Run the server directly:
+
+```sh
+npx @dikolab/kbdb mcp --db /path/to/.kbdb
+```
+
+Or with Deno:
+
+```sh
+deno run -A jsr:@dikolab/kbdb/cli mcp \
+   --db /path/to/.kbdb
+```
+
+### Using `KBDB_DIR` Environment Variable
+
+The `--db` flag can be replaced by the `KBDB_DIR`
+environment variable in any configuration:
+
+```json
+{
+   "mcpServers": {
+      "kbdb": {
+         "command": "npx",
+         "args": ["-y", "@dikolab/kbdb", "mcp"],
+         "env": {
+            "KBDB_DIR": "/path/to/.kbdb"
+         }
+      }
+   }
+}
+```
+
+Resolution order: `--db` flag, then `KBDB_DIR`
+env var. If neither is set, the server exits with
+an error. The server does not fall back to the
+current working directory because the server's cwd
+is determined by the host application, not the
+user.
+
+### Multiple Knowledge Bases
+
+Register multiple server instances pointing to
+different databases:
+
+```json
+{
+   "mcpServers": {
+      "kbdb-docs": {
+         "command": "npx",
+         "args": [
+            "-y", "@dikolab/kbdb", "mcp",
+            "--db", "/home/user/docs/.kbdb"
+         ]
+      },
+      "kbdb-project": {
+         "command": "npx",
+         "args": [
+            "-y", "@dikolab/kbdb", "mcp",
+            "--db", "/home/user/project/.kbdb"
+         ]
+      }
+   }
+}
+```
+
+Each instance runs as a separate process with its
+own worker client connection.
+
+## Tools Reference
+
+The MCP server exposes 17 tools grouped by
+function. All tools communicate with the worker
+daemon via JSON-RPC 2.0 over IPC.
+
+### Knowledge Base Tools
+
+| Tool | Parameters | Description | Read-only | Destructive |
+|------|-----------|-------------|-----------|-------------|
+| `search` | `query` (string, required), `mode` (string), `limit` (number) | Query the knowledge base by keywords. Returns ranked results with kbid, score, and matched terms. | yes | no |
+| `learn` | `content` (string, required), `type` (string), `title` (string), `description` (string), `docid` (string) | Import content into the knowledge base. Extracts keywords and builds indexes. | no | no |
+| `unlearn` | `kbid` (string, required) | Remove a section by kb-id. Cascades deletion to index entries and ranking data. | no | yes |
+| `retrieve` | `kbid` (string), `docid` (string) | Fetch a specific section or document by identifier. At least one of `kbid` or `docid` required. | yes | no |
+| `content` | `ids` (string[], required) | Compose a rendered Markdown document from one or more kbid or docid identifiers. | yes | no |
+| `status` | (none) | Return database status and cache statistics. | yes | no |
+| `check` | (none) | Verify knowledge base integrity. Reports checksum mismatches, orphan sections, broken references. | yes | no |
+| `gc` | (none) | Remove unreferenced sections (no document manifest references). | no | yes |
+| `rebuild` | (none) | Reconstruct all index files from section files and document manifests on disk. | no | no |
+
+### Skills Tools
+
+| Tool | Parameters | Description | Read-only | Destructive |
+|------|-----------|-------------|-----------|-------------|
+| `skill-learn` | `name` (string, required), `description` (string, required), `body` (string, required), `arguments` (array) | Create a new skill definition. Body supports `{{argName}}` template placeholders. | no | no |
+| `skill-list` | (none) | List all skill definitions. Returns array of summaries with kbid, name, description, argumentCount. | yes | no |
+| `skill-get` | `name` (string), `kbid` (string) | Retrieve a single skill by name or kb-id. At least one required; `kbid` takes precedence. | yes | no |
+| `skill-delete` | `kbid` (string, required) | Remove a skill by kb-id. Agent documents referencing this skill will have dangling references. | no | yes |
+
+### Agents Tools
+
+| Tool | Parameters | Description | Read-only | Destructive |
+|------|-----------|-------------|-----------|-------------|
+| `agent-create` | `name` (string, required), `description` (string, required), `persona` (string, required), `skills` (string[], required) | Create an agent document with a persona and ordered skill references. | no | no |
+| `agent-list` | (none) | List all agent documents. Returns array of summaries with docid, name, description, skillCount. | yes | no |
+| `agent-get` | `docid` (string, required) | Retrieve an agent with resolved skill definitions. Deleted skills appear with `name: null`. | yes | no |
+| `agent-delete` | `docid` (string, required) | Remove an agent document. Referenced skill sections are preserved. | no | yes |
+
+### Tool Annotations Summary
+
+| Tool | Idempotent |
+|------|------------|
+| `search` | yes |
+| `learn` | yes |
+| `unlearn` | yes |
+| `retrieve` | yes |
+| `content` | yes |
+| `status` | yes |
+| `check` | yes |
+| `gc` | no |
+| `rebuild` | no |
+| `skill-learn` | yes |
+| `skill-list` | yes |
+| `skill-get` | yes |
+| `skill-delete` | yes |
+| `agent-create` | yes |
+| `agent-list` | yes |
+| `agent-get` | yes |
+| `agent-delete` | yes |
+
+## Prompts
+
+The MCP server exposes knowledge base content as
+discoverable prompts via `prompts/list` and
+`prompts/get`.
+
+### Skills as Prompts
+
+Each skill stored in the database appears as an
+MCP prompt. The skill's `{{argName}}` template
+placeholders become prompt arguments. When an
+agent calls `prompts/get` with argument values,
+the server renders the template with substitutions
+and returns it as a user message.
+
+```json
+{
+   "name": "summarize-document",
+   "description": "Summarize a document into key points",
+   "arguments": [
+      {
+         "name": "docid",
+         "description": "Document identifier",
+         "required": true
+      },
+      {
+         "name": "max_points",
+         "description": "Max bullet points",
+         "required": false
+      }
+   ]
+}
+```
+
+### Agents as Prompts
+
+Each agent appears as a prompt with an `agent:`
+name prefix. Agent prompts have no arguments.
+When rendered, they produce two messages:
+
+1. An assistant message containing the agent's
+   persona text.
+2. A user message listing the agent's available
+   skills.
+
+```json
+{
+   "name": "agent:code-reviewer",
+   "description": "Reviews code for bugs, style, and best practices",
+   "arguments": []
+}
+```
+
+## Resources
+
+Resources provide direct access to knowledge base
+contents by URI, without going through search.
+
+### URI Templates
+
+The server exposes parameterised URI templates
+via `resources/templates/list`:
+
+| URI Template | MIME Type | Description |
+|-------------|----------|-------------|
+| `kbdb://section/{kbid}` | `text/plain` | Raw content of a single section by kb-id. For image sections, returns base64-encoded content with the image MIME type. |
+| `kbdb://document/{docid}` | `application/json` | Document manifest and all sections, ordered by position. |
+
+### Static Resources
+
+The `resources/list` endpoint returns an empty
+list. All resources are accessed through URI
+templates.
+
+### Reading Resources
+
+Use `resources/read` with an expanded URI:
+
+- `kbdb://section/abcdef1234567890abcdef1234` --
+  returns the section content.
+- `kbdb://document/agent-code-reviewer` --
+  returns the document with all sections.
+
+## Protocol Features
+
+The kbdb MCP server implements Model Context
+Protocol version **2025-11-25** and advertises the
+following capabilities:
+
+- **tools** -- `tools/list` and `tools/call` for
+  all 17 tools.
+- **resources** -- `resources/list`,
+  `resources/read`, and
+  `resources/templates/list` for URI-based content
+  access.
+- **prompts** -- `prompts/list` and `prompts/get`
+  for skill and agent prompt discovery.
+- **completions** -- `completion/complete` for
+  autocomplete on prompt names and resource URIs.
+- **logging** -- `logging/setLevel` to control
+  server-to-client log notification verbosity.
+  Levels: `debug`, `info`, `notice`, `warning`,
+  `error`, `critical`, `alert`, `emergency`.
+- **roots** -- `roots/list` returns the `.kbdb`
+  database directory as the single filesystem root.
+- **subscriptions** -- `resources/subscribe` and
+  `resources/unsubscribe` for change notifications
+  on individual resources.
+- **sampling** -- `sampling/createMessage` allows
+  the server to request text generation from the
+  host's language model.
+
+## Error Handling
+
+### Protocol Errors
+
+Standard JSON-RPC 2.0 error codes for protocol
+violations:
+
+| Code | Meaning |
+|------|---------|
+| `-32700` | Parse error (malformed JSON) |
+| `-32601` | Method not found |
+| `-32602` | Invalid params |
+| `-32603` | Internal error |
+| `-32002` | Resource not found (MCP-specific) |
+
+### Tool Execution Errors
+
+Tool-level failures are returned as successful
+JSON-RPC responses with `isError: true` in the
+result:
+
+```json
+{
+   "content": [
+      {
+         "type": "text",
+         "text": "Section not found: abc123"
+      }
+   ],
+   "isError": true
+}
+```
+
+Successful tool results are wrapped as:
+
+```json
+{
+   "content": [
+      {
+         "type": "text",
+         "text": "<JSON result>"
+      }
+   ]
+}
+```
+
+## Transport
+
+The MCP server uses stdio transport:
+
+- Reads JSON-RPC 2.0 requests from **stdin**.
+- Writes JSON-RPC 2.0 responses to **stdout**.
+- Diagnostic messages go to **stderr**.
+
+The host application spawns `kbdb mcp` as a child
+process and communicates over its stdin/stdout
+streams. Each JSON-RPC message is serialised as a
+single line of JSON terminated by `\n`.
+
+## Lifecycle
+
+1. Host sends `initialize` with its capabilities.
+   Server responds with its identity and supported
+   capability groups.
+2. Host sends `notifications/initialized` to
+   confirm the handshake. Server begins accepting
+   tool and resource requests.
+3. Either party can send `ping` to check liveness.
+4. When the host closes stdin, the server
+   disconnects from the worker daemon and exits.