@dikolab/kbdb 0.5.0 → 0.6.1

package/docs/modules/typescript/shared/mcp/classes.md

@@ -1,179 +0,0 @@
-# mcp/classes -- MCP Server Class
-
-*Wraps the MCP protocol layer and routes incoming
-tool calls and resource reads to handler functions.*
-
-## Source
-
-`src/shared/mcp/classes/`
-
-## Classes
-
-### `McpServer`
-
-**File:** `mcp-server.class.ts`
-
-Long-lived MCP server that communicates over stdio.
-Hand-rolled JSON-RPC 2.0 protocol handling over
-stdio using `node:readline`. Implements protocol
-version **2025-11-25**.
-
-```ts
-class McpServer {
-   constructor(client: McpWorkerClient);
-   listen(): Promise<void>;
-   handleLineForTest(line: string): Promise<McpResponse | null>;
-}
-```
-
-#### Constructor
-
-Takes a `McpWorkerClient` instance. Routing happens
-at request dispatch time -- each incoming method
-name is matched to the appropriate handler.
-
-**Properties:**
-
-| Property           | Type                  | Description                  |
-|--------------------|-----------------------|------------------------------|
-| `logLevel`         | `McpLogLevel \| null` | Current log level; `null`    |
-|                    |                       | until `logging/setLevel` is  |
-|                    |                       | received                     |
-| `subscriptions`    | `Set<string>`         | Set of URIs the client has   |
-|                    |                       | subscribed to via            |
-|                    |                       | `resources/subscribe`        |
-| `hostCapabilities` | `object \| null`      | Host capabilities received   |
-|                    |                       | in the `initialize` params;  |
-|                    |                       | `null` until initialized     |
-
-**Protocol methods handled:**
-
-| Method                        | Behavior                         |
-|-------------------------------|----------------------------------|
-| `initialize`                  | Returns protocol version and capabilities |
-| `ping`                        | Returns `{}` (liveness check)    |
-| `notifications/initialized`   | Sets initialized flag            |
-| `notifications/cancelled`     | Silently ignored                 |
-| `tools/list`                  | Returns tool definitions         |
-| `tools/call`                  | Dispatches to `handleToolCall`   |
-| `prompts/list`                | Returns prompt definitions       |
-| `prompts/get`                 | Renders and returns prompt       |
-| `completion/complete`         | Returns completion suggestions   |
-| `logging/setLevel`            | Stores requested log level       |
-| `roots/list`                  | Returns `.kbdb` directory root   |
-| `resources/list`              | Returns `{ resources: [] }`      |
-| `resources/templates/list`    | Returns URI templates            |
-| `resources/read`              | Dispatches to `handleResourceRead` |
-| `resources/subscribe`         | Adds URI to subscriptions set    |
-| `resources/unsubscribe`       | Removes URI from subscriptions   |
-
-**Pre-initialization guard**: all methods except
-`initialize` and `ping` return error `-32002`
-("Server not initialized") until
-`notifications/initialized` is received.
-
-**Tools (via `handleToolCall`):**
-
-| Tool           | Client Method / Handler             |
-|----------------|-------------------------------------|
-| `search`       | `client.search()`                   |
-| `learn`        | `client.addSection()`               |
-| `unlearn`      | `client.removeSection()`            |
-| `retrieve`     | `client.readSections()` or          |
-|                | `client.retrieveDocument()`         |
-| `recall`       | `handleRecall(params, client)`      |
-| `status`       | `client.dbStatus()`                 |
-| `skill-learn`  | `handleSkillLearn(params, client)`  |
-| `skill-list`   | `handleSkillList(client)`           |
-| `skill-get`    | `handleSkillGet(params, client)`    |
-| `skill-delete` | `handleSkillDelete(params, client)` |
-| `agent-create` | `handleAgentCreate(params, client)` |
-| `agent-list`   | `handleAgentList(client)`           |
-| `agent-get`    | `handleAgentGet(params, client)`    |
-| `agent-delete` | `handleAgentDelete(params, client)` |
-
-**Resource URI templates:**
-
-| URI Template                   | MIME Type        |
-|-------------------------------|------------------|
-| `kbdb://section/{kbid}`       | `text/plain`     |
-| `kbdb://document/{docid}`     | `application/json` |
-
-#### `listen()`
-
-Returns a `Promise<void>` that resolves when stdin
-closes. Reads JSON-RPC 2.0 requests from stdin,
-dispatches to the appropriate handler, and writes
-JSON-RPC responses to stdout. Disconnects the
-`McpWorkerClient` when the promise resolves.
-
-#### `handleLineForTest(line)`
-
-Processes a single raw input line and returns the
-JSON-RPC response, or `null` for notifications
-(which have no id and expect no response). Used
-for unit testing protocol handling without stdio.
-
-#### `prompts/list` handler
-
-Calls `client.listByType('skill')` and
-`client.listDocumentsByType('agent')`, then maps
-results to `McpPrompt[]` via
-`createPromptDefinitions(sections)`. Agent prompts
-use the `agent:` name prefix.
-
-#### `prompts/get` handler
-
-Parses the prompt name to determine whether it is
-a skill (no prefix) or agent (`agent:` prefix),
-then calls `handlePromptGet(name, args, client)` to
-render the template and return `McpPromptMessage[]`.
-
-#### `completion/complete` handler
-
-Dispatches to `handleCompletion(ref, argument, client)`
-based on the ref type (`ref/prompt` or `ref/resource`)
-and returns a `McpCompletionResult` with matching
-name or URI suggestions.
-
-#### `logging/setLevel` handler
-
-Stores the requested `McpLogLevel` in `this.logLevel`.
-Subsequent log events emitted at or above this level
-are sent to the client as `notifications/message`
-using the `notify` method.
-
-#### `roots/list` handler
-
-Returns the `.kbdb` directory as a single root entry:
-`{ uri: "file:///path/to/.kbdb", name: "kbdb database" }`.
-
-#### `resources/subscribe` handler
-
-Adds the requested URI to `this.subscriptions`. When
-a subscribed resource is updated (section added,
-modified, or deleted), the server calls `notify` with
-method `notifications/resources/updated`.
-
-#### `resources/unsubscribe` handler
-
-Removes the requested URI from `this.subscriptions`.
-
-#### `notify(method, params)`
-
-Sends a server-initiated JSON-RPC 2.0 notification
-to the client over stdout. Used for log messages
-(`notifications/message`) and resource update events
-(`notifications/resources/updated`).
-
-```ts
-notify(method: string, params: unknown): void;
-```
-
-## Testing
-
-```
-src/shared/mcp/
-├── classes/
-│   └── mcp-server.spec.ts
-```

package/docs/modules/typescript/shared/mcp/functions.md

@@ -1,386 +0,0 @@
-# mcp/functions -- MCP Server Functions
-
-*Factory, tool dispatch, resource dispatch, and
-definition builders.*
-
-## Source
-
-`src/shared/mcp/functions/`
-
-## Functions
-
-### `createMcpServer`
-
-**File:** `create-mcp-server.function.ts`
-
-Factory function. Creates and returns a configured
-`McpServer` bound to the given `McpWorkerClient`.
-
-```ts
-function createMcpServer(
-   client: McpWorkerClient,
-): McpServer;
-```
-
-### `createToolDefinitions`
-
-**File:** `create-tool-definitions.function.ts`
-
-Returns an array of `McpToolDefinition` objects
-describing the MCP tools the server exposes. Each
-definition includes `name`, `description`,
-`inputSchema` (JSON Schema), and `annotations`
-(`McpToolAnnotations`).
-
-```ts
-function createToolDefinitions(): McpToolDefinition[];
-```
-
-**Tools defined (18 total):**
-
-| Name           | Required Params            | Optional Params                      |
-|----------------|----------------------------|--------------------------------------|
-| `search`       | `query`                    | `mode`, `limit`, `content`, `offset` |
-| `learn`        | `content`                  | `type`, `docid`, `title`, `description` |
-| `unlearn`      | `kbid`                     | --                                   |
-| `retrieve`     | `kbid` or `docid`          | --                                   |
-| `recall`       | `kbid` or `kbids`          | `depth`                              |
-| `status`       | --                         | --                                   |
-| `content`      | `ids`                      | --                                   |
-| `check`        | --                         | --                                   |
-| `gc`           | --                         | --                                   |
-| `rebuild`      | --                         | --                                   |
-| `skill-learn`  | `name`, `description`, `body` | `arguments`                       |
-| `skill-list`   | --                         | --                                   |
-| `skill-get`    | `name` or `kbid`           | --                                   |
-| `skill-delete` | `kbid`                     | --                                   |
-| `agent-create` | `name`, `description`, `persona`, `skills` | --             |
-| `agent-list`   | --                         | --                                   |
-| `agent-get`    | `docid`                    | --                                   |
-| `agent-delete` | `docid`                    | --                                   |
-
-### `createResourceTemplates`
-
-**File:** `create-resource-templates.function.ts`
-
-Returns an array of `McpResourceTemplate` objects
-describing the URI templates for MCP resources. These
-are returned by `resources/templates/list`.
-
-```ts
-function createResourceTemplates(): McpResourceTemplate[];
-```
-
-**Templates defined:**
-
-| URI Template                   | MIME Type           |
-|-------------------------------|---------------------|
-| `kbdb://section/{kb_id}`      | `text/plain`        |
-| `kbdb://document/{doc_id}`    | `application/json`  |
-
-### `handleToolCall`
-
-**File:** `handle-tool-call.function.ts`
-
-Single dispatcher for all MCP `tools/call` requests.
-Routes by tool name to the appropriate
-`McpWorkerClient` method.
-
-```ts
-async function handleToolCall(
-   client: McpWorkerClient,
-   name: string,
-   args: Record<string, unknown>,
-): Promise<McpToolResult>;
-```
-
-Routing:
-
-| Tool Name      | Client Method / Handler              |
-|----------------|--------------------------------------|
-| `search`       | `client.search(params)`              |
-| `learn`        | `client.addSection(params)`          |
-| `unlearn`      | `client.removeSection(kbid)`         |
-| `retrieve`     | `client.readSections(kbids)` or      |
-|                | `client.retrieveDocument(docid)`     |
-| `recall`       | `handleRecall(params, client)`       |
-| `status`       | `client.dbStatus()`                  |
-| `content`      | `client.content(ids)`                |
-| `check`        | `client.integrityCheck()`            |
-| `gc`           | `client.gc()`                        |
-| `rebuild`      | `client.rebuildIndexes()`            |
-| `skill-learn`  | `handleSkillLearn(args, client)`     |
-| `skill-list`   | `handleSkillList(client)`            |
-| `skill-get`    | `handleSkillGet(args, client)`       |
-| `skill-delete` | `handleSkillDelete(args, client)`    |
-| `agent-create` | `handleAgentCreate(args, client)`    |
-| `agent-list`   | `handleAgentList(client)`            |
-| `agent-get`    | `handleAgentGet(args, client)`       |
-| `agent-delete` | `handleAgentDelete(args, client)`    |
-
-Tool execution errors (client throws) are caught and
-returned as `{ content: [...], isError: true }`. They
-are **not** returned as JSON-RPC error responses.
-Unknown tool names also return `isError: true`.
-
-### `handleResourceRead`
-
-**File:** `handle-resource-read.function.ts`
-
-Handles MCP `resources/read` requests. Parses the
-URI to determine whether it is a section or document
-request, then calls the appropriate client method.
-
-```ts
-async function handleResourceRead(
-   client: McpWorkerClient,
-   uri: string,
-): Promise<McpResourceResult>;
-```
-
-Throws on invalid or unrecognised URIs. The caller
-(`McpServer`) catches the error and returns a
-`RESOURCE_NOT_FOUND` (-32002) JSON-RPC error
-response.
-
-### `createPromptDefinitions`
-
-**File:** `create-prompt-definitions.function.ts`
-
-Maps an array of skill sections and agent documents
-to `McpPrompt[]` for the `prompts/list` response.
-Skill prompts use the skill name directly; agent
-prompts use `agent:<name>` as the prompt name.
-
-```ts
-function createPromptDefinitions(
-   sections: Section[],
-): McpPrompt[];
-```
-
-### `handlePromptGet`
-
-**File:** `handle-prompt-get.function.ts`
-
-Fetches a skill or agent by prompt name and renders
-it as `McpPromptMessage[]`. For skills: substitutes
-argument values into the template body and returns
-a single user message. For agents: returns an
-assistant message (persona) followed by a user
-message listing available skills.
-
-```ts
-async function handlePromptGet(
-   name: string,
-   args: Record<string, string>,
-   client: McpWorkerClient,
-): Promise<McpPromptMessage[]>;
-```
-
-### `handleCompletion`
-
-**File:** `handle-completion.function.ts`
-
-Provides autocomplete suggestions for prompt names
-and resource URIs. Dispatches based on `ref.type`:
-`ref/prompt` returns matching skill or agent names;
-`ref/resource` returns matching kbid or docid values
-from known URI patterns.
-
-```ts
-async function handleCompletion(
-   ref: McpCompletionRef,
-   argument: Record<string, string> | undefined,
-   client: McpWorkerClient,
-): Promise<McpCompletionResult>;
-```
-
-### `parseSkillContent`
-
-**File:** `parse-skill-content.function.ts`
-
-Parses a JSON string stored as a skill section's
-content into a typed `SkillDefinition`. Throws when
-the JSON is malformed or missing required fields.
-
-```ts
-function parseSkillContent(
-   json: string,
-): SkillDefinition;
-```
-
-### `serializeSkillContent`
-
-**File:** `serialize-skill-content.function.ts`
-
-Serializes a `SkillDefinition` to a JSON string for
-storage as a section content body.
-
-```ts
-function serializeSkillContent(
-   skill: SkillDefinition,
-): string;
-```
-
-### `handleSkillLearn`
-
-**File:** `handle-skill-learn.function.ts`
-
-Handles the `skill-learn` MCP tool call. Validates
-parameters, serializes the skill definition to JSON,
-and calls `client.addSection` with
-`sectionType: 'skill'`.
-
-```ts
-async function handleSkillLearn(
-   params: Record<string, unknown>,
-   client: McpWorkerClient,
-): Promise<McpToolResult>;
-```
-
-### `handleSkillList`
-
-**File:** `handle-skill-list.function.ts`
-
-Handles the `skill-list` MCP tool call. Calls
-`client.listByType('skill')` and formats the results.
-
-```ts
-async function handleSkillList(
-   client: McpWorkerClient,
-): Promise<McpToolResult>;
-```
-
-### `handleSkillGet`
-
-**File:** `handle-skill-get.function.ts`
-
-Handles the `skill-get` MCP tool call. Looks up the
-skill by `name` (via search) or by `kbid` (via
-`client.readSections`), parses the content, and
-returns the full `SkillDefinition`.
-
-```ts
-async function handleSkillGet(
-   params: Record<string, unknown>,
-   client: McpWorkerClient,
-): Promise<McpToolResult>;
-```
-
-### `handleSkillDelete`
-
-**File:** `handle-skill-delete.function.ts`
-
-Handles the `skill-delete` MCP tool call. Calls
-`client.removeSection(kbid)`.
-
-```ts
-async function handleSkillDelete(
-   params: Record<string, unknown>,
-   client: McpWorkerClient,
-): Promise<McpToolResult>;
-```
-
-### `handleAgentCreate`
-
-**File:** `handle-agent-create.function.ts`
-
-Handles the `agent-create` MCP tool call. Validates
-skill kbids, builds the agent document manifest, and
-stores it.
-
-```ts
-async function handleAgentCreate(
-   params: Record<string, unknown>,
-   client: McpWorkerClient,
-): Promise<McpToolResult>;
-```
-
-### `handleAgentList`
-
-**File:** `handle-agent-list.function.ts`
-
-Handles the `agent-list` MCP tool call. Calls
-`client.listDocumentsByType('agent')` and formats
-the results.
-
-```ts
-async function handleAgentList(
-   client: McpWorkerClient,
-): Promise<McpToolResult>;
-```
-
-### `handleAgentGet`
-
-**File:** `handle-agent-get.function.ts`
-
-Handles the `agent-get` MCP tool call. Retrieves
-the agent document by `docid` and resolves each
-referenced skill kbid into a `SkillDefinition`.
-Missing skills appear as `null` name entries.
-
-```ts
-async function handleAgentGet(
-   params: Record<string, unknown>,
-   client: McpWorkerClient,
-): Promise<McpToolResult>;
-```
-
-### `handleAgentDelete`
-
-**File:** `handle-agent-delete.function.ts`
-
-Handles the `agent-delete` MCP tool call. Removes
-the agent document manifest. Referenced skill
-sections are not deleted.
-
-```ts
-async function handleAgentDelete(
-   params: Record<string, unknown>,
-   client: McpWorkerClient,
-): Promise<McpToolResult>;
-```
-
-### `handleRecall`
-
-**File:** `handle-recall.function.ts`
-
-Handles the `recall` MCP tool call. Validates that
-at least one of `kbid` or `kbids` is provided,
-clamps `depth` to 0--3, calls
-`client.recall(params)`, and formats the result
-as a JSON text content item.
-
-```ts
-async function handleRecall(
-   params: Record<string, unknown>,
-   client: McpWorkerClient,
-): Promise<McpToolResult>;
-```
-
-## Testing
-
-Each function has a `.spec.ts` at the module root:
-
-```
-src/shared/mcp/
-├── create-mcp-server.spec.ts
-├── create-tool-definitions.spec.ts
-├── create-prompt-definitions.spec.ts
-├── create-resource-templates.spec.ts
-├── handle-tool-call.spec.ts
-├── handle-resource-read.spec.ts
-├── handle-prompt-get.spec.ts
-├── handle-completion.spec.ts
-├── parse-skill-content.spec.ts
-├── serialize-skill-content.spec.ts
-├── handle-skill-learn.spec.ts
-├── handle-skill-list.spec.ts
-├── handle-skill-get.spec.ts
-├── handle-skill-delete.spec.ts
-├── handle-agent-create.spec.ts
-├── handle-agent-list.spec.ts
-├── handle-agent-get.spec.ts
-├── handle-agent-delete.spec.ts
-└── mcp-server.spec.ts
-```