@dikolab/kbdb 0.1.6 → 0.2.0

package/docs/goals/mcp.md

@@ -0,0 +1,1467 @@
+# 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>]
+```
+
+The `--db` flag specifies the absolute path to the
+`.kbdb` database directory. If omitted, the server
+reads the `KBDB_DIR` environment variable. One of the
+two must be provided -- the MCP server does not fall
+back to the current working directory.
+
+Resolution order:
+
+1. `--db <path>` command-line flag.
+2. `KBDB_DIR` environment variable.
+3. Error: no database directory specified.
+
+The MCP server does not fall back to the current
+working directory because the server's working
+directory is determined by the host application, not
+the user.
+
+See [CLI -- Run Modes](cli.md#run-modes) for how
+the `kbdb` executable dispatches to MCP mode.
+
+## 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_DIR`:
+
+```json
+{
+   "mcpServers": {
+      "kbdb": {
+         "command": "npx",
+         "args": ["@dikolab/kbdb", "mcp"],
+         "env": {
+            "KBDB_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 `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"]
+      }
+   ],
+   "total": 42,
+   "offset": 0,
+   "limit": 20,
+   "has_more": true
+}
+```
+
+- `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.
+
+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. 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 |
+
+**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`.
+
+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`. 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()`.
+
+### 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 18 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     |
+| `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     |
+
+## 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_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 must be explicitly configured
+  via `--db` or `KBDB_DIR`. No working directory
+  fallback.
+- 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.