@dikolab/kbdb 0.1.0

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

@@ -0,0 +1,401 @@
+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:
+            'Search the knowledge base for relevant' +
+            ' sections using natural language queries.',
+         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)',
+               },
+            },
+            required: ['query'],
+         },
+         annotations: {
+            title: 'Search KB',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+         },
+      },
+      {
+         name: 'learn',
+         description: 'Add a text section to the knowledge base.',
+         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',
+               },
+            },
+            required: ['content'],
+         },
+         annotations: {
+            title: 'Import Content',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+         },
+      },
+      {
+         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,
+         },
+      },
+      {
+         name: 'retrieve',
+         description:
+            'Retrieve a section or document by ID.' +
+            ' Provide kbid or docid.',
+         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,
+         },
+      },
+      {
+         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,
+         },
+      },
+      {
+         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,
+         },
+      },
+      {
+         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,
+         },
+      },
+      {
+         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,
+         },
+      },
+      {
+         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,
+         },
+      },
+      {
+         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,
+         },
+      },
+      {
+         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,
+         },
+      },
+      {
+         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,
+         },
+      },
+      {
+         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,
+         },
+      },
+      {
+         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,
+         },
+      },
+      {
+         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,
+         },
+      },
+      {
+         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,
+         },
+      },
+      {
+         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,
+         },
+      },
+   ];
+}

package/src/shared/mcp/functions/extract-skill-arguments.function.ts

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

@@ -0,0 +1,116 @@
+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);
+
+   return {
+      content: [
+         {
+            type: 'text',
+            text: JSON.stringify({
+               docid,
+               name,
+               skillCount: skills.length,
+            }),
+         },
+      ],
+   };
+}

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

@@ -0,0 +1,50 @@
+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-delete 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;
+}
+
+/**
+ * Handles the `agent:delete` MCP tool call.
+ *
+ * Removes the document grouping identified by `docid`. The skill
+ * sections referenced by the agent are not deleted; only the grouping
+ * record is removed.
+ *
+ * @param client - the worker client used to execute operations
+ * @param args - tool arguments; must include a `docid` string
+ * @returns content items confirming removal, or an error item
+ */
+export async function handleAgentDelete(
+   client: McpWorkerClient,
+   args: Record<string, unknown>,
+): Promise<ToolCallResult> {
+   const docid = typeof args['docid'] === 'string' ? args['docid'] : '';
+   if (!docid) {
+      return {
+         content: [{ type: 'text', text: 'docid is required' }],
+         isError: true,
+      };
+   }
+   await client.removeGrouping(docid);
+   return {
+      content: [
+         {
+            type: 'text',
+            text: JSON.stringify({ docid, removed: true }),
+         },
+      ],
+   };
+}