@dikolab/kbdb 0.5.0 → 0.6.0

package/docs/details/mcp-server.md

@@ -1,482 +0,0 @@
-# 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_DB_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_DB_DIR` Environment Variable
-
-The `--db` flag can be replaced by the `KBDB_DB_DIR`
-environment variable in any configuration:
-
-```json
-{
-   "mcpServers": {
-      "kbdb": {
-         "command": "npx",
-         "args": ["-y", "@dikolab/kbdb", "mcp"],
-         "env": {
-            "KBDB_DB_DIR": "/path/to/.kbdb"
-         }
-      }
-   }
-}
-```
-
-Resolution order: `--db` flag, then `KBDB_DB_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.
-
-### `KBDB_DAEMON_TIMEOUT`
-
-Per-request daemon timeout in milliseconds.
-Defaults to `30000` (30 seconds). Overridden by
-the `--timeout-ms` flag.
-
-### `KBDB_RETRY`
-
-Maximum number of retries with daemon respawn when
-a request times out. Defaults to `1`. Overridden
-by the `--retry` flag.
-
-### `KBDB_LOG_LEVEL`
-
-Log verbosity: `debug`, `info`, `warning`, `error`
-(case-insensitive). Defaults to `error`. Overridden
-by `-v`/`-vv`/`-vvv` flags. The level is forwarded
-to the worker daemon via `--log-level`.
-
-### `KBDB_NON_INTERACTIVE`
-
-Suppress interactive prompts. Accepts `1` or
-`true`. The MCP server does not prompt interactively
-(it reads JSON-RPC from stdin), but the variable is
-inherited by the worker daemon for consistency.
-
-These variables can be set in the `env` block of
-your MCP configuration:
-
-```json
-{
-   "mcpServers": {
-      "kbdb": {
-         "command": "npx",
-         "args": ["-y", "@dikolab/kbdb", "mcp"],
-         "env": {
-            "KBDB_DB_DIR": "/path/to/.kbdb",
-            "KBDB_DAEMON_TIMEOUT": "60000",
-            "KBDB_RETRY": "2",
-            "KBDB_LOG_LEVEL": "warning"
-         }
-      }
-   }
-}
-```
-
-### 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 20 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), `algo` (string: lexical, vector, hybrid), `limit` (number), `offset` (number), `content` (boolean) | Query the knowledge base by keywords. Returns ranked results with heading, snippet, and matched terms. Use `algo` to select search algorithm (default: lexical). | yes | no |
-| `learn` | `content` (string, required), `type` (string), `title` (string), `description` (string), `docid` (string), `tags` (string[]), `replace` (boolean) | Import content into the knowledge base. Use for durable facts, decisions, and corrections. Use `replace` when updating existing knowledge. Attach `tags` for scoping. | 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 |
-| `recall` | `kbid` (string), `kbids` (string[]), `depth` (number) | Retrieve full content and progressive context for sections. Use after `search` to read relevant results. Depth 0-3 controls context expansion. | 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 |
-| `export` | `path` (string) | Export the knowledge base as a self-contained directory snapshot for backup or versioning. Copies sections, documents, and catalog (no indexes). | no | no |
-| `auto-capture-review` | `action` (string: list, approve, reject) | Review and approve pending auto-captured knowledge before storage. | no | no |
-
-### Skills Tools
-
-| Tool | Parameters | Description | Read-only | Destructive |
-|------|-----------|-------------|-----------|-------------|
-| `skill-learn` | `name` (string, required), `description` (string), `body` (string, required) | Create or update a 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), `persona` (string, required), `skills` (string[]) | Create an agent with a persona and optional 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 |
-| `recall` | yes |
-| `rebuild` | no |
-| `export` | yes |
-| `skill-learn` | yes |
-| `skill-list` | yes |
-| `skill-get` | yes |
-| `skill-delete` | yes |
-| `agent-create` | yes |
-| `agent-list` | yes |
-| `agent-get` | yes |
-| `agent-delete` | yes |
-| `auto-capture-review` | 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 20 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.