@dikolab/kbdb 0.1.6 → 0.2.1

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

@@ -0,0 +1,386 @@
+# 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
+```

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

@@ -0,0 +1,160 @@
+# 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_DIR env)
+  ├─ 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.