@dikolab/kbdb 0.4.3 → 0.6.0

package/docs/goals/mcp.md

@@ -1,1541 +0,0 @@
-# MCP -- Model Context Protocol Server
-
-*An MCP server mode that exposes the knowledge base
-to AI agents -- search, retrieve, and manage knowledge
-programmatically over the Model Context Protocol.*
-
-## Goal
-
-When invoked as `kbdb mcp`, the executable starts as a
-long-lived MCP server. It communicates with the AI
-agent host over **stdio** using **JSON-RPC 2.0** and
-delegates all knowledge base operations to the worker
-daemon via the worker client module (see
-[Worker Client](worker-client.md)).
-
-The MCP server exposes the knowledge base's search,
-retrieval, and content management capabilities as MCP
-tools and resources. AI agents -- Claude, LangChain
-agents, custom harnesses, or any MCP-compatible
-client -- interact with the knowledge base through
-these primitives.
-
-The MCP server has no knowledge of which AI agent is
-connected. It serves any MCP-compatible client
-identically.
-
-## Invocation
-
-```
-kbdb mcp [--db <path>] [--timeout-ms <ms>]
-   [--retry <n>] [--non-interactive]
-```
-
-All flags are optional. `--db` specifies the path
-to the `.kbdb` database directory. If omitted, the
-server reads the `KBDB_DB_DIR` environment variable,
-then falls back to the current working directory.
-
-Resolution order:
-
-1. `--db <path>` command-line flag.
-2. `KBDB_DB_DIR` environment variable.
-3. Current working directory.
-
-### Environment Variables
-
-| Variable              | Description             |
-|-----------------------|-------------------------|
-| `KBDB_DB_DIR`         | Fallback database directory when `--db` is not specified |
-| `KBDB_DAEMON_TIMEOUT` | Request timeout fallback (ms); default 30 000 |
-| `KBDB_RETRY`          | Retry count fallback; default 5 |
-| `KBDB_LOG_LEVEL`      | Log verbosity: `debug`, `info`, `warning`, `error` |
-| `KBDB_NON_INTERACTIVE`| Suppress prompts (`1` or `true`) |
-
-See [CLI -- Run Modes](cli.md#run-modes) for how
-the `kbdb` executable dispatches to MCP mode.
-
-## Startup Health Check
-
-When the MCP server starts, it runs
-`client.integrityCheck()` automatically after the
-worker daemon connection is established. If the
-check returns `ok: false`, the server emits a
-`notifications/message` log with level `warning`
-listing the error summary. The server continues to
-operate -- health issues are not fatal. This ensures
-corruption surfaces before it produces wrong answers.
-
-## Installation and Wiring
-
-Installation is the same as the CLI:
-
-- **Node.js**: `npm install -g @dikolab/kbdb`
-- **Deno**: `deno install` or `deno add @dikolab/kbdb`
-  (via [jsr.io](https://jsr.io))
-
-To wire the MCP server to an AI agent, add a server
-entry to the agent host's MCP configuration.
-
-### Claude Desktop
-
-Add to `claude_desktop_config.json`:
-
-```json
-{
-   "mcpServers": {
-      "kbdb": {
-         "command": "npx",
-         "args": [
-            "@dikolab/kbdb", "mcp",
-            "--db", "/path/to/.kbdb"
-         ]
-      }
-   }
-}
-```
-
-### Claude Code
-
-Add to `.claude/settings.json` or project settings:
-
-```json
-{
-   "mcpServers": {
-      "kbdb": {
-         "command": "npx",
-         "args": [
-            "@dikolab/kbdb", "mcp",
-            "--db", "/path/to/.kbdb"
-         ]
-      }
-   }
-}
-```
-
-### Deno
-
-```json
-{
-   "mcpServers": {
-      "kbdb": {
-         "command": "deno",
-         "args": [
-            "run", "--allow-all",
-            "jsr:@dikolab/kbdb", "mcp",
-            "--db", "/path/to/.kbdb"
-         ]
-      }
-   }
-}
-```
-
-### Environment Variable
-
-The `--db` flag can be replaced by `KBDB_DB_DIR`:
-
-```json
-{
-   "mcpServers": {
-      "kbdb": {
-         "command": "npx",
-         "args": ["@dikolab/kbdb", "mcp"],
-         "env": {
-            "KBDB_DB_DIR": "/path/to/.kbdb"
-         }
-      }
-   }
-}
-```
-
-### Multiple Knowledge Bases
-
-Register multiple server instances pointing to
-different databases:
-
-```json
-{
-   "mcpServers": {
-      "kbdb-docs": {
-         "command": "npx",
-         "args": [
-            "@dikolab/kbdb", "mcp",
-            "--db", "/home/user/docs/.kbdb"
-         ]
-      },
-      "kbdb-project": {
-         "command": "npx",
-         "args": [
-            "@dikolab/kbdb", "mcp",
-            "--db", "/home/user/project/.kbdb"
-         ]
-      }
-   }
-}
-```
-
-Each registration spawns a separate `kbdb mcp`
-process with its own worker client connection. The
-worker daemon disambiguates by context ID (SHA-256
-of the database path), so multiple MCP instances
-hitting different databases work without conflict.
-
-## 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 AI agent host (Claude Desktop, Claude Code, or
-any MCP-compatible client) spawns `kbdb mcp` as a
-child process and communicates over its stdin/stdout
-streams.
-
-## Protocol
-
-The MCP server implements the **Model Context Protocol
-version 2025-11-25** over **JSON-RPC 2.0**. This is
-the same wire format the worker daemon uses for IPC
-(see [Worker Daemon](worker-daemon.md)), but with
-MCP-defined method names and semantics.
-
-Every MCP-compatible AI agent host -- Claude Desktop,
-Claude Code, Cursor, Windsurf, or any custom harness
--- uses this same protocol. The server has no knowledge
-of which host is connected.
-
-### Lifecycle
-
-Three methods form the mandatory startup handshake.
-Nothing else may be called before `initialize`
-completes.
-
-#### 1. `initialize` (request)
-
-The host sends its identity and supported capabilities.
-The server responds with its own identity, the
-protocol version it speaks, and which capability
-groups it supports.
-
-**Host request:**
-
-```json
-{
-   "jsonrpc": "2.0",
-   "id": 1,
-   "method": "initialize",
-   "params": {
-      "protocolVersion": "2025-11-25",
-      "capabilities": {},
-      "clientInfo": {
-         "name": "ExampleHost",
-         "version": "1.0.0"
-      }
-   }
-}
-```
-
-**Server response:**
-
-```json
-{
-   "jsonrpc": "2.0",
-   "id": 1,
-   "result": {
-      "protocolVersion": "2025-11-25",
-      "serverInfo": {
-         "name": "kbdb",
-         "version": "0.1.0"
-      },
-      "capabilities": {
-         "tools": {},
-         "resources": {}
-      }
-   }
-}
-```
-
-**Version negotiation:** the host sends the latest
-version it supports. If the server supports it, it
-responds with the same version. Otherwise, the server
-responds with another version it supports. If the
-host does not support the server's version, it should
-disconnect.
-
-#### 2. `notifications/initialized` (notification)
-
-The host sends this notification (no `id`, no
-response) to confirm that the handshake is complete.
-The server flips its internal ready state and begins
-accepting tool and resource requests.
-
-```json
-{
-   "jsonrpc": "2.0",
-   "method": "notifications/initialized"
-}
-```
-
-#### 3. `ping` (request)
-
-Either party can send a `ping` to check liveness.
-The receiver must respond promptly with an empty
-result.
-
-```json
-{
-   "jsonrpc": "2.0",
-   "id": 99,
-   "method": "ping"
-}
-```
-
-Response:
-
-```json
-{
-   "jsonrpc": "2.0",
-   "id": 99,
-   "result": {}
-}
-```
-
-### Capability Negotiation
-
-The `capabilities` object in the `initialize` response
-tells the host which method groups the server supports.
-The host must not call methods for capabilities the
-server did not advertise.
-
-kbdb advertises:
-
-```json
-{
-   "tools": {},
-   "resources": {},
-   "prompts": {},
-   "logging": {},
-   "completions": {}
-}
-```
-
-This means the host can call `tools/list`,
-`tools/call`, `resources/list`, `resources/read`,
-`resources/templates/list`, `prompts/list`,
-`prompts/get`, `logging/setLevel`, and
-`completion/complete`.
-
-Optional capability flags:
-
-| Flag | Meaning |
-|------|---------|
-| `tools.listChanged` | Server emits `notifications/tools/list_changed` |
-| `resources.listChanged` | Server emits `notifications/resources/list_changed` |
-| `resources.subscribe` | Client can subscribe to resource changes |
-| `prompts` | Server supports `prompts/list` and `prompts/get` |
-| `logging` | Server supports `logging/setLevel` and emits log notifications |
-| `completions` | Server supports `completion/complete` |
-
-## MCP Tools
-
-Tools are callable actions that the AI agent invokes.
-Each tool sends a JSON-RPC 2.0 request to the worker
-daemon via the worker client.
-
-### search
-
-Search the knowledge base. Returns ranked results
-with headings and snippets for relevance evaluation.
-Use multiple short keyword queries for best coverage.
-Use `recall` to get full content of specific results.
-
-**Parameters:**
-
-| Name      | Type    | Required | Description                |
-|-----------|---------|----------|----------------------------|
-| `query`   | string  | yes      | Search query text          |
-| `mode`    | string  | no       | `"sections"` (default), `"documents"`, or `"stats"` |
-| `limit`   | number  | no       | Max results (default: 20)  |
-| `offset`  | number  | no       | Zero-based result offset (default: 0) |
-| `content` | boolean | no       | When `true`, include full section text in each result (default: `false`) |
-
-**Returns:** Paged JSON envelope containing ranked
-results. Each result includes contextual metadata
-the AI agent needs to judge relevance without
-additional calls:
-
-```json
-{
-   "items": [
-      {
-         "kbid": "a1b2c3d4e5f6g7h8j9k0l1m2n3",
-         "heading": "Architecture Overview",
-         "type": "text/markdown",
-         "docids": ["doc-5678"],
-         "snippet": "The system is organized...",
-         "matched_terms": ["architecture", "system"],
-         "matched_fields": ["heading", "body"],
-         "created_at": "2026-06-20T14:30:00Z"
-      }
-   ],
-   "total": 42,
-   "offset": 0,
-   "limit": 20,
-   "has_more": true,
-   "relaxed": false
-}
-```
-
-- `heading` -- the section's title text, or `null`
-  when the section has no title.
-- `type` -- section MIME type (e.g.
-  `"text/markdown"`, `"text/typescript"`).
-- `docids` -- document identifiers this section
-  belongs to (may be empty for standalone sections).
-- `snippet` -- KWIC (keyword-in-context) excerpt,
-  ~150 characters centered on the highest-scoring
-  matched term. Empty string for image sections.
-- `matched_terms` -- query terms that matched, as a
-  flat `string[]`. No frequency counts.
-- `matched_fields` -- subset of `["heading", "body",
-  "code"]` indicating which fields contained matches.
-- `created_at` -- ISO 8601 timestamp of when the
-  section was first indexed.
-- `relaxed` -- `true` when the result came from an
-  automatic AND-to-OR fallback (see
-  [Query Result -- Relaxed-Match
-  Fallback](query-result.md)). `false` for normal
-  results.
-
-When `content` is `true`, each item also includes
-a `content` field with the full section text.
-
-Results are ordered by relevance (highest first).
-The ordering itself carries the ranking signal --
-no numeric score is exposed.
-
-Result is serialised with 2-space indentation.
-
-Maps to `client.search()`.
-
-### learn
-
-Import content into the knowledge base. Use for
-durable facts, decisions, and corrections. Use
-`--replace` when updating existing knowledge. Attach
-tags for scoping. The daemon decomposes the content
-into sections, extracts keywords, builds indexes,
-and assigns ranking weights.
-
-**Parameters:**
-
-| Name          | Type   | Required | Description      |
-|---------------|--------|----------|------------------|
-| `content`     | string   | yes      | Text content or base64-encoded image data |
-| `type`        | string   | no       | `"text/markdown"` (default), `text/*` MIME type, `"application/json"`, or `image/*` MIME type |
-| `title`       | string   | no*      | Section title. ***Required** for `image/*` types.* Optional for text and code types. |
-| `description` | string   | no       | Optional section description |
-| `docid`       | string   | no       | Group under this document ID |
-| `tags`        | string[] | no       | Tags for scoping and filtering |
-| `replace`     | boolean  | no       | Enable supersession by source key. When `true` and a section with the same source key exists, the old section is replaced. |
-
-**Content type rules:**
-
-1. **`type` is `text/*` or omitted** (default
-   `text/markdown`) -- `title` and `description` are
-   optional. `content` is the raw text.
-2. **`type` is `image/*`** -- **`title` is required.**
-   `content` must be base64-encoded binary image data.
-   Omitting `title` returns a tool error
-   (`isError: true`). `description` is optional.
-3. **`description`** -- always optional for all types.
-
-Text and code content is preprocessed (BOM removal,
-line ending normalization, Unicode NFC, whitespace
-trimming) before the kbid hash is computed. Image
-content is stored verbatim. See
-[Database -- Content Preprocessing](database.md)
-for the full pipeline.
-
-For code sections (`text/*` or `application/json`),
-`content` is the raw source text. For image sections
-(`image/*`), `content` is the base64-encoded binary
-image data. See
-[Database -- Section Types](database.md).
-
-**Returns:** JSON (compact, no indentation) with the
-new section's `AddSectionResult` from the daemon.
-Fields include the assigned kbid, content type, title
-(if provided), description (if provided), indexed
-term count, elapsed time, and an `attached` flag.
-Text and code sections return a positive
-`indexed_terms_count`. Image sections return
-`indexed_terms_count: 0`.
-
-Additional result fields when applicable:
-- `superseded` -- kbid of the section this one
-  replaced via `replace: true`, or `null`.
-- `warnings` -- string array of advisory warnings
-  (e.g. `"heading_missing"` when a text section has
-  no title).
-- `near_duplicates` -- array of
-  `{ kbid, similarity }` objects for existing
-  sections with Jaccard similarity >= 0.85.
-
-If the content already exists in the database (same
-kb-id) and `docid` is provided, the section is not
-duplicated. Instead, the docid is added to the
-existing section's `docids` list. The result reports
-`attached: true` and `indexed_terms_count: 0` (no
-re-indexing). If no `docid` is provided and the
-content already exists, the section is skipped. If
-the docid is already in the section's `docids` array,
-the operation is idempotent: `attached: false`.
-
-Maps to `client.addSection()`. Internally maps the
-`type` tool parameter to the `sectionType` field
-expected by `McpWorkerClient.addSection()`.
-
-### unlearn
-
-Remove content from the knowledge base by kb-id.
-Cascades deletion to associated index entries and
-ranking data.
-
-**Parameters:**
-
-| Name    | Type   | Required | Description       |
-|---------|--------|----------|-------------------|
-| `kbid` | string | yes      | KB ID of section to remove |
-
-**Returns:** Compact JSON `{ "removed": bool,
-"elapsed_ms": number }` where `removed` is `true`
-when the section was found and removed.
-
-Maps to `client.removeSection()`.
-
-### retrieve
-
-Low-level fetch of a section or document by
-identifier. For AI agent workflows, prefer `recall`
-which includes metadata, context, and
-back-references.
-
-**Parameters:**
-
-| Name    | Type   | Required | Description      |
-|---------|--------|----------|------------------|
-| `kbid` | string | no       | KB ID of section |
-| `docid` | string | no       | Document ID      |
-
-Neither field is marked required in the schema, but
-at least one must be provided. Omitting both returns
-`isError: true` with the message `Provide kbid or
-docid`.
-
-When `kbid` is provided, maps to
-`client.readSections([kbid])` and returns a JSON
-array of section objects: `[{ kbid, sectionType,
-content, size }]`. When `docid` is provided, maps to
-`client.retrieveDocument(docid)` and returns the raw
-document record from the daemon.
-
-Maps to `client.readSections()` or
-`client.retrieveDocument()`.
-
-### recall
-
-Retrieve full content and context for one or more
-sections by identifier. Use after `search` to read
-relevant results. Returns section text, metadata,
-references, and back-references.
-
-**Parameters:**
-
-| Name    | Type     | Required | Description              |
-|---------|----------|----------|--------------------------|
-| `kbid`  | string   | no*      | Single section identifier |
-| `kbids` | string[] | no*      | Batch section identifiers |
-| `depth` | number   | no       | Expansion depth (0--3, default: 0) |
-
-*At least one of `kbid` or `kbids` is required.
-Omitting both returns `isError: true`. When both
-are provided, `kbids` takes precedence and `kbid`
-is appended to the list.
-
-**Expansion levels:**
-
-| Depth | Returns                               |
-|-------|---------------------------------------|
-| 0     | Full section content with heading,    |
-|       | type, and docids.                     |
-| 1     | Depth-0 content, plus parent document |
-|       | manifests (title, all section kbids   |
-|       | with headings and types) for each     |
-|       | docid, plus back-references (sections |
-|       | that reference this section, from the |
-|       | reference graph index, each with      |
-|       | marker_type and context_snippet).     |
-| 2     | Depth-1 content, plus full text of    |
-|       | sibling sections (other sections in   |
-|       | the same documents), plus forward     |
-|       | references from the section's own     |
-|       | content markers.                      |
-| 3     | Depth-2 content, plus full text of    |
-|       | referenced sections (one level deep), |
-|       | plus their back-references.           |
-
-Depth values above 3 are clamped to 3.
-
-**Single result shape (depth 0):**
-
-```json
-{
-   "kbid": "a1b2c3d4e5f6g7h8j9k0l1m2n3",
-   "heading": "Architecture Overview",
-   "type": "text/markdown",
-   "content": "Full section text...",
-   "docids": ["doc-5678"]
-}
-```
-
-**Single result shape (depth 1+):**
-
-```json
-{
-   "kbid": "a1b2c3d4e5f6g7h8j9k0l1m2n3",
-   "heading": "Architecture Overview",
-   "type": "text/markdown",
-   "content": "Full section text...",
-   "docids": ["doc-5678"],
-   "documents": [
-      {
-         "docid": "doc-5678",
-         "title": "System Architecture",
-         "sections": [
-            {
-               "kbid": "...",
-               "heading": "...",
-               "type": "..."
-            }
-         ]
-      }
-   ],
-   "back_references": [
-      {
-         "kbid": "ref-section-kbid",
-         "heading": "Related Section",
-         "type": "text/markdown",
-         "marker_type": "link",
-         "context_snippet": "For details, see ...",
-         "direction": "back"
-      }
-   ],
-   "siblings": [ ... ],
-   "references": [ ... ]
-}
-```
-
-Fields beyond `content` and `docids` are present
-only at the corresponding depth level. At depth 0,
-`documents`, `back_references`, `siblings`, and
-`references` are absent. At depth 1, `siblings`
-and `references` are absent. And so on.
-
-When batch `kbids` is used, the response is a JSON
-array of result objects (one per kbid). The depth
-parameter applies to all sections in the batch.
-
-Maps to `client.recall()`.
-
-### content
-
-Compose a rendered Markdown document from one or
-more kbid or docid identifiers.
-
-**Parameters:**
-
-| Name  | Type     | Required | Description       |
-|-------|----------|----------|-------------------|
-| `ids` | string[] | yes      | One or more kbid or docid identifiers (mixed) |
-
-**Returns:** Tool result with text content containing
-JSON: `{ "type": "text/markdown", "data": "...",
-"total": <char count> }`. The `total` field is the
-character count of `data` (not byte count).
-
-Maps to `client.content()`.
-
-See [Content Composer](content-composer.md) for the
-full composition specification.
-
-### status
-
-Return database status and cache statistics.
-
-**Parameters:** None.
-
-**Returns:** JSON with the following fields:
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `initialized` | boolean | Whether the daemon has finished loading its WASM modules |
-| `contextPath` | string | Absolute path to the database directory the daemon serves |
-| `cacheStats.contentCount` | number | Number of content entries currently in the in-memory cache |
-| `cacheStats.indexCount` | number | Number of index entries currently in the in-memory cache |
-
-Maps to `client.dbStatus()`.
-
-### check
-
-Verify the integrity of the knowledge base. Reports
-checksum mismatches, orphan sections and documents,
-broken marker references, type mismatches, and
-circular reference chains.
-
-**Parameters:** None.
-
-**Returns:** JSON with `ok` boolean, `errors` array
-(each with `type`, `entity`, `detail`),
-`sections_checked`, `documents_checked`,
-`references_checked`, and `elapsed_ms`. When all
-checks pass, `ok` is `true` and `errors` is empty.
-
-Error types: `checksum_mismatch`, `orphan_section`,
-`orphan_document`, `broken_reference`,
-`type_mismatch`, `circular_reference`,
-`divergent_content`. The `divergent_content` error
-flags sections sharing the same `source_key` that
-have different content -- indicates contradictory
-versions that should be resolved via supersession.
-See [Database -- Integrity and
-Maintenance](database.md).
-
-Maps to `client.integrityCheck()`.
-
-### gc
-
-Remove unreferenced sections from the knowledge
-base. A section is eligible for removal when no
-document manifest references it.
-
-**Parameters:** None.
-
-**Returns:** JSON with `removed_sections` (count),
-`removed_bytes`, and `elapsed_ms`. When no sections
-are eligible, counts are `0`.
-
-Maps to `client.gc()`.
-
-### rebuild
-
-Reconstruct all index files from section files and
-document manifests on disk. Text and code sections
-are re-tokenized; image sections are skipped. Use
-this to recover from index corruption.
-
-**Parameters:** None.
-
-**Returns:** JSON with `sections_reindexed`,
-`terms_indexed`, and `elapsed_ms`.
-
-Maps to `client.rebuildIndexes()`.
-
-### export
-
-Export the knowledge base as a self-contained
-directory snapshot for backup or versioning. Copies
-sections, documents, and catalog (no indexes -- they
-are rebuildable via `rebuild`).
-
-**Parameters:**
-
-| Name   | Type   | Required | Description               |
-|--------|--------|----------|---------------------------|
-| `path` | string | no       | Export destination path (default: `./kbdb-export/`) |
-
-**Returns:** Compact JSON with export summary:
-
-```json
-{
-   "path": "/home/user/kbdb-export",
-   "sections_exported": 142,
-   "documents_exported": 23,
-   "elapsed_ms": 350
-}
-```
-
-Maps to `client.export()`.
-
-### skill-learn
-
-Create a new skill definition and store it in the
-knowledge base as a section with `sectionType:
-'skill'`.
-
-**Parameters:**
-
-| Name          | Type   | Required | Description                              |
-|---------------|--------|----------|------------------------------------------|
-| `name`        | string | yes      | Skill name (kebab-case identifier)       |
-| `description` | string | yes      | What the skill does                      |
-| `arguments`   | array  | no       | Prompt argument definitions              |
-| `body`        | string | yes      | Template body with `{{argName}}` placeholders |
-
-**Returns:** Compact JSON `AddSectionResult` with the
-assigned `kbid`, `name`, and auto-detected `arguments`
-array extracted from `{{...}}` placeholders in `body`.
-
-Maps to `client.addSection()` with
-`sectionType: 'skill'`.
-
-### skill-list
-
-List all skill definitions stored in the knowledge
-base.
-
-**Parameters:** None.
-
-**Returns:** JSON array of skill summary objects:
-`[{ kbid, name, description, argumentCount }]`.
-Result is serialised with 2-space indentation.
-
-Maps to `client.listByType('skill')`.
-
-### skill-get
-
-Retrieve a single skill definition by name or kb-id.
-
-**Parameters:**
-
-| Name   | Type   | Required | Description                         |
-|--------|--------|----------|-------------------------------------|
-| `name` | string | no*      | Skill name to look up               |
-| `kbid` | string | no*      | Skill kb-id to look up              |
-
-*At least one of `name` or `kbid` is required.
-Omitting both returns `isError: true`. When both are
-provided, `kbid` takes precedence.
-
-**Returns:** Full `SkillDefinition` JSON with `kbid`,
-`name`, `description`, `arguments`, and `body`.
-Result is serialised with 2-space indentation.
-
-Maps to `client.readSections([kbid])` (by kbid) or
-`client.listByType('skill')` filtered by name (by
-name).
-
-### skill-delete
-
-Remove a skill definition by kb-id. The skill section
-is removed from the database. Agent documents that
-reference this kbid will have a dangling reference.
-
-**Parameters:**
-
-| Name   | Type   | Required | Description           |
-|--------|--------|----------|-----------------------|
-| `kbid` | string | yes      | Skill kb-id to remove |
-
-**Returns:** Compact JSON `{ "kbid": "...",
-"removed": true }`.
-
-Maps to `client.removeSection()`.
-
-### agent-create
-
-Create a new agent document in the knowledge base.
-An agent is a document with `type: 'agent'` that
-holds a persona and an ordered list of skill kbid
-references.
-
-**Parameters:**
-
-| Name          | Type     | Required | Description                          |
-|---------------|----------|----------|--------------------------------------|
-| `name`        | string   | yes      | Agent name (kebab-case identifier)   |
-| `description` | string   | yes      | What the agent does                  |
-| `persona`     | string   | yes      | System prompt text for the agent     |
-| `skills`      | string[] | yes      | Ordered skill kbid list              |
-
-**Returns:** Compact JSON `{ "docid": "agent-...",
-"name": "...", "skills": [...] }`.
-
-Maps to `client.groupSections()` with
-`type: 'agent'` and `[agent]` metadata.
-
-### agent-list
-
-List all agent documents in the knowledge base.
-
-**Parameters:** None.
-
-**Returns:** JSON array of agent summary objects:
-`[{ docid, name, description, skillCount }]`.
-Result is serialised with 2-space indentation.
-
-Maps to `client.listDocumentsByType('agent')`.
-
-### agent-get
-
-Retrieve a single agent document with its resolved
-skill definitions.
-
-**Parameters:**
-
-| Name    | Type   | Required | Description              |
-|---------|--------|----------|--------------------------|
-| `docid` | string | yes      | Agent document ID        |
-
-**Returns:** Full `AgentDefinition` JSON with `docid`,
-`name`, `description`, `persona`, and `skills` array.
-Each skill entry includes `kbid`, `name`, and
-`position`. If a referenced skill has been deleted,
-its `name` is `null`. Result is serialised with
-2-space indentation.
-
-Maps to `client.retrieveDocument(docid)` followed by
-`client.readSections(kbids)` for skill resolution.
-
-### agent-delete
-
-Remove an agent document. Only the document manifest
-is deleted; the referenced skill sections remain.
-
-**Parameters:**
-
-| Name    | Type   | Required | Description              |
-|---------|--------|----------|--------------------------|
-| `docid` | string | yes      | Agent document ID        |
-
-**Returns:** Compact JSON `{ "docid": "...",
-"removed": true }`.
-
-Maps to `client.removeGrouping()`.
-
-## MCP Resources
-
-Resources are data items the AI agent can read by
-URI. They provide direct access to knowledge base
-contents without going through search.
-
-The MCP `2025-11-25` spec distinguishes two listing
-methods:
-
-### `resources/list` -- Static Resources
-
-Returns resources with concrete URIs. kbdb has no
-static resources, so this returns an empty list:
-
-```json
-{ "resources": [] }
-```
-
-### `resources/templates/list` -- URI Templates
-
-Returns parameterized URI templates (RFC 6570) that
-the client can expand with arguments. kbdb exposes
-two templates:
-
-| URI Template | MIME Type | Description |
-|-------------|----------|-------------|
-| `kbdb://section/{kbid}` | `text/plain` | Section by kb-id |
-| `kbdb://document/{docid}` | `application/json` | Document + sections |
-
-### `resources/read` -- Fetch Resource
-
-**URI:** `kbdb://section/{kbid}`
-
-Returns the content of a single section identified
-by kb-id. For text sections, returns the raw text
-content. For code sections (`text/*` or
-`application/json`), returns the raw source text
-with the MIME type. For image sections (`image/*`
-type), returns the base64-encoded content with the
-MIME type.
-
-**URI:** `kbdb://document/{docid}`
-
-Returns a document and all its sections. Sections
-are ordered by position within the document.
-
-## MCP Prompts
-
-Prompts are reusable templates that the AI agent host
-can discover and render. kbdb exposes two categories
-of prompts: **skills** (stored as sections with
-`sectionType: 'skill'`) and **agents** (stored as
-documents with `type: 'agent'`, identified by an
-`agent:` name prefix).
-
-### prompts/list
-
-Returns all available prompts. Skills appear as
-`McpPrompt` objects; agents appear with the `agent:`
-name prefix and no arguments.
-
-**Request:**
-
-```json
-{
-   "jsonrpc": "2.0",
-   "id": 1,
-   "method": "prompts/list"
-}
-```
-
-**Response:**
-
-```json
-{
-   "jsonrpc": "2.0",
-   "id": 1,
-   "result": {
-      "prompts": [
-         {
-            "name": "summarize-document",
-            "description": "Summarize a document into
-               key points with configurable depth",
-            "arguments": [
-               {
-                  "name": "docid",
-                  "description": "Document identifier",
-                  "required": true
-               },
-               {
-                  "name": "max_points",
-                  "description": "Max bullet points",
-                  "required": false
-               }
-            ]
-         },
-         {
-            "name": "agent:code-reviewer",
-            "description": "Reviews code for bugs,
-               style, and best practices",
-            "arguments": []
-         }
-      ]
-   }
-}
-```
-
-Maps to `client.listByType('skill')` and
-`client.listDocumentsByType('agent')`.
-
-### prompts/get
-
-Retrieves a single prompt rendered with the given
-argument values.
-
-**Request params:**
-
-| Parameter   | Type   | Required | Description              |
-|-------------|--------|----------|--------------------------|
-| `name`      | string | yes      | Prompt name              |
-| `arguments` | object | no       | Key-value argument map   |
-
-**Response for a skill prompt** (single user message
-with the rendered template body):
-
-```json
-{
-   "jsonrpc": "2.0",
-   "id": 2,
-   "result": {
-      "messages": [
-         {
-            "role": "user",
-            "content": {
-               "type": "text",
-               "text": "Summarize the document
-                  identified by DOC-001.\nExtract
-                  at most 5 key points.\nReturn as
-                  a bulleted markdown list."
-            }
-         }
-      ]
-   }
-}
-```
-
-**Response for an agent prompt** (assistant message
-with persona, then user message with skill listing):
-
-```json
-{
-   "jsonrpc": "2.0",
-   "id": 3,
-   "result": {
-      "messages": [
-         {
-            "role": "assistant",
-            "content": {
-               "type": "text",
-               "text": "You are an expert code
-                  reviewer. You focus on
-                  correctness, readability, and
-                  maintainability."
-            }
-         },
-         {
-            "role": "user",
-            "content": {
-               "type": "text",
-               "text": "Available skills:\n- summarize-document: Summarize a document...\n- review-diff: Review a code diff..."
-            }
-         }
-      ]
-   }
-}
-```
-
-Maps to `client.readSections([kbid])` (skill) or
-`client.retrieveDocument(docid)` with
-`client.readSections(skillKbids)` (agent).
-
-### Prompt Discovery Flow
-
-How an AI agent discovers and invokes a skill using
-the prompt protocol:
-
-1. Agent calls `prompts/list` to enumerate all
-   available prompts (skills and agents).
-2. Agent selects a prompt by name based on its
-   description and argument list.
-3. Agent calls `prompts/get` with the prompt name
-   and a key-value map of argument values.
-4. Agent receives one or more rendered
-   `McpPromptMessage` objects with the substituted
-   template text.
-5. Agent uses the rendered message(s) in its
-   workflow (as a system prompt, user turn, or
-   context injection).
-
-## Tool Annotations
-
-Tool annotations provide hints to the MCP host about
-the nature of each tool. The `McpToolAnnotations`
-type adds metadata to the tool definition:
-
-```typescript
-interface McpToolAnnotations {
-   readonly title?: string;
-   readonly readOnlyHint?: boolean;
-   readonly destructiveHint?: boolean;
-   readonly idempotentHint?: boolean;
-   readonly openWorldHint?: boolean;
-}
-```
-
-Annotations for all 20 kbdb tools:
-
-| Tool           | title             | readOnly | destructive | idempotent | openWorld |
-|----------------|-------------------|----------|-------------|------------|-----------|
-| `search`       | Search KB         | true     | false       | true       | false     |
-| `learn`        | Import Content    | false    | false       | true       | false     |
-| `unlearn`      | Remove Section    | false    | true        | true       | false     |
-| `retrieve`     | Fetch Content     | true     | false       | true       | false     |
-| `recall`       | Recall Context    | true     | false       | true       | false     |
-| `content`      | Compose Content   | true     | false       | true       | false     |
-| `status`       | DB Status         | true     | false       | true       | false     |
-| `check`        | Integrity Check   | true     | false       | true       | false     |
-| `gc`           | Garbage Collect   | false    | true        | false      | false     |
-| `rebuild`      | Rebuild Indexes   | false    | false       | false      | false     |
-| `export`       | Export Snapshot    | false    | false       | true       | false     |
-| `skill-learn`  | Create Skill      | false    | false       | true       | false     |
-| `skill-list`   | List Skills       | true     | false       | true       | false     |
-| `skill-get`    | Get Skill         | true     | false       | true       | false     |
-| `skill-delete` | Delete Skill      | false    | true        | true       | false     |
-| `agent-create` | Create Agent      | false    | false       | true       | false     |
-| `agent-list`   | List Agents       | true     | false       | true       | false     |
-| `agent-get`    | Get Agent         | true     | false       | true       | false     |
-| `agent-delete` | Delete Agent      | false    | true        | true       | false     |
-| `auto-capture-review` | Review Captures | false | false    | false      | false     |
-
-## Completions
-
-The `completion/complete` handler provides
-autocomplete suggestions for prompt names and
-resource URIs. Clients use this to offer tab
-completion in UI surfaces.
-
-**Request params:**
-
-| Parameter  | Type   | Required | Description                         |
-|------------|--------|----------|-------------------------------------|
-| `ref`      | object | yes      | Reference describing what to complete |
-| `argument` | object | no       | Argument being completed            |
-
-**Ref types:**
-
-- `ref/prompt` with `name`: autocomplete skill and
-  agent prompt names that match the given prefix.
-  Returns all prompts whose name starts with the
-  prefix string.
-- `ref/resource` with `uri`: autocomplete kbid or
-  docid in URI patterns (`kbdb://section/...` or
-  `kbdb://document/...`) that match the given prefix.
-
-**Response (`McpCompletionResult`):**
-
-```json
-{
-   "completion": {
-      "values": [
-         "summarize-document",
-         "search-and-report"
-      ],
-      "hasMore": false,
-      "total": 2
-   }
-}
-```
-
-## Sampling
-
-The sampling capability allows the kbdb MCP server
-to request the AI agent host to generate text using
-its own language model. The server sends a
-`sampling/createMessage` request; the host runs the
-LLM and returns the generated text.
-
-**Request params:**
-
-| Parameter   | Type   | Required | Description                |
-|-------------|--------|----------|----------------------------|
-| `messages`  | array  | yes      | Message array to send      |
-| `maxTokens` | number | yes      | Maximum response tokens    |
-
-Before using sampling, the server checks the host's
-capabilities from the `initialize` response to
-confirm `sampling` is supported.
-
-**Use cases:**
-
-1. Auto-generate a skill body from a name and
-   description (used by `skill-learn` when `body`
-   is omitted).
-2. Extract keywords from content before indexing
-   (alternative to WASM keyword extraction).
-3. Summarise content for preview generation in
-   `skill-list` and `agent-list` responses.
-
-## Roots
-
-The `roots/list` handler returns the filesystem roots
-that the server considers relevant to its operation.
-kbdb returns the `.kbdb` database directory as its
-single root.
-
-**Response:**
-
-```json
-{
-   "roots": [
-      {
-         "uri": "file:///path/to/.kbdb",
-         "name": "kbdb database"
-      }
-   ]
-}
-```
-
-The URI uses the `file://` scheme with the absolute
-path to the context directory. The name is always
-`"kbdb database"`.
-
-## Logging
-
-The `logging/setLevel` handler controls the verbosity
-of server-to-client log notifications. Clients set
-the level once after initialization; the server
-applies it for the lifetime of the connection.
-
-**Parameter:** `level` (one of the `McpLogLevel`
-string values).
-
-**Log levels** (in ascending severity order):
-
-- `debug`
-- `info`
-- `notice`
-- `warning`
-- `error`
-- `critical`
-- `alert`
-- `emergency`
-
-When the log level is set, the server emits
-`notifications/message` for any event at or above
-the configured level:
-
-```json
-{
-   "jsonrpc": "2.0",
-   "method": "notifications/message",
-   "params": {
-      "level": "info",
-      "logger": "kbdb",
-      "data": "Indexed 42 terms for section abc123"
-   }
-}
-```
-
-## Resource Subscriptions
-
-Clients can subscribe to individual resources to
-receive change notifications without polling.
-
-- **`resources/subscribe`** -- client provides a
-  resource URI; the server adds it to the active
-  subscription set.
-- **`resources/unsubscribe`** -- client provides a
-  URI; the server removes it from the subscription
-  set.
-
-When a subscribed resource changes (section added,
-updated, or deleted; document manifest modified),
-the server emits `notifications/resources/updated`
-with the affected URI:
-
-```json
-{
-   "jsonrpc": "2.0",
-   "method": "notifications/resources/updated",
-   "params": {
-      "uri": "kbdb://section/a1b2c3d4e5f6g7h8j9k0"
-   }
-}
-```
-
-## Execution Model
-
-```
-AI agent host (Claude Desktop, Claude Code, etc.)
-  │
-  │  spawns child process
-  ▼
-kbdb mcp --db /path/to/.kbdb
-  │
-  │  stdio: JSON-RPC 2.0 (stdin/stdout)
-  ▼
-MCP Server (src/cli.ts -- MCP mode)
-  │
-  │  imports src/shared/worker-client/
-  ▼
-Worker Client
-  │
-  │  IPC: JSON-RPC 2.0 (Unix socket / named pipe)
-  ▼
-Worker Daemon (src/worker.ts)
-```
-
-The MCP server is a long-lived process. It creates a
-worker client on startup, holds the IPC connection
-open, and routes all incoming MCP requests through
-it. The daemon handles concurrency, caching, and WASM
-module orchestration.
-
-When the AI agent host terminates the connection
-(closes stdin), the MCP server disconnects from the
-worker daemon and exits. The daemon may continue
-running for other clients or shut down on idle
-timeout.
-
-## Relationship to CLI Mode
-
-The MCP server and CLI mode share:
-
-- The same `kbdb` executable and installation.
-- The same worker client module
-  (`src/shared/worker-client/`).
-- The same worker daemon and WASM modules.
-- The same `.kbdb` database directory.
-
-Changes made via CLI commands are visible to the MCP
-server and vice versa -- both operate on the same
-database through the same daemon.
-
-The difference is the interface:
-
-| Aspect    | CLI Mode               | MCP Mode               |
-|-----------|------------------------|------------------------|
-| Lifecycle | Short-lived (one cmd)  | Long-lived (persistent)|
-| Interface | Command-line arguments | MCP protocol (stdio)   |
-| Consumer  | Human / shell script   | AI agent               |
-| Output    | stdout (JSON/text/MCP) | MCP tool result format |
-| DB path   | CWD or `--db` flag     | `--db` flag or `KBDB_DB_DIR` env |
-
-See [CLI](cli.md) for CLI mode details,
-[Worker Client](worker-client.md) for the shared
-client module, and [Database](database.md) for
-storage details.
-
-## Notifications
-
-Notifications are one-way JSON-RPC messages with no
-`id` and no response expected.
-
-### Client -> Server
-
-| Notification | When |
-|-------------|------|
-| `notifications/initialized` | After `initialize` response received (required) |
-| `notifications/cancelled` | Client cancels an in-flight request |
-| `notifications/roots/list_changed` | If `roots.listChanged` advertised |
-
-### Server -> Client
-
-| Notification | When |
-|-------------|------|
-| `notifications/tools/list_changed` | Tool set changed (if `tools.listChanged`) |
-| `notifications/resources/list_changed` | Resource set changed (if `resources.listChanged`) |
-| `notifications/resources/updated` | Subscribed resource changed |
-| `notifications/prompts/list_changed` | Prompt set changed (if `prompts.listChanged`) |
-| `notifications/message` | Structured log message (if `logging` capability) |
-| `notifications/progress` | Long-running request progress update |
-
-kbdb does not currently emit any server-to-client
-notifications. It handles `notifications/initialized`
-from the client and ignores unknown notifications.
-
-## Error Handling
-
-### Protocol Errors
-
-Protocol-level errors use JSON-RPC 2.0 error
-responses:
-
-| 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 **not** protocol errors.
-They are returned as successful JSON-RPC responses
-with `isError: true` in the tool result:
-
-```json
-{
-   "jsonrpc": "2.0",
-   "id": 5,
-   "result": {
-      "content": [
-         {
-            "type": "text",
-            "text": "Section not found: abc123"
-         }
-      ],
-      "isError": true
-   }
-}
-```
-
-`handleToolCall` wraps every tool dispatch in a
-`try/catch`. When an error is thrown, the handler
-returns `{ content: [{ type: 'text', text:
-err.message }], isError: true }` where `err.message`
-is the message string when `err` is an `Error`
-instance, or `String(err)` otherwise. Validation
-errors within a tool handler (e.g. missing `title`
-for `image/*` types, unknown tool name, or `retrieve`
-called without `kbid` or `docid`) follow the same
-format but are returned directly rather than thrown.
-
-All successful tool results are wrapped as:
-```json
-{ "content": [{ "type": "text", "text": "<JSON>" }] }
-```
-where `<JSON>` is the result serialised with
-`JSON.stringify`. Most tools use 2-space indentation;
-`learn`, `unlearn`, and `content` return compact JSON
-(no indentation).
-
-Reserve JSON-RPC error responses for protocol
-violations (bad JSON, unknown method, missing
-required params). Application errors from tool
-execution go in the result.
-
-### Prompt and Skill Errors
-
-Additional error cases for the prompts and skill/agent
-tools:
-
-| Condition | Response |
-|-----------|----------|
-| `prompts/get` with unknown prompt name | JSON-RPC error `-32002` (resource not found) |
-| `skill-learn` with empty `body` | Tool result with `isError: true`, message: `"skill body must not be empty"` |
-| `skill-get` called without `name` or `kbid` | Tool result with `isError: true`, message: `"Provide name or kbid"` |
-| `skill-learn` with duplicate name | Not an error -- duplicate names are allowed, each gets a distinct kbid |
-| `agent-get` with skill kbid that has been deleted | Not an error -- the skill entry appears with `"name": null` in the skills array |
-
-## Required vs Optional Methods
-
-Methods are grouped by the capability that gates
-them. A server must implement all methods for every
-capability it advertises.
-
-| Method | Gate | kbdb Status |
-|--------|------|-------------|
-| `initialize` | required | implemented |
-| `notifications/initialized` | required | implemented |
-| `ping` | required | implemented |
-| `tools/list` | `tools` capability | implemented |
-| `tools/call` | `tools` capability | implemented |
-| `resources/list` | `resources` capability | empty list |
-| `resources/read` | `resources` capability | implemented |
-| `resources/templates/list` | `resources` capability | implemented |
-| `resources/subscribe` | `resources.subscribe` | planned |
-| `resources/unsubscribe` | `resources.subscribe` | planned |
-| `prompts/list` | `prompts` capability | implemented |
-| `prompts/get` | `prompts` capability | implemented |
-| `completion/complete` | `completions` capability | implemented |
-| `sampling/createMessage` | `sampling` capability | planned |
-| `roots/list` | `roots` capability | implemented |
-| `logging/setLevel` | `logging` capability | planned |
-
-Methods listed as "planned" are documented for
-future implementation. Until implemented, the server
-returns `-32601` if they are called.
-
-## Design Constraints
-
-- The MCP server conforms to the Model Context
-  Protocol specification version **2025-11-25**.
-- Output follows MCP tool result conventions. The
-  CLI's output format flags do not apply in MCP mode.
-- The server runs as a persistent process. It stays
-  alive and handles multiple requests from the
-  connected agent until the host terminates the
-  connection.
-- The server works with both Deno and Node.js
-  runtimes, consistent with the project's
-  dual-runtime requirement.
-- The database path is resolved from `--db`,
-  `KBDB_DB_DIR`, or the current working directory.
-- The MCP server does not perform keyword extraction,
-  indexing, ranking, or database I/O itself. All
-  processing is delegated to the worker daemon via
-  the worker client.
-
-### Wire Format Rules
-
-- **stdout is sacred** -- only JSON-RPC messages may
-  be written to stdout. Debug output, diagnostics,
-  and progress messages must go to stderr. Any
-  non-JSON-RPC output on stdout corrupts the stream.
-- **One message per line** -- each JSON-RPC message
-  is serialized as a single line of JSON with no
-  embedded newlines, terminated by `\n`.
-- **Request ID must not be null** -- unlike standard
-  JSON-RPC 2.0, MCP requires the `id` field to be a
-  non-null `string` or `number`. Notifications omit
-  `id` entirely.