@dikolab/kbdb 0.3.0 → 0.3.1

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

@@ -37,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'],
          },
@@ -498,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,
+            },
+         };
+   }
+}

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

@@ -15,10 +15,8 @@ interface ReadSection {
    readonly content: string;
 }
 
-/** Minimal agent document shape returned by retrieveDocument. */
+/** Minimal agent document shape from listDocumentsByType. */
 interface AgentDocument {
-   /** Document identifier. */
-   readonly docid: string;
    /** Document title. */
    readonly title: string;
    /** Ordered section references. */
@@ -86,17 +84,24 @@ function buildSkillsText(skillSections: ReadSection[]): string | null {
 /**
  * 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.
+ * Looks up the agent by title via `listDocumentsByType('agent')`,
+ * 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.
  */
 async function handleAgentPrompt(
    name: string,
    client: McpWorkerClient,
 ): Promise<McpPromptMessage[]> {
-   const docid = name.slice(6);
-   const doc = (await client.retrieveDocument(docid)) as AgentDocument;
+   const agentName = name.slice(6);
+   const agents = await client.listDocumentsByType('agent');
+   const doc = agents.find((a) => a.title === agentName) as
+      | AgentDocument
+      | undefined;
+   if (!doc) {
+      throw new Error('agent not found: ' + agentName);
+   }
    const sections = doc.sections;
 
    const metaSection = sections.at(0);
@@ -192,9 +197,10 @@ async function handleSkillPrompt(
  * substitutes `{{argName}}` placeholders in the body, and returns a
  * single user message.
  *
- * For agent prompts: reads the agent document via `retrieveDocument`,
- * builds an assistant message from the persona section, and (when
- * skills exist) a user message listing their names and descriptions.
+ * For agent prompts: looks up the agent by title via
+ * `listDocumentsByType('agent')`, builds an assistant message from
+ * the persona section, and (when skills exist) a user message
+ * listing their names and descriptions.
  *
  * @param name - prompt name from the MCP request
  * @param promptArgs - argument key-value map from the MCP request

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

@@ -0,0 +1,44 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { McpPromptMessage } from '../typings/prompt-types.interface.ts';
+
+/**
+ * Handles an MCP `prompts/get` request for a skill prompt.
+ *
+ * Looks up the skill by name in the `listByType('skill')` results,
+ * picks the most recent match (last occurrence), parses its body,
+ * and substitutes `{{argName}}` placeholders from `promptArgs`.
+ * Unresolved placeholders are left as-is.
+ *
+ * @param name - skill prompt name to look up
+ * @param promptArgs - argument key-value map from the MCP request
+ * @param client - worker client used to access the knowledge base
+ * @throws {Error} when no skill with the given name is found
+ */
+export async function handleSkillPrompt(
+   name: string,
+   promptArgs: Record<string, string>,
+   client: McpWorkerClient,
+): Promise<McpPromptMessage[]> {
+   const sections = await client.listByType('skill');
+   let matchContent: string | undefined;
+   for (const sec of sections) {
+      if (sec.title === name) {
+         matchContent = sec.content;
+      }
+   }
+   if (matchContent === undefined) {
+      throw new Error(`Prompt not found: ${name}`);
+   }
+
+   const parsed = JSON.parse(matchContent) as Record<string, unknown>;
+   const body =
+      typeof parsed['body'] === 'string' ? parsed['body'] : '';
+
+   const rendered = body.replace(
+      /\{\{(\w+)\}\}/g,
+      (_match, key: string) =>
+         key in promptArgs ? (promptArgs[key] ?? _match) : _match,
+   );
+
+   return [{ role: 'user', content: { type: 'text', text: rendered } }];
+}

package/src/shared/mcp/functions/handle-tool-auto-capture-review.function.ts

@@ -0,0 +1,24 @@
+import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
+
+/**
+ * Handles the `auto-capture-review` MCP tool call.
+ *
+ * Returns a stub response indicating no pending captures are
+ * available. Full implementation requires wiring the auto-capture
+ * controller into the MCP server state.
+ *
+ * @param _args - tool arguments; `action` may be list, approve,
+ *   or reject
+ */
+export function handleToolAutoCaptureReview(
+   _args: Record<string, unknown>,
+): Promise<ToolCallResult> {
+   return Promise.resolve({
+      content: [
+         {
+            type: 'text' as const,
+            text: 'No pending auto-captured knowledge entries.',
+         },
+      ],
+   });
+}

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

@@ -124,6 +124,8 @@ export async function handleToolCall(
             return await handleAgentGet(client, args);
          case 'agent-delete':
             return await handleAgentDelete(client, args);
+         case 'auto-capture-review':
+            return handleAutoCaptureReview();
          default:
             return {
                content: [
@@ -157,6 +159,7 @@ async function handleSearch(
       mode: args['mode'] as string | undefined,
       limit: args['limit'] as number | undefined,
       offset: args['offset'] as number | undefined,
+      algo: args['algo'] as string | undefined,
    });
 
    const stripped = {
@@ -226,6 +229,7 @@ async function handleLearn(
       near_duplicates: (result.near_duplicates ?? []).map((d) => ({
          kbid: d.kbid,
          similarity: d.similarity,
+         ...(d.method !== undefined ? { method: d.method } : {}),
       })),
    };
    return {
@@ -522,6 +526,20 @@ async function handleSkillDelete(
    };
 }
 
+function handleAutoCaptureReview(): ToolCallResult {
+   return {
+      content: [
+         {
+            type: 'text',
+            text: JSON.stringify({
+               pending: [],
+               message: 'No pending auto-captured knowledge entries.',
+            }),
+         },
+      ],
+   };
+}
+
 async function handleExport(
    client: McpWorkerClient,
    args: Record<string, unknown>,

package/src/shared/mcp/functions/handle-tool-check.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 `check` MCP tool call.
+ *
+ * Runs an integrity check on the knowledge base and returns the
+ * report as formatted JSON.
+ *
+ * @param client - the worker client used to execute operations
+ */
+export async function handleToolCheck(
+   client: McpWorkerClient,
+): Promise<ToolCallResult> {
+   const report = await client.integrityCheck();
+   return {
+      content: [
+         { type: 'text', text: JSON.stringify(report, null, 2) },
+      ],
+   };
+}

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

@@ -0,0 +1,23 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
+import { asStringArray } from './as-string-array.function.ts';
+
+/**
+ * Handles the `content` MCP tool call.
+ *
+ * Composes a rendered Markdown document from the given identifiers
+ * and returns the result as JSON.
+ *
+ * @param client - the worker client used to execute operations
+ * @param args - tool arguments from the MCP request
+ */
+export async function handleToolContent(
+   client: McpWorkerClient,
+   args: Record<string, unknown>,
+): Promise<ToolCallResult> {
+   const ids = asStringArray(args['ids']);
+   const result = await client.content(ids);
+   return {
+      content: [{ type: 'text', text: JSON.stringify(result) }],
+   };
+}