@dikolab/kbdb 0.3.1 → 0.4.0

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

@@ -1,69 +0,0 @@
-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 { asStringArrayOrUndefined } from './as-string-array-or-undefined.function.ts';
-import { asBooleanOrUndefined } from './as-boolean-or-undefined.function.ts';
-
-/**
- * Handles the `learn` MCP tool call.
- *
- * Validates that image content includes a title, then imports the
- * content into the knowledge base via the worker client.
- *
- * @param client - the worker client used to execute operations
- * @param args - tool arguments from the MCP request
- */
-export async function handleToolLearn(
-   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,
-      })),
-   };
-
-   return {
-      content: [{ type: 'text', text: JSON.stringify(normalized) }],
-   };
-}

package/src/shared/mcp/functions/handle-tool-rebuild.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 `rebuild` MCP tool call.
- *
- * Reconstructs all index files from section and document files and
- * returns the rebuild report as formatted JSON.
- *
- * @param client - the worker client used to execute operations
- */
-export async function handleToolRebuild(
-   client: McpWorkerClient,
-): Promise<ToolCallResult> {
-   const report = await client.rebuildIndexes();
-   return {
-      content: [
-         { type: 'text', text: JSON.stringify(report, null, 2) },
-      ],
-   };
-}

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

@@ -1,40 +0,0 @@
-import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
-import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
-
-/**
- * Handles the `retrieve` MCP tool call.
- *
- * Fetches a section by `kbid` or a document by `docid`. Returns an
- * error when neither identifier is supplied.
- *
- * @param client - the worker client used to execute operations
- * @param args - tool arguments from the MCP request
- */
-export async function handleToolRetrieve(
-   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,
-   };
-}

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

@@ -1,47 +0,0 @@
-import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
-import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
-
-/**
- * Handles the `search` MCP tool call.
- *
- * Forwards query parameters to the worker client and strips internal
- * scoring fields (`score`, `confidence`) from each result item before
- * returning.
- *
- * @param client - the worker client used to execute operations
- * @param args - tool arguments from the MCP request
- */
-export async function handleToolSearch(
-   client: McpWorkerClient,
-   args: Record<string, unknown>,
-): Promise<ToolCallResult> {
-   const query = typeof args['query'] === 'string' ? args['query'] : '';
-   const algo =
-      typeof args['algo'] === 'string' ? args['algo'] : undefined;
-   const results = await client.search({
-      query,
-      mode: args['mode'] as string | undefined,
-      ...(algo !== undefined ? { algo } : {}),
-      limit: args['limit'] as number | undefined,
-      offset: args['offset'] as number | 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) },
-      ],
-   };
-}

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

@@ -1,34 +0,0 @@
-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 `skill-delete` MCP tool call.
- *
- * Removes the skill section identified by `kbid` from the knowledge
- * base and returns the result.
- *
- * @param client - the worker client used to execute operations
- * @param args - tool arguments from the MCP request
- */
-export async function handleToolSkillDelete(
-   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 }),
-         },
-      ],
-   };
-}

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

@@ -1,59 +0,0 @@
-import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
-import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
-import { parseSkillContent } from './parse-skill-content.function.ts';
-
-/**
- * Handles the `skill-get` MCP tool call.
- *
- * Looks up a skill by `kbid` first, then falls back to searching by
- * `name`. Returns an error when neither identifier resolves to a
- * known skill.
- *
- * @param client - the worker client used to execute operations
- * @param args - tool arguments from the MCP request
- */
-export async function handleToolSkillGet(
-   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) }],
-   };
-}

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

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

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

@@ -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 `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

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

@@ -1,27 +0,0 @@
-/** 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

@@ -1,36 +0,0 @@
-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/parse-skill-content.function.ts

@@ -1,38 +0,0 @@
-import type {
-   SkillArgument,
-   SkillDefinition,
-} from '../typings/skill-types.interface.ts';
-
-/**
- * Parses a JSON string into a `SkillDefinition`.
- *
- * Validates that the required `name` and `body` fields are present
- * and are non-empty strings, then returns the full definition
- * including optional `description` and `arguments`.
- *
- * @param json - JSON string representing a serialized skill
- * @returns the parsed skill definition
- * @throws {SyntaxError} when `json` is not valid JSON
- * @throws {Error} when `name` is missing or empty
- * @throws {Error} when `body` is missing or not a string
- */
-export function parseSkillContent(json: string): SkillDefinition {
-   const raw = JSON.parse(json) as Record<string, unknown>;
-   if (typeof raw['name'] !== 'string' || !raw['name']) {
-      throw new Error('skill name is required');
-   }
-   if (typeof raw['body'] !== 'string') {
-      throw new Error('skill body is required');
-   }
-   return {
-      name: raw['name'],
-      description:
-         typeof raw['description'] === 'string'
-            ? raw['description']
-            : undefined,
-      arguments: Array.isArray(raw['arguments'])
-         ? (raw['arguments'] as SkillArgument[])
-         : undefined,
-      body: raw['body'],
-   };
-}

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

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

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

@@ -1,34 +0,0 @@
-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/functions/serialize-skill-content.function.ts

@@ -1,12 +0,0 @@
-import type { SkillDefinition } from '../typings/skill-types.interface.ts';
-
-/**
- * Serializes a `SkillDefinition` to a JSON string suitable for
- * storage as a knowledge-base section's `content` field.
- *
- * @param skill - skill definition to serialize
- * @returns JSON string representation of the skill
- */
-export function serializeSkillContent(skill: SkillDefinition): string {
-   return JSON.stringify(skill);
-}