@dikolab/kbdb 0.3.1 → 0.4.0

package/src/shared/mcp/functions/create-resource-templates.function.ts

@@ -1,23 +0,0 @@
-import type { McpResourceTemplate } from '../typings/mcp-types.interface.ts';
-
-/**
- * Returns the list of MCP resource URI templates served by the
- * knowledge-base server. Each template describes the URI pattern,
- * human-readable metadata, and the MIME type of the resource body.
- */
-export function createResourceTemplates(): McpResourceTemplate[] {
-   return [
-      {
-         uriTemplate: 'kbdb://section/{kb_id}',
-         name: 'Section',
-         description: 'A knowledge base section by its kb-id.',
-         mimeType: 'text/plain',
-      },
-      {
-         uriTemplate: 'kbdb://document/{doc_id}',
-         name: 'Document',
-         description: 'A document with its ordered sections.',
-         mimeType: 'application/json',
-      },
-   ];
-}

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

@@ -1,530 +0,0 @@
-import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
-
-/**
- * Returns the full list of MCP tool definitions exposed by the
- * knowledge-base server. Each definition includes the tool name,
- * a human-readable description, and a JSON Schema for its inputs.
- */
-export function createToolDefinitions(): McpToolDefinition[] {
-   return [
-      {
-         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)',
-               },
-               limit: {
-                  type: 'number',
-                  description: 'Maximum results (default: 20)',
-               },
-               offset: {
-                  type: 'number',
-                  description:
-                     'Number of results to skip for' +
-                     ' pagination (default: 0)',
-               },
-               algo: {
-                  type: 'string',
-                  enum: ['lexical', 'vector', 'hybrid'],
-                  description: 'Search algorithm (default: lexical)',
-               },
-            },
-            required: ['query'],
-         },
-         annotations: {
-            title: 'Search KB',
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-         },
-      },
-      {
-         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,
-         },
-      },
-      {
-         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,
-         },
-      },
-      {
-         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,
-         },
-      },
-      {
-         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,
-         },
-      },
-      {
-         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,
-         },
-      },
-      {
-         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,
-         },
-      },
-      {
-         name: 'check',
-         description:
-            'Verify the integrity of the knowledge base.' +
-            ' Reports checksum mismatches, orphan sections,' +
-            ' broken references, and circular reference chains.',
-         inputSchema: {
-            type: 'object',
-            properties: {},
-         },
-         annotations: {
-            title: 'Integrity Check',
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-         },
-      },
-      {
-         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,
-         },
-      },
-      {
-         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,
-         },
-      },
-      {
-         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:
-            '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,
-         },
-      },
-      {
-         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,
-         },
-      },
-      {
-         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,
-         },
-      },
-      {
-         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,
-         },
-      },
-      {
-         name: 'agent-create',
-         description:
-            'Create an AI agent with a persona and' +
-            ' optional skill references.',
-         inputSchema: {
-            type: 'object',
-            properties: {
-               name: {
-                  type: 'string',
-                  description: 'Agent name',
-               },
-               description: {
-                  type: 'string',
-                  description: 'Agent description',
-               },
-               persona: {
-                  type: 'string',
-                  description: 'Agent persona prompt',
-               },
-               skills: {
-                  type: 'array',
-                  items: { type: 'string' },
-                  description: 'Skill kbid references to attach',
-               },
-            },
-            required: ['name', 'persona'],
-         },
-         annotations: {
-            title: 'Create Agent',
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-         },
-      },
-      {
-         name: 'agent-list',
-         description: 'List all agents in the knowledge base.',
-         inputSchema: {
-            type: 'object',
-            properties: {},
-         },
-         annotations: {
-            title: 'List Agents',
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-         },
-      },
-      {
-         name: 'agent-get',
-         description: 'Get an agent definition by document ID.',
-         inputSchema: {
-            type: 'object',
-            properties: {
-               docid: {
-                  type: 'string',
-                  description: 'Document ID of the agent',
-               },
-            },
-            required: ['docid'],
-         },
-         annotations: {
-            title: 'Get Agent',
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-         },
-      },
-      {
-         name: 'agent-delete',
-         description:
-            'Delete an agent by its document ID.' +
-            ' Skill sections are not removed.',
-         inputSchema: {
-            type: 'object',
-            properties: {
-               docid: {
-                  type: 'string',
-                  description: 'Document ID of the agent',
-               },
-            },
-            required: ['docid'],
-         },
-         annotations: {
-            title: 'Delete Agent',
-            readOnlyHint: false,
-            destructiveHint: true,
-            idempotentHint: true,
-            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/extract-skill-arguments.function.ts

@@ -1,27 +0,0 @@
-import type { SkillArgument } from '../typings/skill-types.interface.ts';
-
-/**
- * Extracts `{{argName}}` placeholder names from a skill body string
- * and returns them as `SkillArgument` objects marked as required.
- *
- * Each placeholder is included only once regardless of how many
- * times it appears, and the returned array preserves the order of
- * first occurrence.
- *
- * @param body - skill body template text to scan for placeholders
- * @returns ordered, deduplicated list of argument definitions
- */
-export function extractSkillArguments(body: string): SkillArgument[] {
-   const seen = new Set<string>();
-   const args: SkillArgument[] = [];
-   const re = /\{\{(\w+)\}\}/g;
-   let match: RegExpExecArray | null;
-   while ((match = re.exec(body)) !== null) {
-      const name = match[1];
-      if (!seen.has(name)) {
-         seen.add(name);
-         args.push({ name, required: true });
-      }
-   }
-   return args;
-}

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

@@ -1,116 +0,0 @@
-import type { McpWorkerClient } from '../typings/mcp-client.interface.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 the agent-create tool 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 `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 [];
-}
-
-/**
- * Handles the `agent:create` MCP tool call.
- *
- * Validates required arguments, verifies that referenced skill kbids
- * exist, stores agent metadata as a JSON section, groups all sections
- * into a single document, and returns the resulting document
- * identifier.
- *
- * @param client - the worker client used to execute operations
- * @param args - tool arguments from the MCP request
- * @returns content items with optional `isError` flag
- */
-export async function handleAgentCreate(
-   client: McpWorkerClient,
-   args: Record<string, unknown>,
-): Promise<ToolCallResult> {
-   const name = asString(args['name'], '');
-   const description = asString(args['description'], '');
-   const persona = asString(args['persona'], '');
-   const skills = asStringArray(args['skills']);
-
-   if (!name) {
-      return {
-         content: [{ type: 'text', text: 'name is required' }],
-         isError: true,
-      };
-   }
-   if (!persona) {
-      return {
-         content: [{ type: 'text', text: 'persona is required' }],
-         isError: true,
-      };
-   }
-
-   if (skills.length > 0) {
-      const sections = await client.readSections(skills);
-      const found = new Set(sections.map((s) => s.kbid));
-      const missing = skills.filter((k) => !found.has(k));
-      if (missing.length > 0) {
-         return {
-            content: [
-               {
-                  type: 'text',
-                  text: `skill not found: ${missing.join(', ')}`,
-               },
-            ],
-            isError: true,
-         };
-      }
-   }
-
-   const metadata = JSON.stringify({ name, description, persona });
-
-   const metaResult = await client.addSection({
-      sectionType: 'text',
-      content: metadata,
-      title: name,
-      description,
-   });
-
-   const allKbids = [metaResult.kbid, ...skills];
-   const docid = await client.groupSections(name, allKbids, 'agent');
-
-   return {
-      content: [
-         {
-            type: 'text',
-            text: JSON.stringify({
-               docid,
-               name,
-               skillCount: skills.length,
-            }),
-         },
-      ],
-   };
-}