@dikolab/kbdb 0.2.2 → 0.3.1

package/src/shared/mcp/functions/handle-tool-skill-learn.function.ts

@@ -0,0 +1,61 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
+import { asString } from './as-string.function.ts';
+import { extractSkillArguments } from './extract-skill-arguments.function.ts';
+import { serializeSkillContent } from './serialize-skill-content.function.ts';
+
+/**
+ * Handles the `skill-learn` MCP tool call.
+ *
+ * Validates required arguments, extracts template placeholders from
+ * the body, serialises the skill, and stores it as a knowledge-base
+ * section.
+ *
+ * @param client - the worker client used to execute operations
+ * @param args - tool arguments from the MCP request
+ */
+export async function handleToolSkillLearn(
+   client: McpWorkerClient,
+   args: Record<string, unknown>,
+): Promise<ToolCallResult> {
+   const name = asString(args['name'], '');
+   if (!name) {
+      return {
+         content: [{ type: 'text', text: 'name is required' }],
+         isError: true,
+      };
+   }
+   const body = asString(args['body'], '');
+   if (!body) {
+      return {
+         content: [{ type: 'text', text: 'body is required' }],
+         isError: true,
+      };
+   }
+   const description =
+      typeof args['description'] === 'string'
+         ? args['description']
+         : undefined;
+   const skillArgs = extractSkillArguments(body);
+   const skill = {
+      name,
+      description,
+      arguments: skillArgs.length > 0 ? skillArgs : undefined,
+      body,
+   };
+   const json = serializeSkillContent(skill);
+   const result = await client.addSection({
+      sectionType: 'skill',
+      content: json,
+      title: name,
+      description,
+   });
+   return {
+      content: [
+         {
+            type: 'text',
+            text: JSON.stringify({ kbid: result.kbid, name }),
+         },
+      ],
+   };
+}

package/src/shared/mcp/functions/handle-tool-skill-list.function.ts

@@ -0,0 +1,39 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
+
+/**
+ * Handles the `skill-list` MCP tool call.
+ *
+ * Lists all skills stored in the knowledge base, including the
+ * argument count extracted from each skill's JSON content.
+ *
+ * @param client - the worker client used to execute operations
+ */
+export async function handleToolSkillList(
+   client: McpWorkerClient,
+): Promise<ToolCallResult> {
+   const records = await client.listByType('skill');
+   const items = records.map((r) => {
+      let argumentCount = 0;
+      try {
+         const parsed = JSON.parse(r.content) as Record<
+            string,
+            unknown
+         >;
+         if (Array.isArray(parsed['arguments'])) {
+            argumentCount = parsed['arguments'].length;
+         }
+      } catch {
+         // ignore parse errors
+      }
+      return {
+         kbid: r.kbid,
+         name: r.title,
+         description: r.description,
+         argumentCount,
+      };
+   });
+   return {
+      content: [{ type: 'text', text: JSON.stringify(items, null, 2) }],
+   };
+}

package/src/shared/mcp/functions/handle-tool-status.function.ts

@@ -0,0 +1,21 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
+
+/**
+ * Handles the `status` MCP tool call.
+ *
+ * Fetches database metadata from the worker client and returns it as
+ * formatted JSON.
+ *
+ * @param client - the worker client used to execute operations
+ */
+export async function handleToolStatus(
+   client: McpWorkerClient,
+): Promise<ToolCallResult> {
+   const status = await client.dbStatus();
+   return {
+      content: [
+         { type: 'text', text: JSON.stringify(status, null, 2) },
+      ],
+   };
+}

package/src/shared/mcp/functions/handle-tool-unlearn.function.ts

@@ -0,0 +1,24 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
+import { asString } from './as-string.function.ts';
+
+/**
+ * Handles the `unlearn` MCP tool call.
+ *
+ * Removes the section identified by `kbid` from the knowledge base
+ * and returns the removal result as JSON.
+ *
+ * @param client - the worker client used to execute operations
+ * @param args - tool arguments from the MCP request
+ */
+export async function handleToolUnlearn(
+   client: McpWorkerClient,
+   args: Record<string, unknown>,
+): Promise<ToolCallResult> {
+   const result = await client.removeSection(
+      asString(args['kbid'], ''),
+   );
+   return {
+      content: [{ type: 'text', text: JSON.stringify(result) }],
+   };
+}

package/src/shared/mcp/functions/parse-agent-meta.function.ts

@@ -0,0 +1,27 @@
+/** Parsed shape of an agent metadata section. */
+export interface AgentMeta {
+   /** Agent persona text. */
+   readonly persona: string;
+}
+
+/**
+ * Parses agent metadata from a raw JSON content string.
+ *
+ * Returns an object with an empty `persona` when parsing fails or
+ * the required field is absent or not a string.
+ *
+ * @param content - raw JSON content string of the agent metadata section
+ */
+export function parseAgentMeta(content: string): AgentMeta {
+   try {
+      const parsed = JSON.parse(content) as Record<string, unknown>;
+      return {
+         persona:
+            typeof parsed['persona'] === 'string'
+               ? parsed['persona']
+               : '',
+      };
+   } catch {
+      return { persona: '' };
+   }
+}

package/src/shared/mcp/functions/parse-skill-arguments.function.ts

@@ -0,0 +1,36 @@
+import type { McpPromptArgument } from '../typings/prompt-types.interface.ts';
+
+/**
+ * Parses the `arguments` field from a skill's JSON content string.
+ *
+ * Returns the array of prompt argument definitions when the content
+ * is valid JSON with an `arguments` array, or `undefined` when JSON
+ * parsing fails or the field is absent.
+ *
+ * @param content - raw JSON string of the skill section content
+ */
+export function parseSkillArguments(
+   content: string,
+): readonly McpPromptArgument[] | undefined {
+   try {
+      const parsed = JSON.parse(content) as Record<string, unknown>;
+      if (!Array.isArray(parsed['arguments'])) {
+         return undefined;
+      }
+      return (parsed['arguments'] as Record<string, unknown>[]).map(
+         (arg) => ({
+            name: typeof arg['name'] === 'string' ? arg['name'] : '',
+            description:
+               typeof arg['description'] === 'string'
+                  ? arg['description']
+                  : undefined,
+            required:
+               typeof arg['required'] === 'boolean'
+                  ? arg['required']
+                  : undefined,
+         }),
+      );
+   } catch {
+      return undefined;
+   }
+}

package/src/shared/mcp/functions/read-agent-meta.function.ts

@@ -0,0 +1,41 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+
+/**
+ * Reads the metadata JSON stored in the first section of an agent
+ * document and extracts `name`, `description`, and `persona`.
+ *
+ * Returns defaults when the section is absent or its content is
+ * not parseable as JSON.
+ *
+ * @param client - the worker client used to read sections
+ * @param metaKbid - kbid of the agent metadata section
+ * @param fallbackName - name returned when `name` is absent from JSON
+ */
+export async function readAgentMeta(
+   client: McpWorkerClient,
+   metaKbid: string,
+   fallbackName: string,
+): Promise<{ name: string; description: string; persona: string }> {
+   const metaSections = await client.readSections([metaKbid]);
+   const first = metaSections.at(0);
+   if (!first) {
+      return { name: fallbackName, description: '', persona: '' };
+   }
+   try {
+      const meta = JSON.parse(first.content) as Record<string, unknown>;
+      return {
+         name:
+            typeof meta['name'] === 'string'
+               ? meta['name']
+               : fallbackName,
+         description:
+            typeof meta['description'] === 'string'
+               ? meta['description']
+               : '',
+         persona:
+            typeof meta['persona'] === 'string' ? meta['persona'] : '',
+      };
+   } catch {
+      return { name: fallbackName, description: '', persona: '' };
+   }
+}

package/src/shared/mcp/functions/resolve-skill-refs.function.ts

@@ -0,0 +1,50 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+
+/** A section reference within an agent document. */
+export interface AgentSectionRef {
+   /** Knowledge-base identifier of the section. */
+   readonly kbid: string;
+   /** Zero-based position of the section within the document. */
+   readonly position: number;
+}
+
+/**
+ * Resolves skill names for a list of section references by reading
+ * each section's JSON content and extracting the `name` field.
+ *
+ * Returns `name: null` for references where the section no longer
+ * exists (dangling references) or whose content is not valid JSON.
+ *
+ * @param client - the worker client used to read sections
+ * @param skillRefs - ordered list of section references to resolve
+ */
+export async function resolveSkillRefs(
+   client: McpWorkerClient,
+   skillRefs: AgentSectionRef[],
+): Promise<{ kbid: string; name: string | null; position: number }[]> {
+   if (skillRefs.length === 0) return [];
+   const skillKbids = skillRefs.map((s) => s.kbid);
+   const skillSections = await client.readSections(skillKbids);
+   const sectionMap = new Map(skillSections.map((s) => [s.kbid, s]));
+   return skillRefs.map((ref) => {
+      const sec = sectionMap.get(ref.kbid);
+      if (!sec) {
+         return { kbid: ref.kbid, name: null, position: ref.position };
+      }
+      try {
+         const parsed = JSON.parse(sec.content) as Record<
+            string,
+            unknown
+         >;
+         const skillName =
+            typeof parsed['name'] === 'string' ? parsed['name'] : null;
+         return {
+            kbid: ref.kbid,
+            name: skillName,
+            position: ref.position,
+         };
+      } catch {
+         return { kbid: ref.kbid, name: null, position: ref.position };
+      }
+   });
+}

package/src/shared/mcp/functions/run-startup-health-check.function.ts

@@ -0,0 +1,34 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+
+/**
+ * Runs an integrity check immediately after the MCP handshake
+ * completes.
+ *
+ * Calls `notify` with a `notifications/message` warning when the
+ * check detects issues so the connected agent is aware before making
+ * requests. Errors from the check itself are swallowed -- the server
+ * continues operating regardless.
+ *
+ * @param client - the worker client used to run the integrity check
+ * @param notify - callback used to send notifications to the host
+ */
+export async function runStartupHealthCheck(
+   client: McpWorkerClient,
+   notify: (method: string, params: Record<string, unknown>) => void,
+): Promise<void> {
+   try {
+      const report = await client.integrityCheck();
+      if (!report.ok) {
+         const summary = report.errors
+            .map((e) => `${e.type}: ${e.entity} -- ${e.detail}`)
+            .join('; ');
+         notify('notifications/message', {
+            level: 'warning',
+            logger: 'kbdb',
+            data: `Database integrity issues detected: ${summary}`,
+         });
+      }
+   } catch {
+      // Health check failure is non-fatal -- server continues
+   }
+}

package/src/shared/mcp/typings/mcp-capabilities.interface.ts

@@ -0,0 +1,16 @@
+/** MCP capability flags advertised during initialization. */
+export interface McpCapabilities {
+   /** Indicates the server supports the tools capability. */
+   readonly tools?: Record<string, unknown>;
+   /** Indicates the server supports the resources capability. */
+   readonly resources?: Record<string, unknown>;
+   /** Indicates the server supports the prompts capability. */
+   readonly prompts?: Record<string, unknown>;
+   /** Indicates the server supports the logging capability. */
+   readonly logging?: Record<string, unknown>;
+   /**
+    * Indicates the server supports the completions capability,
+    * providing argument auto-completion for prompts and resources.
+    */
+   readonly completions?: Record<string, unknown>;
+}

package/src/shared/mcp/typings/mcp-client.interface.ts

@@ -45,6 +45,18 @@ export interface McpIntegrityCheckResult {
    readonly elapsed_ms: number;
 }
 
+/** Export report returned by the daemon. */
+export interface McpExportResult {
+   /** Absolute path to the directory where files were written. */
+   readonly path: string;
+   /** Number of section files copied to the export directory. */
+   readonly sections_exported: number;
+   /** Number of document manifest files copied. */
+   readonly documents_exported: number;
+   /** Time taken to complete the export, in milliseconds. */
+   readonly elapsed_ms: number;
+}
+
 /** Garbage collection report returned by the daemon. */
 export interface McpGcResult {
    /** Number of unreferenced sections removed. */
@@ -53,6 +65,12 @@ export interface McpGcResult {
    readonly removed_bytes: number;
    /** Time taken to complete garbage collection, in milliseconds. */
    readonly elapsed_ms: number;
+   /**
+    * Number of sections whose source_path file no longer contains
+    * their heading text. Advisory; not auto-removed by gc.
+    * Absent on older daemon versions.
+    */
+   readonly stale_sources?: number;
 }
 
 /** Index rebuild report returned by the daemon. */
@@ -87,6 +105,8 @@ export interface McpWorkerClient {
       readonly limit?: number;
       /** Number of results to skip for pagination. */
       readonly offset?: number;
+      /** Search algorithm: 'lexical', 'vector', or 'hybrid'. */
+      readonly algo?: string;
    }): Promise<{
       readonly items: readonly {
          readonly kbid: string;
@@ -96,11 +116,20 @@ export interface McpWorkerClient {
          readonly score: number;
          readonly snippet: string;
          readonly matched_terms: readonly string[];
+         /** Fields that contained matches (heading, body, code). */
+         readonly matched_fields?: readonly string[];
+         /** ISO 8601 creation timestamp of the section. */
+         readonly created_at?: string;
       }[];
       readonly total: number;
       readonly offset: number;
       readonly limit: number;
       readonly has_more: boolean;
+      /**
+       * `true` when results came from an automatic AND-to-OR
+       * fallback query relaxation.
+       */
+      readonly relaxed?: boolean;
    }>;
 
    /**
@@ -120,6 +149,13 @@ export interface McpWorkerClient {
       readonly description?: string;
       /** Optional document ID to group this section under. */
       readonly docid?: string;
+      /** Optional tags for scoping and filtering. */
+      readonly tags?: string[];
+      /**
+       * When `true`, replaces an existing section that has the same
+       * source key (supersession).
+       */
+      readonly replace?: boolean;
    }): Promise<AddSectionResult>;
 
    /**
@@ -263,6 +299,17 @@ export interface McpWorkerClient {
       readonly depth?: number;
    }): Promise<unknown>;
 
+   /**
+    * Exports the database to a target directory as a self-contained
+    * snapshot (sections, documents, catalog -- no indexes).
+    *
+    * @param params - optional export parameters
+    * @returns export report with the resolved path and file counts
+    */
+   export(params?: {
+      readonly path?: string;
+   }): Promise<McpExportResult>;
+
    /** Destroys the IPC socket and clears the connection state. */
    disconnect(): void;
 }

package/src/shared/mcp/typings/mcp-completion.interface.ts

@@ -0,0 +1,45 @@
+/**
+ * Discriminated reference used in MCP completion requests.
+ * Identifies whether the completion target is a prompt or a resource.
+ */
+export interface McpCompletionRef {
+   /**
+    * The reference type: `'ref/prompt'` for named prompts (skills
+    * and agents) or `'ref/resource'` for resource URIs.
+    */
+   readonly type: 'ref/prompt' | 'ref/resource';
+   /** Prompt name, present when `type` is `'ref/prompt'`. */
+   readonly name?: string;
+   /** Resource URI, present when `type` is `'ref/resource'`. */
+   readonly uri?: string;
+}
+
+/**
+ * Completion argument supplied by the client, describing which
+ * argument is being completed and the current partial value.
+ */
+export interface McpCompletionArgument {
+   /** The argument name being completed. */
+   readonly name: string;
+   /** The partial value typed so far; used for prefix filtering. */
+   readonly value: string;
+}
+
+/**
+ * Result returned by `handleCompletion`, containing the list of
+ * matching completion values and pagination metadata.
+ */
+export interface McpCompletionResult {
+   /** Completion payload. */
+   readonly completion: {
+      /** Matching completion strings for the given prefix. */
+      readonly values: string[];
+      /**
+       * Whether more results are available beyond what is returned.
+       * Always `false` in this implementation.
+       */
+      readonly hasMore: boolean;
+      /** Total number of values returned. */
+      readonly total: number;
+   };
+}

package/src/shared/mcp/typings/mcp-content-result.model.ts

@@ -0,0 +1,9 @@
+/** Result returned by content composition. */
+export interface McpContentResult {
+   /** MIME type of the composed output, always `'text/markdown'`. */
+   readonly type: 'text/markdown';
+   /** The composed Markdown string. */
+   readonly data: string;
+   /** Character count of `data` (not byte count). */
+   readonly total: number;
+}

package/src/shared/mcp/typings/mcp-export-result.model.ts

@@ -0,0 +1,11 @@
+/** Export report returned by the daemon. */
+export interface McpExportResult {
+   /** Absolute path to the directory where files were written. */
+   readonly path: string;
+   /** Number of section files copied to the export directory. */
+   readonly sections_exported: number;
+   /** Number of document manifest files copied. */
+   readonly documents_exported: number;
+   /** Time taken to complete the export, in milliseconds. */
+   readonly elapsed_ms: number;
+}

package/src/shared/mcp/typings/mcp-gc-result.model.ts

@@ -0,0 +1,15 @@
+/** Garbage collection report returned by the daemon. */
+export interface McpGcResult {
+   /** Number of unreferenced sections removed. */
+   readonly removed_sections: number;
+   /** Total bytes freed by removing unreferenced sections. */
+   readonly removed_bytes: number;
+   /** Time taken to complete garbage collection, in milliseconds. */
+   readonly elapsed_ms: number;
+   /**
+    * Number of sections whose source_path file no longer contains
+    * their heading text. Advisory; not auto-removed by gc.
+    * Absent on older daemon versions.
+    */
+   readonly stale_sources?: number;
+}

package/src/shared/mcp/typings/mcp-integrity-check-result.model.ts

@@ -0,0 +1,17 @@
+import type { McpIntegrityError } from './mcp-integrity-error.model.ts';
+
+/** Integrity check report returned by the daemon. */
+export interface McpIntegrityCheckResult {
+   /** `true` when all checks passed and no errors were found. */
+   readonly ok: boolean;
+   /** All integrity errors found; empty when `ok` is `true`. */
+   readonly errors: McpIntegrityError[];
+   /** Total number of sections examined. */
+   readonly sections_checked: number;
+   /** Total number of documents examined. */
+   readonly documents_checked: number;
+   /** Total number of marker references checked. */
+   readonly references_checked: number;
+   /** Time taken to complete the check, in milliseconds. */
+   readonly elapsed_ms: number;
+}

package/src/shared/mcp/typings/mcp-integrity-error.model.ts

@@ -0,0 +1,15 @@
+/** A single integrity error found during a database check. */
+export interface McpIntegrityError {
+   /** The category of integrity violation detected. */
+   readonly type:
+      | 'checksum_mismatch'
+      | 'orphan_section'
+      | 'orphan_document'
+      | 'broken_reference'
+      | 'type_mismatch'
+      | 'circular_reference';
+   /** Identifier of the entity (kbid or docid) that has the issue. */
+   readonly entity: string;
+   /** Human-readable description of the specific problem. */
+   readonly detail: string;
+}

package/src/shared/mcp/typings/mcp-notification.interface.ts

@@ -0,0 +1,9 @@
+/** A JSON-RPC 2.0 notification with no expected response. */
+export interface McpNotification {
+   /** JSON-RPC protocol version. Must always be '2.0'. */
+   readonly jsonrpc: '2.0';
+   /** Notification method name. */
+   readonly method: string;
+   /** Optional notification parameters. */
+   readonly params?: Record<string, unknown>;
+}

package/src/shared/mcp/typings/mcp-rebuild-result.model.ts

@@ -0,0 +1,9 @@
+/** Index rebuild report returned by the daemon. */
+export interface McpRebuildResult {
+   /** Number of text and code sections that were re-indexed. */
+   readonly sections_reindexed: number;
+   /** Total number of unique terms written to the rebuilt indexes. */
+   readonly terms_indexed: number;
+   /** Time taken to complete the rebuild, in milliseconds. */
+   readonly elapsed_ms: number;
+}

package/src/shared/mcp/typings/mcp-request.interface.ts

@@ -0,0 +1,11 @@
+/** A JSON-RPC 2.0 request message sent to the MCP server. */
+export interface McpRequest {
+   /** JSON-RPC protocol version. Must always be '2.0'. */
+   readonly jsonrpc: '2.0';
+   /** Request identifier; absent for notifications. */
+   readonly id?: number | string;
+   /** RPC method name. */
+   readonly method: string;
+   /** Optional method parameters. */
+   readonly params?: Record<string, unknown>;
+}

package/src/shared/mcp/typings/mcp-resource-result.interface.ts

@@ -0,0 +1,12 @@
+/** Result returned by `handleResourceRead`. */
+export interface McpResourceResult {
+   /** One or more content items for the requested resource URI. */
+   readonly contents: readonly {
+      /** The resource URI that was read. */
+      readonly uri: string;
+      /** MIME type of the content body. */
+      readonly mimeType: string;
+      /** Text body of the resource. */
+      readonly text: string;
+   }[];
+}

package/src/shared/mcp/typings/mcp-resource-template.interface.ts

@@ -0,0 +1,11 @@
+/** A URI template describing an MCP resource the server serves. */
+export interface McpResourceTemplate {
+   /** RFC 6570 URI template for the resource. */
+   readonly uriTemplate: string;
+   /** Human-readable resource name. */
+   readonly name: string;
+   /** Human-readable description of the resource. */
+   readonly description: string;
+   /** Optional MIME type for the resource content. */
+   readonly mimeType?: string;
+}

package/src/shared/mcp/typings/mcp-response.interface.ts

@@ -0,0 +1,18 @@
+/** A JSON-RPC 2.0 response message sent from the MCP server. */
+export interface McpResponse {
+   /** JSON-RPC protocol version. Must always be '2.0'. */
+   readonly jsonrpc: '2.0';
+   /** Echoes the request identifier. */
+   readonly id: number | string;
+   /** Successful result payload; absent when error is set. */
+   readonly result?: unknown;
+   /** Error payload; absent when result is set. */
+   readonly error?: {
+      /** Numeric error code as defined by JSON-RPC or MCP. */
+      readonly code: number;
+      /** Human-readable error message. */
+      readonly message: string;
+      /** Optional additional error data. */
+      readonly data?: unknown;
+   };
+}

package/src/shared/mcp/typings/mcp-server-info.interface.ts

@@ -0,0 +1,7 @@
+/** Identity information for the MCP server. */
+export interface McpServerInfo {
+   /** Server name reported during MCP initialization. */
+   readonly name: string;
+   /** Server version string reported during MCP initialization. */
+   readonly version: string;
+}