@dikolab/kbdb 0.2.2 → 0.3.1

package/src/shared/mcp/constants/tool-skill-get.constant.ts

@@ -0,0 +1,27 @@
+import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
+
+/** MCP tool definition for the `skill-get` operation. */
+export const TOOL_SKILL_GET: McpToolDefinition = {
+   name: 'skill-get',
+   description: 'Get a skill definition by name or kbid.',
+   inputSchema: {
+      type: 'object',
+      properties: {
+         name: {
+            type: 'string',
+            description: 'Skill name',
+         },
+         kbid: {
+            type: 'string',
+            description: 'Knowledge base ID',
+         },
+      },
+   },
+   annotations: {
+      title: 'Get Skill',
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+   },
+};

package/src/shared/mcp/constants/tool-skill-learn.constant.ts

@@ -0,0 +1,37 @@
+import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
+
+/** MCP tool definition for the `skill-learn` operation. */
+export const TOOL_SKILL_LEARN: McpToolDefinition = {
+   name: 'skill-learn',
+   description:
+      'Create or update a skill definition.' +
+      ' Skills are reusable AI agent capabilities' +
+      ' with template placeholders.',
+   inputSchema: {
+      type: 'object',
+      properties: {
+         name: {
+            type: 'string',
+            description: 'Skill name',
+         },
+         description: {
+            type: 'string',
+            description: 'Skill description',
+         },
+         body: {
+            type: 'string',
+            description:
+               'Skill body template.' +
+               ' Use {{argName}} for placeholders.',
+         },
+      },
+      required: ['name', 'body'],
+   },
+   annotations: {
+      title: 'Create Skill',
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+   },
+};

package/src/shared/mcp/constants/tool-skill-list.constant.ts

@@ -0,0 +1,18 @@
+import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
+
+/** MCP tool definition for the `skill-list` operation. */
+export const TOOL_SKILL_LIST: McpToolDefinition = {
+   name: 'skill-list',
+   description: 'List all skills in the knowledge base.',
+   inputSchema: {
+      type: 'object',
+      properties: {},
+   },
+   annotations: {
+      title: 'List Skills',
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+   },
+};

package/src/shared/mcp/constants/tool-status.constant.ts

@@ -0,0 +1,20 @@
+import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
+
+/** MCP tool definition for the `status` operation. */
+export const TOOL_STATUS: McpToolDefinition = {
+   name: 'status',
+   description:
+      'Get database metadata including document count,' +
+      ' section count, index size, and cache statistics.',
+   inputSchema: {
+      type: 'object',
+      properties: {},
+   },
+   annotations: {
+      title: 'DB Status',
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+   },
+};

package/src/shared/mcp/constants/tool-unlearn.constant.ts

@@ -0,0 +1,25 @@
+import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
+
+/** MCP tool definition for the `unlearn` operation. */
+export const TOOL_UNLEARN: McpToolDefinition = {
+   name: 'unlearn',
+   description:
+      'Remove a section from the knowledge base' + ' by its kb-id.',
+   inputSchema: {
+      type: 'object',
+      properties: {
+         kbid: {
+            type: 'string',
+            description: 'Knowledge base ID of the section',
+         },
+      },
+      required: ['kbid'],
+   },
+   annotations: {
+      title: 'Remove Section',
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: false,
+   },
+};

package/src/shared/mcp/functions/as-boolean-or-undefined.function.ts

@@ -0,0 +1,11 @@
+/**
+ * Narrows an `unknown` value to a boolean, returning `undefined`
+ * when the value is not a boolean.
+ *
+ * @param value - the value to narrow
+ */
+export function asBooleanOrUndefined(
+   value: unknown,
+): boolean | undefined {
+   return typeof value === 'boolean' ? value : undefined;
+}

package/src/shared/mcp/functions/as-string-array-or-undefined.function.ts

@@ -0,0 +1,17 @@
+/**
+ * Narrows an `unknown` value to a `string[]`, returning `undefined`
+ * when the value is not an array of strings.
+ *
+ * @param value - the value to narrow
+ */
+export function asStringArrayOrUndefined(
+   value: unknown,
+): string[] | undefined {
+   if (
+      Array.isArray(value) &&
+      value.every((item) => typeof item === 'string')
+   ) {
+      return value;
+   }
+   return undefined;
+}

package/src/shared/mcp/functions/as-string-array.function.ts

@@ -0,0 +1,15 @@
+/**
+ * Narrows an `unknown` value to a `string[]`, returning an empty
+ * array when the value is not an array of strings.
+ *
+ * @param value - the value to narrow
+ */
+export function asStringArray(value: unknown): string[] {
+   if (
+      Array.isArray(value) &&
+      value.every((item) => typeof item === 'string')
+   ) {
+      return value;
+   }
+   return [];
+}

package/src/shared/mcp/functions/as-string.function.ts

@@ -0,0 +1,10 @@
+/**
+ * Narrows an `unknown` value to a string, returning the fallback
+ * when the value is not already a string.
+ *
+ * @param value - the value to narrow
+ * @param fallback - returned when `value` is not a string
+ */
+export function asString(value: unknown, fallback: string): string {
+   return typeof value === 'string' ? value : fallback;
+}

package/src/shared/mcp/functions/build-skills-text.function.ts

@@ -0,0 +1,43 @@
+/** Minimal section shape for building the skills listing text. */
+export interface SkillSection {
+   /** Knowledge-base identifier of the section. */
+   readonly kbid: string;
+   /** Raw JSON content of the skill section. */
+   readonly content: string;
+}
+
+/**
+ * Builds a human-readable skills listing from an array of skill
+ * section records.
+ *
+ * Sections whose JSON is not parseable or whose `name` field is
+ * absent are silently omitted. Returns `null` when no valid skills
+ * remain after filtering.
+ *
+ * @param skillSections - array of section records to summarise
+ */
+export function buildSkillsText(
+   skillSections: SkillSection[],
+): string | null {
+   const lines: string[] = [];
+   for (const sec of skillSections) {
+      try {
+         const parsed = JSON.parse(sec.content) as Record<
+            string,
+            unknown
+         >;
+         const name =
+            typeof parsed['name'] === 'string' ? parsed['name'] : null;
+         if (name === null) continue;
+         const description =
+            typeof parsed['description'] === 'string'
+               ? parsed['description']
+               : '';
+         lines.push(`- ${name}: ${description}`);
+      } catch {
+         // skip unparseable sections
+      }
+   }
+   if (lines.length === 0) return null;
+   return `Available skills:\n${lines.join('\n')}`;
+}

package/src/shared/mcp/functions/create-tool-definitions.function.ts

@@ -10,10 +10,11 @@ export function createToolDefinitions(): McpToolDefinition[] {
       {
          name: 'search',
          description:
-            'Search the knowledge base. Returns ranked' +
-            ' results with headings and snippets for' +
-            ' relevance evaluation. Use `recall` to' +
-            ' get full content of specific results.',
+            'Query the knowledge base by keywords.' +
+            ' Returns ranked results with heading,' +
+            ' snippet, and matched terms. Use multiple' +
+            ' short keyword queries for best coverage.' +
+            ' Use recall to get full content.',
          inputSchema: {
             type: 'object',
             properties: {
@@ -36,6 +37,11 @@ export function createToolDefinitions(): McpToolDefinition[] {
                      'Number of results to skip for' +
                      ' pagination (default: 0)',
                },
+               algo: {
+                  type: 'string',
+                  enum: ['lexical', 'vector', 'hybrid'],
+                  description: 'Search algorithm (default: lexical)',
+               },
             },
             required: ['query'],
          },
@@ -49,7 +55,11 @@ export function createToolDefinitions(): McpToolDefinition[] {
       },
       {
          name: 'learn',
-         description: 'Add a text section to the knowledge base.',
+         description:
+            'Import content into the knowledge base.' +
+            ' Use for durable facts, decisions, and' +
+            ' corrections. Use replace when updating' +
+            ' existing knowledge. Attach tags for scoping.',
          inputSchema: {
             type: 'object',
             properties: {
@@ -76,6 +86,17 @@ export function createToolDefinitions(): McpToolDefinition[] {
                   type: 'string',
                   description: 'Document ID to group under',
                },
+               tags: {
+                  type: 'array',
+                  items: { type: 'string' },
+                  description: 'Tags for scoping and filtering',
+               },
+               replace: {
+                  type: 'boolean',
+                  description:
+                     'Replace existing section with same' +
+                     ' source key (supersession)',
+               },
             },
             required: ['content'],
          },
@@ -268,6 +289,31 @@ export function createToolDefinitions(): McpToolDefinition[] {
             openWorldHint: false,
          },
       },
+      {
+         name: 'export',
+         description:
+            'Export the database as a self-contained' +
+            ' directory snapshot (sections, documents,' +
+            ' catalog -- no indexes).',
+         inputSchema: {
+            type: 'object',
+            properties: {
+               path: {
+                  type: 'string',
+                  description:
+                     'Export destination path' +
+                     ' (default: ./kbdb-export/)',
+               },
+            },
+         },
+         annotations: {
+            title: 'Export Snapshot',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+         },
+      },
       {
          name: 'skill-learn',
          description:
@@ -457,5 +503,28 @@ export function createToolDefinitions(): McpToolDefinition[] {
             openWorldHint: false,
          },
       },
+      {
+         name: 'auto-capture-review',
+         description:
+            'Review and approve pending auto-captured' +
+            ' knowledge before storage.',
+         inputSchema: {
+            type: 'object',
+            properties: {
+               action: {
+                  type: 'string',
+                  enum: ['list', 'approve', 'reject'],
+                  description: 'Action to perform on pending captures',
+               },
+            },
+         },
+         annotations: {
+            title: 'Auto-Capture Review',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+         },
+      },
    ];
 }

package/src/shared/mcp/functions/handle-agent-create.function.ts

@@ -99,7 +99,7 @@ export async function handleAgentCreate(
    });
 
    const allKbids = [metaResult.kbid, ...skills];
-   const docid = await client.groupSections(name, allKbids);
+   const docid = await client.groupSections(name, allKbids, 'agent');
 
    return {
       content: [

package/src/shared/mcp/functions/handle-agent-prompt.function.ts

@@ -0,0 +1,68 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { McpPromptMessage } from '../typings/prompt-types.interface.ts';
+import { parseAgentMeta } from './parse-agent-meta.function.ts';
+import { buildSkillsText } from './build-skills-text.function.ts';
+
+/** Minimal agent document shape returned by retrieveDocument. */
+interface AgentDocument {
+   /** Document identifier. */
+   readonly docid: string;
+   /** Document title. */
+   readonly title: string;
+   /** Ordered section references. */
+   readonly sections: readonly {
+      readonly kbid: string;
+      readonly position: number;
+   }[];
+}
+
+/**
+ * Handles an MCP `prompts/get` request for an agent prompt.
+ *
+ * Reads the agent document, extracts its persona from the metadata
+ * section, then reads all skill sections and composes the response.
+ * Returns an assistant message with the persona and, when skills
+ * exist, a user message listing them.
+ *
+ * @param name - prompt name with `agent:` prefix
+ * @param client - worker client used to access the knowledge base
+ */
+export async function handleAgentPrompt(
+   name: string,
+   client: McpWorkerClient,
+): Promise<McpPromptMessage[]> {
+   const docid = name.slice(6);
+   const doc = (await client.retrieveDocument(docid)) as AgentDocument;
+   const metaSection = doc.sections.at(0);
+   const skillRefs = doc.sections.slice(1);
+
+   let persona = '';
+   if (metaSection !== undefined) {
+      const metaSections = await client.readSections([
+         metaSection.kbid,
+      ]);
+      const metaContent = metaSections.at(0);
+      if (metaContent !== undefined) {
+         persona = parseAgentMeta(metaContent.content).persona;
+      }
+   }
+
+   const messages: McpPromptMessage[] = [
+      { role: 'assistant', content: { type: 'text', text: persona } },
+   ];
+
+   if (skillRefs.length === 0) return messages;
+
+   const skillKbids = skillRefs.map((s) => s.kbid);
+   const skillSections = await client.readSections(skillKbids);
+   const skillsText = buildSkillsText(skillSections);
+
+   if (skillsText !== null) {
+      messages.push({
+         role: 'user',
+         content: { type: 'text', text: skillsText },
+      });
+   }
+
+   return messages;
+}

package/src/shared/mcp/functions/handle-mcp-request.function.ts

@@ -0,0 +1,202 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type {
+   McpRequest,
+   McpResponse,
+} from '../typings/mcp-types.interface.ts';
+import type { McpLogLevel } from '../typings/log-types.interface.ts';
+import type {
+   McpCompletionRef,
+   McpCompletionArgument,
+} from '../typings/mcp-completion.interface.ts';
+import type { McpServerState } from '../typings/mcp-server-state.interface.ts';
+import { createToolDefinitions } from './create-tool-definitions.function.ts';
+import { createResourceTemplates } from './create-resource-templates.function.ts';
+import { handleToolCall } from './handle-tool-call.function.ts';
+import { handleResourceRead } from './handle-resource-read.function.ts';
+import { createPromptDefinitions } from './create-prompt-definitions.function.ts';
+import { handlePromptGet } from './handle-prompt-get.function.ts';
+import { handleCompletion } from './handle-completion.function.ts';
+import { handleRootsList } from './handle-roots-list.function.ts';
+import {
+   METHOD_NOT_FOUND,
+   RESOURCE_NOT_FOUND,
+} from '../constants/mcp-error-codes.constant.ts';
+
+/**
+ * Routes an MCP JSON-RPC request to the appropriate handler and
+ * returns the JSON-RPC response. Mutates `state` for methods that
+ * update server-side configuration (logging level, subscriptions,
+ * capabilities).
+ *
+ * @param request - the parsed MCP request
+ * @param client - worker client for knowledge-base operations
+ * @param state - mutable server state shared with `McpServer`
+ */
+export async function handleMcpRequest(
+   request: McpRequest,
+   client: McpWorkerClient,
+   state: McpServerState,
+): Promise<McpResponse> {
+   const id = request.id as number | string;
+
+   switch (request.method) {
+      case 'initialize': {
+         const params = request.params ?? {};
+         const caps = params['capabilities'];
+         state.hostCapabilities = caps
+            ? (caps as Record<string, unknown>)
+            : null;
+         return {
+            jsonrpc: '2.0',
+            id,
+            result: {
+               protocolVersion: '2025-11-25',
+               serverInfo: { name: 'kbdb', version: '0.1.0' },
+               capabilities: {
+                  tools: {},
+                  resources: { subscribe: true },
+                  prompts: {},
+                  logging: {},
+                  completions: {},
+               },
+            },
+         };
+      }
+
+      case 'ping':
+         return { jsonrpc: '2.0', id, result: {} };
+
+      case 'tools/list':
+         return {
+            jsonrpc: '2.0',
+            id,
+            result: { tools: createToolDefinitions() },
+         };
+
+      case 'resources/list':
+         return { jsonrpc: '2.0', id, result: { resources: [] } };
+
+      case 'resources/templates/list':
+         return {
+            jsonrpc: '2.0',
+            id,
+            result: { resourceTemplates: createResourceTemplates() },
+         };
+
+      case 'tools/call': {
+         const params = request.params ?? {};
+         const rawName = params['name'];
+         const name = typeof rawName === 'string' ? rawName : '';
+         const args = (params['arguments'] ?? {}) as Record<
+            string,
+            unknown
+         >;
+         const result = await handleToolCall(client, name, args);
+         return { jsonrpc: '2.0', id, result };
+      }
+
+      case 'resources/read': {
+         const params = request.params ?? {};
+         const rawUri = params['uri'];
+         const uri = typeof rawUri === 'string' ? rawUri : '';
+         try {
+            const result = await handleResourceRead(client, uri);
+            return { jsonrpc: '2.0', id, result };
+         } catch (err) {
+            return {
+               jsonrpc: '2.0',
+               id,
+               error: {
+                  code: RESOURCE_NOT_FOUND,
+                  message:
+                     err instanceof Error ? err.message : String(err),
+               },
+            };
+         }
+      }
+
+      case 'prompts/list': {
+         const skills = await client.listByType('skill');
+         const agents = await client.listDocumentsByType('agent');
+         const prompts = createPromptDefinitions(skills, agents);
+         return { jsonrpc: '2.0', id, result: { prompts } };
+      }
+
+      case 'prompts/get': {
+         const params = request.params ?? {};
+         const name =
+            typeof params['name'] === 'string' ? params['name'] : '';
+         const promptArgs = (params['arguments'] ?? {}) as Record<
+            string,
+            string
+         >;
+         try {
+            const messages = await handlePromptGet(
+               name,
+               promptArgs,
+               client,
+            );
+            return { jsonrpc: '2.0', id, result: { messages } };
+         } catch (err) {
+            return {
+               jsonrpc: '2.0',
+               id,
+               error: {
+                  code: RESOURCE_NOT_FOUND,
+                  message:
+                     err instanceof Error ? err.message : String(err),
+               },
+            };
+         }
+      }
+
+      case 'completion/complete': {
+         const params = request.params ?? {};
+         const ref = params['ref'] as McpCompletionRef;
+         const argument = (params['argument'] ?? {
+            name: '',
+            value: '',
+         }) as McpCompletionArgument;
+         const result = await handleCompletion(ref, argument, client);
+         return { jsonrpc: '2.0', id, result };
+      }
+
+      case 'roots/list': {
+         const roots = handleRootsList(state.contextPath);
+         return { jsonrpc: '2.0', id, result: { roots } };
+      }
+
+      case 'logging/setLevel': {
+         const params = request.params ?? {};
+         const level = params['level'] as McpLogLevel | undefined;
+         state.logLevel = level ?? null;
+         return { jsonrpc: '2.0', id, result: {} };
+      }
+
+      case 'resources/subscribe': {
+         const params = request.params ?? {};
+         const uri =
+            typeof params['uri'] === 'string' ? params['uri'] : '';
+         state.subscriptions.add(uri);
+         return { jsonrpc: '2.0', id, result: {} };
+      }
+
+      case 'resources/unsubscribe': {
+         const params = request.params ?? {};
+         const uri =
+            typeof params['uri'] === 'string' ? params['uri'] : '';
+         state.subscriptions.delete(uri);
+         return { jsonrpc: '2.0', id, result: {} };
+      }
+
+      default:
+         return {
+            jsonrpc: '2.0',
+            id,
+            error: {
+               code: METHOD_NOT_FOUND,
+               message: `Method not found: ` + request.method,
+            },
+         };
+   }
+}