@dikolab/kbdb 0.5.0 → 0.6.0

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

@@ -1,160 +0,0 @@
-# mcp -- MCP Server Module
-
-*Long-lived MCP server over stdio. Routes tool and
-resource requests to the worker daemon via the
-worker-client module.*
-
-## Source
-
-`src/shared/mcp/`
-
-## Responsibility
-
-Starts an MCP server that listens on stdin and writes
-responses to stdout using JSON-RPC 2.0 (protocol
-version **2025-11-25**). On startup it creates a
-`WorkerClient` to connect to the worker daemon. All
-incoming MCP tool calls and resource reads are routed
-through that client. The MCP module does **not**
-perform keyword extraction, indexing, ranking, or
-database I/O itself.
-
-See [MCP](../../../../goals/mcp.md) for the full
-behavioral specification.
-
-## Directory Layout
-
-```
-src/shared/mcp/
-├── index.ts
-├── classes/
-│   └── mcp-server.class.ts
-├── constants/
-│   └── mcp-error-codes.constant.ts
-├── functions/
-│   ├── create-mcp-server.function.ts
-│   ├── create-prompt-definitions.function.ts
-│   ├── create-resource-templates.function.ts
-│   ├── create-tool-definitions.function.ts
-│   ├── handle-agent-create.function.ts
-│   ├── handle-agent-delete.function.ts
-│   ├── handle-agent-get.function.ts
-│   ├── handle-agent-list.function.ts
-│   ├── handle-completion.function.ts
-│   ├── handle-prompt-get.function.ts
-│   ├── handle-recall.function.ts
-│   ├── handle-resource-read.function.ts
-│   ├── handle-skill-delete.function.ts
-│   ├── handle-skill-get.function.ts
-│   ├── handle-skill-learn.function.ts
-│   ├── handle-skill-list.function.ts
-│   ├── handle-tool-call.function.ts
-│   ├── parse-skill-content.function.ts
-│   └── serialize-skill-content.function.ts
-├── typings/
-│   ├── mcp-client.interface.ts
-│   ├── mcp-types.interface.ts
-│   └── remove-section-result.model.ts
-├── tests/
-│   └── mcp-protocol.spec.ts
-└── *.spec.ts
-```
-
-## Exports
-
-- **[classes.md](classes.md)** -- `McpServer`.
-- **[functions.md](functions.md)** --
-  `createMcpServer`, `createToolDefinitions`,
-  `createPromptDefinitions`, `createResourceTemplates`,
-  `handleToolCall`, `handleResourceRead`,
-  `handlePromptGet`, `handleCompletion`,
-  `parseSkillContent`, `serializeSkillContent`,
-  `handleSkillLearn`, `handleSkillList`,
-  `handleSkillGet`, `handleSkillDelete`,
-  `handleAgentCreate`, `handleAgentList`,
-  `handleAgentGet`, `handleAgentDelete`,
-  `handleRecall`.
-- **[typings.md](typings.md)** -- `McpWorkerClient`,
-  `McpRequest`, `McpResponse`, `McpNotification`,
-  `McpToolDefinition`, `McpResourceTemplate`,
-  `McpServerInfo`, `McpCapabilities`, `McpToolResult`,
-  `McpResourceResult`, `RemoveSectionResult`,
-  `McpPrompt`, `McpPromptArgument`, `McpPromptMessage`,
-  `McpPromptMessageContent`, `McpToolAnnotations`,
-  `McpCompletionRef`, `McpCompletionResult`,
-  `McpLogLevel`, `McpLogMessage`, `SkillDefinition`,
-  `SkillArgument`, `AgentDefinition`.
-- **Error code constants**: `PARSE_ERROR`,
-  `METHOD_NOT_FOUND`, `INVALID_PARAMS`,
-  `INTERNAL_ERROR`, `RESOURCE_NOT_FOUND`.
-
-## Execution Flow
-
-```
-cli.ts (entry point, MCP mode)
-  │
-  ├─ detect runtime (Deno / Node)
-  ├─ resolve db path (--db flag or KBDB_DB_DIR env or cwd)
-  ├─ createWorkerClient({ targetDir })
-  ├─ createMcpServer(client)
-  │    └─ returns McpServer
-  ├─ server.listen()
-  │    ├─ opens stdio transport
-  │    ├─ reads JSON-RPC 2.0 requests from stdin
-  │    ├─ pre-init guard: rejects all methods except
-  │    │    initialize and ping until
-  │    │    notifications/initialized received
-  │    ├─ routes protocol messages:
-  │    │    ├─ initialize          → version 2025-11-25
-  │    │    ├─ ping                → {}
-  │    │    ├─ notifications/initialized → sets flag
-  │    │    └─ notifications/cancelled  → ignored
-  │    ├─ routes tool calls via handleToolCall:
-  │    │    ├─ 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()
-  │    │    ├─ 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)
-  │    ├─ routes prompt requests:
-  │    │    ├─ prompts/list → createPromptDefinitions(sections)
-  │    │    └─ prompts/get  → handlePromptGet(name, args, client)
-  │    ├─ routes completion requests:
-  │    │    └─ completion/complete → handleCompletion(ref, arg, client)
-  │    ├─ routes resource requests:
-  │    │    ├─ resources/list           → { resources: [] }
-  │    │    ├─ resources/templates/list → URI templates
-  │    │    ├─ resources/subscribe      → add URI to subscriptions
-  │    │    ├─ resources/unsubscribe    → remove URI from subscriptions
-  │    │    └─ resources/read           → handleResourceRead
-  │    │         ├─ kbdb://section/{kbid}
-  │    │         └─ kbdb://document/{docid}
-  │    ├─ routes logging and roots:
-  │    │    ├─ logging/setLevel → stores logLevel
-  │    │    └─ roots/list       → returns .kbdb URI
-  │    └─ writes JSON-RPC 2.0 responses to stdout
-  └─ on stdin close:
-       └─ client.disconnect()
-```
-
-## 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.

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

@@ -1,529 +0,0 @@
-# mcp/typings -- MCP Type Definitions
-
-*Interfaces and type aliases for the MCP server's
-JSON-RPC protocol and worker client contract.*
-
-## Source
-
-`src/shared/mcp/typings/`
-
-## Typings
-
-### `McpWorkerClient`
-
-**File:** `mcp-client.interface.ts`
-
-Interface for the worker client dependency consumed
-by the MCP server. Defines the knowledge-base
-operations the server exposes as MCP tools and
-resources without coupling to the concrete
-`WorkerClient` class.
-
-```ts
-interface McpWorkerClient {
-   search(params: {
-      readonly query: string;
-      readonly mode?: string;
-      readonly limit?: number;
-      readonly content?: boolean;
-      readonly offset?: number;
-   }): Promise<PagedSearchResult>;
-
-   addSection(params: {
-      readonly type: string;
-      readonly content: string;
-      readonly title?: string;
-      readonly description?: string;
-      readonly docid?: string;
-   }): Promise<string>;
-
-   removeSection(kbid: string): Promise<RemoveSectionResult>;
-
-   readSections(
-      kbids: string[],
-   ): Promise<Section[]>;
-
-   retrieveDocument(
-      docid: string,
-   ): Promise<unknown>;
-
-   listByType(
-      sectionType: string,
-   ): Promise<Section[]>;
-
-   listDocumentsByType(
-      docType: string,
-   ): Promise<unknown[]>;
-
-   recall(params: {
-      readonly kbid?: string;
-      readonly kbids?: readonly string[];
-      readonly depth?: number;
-   }): Promise<RecallResult | RecallResult[]>;
-
-   dbStatus(): Promise<{
-      initialized: boolean;
-      contextPath: string;
-      cacheStats: {
-         contentCount: number;
-         indexCount: number;
-      };
-   }>;
-
-   disconnect(): void;
-}
-```
-
-| Method                  | Description                       |
-|-------------------------|-----------------------------------|
-| `listByType`            | Returns all sections whose        |
-|                         | `sectionType` matches the given   |
-|                         | value (e.g. `'skill'`)            |
-| `listDocumentsByType`   | Returns all document manifests    |
-|                         | whose `type` field matches (e.g.  |
-|                         | `'agent'`)                        |
-
-### `RemoveSectionResult`
-
-**File:** `remove-section-result.model.ts`
-
-Result returned by `McpWorkerClient.removeSection`.
-Reports whether the section was found and removed
-and the elapsed operation time.
-
-```ts
-interface RemoveSectionResult {
-   readonly removed: boolean;
-   readonly elapsed_ms: number;
-}
-```
-
-### `McpRequest`
-
-**File:** `mcp-types.interface.ts`
-
-A JSON-RPC 2.0 request message sent to the MCP
-server. The `id` field is absent for notifications.
-
-```ts
-interface McpRequest {
-   readonly jsonrpc: '2.0';
-   readonly id?: number | string;
-   readonly method: string;
-   readonly params?: Record<string, unknown>;
-}
-```
-
-### `McpResponse`
-
-**File:** `mcp-types.interface.ts`
-
-A JSON-RPC 2.0 response message. Contains either
-`result` (success) or `error` (failure), never both.
-
-```ts
-interface McpResponse {
-   readonly jsonrpc: '2.0';
-   readonly id: number | string;
-   readonly result?: unknown;
-   readonly error?: {
-      readonly code: number;
-      readonly message: string;
-      readonly data?: unknown;
-   };
-}
-```
-
-### `McpNotification`
-
-**File:** `mcp-types.interface.ts`
-
-A JSON-RPC 2.0 notification with no `id` and no
-expected response.
-
-```ts
-interface McpNotification {
-   readonly jsonrpc: '2.0';
-   readonly method: string;
-   readonly params?: Record<string, unknown>;
-}
-```
-
-### `McpToolDefinition`
-
-**File:** `mcp-types.interface.ts`
-
-Definition of a single MCP tool exposed by the
-server via `tools/list`.
-
-```ts
-interface McpToolDefinition {
-   readonly name: string;
-   readonly description: string;
-   readonly inputSchema: Record<string, unknown>;
-   readonly annotations?: McpToolAnnotations;
-}
-```
-
-The optional `annotations` field carries hints for
-MCP clients about the tool's side effects and safety
-characteristics.
-
-### `McpResourceTemplate`
-
-**File:** `mcp-types.interface.ts`
-
-A URI template describing an MCP resource served
-via `resources/templates/list`.
-
-```ts
-interface McpResourceTemplate {
-   readonly uriTemplate: string;
-   readonly name: string;
-   readonly description: string;
-   readonly mimeType?: string;
-}
-```
-
-### `McpServerInfo`
-
-**File:** `mcp-types.interface.ts`
-
-Identity information for the MCP server, reported
-in the `initialize` response.
-
-```ts
-interface McpServerInfo {
-   readonly name: string;
-   readonly version: string;
-}
-```
-
-### `McpCapabilities`
-
-**File:** `mcp-types.interface.ts`
-
-MCP capability flags advertised during
-initialization. Each key enables a group of methods.
-
-```ts
-interface McpCapabilities {
-   readonly tools?: Record<string, never>;
-   readonly resources?: Record<string, never>;
-   readonly prompts?: Record<string, never>;
-   readonly logging?: Record<string, never>;
-   readonly completions?: Record<string, never>;
-}
-```
-
-| Key           | Methods enabled                          |
-|---------------|------------------------------------------|
-| `tools`       | `tools/list`, `tools/call`               |
-| `resources`   | `resources/list`, `resources/read`, etc. |
-| `prompts`     | `prompts/list`, `prompts/get`            |
-| `logging`     | `logging/setLevel`                       |
-| `completions` | `completion/complete`                    |
-
-### `McpToolResult`
-
-**File:** `mcp-types.interface.ts`
-
-Result returned by `handleToolCall`. Tool-level
-errors use `isError: true` in the result rather than
-JSON-RPC error responses.
-
-```ts
-interface McpToolResult {
-   readonly content: readonly {
-      readonly type: string;
-      readonly text: string;
-   }[];
-   readonly isError?: boolean;
-}
-```
-
-### `McpResourceResult`
-
-**File:** `mcp-types.interface.ts`
-
-Result returned by `handleResourceRead`.
-
-```ts
-interface McpResourceResult {
-   readonly contents: readonly {
-      readonly uri: string;
-      readonly mimeType: string;
-      readonly text: string;
-   }[];
-}
-```
-
-### `McpPrompt`
-
-**File:** `mcp-types.interface.ts`
-
-A single prompt entry returned by `prompts/list`.
-Skills use `name` directly; agents use `agent:<name>`.
-
-```ts
-interface McpPrompt {
-   readonly name: string;
-   readonly description?: string;
-   readonly arguments?: readonly McpPromptArgument[];
-}
-```
-
-| Property      | Description                          |
-|---------------|--------------------------------------|
-| `name`        | Prompt name (or `agent:<name>`)      |
-| `description` | Human-readable description           |
-| `arguments`   | Accepted arguments for the prompt    |
-
-### `McpPromptArgument`
-
-**File:** `mcp-types.interface.ts`
-
-A single argument accepted by an MCP prompt.
-
-```ts
-interface McpPromptArgument {
-   readonly name: string;
-   readonly description?: string;
-   readonly required?: boolean;
-}
-```
-
-| Property      | Description                       |
-|---------------|-----------------------------------|
-| `name`        | Argument identifier               |
-| `description` | Human-readable hint               |
-| `required`    | Whether the argument is required  |
-
-### `McpPromptMessage`
-
-**File:** `mcp-types.interface.ts`
-
-A single message in the array returned by `prompts/get`.
-
-```ts
-interface McpPromptMessage {
-   readonly role: 'user' | 'assistant';
-   readonly content: McpPromptMessageContent;
-}
-```
-
-### `McpPromptMessageContent`
-
-**File:** `mcp-types.interface.ts`
-
-Content body of an `McpPromptMessage`.
-
-```ts
-interface McpPromptMessageContent {
-   readonly type: 'text';
-   readonly text: string;
-}
-```
-
-### `McpToolAnnotations`
-
-**File:** `mcp-types.interface.ts`
-
-Hints for MCP clients about a tool's side effects
-and safety characteristics.
-
-```ts
-interface McpToolAnnotations {
-   readonly title?: string;
-   readonly readOnlyHint?: boolean;
-   readonly destructiveHint?: boolean;
-   readonly idempotentHint?: boolean;
-   readonly openWorldHint?: boolean;
-}
-```
-
-| Property          | Description                        |
-|-------------------|------------------------------------|
-| `title`           | Human-readable tool title          |
-| `readOnlyHint`    | `true` if the tool only reads data |
-| `destructiveHint` | `true` if the tool deletes data    |
-| `idempotentHint`  | `true` if repeated calls are safe  |
-| `openWorldHint`   | `true` if side effects may extend  |
-|                   | outside the knowledge base         |
-
-### `McpCompletionRef`
-
-**File:** `mcp-types.interface.ts`
-
-Reference descriptor sent with a `completion/complete`
-request, identifying the kind of value to complete.
-
-```ts
-interface McpCompletionRef {
-   readonly type: 'ref/prompt' | 'ref/resource';
-   readonly name?: string;
-   readonly uri?: string;
-}
-```
-
-| Property | Description                                  |
-|----------|----------------------------------------------|
-| `type`   | `'ref/prompt'` to complete prompt names;     |
-|          | `'ref/resource'` to complete resource URIs   |
-| `name`   | Prompt name prefix (for `ref/prompt`)        |
-| `uri`    | Resource URI prefix (for `ref/resource`)     |
-
-### `McpCompletionResult`
-
-**File:** `mcp-types.interface.ts`
-
-Result returned by `handleCompletion`.
-
-```ts
-interface McpCompletionResult {
-   readonly completion: {
-      readonly values: readonly string[];
-      readonly hasMore?: boolean;
-      readonly total?: number;
-   };
-}
-```
-
-| Property           | Description                      |
-|--------------------|----------------------------------|
-| `completion.values`| Matching completion strings      |
-| `completion.hasMore` | More results exist beyond this list |
-| `completion.total` | Total number of matches          |
-
-### `McpLogLevel`
-
-**File:** `mcp-types.interface.ts`
-
-MCP log severity levels as defined in the MCP spec.
-
-```ts
-type McpLogLevel =
-   | 'debug'
-   | 'info'
-   | 'notice'
-   | 'warning'
-   | 'error'
-   | 'critical'
-   | 'alert'
-   | 'emergency';
-```
-
-### `McpLogMessage`
-
-**File:** `mcp-types.interface.ts`
-
-Parameters for a `notifications/message` server
-notification.
-
-```ts
-interface McpLogMessage {
-   readonly level: McpLogLevel;
-   readonly logger?: string;
-   readonly data?: unknown;
-}
-```
-
-| Property | Description                            |
-|----------|----------------------------------------|
-| `level`  | Severity level of the log entry        |
-| `logger` | Optional logger name (e.g. `'kbdb'`)  |
-| `data`   | Log message or structured data         |
-
-### `SkillDefinition`
-
-**File:** `mcp-types.interface.ts`
-
-A complete skill definition as stored in the knowledge
-base and returned by skill retrieval operations.
-
-```ts
-interface SkillDefinition {
-   readonly name: string;
-   readonly description: string;
-   readonly arguments?: readonly SkillArgument[];
-   readonly body: string;
-}
-```
-
-| Property      | Description                           |
-|---------------|---------------------------------------|
-| `name`        | Skill name in kebab-case              |
-| `description` | What the skill does                   |
-| `arguments`   | Auto-detected template arguments      |
-| `body`        | Template body with `{{arg}}` syntax   |
-
-### `SkillArgument`
-
-**File:** `mcp-types.interface.ts`
-
-A single argument accepted by a skill template.
-
-```ts
-interface SkillArgument {
-   readonly name: string;
-   readonly type?: 'string' | 'number' | 'boolean';
-   readonly description?: string;
-   readonly required?: boolean;
-}
-```
-
-| Property      | Description                        |
-|---------------|------------------------------------|
-| `name`        | Argument identifier                |
-| `type`        | Value type (defaults to `string`)  |
-| `description` | Human-readable argument hint       |
-| `required`    | Whether the argument is required   |
-
-### `AgentDefinition`
-
-**File:** `mcp-types.interface.ts`
-
-A complete agent definition as returned by agent
-retrieval operations. Skills are resolved from kbid
-references; missing skills appear with `name: null`.
-
-```ts
-interface AgentDefinition {
-   readonly docid: string;
-   readonly name: string;
-   readonly description: string;
-   readonly persona: string;
-   readonly skills: readonly {
-      readonly kbid: string;
-      readonly name: string | null;
-      readonly position: number;
-   }[];
-}
-```
-
-| Property      | Description                          |
-|---------------|--------------------------------------|
-| `docid`       | Agent document identifier            |
-| `name`        | Agent name in kebab-case             |
-| `description` | What the agent does                  |
-| `persona`     | System prompt text for the agent     |
-| `skills`      | Ordered skill references (resolved)  |
-
-## Error Code Constants
-
-**File:** `src/shared/mcp/constants/mcp-error-codes.constant.ts`
-
-Named constants for JSON-RPC 2.0 and MCP-specific
-error codes. Use these instead of inline numbers.
-
-| Constant            | Value   | Meaning                        |
-|---------------------|---------|--------------------------------|
-| `PARSE_ERROR`       | -32700  | Malformed JSON in request      |
-| `METHOD_NOT_FOUND`  | -32601  | Method not implemented         |
-| `INVALID_PARAMS`    | -32602  | Invalid or missing parameters  |
-| `INTERNAL_ERROR`    | -32603  | Unexpected server error        |
-| `RESOURCE_NOT_FOUND`| -32002  | Resource not found (MCP-specific); also used for pre-initialization guard |
-
-No spec -- typings are compile-time only. Constants
-have a spec (`mcp-error-codes.spec.ts`) that verifies
-the exported values.