@dikolab/kbdb 0.3.1 → 0.4.0

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

@@ -1,29 +0,0 @@
-import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
-
-/** MCP tool definition for the `content` operation. */
-export const TOOL_CONTENT: McpToolDefinition = {
-   name: 'content',
-   description:
-      'Compose a rendered Markdown document from one or' +
-      ' more kbid or docid identifiers.',
-   inputSchema: {
-      type: 'object',
-      properties: {
-         ids: {
-            type: 'array',
-            items: { type: 'string' },
-            description:
-               'One or more kbid or docid identifiers' +
-               ' (may be mixed)',
-         },
-      },
-      required: ['ids'],
-   },
-   annotations: {
-      title: 'Compose Content',
-      readOnlyHint: true,
-      destructiveHint: false,
-      idempotentHint: true,
-      openWorldHint: false,
-   },
-};

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

@@ -1,27 +0,0 @@
-import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
-
-/** MCP tool definition for the `export` operation. */
-export const TOOL_EXPORT: McpToolDefinition = {
-   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,
-   },
-};

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

@@ -1,21 +0,0 @@
-import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
-
-/** MCP tool definition for the `gc` operation. */
-export const TOOL_GC: McpToolDefinition = {
-   name: 'gc',
-   description:
-      'Remove unreferenced sections from the knowledge' +
-      ' base. A section is eligible when no document' +
-      ' manifest references it.',
-   inputSchema: {
-      type: 'object',
-      properties: {},
-   },
-   annotations: {
-      title: 'Garbage Collect',
-      readOnlyHint: false,
-      destructiveHint: true,
-      idempotentHint: false,
-      openWorldHint: false,
-   },
-};

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

@@ -1,58 +0,0 @@
-import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
-
-/** MCP tool definition for the `learn` operation. */
-export const TOOL_LEARN: McpToolDefinition = {
-   name: 'learn',
-   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: {
-         content: {
-            type: 'string',
-            description: 'Text content to add',
-         },
-         type: {
-            type: 'string',
-            description:
-               'MIME type (default: text/markdown).' +
-               ' Use image/* for images.',
-         },
-         title: {
-            type: 'string',
-            description:
-               'Section title.' + ' Required for image/* types.',
-         },
-         description: {
-            type: 'string',
-            description: 'Optional section description',
-         },
-         docid: {
-            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'],
-   },
-   annotations: {
-      title: 'Import Content',
-      readOnlyHint: false,
-      destructiveHint: false,
-      idempotentHint: true,
-      openWorldHint: false,
-   },
-};

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

@@ -1,21 +0,0 @@
-import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
-
-/** MCP tool definition for the `rebuild` operation. */
-export const TOOL_REBUILD: McpToolDefinition = {
-   name: 'rebuild',
-   description:
-      'Reconstruct all index files from section files' +
-      ' and document manifests on disk. Use this to' +
-      ' recover from index corruption.',
-   inputSchema: {
-      type: 'object',
-      properties: {},
-   },
-   annotations: {
-      title: 'Rebuild Indexes',
-      readOnlyHint: false,
-      destructiveHint: false,
-      idempotentHint: false,
-      openWorldHint: false,
-   },
-};

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

@@ -1,36 +0,0 @@
-import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
-
-/** MCP tool definition for the `recall` operation. */
-export const TOOL_RECALL: McpToolDefinition = {
-   name: 'recall',
-   description:
-      'Retrieve full content and context for sections' +
-      ' by identifier. Use after search to read relevant' +
-      ' results. Returns section text, metadata,' +
-      ' references, and back-references.',
-   inputSchema: {
-      type: 'object',
-      properties: {
-         kbid: {
-            type: 'string',
-            description: 'Single section identifier',
-         },
-         kbids: {
-            type: 'array',
-            items: { type: 'string' },
-            description: 'Batch section identifiers',
-         },
-         depth: {
-            type: 'number',
-            description: 'Expansion depth (0-3, default: 0)',
-         },
-      },
-   },
-   annotations: {
-      title: 'Recall Context',
-      readOnlyHint: true,
-      destructiveHint: false,
-      idempotentHint: true,
-      openWorldHint: false,
-   },
-};

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

@@ -1,31 +0,0 @@
-import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
-
-/** MCP tool definition for the `retrieve` operation. */
-export const TOOL_RETRIEVE: McpToolDefinition = {
-   name: 'retrieve',
-   description:
-      'Low-level fetch of a section or document' +
-      ' by identifier. For AI agent workflows,' +
-      ' prefer `recall` which includes metadata,' +
-      ' context, and back-references.',
-   inputSchema: {
-      type: 'object',
-      properties: {
-         kbid: {
-            type: 'string',
-            description: 'Section kb-id',
-         },
-         docid: {
-            type: 'string',
-            description: 'Document ID',
-         },
-      },
-   },
-   annotations: {
-      title: 'Fetch Content',
-      readOnlyHint: true,
-      destructiveHint: false,
-      idempotentHint: true,
-      openWorldHint: false,
-   },
-};

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

@@ -1,51 +0,0 @@
-import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
-
-/** MCP tool definition for the `search` operation. */
-export const TOOL_SEARCH: McpToolDefinition = {
-   name: 'search',
-   description:
-      '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: {
-         query: {
-            type: 'string',
-            description: 'Search query text',
-         },
-         mode: {
-            type: 'string',
-            enum: ['sections', 'documents', 'stats'],
-            description: 'Search mode (default: sections)',
-         },
-         algo: {
-            type: 'string',
-            enum: ['lexical', 'vector', 'hybrid'],
-            description:
-               'Search algorithm (default: lexical).' +
-               ' Use hybrid for embedding+keyword fusion.',
-         },
-         limit: {
-            type: 'number',
-            description: 'Maximum results (default: 20)',
-         },
-         offset: {
-            type: 'number',
-            description:
-               'Number of results to skip for' +
-               ' pagination (default: 0)',
-         },
-      },
-      required: ['query'],
-   },
-   annotations: {
-      title: 'Search KB',
-      readOnlyHint: true,
-      destructiveHint: false,
-      idempotentHint: true,
-      openWorldHint: false,
-   },
-};

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

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

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

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

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

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

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

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

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

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

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

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

@@ -1,43 +0,0 @@
-/** 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-mcp-server.function.ts

@@ -1,14 +0,0 @@
-import { McpServer } from '../classes/mcp-server.class.ts';
-import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
-
-/**
- * Factory that constructs a new `McpServer` bound to the given
- * worker client. Call `server.listen()` on the returned instance
- * to start processing stdio input.
- *
- * @param client - worker client providing knowledge-base operations
- * @returns a configured `McpServer` ready to listen
- */
-export function createMcpServer(client: McpWorkerClient): McpServer {
-   return new McpServer(client);
-}

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

@@ -1,102 +0,0 @@
-import type { McpPrompt } from '../typings/prompt-types.interface.ts';
-import type { McpPromptArgument } from '../typings/prompt-types.interface.ts';
-
-/** Minimal skill section record shape required by this function. */
-interface SkillSectionRecord {
-   /** Knowledge-base identifier of the section. */
-   readonly kbid: string;
-   /** Human-readable section title used as the prompt name. */
-   readonly title: string | null;
-   /** JSON-encoded skill definition content. */
-   readonly content: string;
-   /** Optional human-readable section description. */
-   readonly description?: string | null;
-}
-
-/** Minimal document manifest shape required by this function. */
-interface AgentDocumentRecord {
-   /** Unique document identifier. */
-   readonly docid: string;
-   /** Human-readable document title used in the prompt name. */
-   readonly title: string;
-   /** Ordered section references belonging to the document. */
-   readonly sections: readonly {
-      readonly kbid: string;
-      readonly position: number;
-   }[];
-}
-
-/**
- * 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.
- */
-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;
-   }
-}
-
-/**
- * Builds the list of MCP prompt definitions from skill sections and
- * agent document manifests stored in the knowledge base.
- *
- * Skills are mapped first (in input order), followed by agents.
- * Each skill becomes a prompt whose name is the section title and
- * whose arguments are extracted from the JSON content. Each agent
- * becomes a prompt prefixed with `"agent:"` and carries an empty
- * arguments array.
- *
- * @param skills - skill section records from `listByType('skill')`
- * @param agents - agent document manifests from
- *   `listDocumentsByType('agent')`
- * @returns ordered list of MCP prompt definitions
- */
-export function createPromptDefinitions(
-   skills: readonly SkillSectionRecord[],
-   agents: readonly AgentDocumentRecord[],
-): McpPrompt[] {
-   const skillPrompts: McpPrompt[] = skills
-      .filter(
-         (r): r is SkillSectionRecord & { title: string } =>
-            r.title !== null,
-      )
-      .map((record) => {
-         const args = parseSkillArguments(record.content);
-         const prompt: McpPrompt = {
-            name: record.title,
-            description: record.description ?? undefined,
-            arguments: args,
-         };
-         return prompt;
-      });
-
-   const agentPrompts: McpPrompt[] = agents.map((doc) => ({
-      name: `agent:${doc.title}`,
-      arguments: [],
-   }));
-
-   return [...skillPrompts, ...agentPrompts];
-}