@dikolab/kbdb 0.3.1 → 0.4.0

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

@@ -1,560 +0,0 @@
-import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
-import { extractSkillArguments } from './extract-skill-arguments.function.ts';
-import { parseSkillContent } from './parse-skill-content.function.ts';
-import { serializeSkillContent } from './serialize-skill-content.function.ts';
-import { handleAgentCreate } from './handle-agent-create.function.ts';
-import { handleAgentList } from './handle-agent-list.function.ts';
-import { handleAgentGet } from './handle-agent-get.function.ts';
-import { handleAgentDelete } from './handle-agent-delete.function.ts';
-import { handleRecall } from './handle-recall.function.ts';
-
-/** Shape of a content item in an MCP tool call response. */
-interface ToolContent {
-   /** Content type identifier, typically 'text'. */
-   readonly type: string;
-   /** The text payload. */
-   readonly text: string;
-}
-
-/** Result returned by a tool call handler. */
-interface ToolCallResult {
-   /** One or more content items describing the result. */
-   readonly content: ToolContent[];
-   /** Set to `true` when the tool encountered an error. */
-   readonly isError?: boolean;
-}
-
-/**
- * Narrows an `unknown` value to a string, returning the fallback
- * when the value is not already a string.
- */
-function asString(value: unknown, fallback: string): string {
-   return typeof value === 'string' ? value : fallback;
-}
-
-/**
- * Narrows an `unknown` value to a boolean, returning `undefined`
- * when the value is not a boolean.
- */
-function asBooleanOrUndefined(value: unknown): boolean | undefined {
-   return typeof value === 'boolean' ? value : undefined;
-}
-
-/**
- * Narrows an `unknown` value to a `string[]`, returning `undefined`
- * when the value is not an array of strings.
- */
-function asStringArrayOrUndefined(
-   value: unknown,
-): string[] | undefined {
-   if (
-      Array.isArray(value) &&
-      value.every((item) => typeof item === 'string')
-   ) {
-      return value;
-   }
-   return undefined;
-}
-
-/**
- * Narrows an `unknown` value to a `string[]`, returning an empty
- * array when the value is not an array of strings.
- */
-function asStringArray(value: unknown): string[] {
-   if (
-      Array.isArray(value) &&
-      value.every((item) => typeof item === 'string')
-   ) {
-      return value;
-   }
-   return [];
-}
-
-/**
- * Dispatches an MCP tool call to the appropriate knowledge-base
- * operation and returns the result formatted as MCP content.
- *
- * @param client - the worker client used to execute operations
- * @param name - the tool name to invoke
- * @param args - tool arguments from the MCP request
- * @returns content items with optional isError flag
- */
-export async function handleToolCall(
-   client: McpWorkerClient,
-   name: string,
-   args: Record<string, unknown>,
-): Promise<ToolCallResult> {
-   try {
-      switch (name) {
-         case 'search':
-            return await handleSearch(client, args);
-         case 'learn':
-            return await handleLearn(client, args);
-         case 'unlearn':
-            return await handleUnlearn(client, args);
-         case 'retrieve':
-            return await handleRetrieve(client, args);
-         case 'recall':
-            return await handleRecall(client, args);
-         case 'status':
-            return await handleStatus(client);
-         case 'content':
-            return await handleContent(client, args);
-         case 'check':
-            return await handleCheck(client);
-         case 'gc':
-            return await handleGc(client);
-         case 'rebuild':
-            return await handleRebuild(client);
-         case 'export':
-            return await handleExport(client, args);
-         case 'skill-learn':
-            return await handleSkillLearn(client, args);
-         case 'skill-list':
-            return await handleSkillList(client);
-         case 'skill-get':
-            return await handleSkillGet(client, args);
-         case 'skill-delete':
-            return await handleSkillDelete(client, args);
-         case 'agent-create':
-            return await handleAgentCreate(client, args);
-         case 'agent-list':
-            return await handleAgentList(client);
-         case 'agent-get':
-            return await handleAgentGet(client, args);
-         case 'agent-delete':
-            return await handleAgentDelete(client, args);
-         case 'auto-capture-review':
-            return handleAutoCaptureReview();
-         default:
-            return {
-               content: [
-                  {
-                     type: 'text',
-                     text: `Unknown tool: ${name}`,
-                  },
-               ],
-               isError: true,
-            };
-      }
-   } catch (err) {
-      return {
-         content: [
-            {
-               type: 'text',
-               text: err instanceof Error ? err.message : String(err),
-            },
-         ],
-         isError: true,
-      };
-   }
-}
-
-async function handleSearch(
-   client: McpWorkerClient,
-   args: Record<string, unknown>,
-): Promise<ToolCallResult> {
-   const results = await client.search({
-      query: asString(args['query'], ''),
-      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 = {
-      ...results,
-      items: results.items.map(
-         ({
-            score: _score,
-            confidence: _confidence,
-            ...rest
-         }: (typeof results.items)[number] & {
-            confidence?: number;
-         }) => rest,
-      ),
-   };
-
-   return {
-      content: [
-         {
-            type: 'text',
-            text: JSON.stringify(stripped, null, 2),
-         },
-      ],
-   };
-}
-
-async function handleLearn(
-   client: McpWorkerClient,
-   args: Record<string, unknown>,
-): Promise<ToolCallResult> {
-   const sectionType = asString(args['type'], 'text/markdown');
-   const title =
-      typeof args['title'] === 'string' ? args['title'] : undefined;
-   const description =
-      typeof args['description'] === 'string'
-         ? args['description']
-         : undefined;
-   const docid =
-      typeof args['docid'] === 'string' ? args['docid'] : undefined;
-   const tags = asStringArrayOrUndefined(args['tags']);
-   const replace = asBooleanOrUndefined(args['replace']);
-   if (sectionType.startsWith('image/') && !title) {
-      return {
-         content: [
-            {
-               type: 'text',
-               text: 'title is required for image/* types',
-            },
-         ],
-         isError: true,
-      };
-   }
-   const result = await client.addSection({
-      sectionType,
-      content: asString(args['content'], ''),
-      title,
-      description,
-      docid,
-      tags,
-      replace,
-   });
-   const normalized = {
-      kbid: result.kbid,
-      indexed_terms_count: result.indexed_terms_count ?? 0,
-      elapsed_ms: result.elapsed_ms ?? 0,
-      superseded: result.superseded ?? null,
-      warnings: result.warnings ?? [],
-      near_duplicates: (result.near_duplicates ?? []).map((d) => ({
-         kbid: d.kbid,
-         similarity: d.similarity,
-         ...(d.method !== undefined ? { method: d.method } : {}),
-      })),
-   };
-   return {
-      content: [
-         {
-            type: 'text',
-            text: JSON.stringify(normalized),
-         },
-      ],
-   };
-}
-
-async function handleUnlearn(
-   client: McpWorkerClient,
-   args: Record<string, unknown>,
-): Promise<ToolCallResult> {
-   const result = await client.removeSection(
-      asString(args['kbid'], ''),
-   );
-   return {
-      content: [
-         {
-            type: 'text',
-            text: JSON.stringify(result),
-         },
-      ],
-   };
-}
-
-async function handleRetrieve(
-   client: McpWorkerClient,
-   args: Record<string, unknown>,
-): Promise<ToolCallResult> {
-   if (typeof args['kbid'] === 'string') {
-      const sections = await client.readSections([args['kbid']]);
-      return {
-         content: [
-            {
-               type: 'text',
-               text: JSON.stringify(sections, null, 2),
-            },
-         ],
-      };
-   }
-   if (typeof args['docid'] === 'string') {
-      const doc = await client.retrieveDocument(args['docid']);
-      return {
-         content: [
-            {
-               type: 'text',
-               text: JSON.stringify(doc, null, 2),
-            },
-         ],
-      };
-   }
-   return {
-      content: [
-         {
-            type: 'text',
-            text: 'Provide kbid or docid',
-         },
-      ],
-      isError: true,
-   };
-}
-
-async function handleStatus(
-   client: McpWorkerClient,
-): Promise<ToolCallResult> {
-   const status = await client.dbStatus();
-   return {
-      content: [
-         {
-            type: 'text',
-            text: JSON.stringify(status, null, 2),
-         },
-      ],
-   };
-}
-
-async function handleContent(
-   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),
-         },
-      ],
-   };
-}
-
-async function handleCheck(
-   client: McpWorkerClient,
-): Promise<ToolCallResult> {
-   const report = await client.integrityCheck();
-   return {
-      content: [
-         {
-            type: 'text',
-            text: JSON.stringify(report, null, 2),
-         },
-      ],
-   };
-}
-
-async function handleGc(
-   client: McpWorkerClient,
-): Promise<ToolCallResult> {
-   const report = await client.gc();
-   return {
-      content: [
-         {
-            type: 'text',
-            text: JSON.stringify(report, null, 2),
-         },
-      ],
-   };
-}
-
-async function handleRebuild(
-   client: McpWorkerClient,
-): Promise<ToolCallResult> {
-   const report = await client.rebuildIndexes();
-   return {
-      content: [
-         {
-            type: 'text',
-            text: JSON.stringify(report, null, 2),
-         },
-      ],
-   };
-}
-
-async function handleSkillLearn(
-   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 }),
-         },
-      ],
-   };
-}
-
-async function handleSkillList(
-   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),
-         },
-      ],
-   };
-}
-
-async function handleSkillGet(
-   client: McpWorkerClient,
-   args: Record<string, unknown>,
-): Promise<ToolCallResult> {
-   const kbid =
-      typeof args['kbid'] === 'string' ? args['kbid'] : undefined;
-   const name =
-      typeof args['name'] === 'string' ? args['name'] : undefined;
-   if (!kbid && !name) {
-      return {
-         content: [
-            {
-               type: 'text',
-               text: 'name or kbid is required',
-            },
-         ],
-         isError: true,
-      };
-   }
-   let content: string | undefined;
-   if (kbid) {
-      const sections = await client.readSections([kbid]);
-      if (sections.length > 0) {
-         content = sections[0]?.content;
-      }
-   }
-   if (content === undefined && name) {
-      const records = await client.listByType('skill');
-      const match = records.filter((r) => r.title === name).pop();
-      if (match) {
-         content = match.content;
-      }
-   }
-   if (content === undefined) {
-      const identifier = kbid ?? name ?? '';
-      return {
-         content: [
-            {
-               type: 'text',
-               text: `skill not found: ${identifier}`,
-            },
-         ],
-         isError: true,
-      };
-   }
-   const skill = parseSkillContent(content);
-   return {
-      content: [
-         {
-            type: 'text',
-            text: JSON.stringify(skill, null, 2),
-         },
-      ],
-   };
-}
-
-async function handleSkillDelete(
-   client: McpWorkerClient,
-   args: Record<string, unknown>,
-): Promise<ToolCallResult> {
-   const kbid = asString(args['kbid'], '');
-   if (!kbid) {
-      return {
-         content: [{ type: 'text', text: 'kbid is required' }],
-         isError: true,
-      };
-   }
-   const result = await client.removeSection(kbid);
-   return {
-      content: [
-         {
-            type: 'text',
-            text: JSON.stringify({ kbid, removed: result.removed }),
-         },
-      ],
-   };
-}
-
-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>,
-): Promise<ToolCallResult> {
-   const path =
-      typeof args['path'] === 'string' ? args['path'] : undefined;
-   const result = await client.export(
-      path !== undefined ? { path } : {},
-   );
-   return {
-      content: [
-         {
-            type: 'text',
-            text: JSON.stringify(result),
-         },
-      ],
-   };
-}

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

@@ -1,21 +0,0 @@
-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

@@ -1,23 +0,0 @@
-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) }],
-   };
-}

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

@@ -1,25 +0,0 @@
-import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
-import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
-
-/**
- * Handles the `export` MCP tool call.
- *
- * Exports the database as a self-contained directory snapshot.
- * Passes the optional `path` argument when supplied.
- *
- * @param client - the worker client used to execute operations
- * @param args - tool arguments from the MCP request
- */
-export async function handleToolExport(
-   client: McpWorkerClient,
-   args: Record<string, unknown>,
-): Promise<ToolCallResult> {
-   const path =
-      typeof args['path'] === 'string' ? args['path'] : undefined;
-   const result = await client.export(
-      path !== undefined ? { path } : {},
-   );
-   return {
-      content: [{ type: 'text', text: JSON.stringify(result) }],
-   };
-}

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

@@ -1,21 +0,0 @@
-import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
-import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
-
-/**
- * Handles the `gc` MCP tool call.
- *
- * Removes unreferenced sections from the knowledge base and returns
- * the collection report as formatted JSON.
- *
- * @param client - the worker client used to execute operations
- */
-export async function handleToolGc(
-   client: McpWorkerClient,
-): Promise<ToolCallResult> {
-   const report = await client.gc();
-   return {
-      content: [
-         { type: 'text', text: JSON.stringify(report, null, 2) },
-      ],
-   };
-}