@dikolab/kbdb 0.1.0

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

@@ -0,0 +1,464 @@
+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';
+
+/** 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 `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 '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 '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);
+         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,
+   });
+   return {
+      content: [
+         {
+            type: 'text',
+            text: JSON.stringify(results, 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;
+   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,
+   });
+   return {
+      content: [
+         {
+            type: 'text',
+            text: JSON.stringify(result),
+         },
+      ],
+   };
+}
+
+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 }),
+         },
+      ],
+   };
+}

package/src/shared/mcp/functions/parse-skill-content.function.ts

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

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

package/src/shared/mcp/functions/should-emit-log.function.ts

@@ -0,0 +1,38 @@
+import type { McpLogLevel } from '../typings/log-types.interface.ts';
+
+/**
+ * Ordered list of MCP log severity levels, from least severe
+ * (`debug`) to most severe (`emergency`). Used to compare levels
+ * when filtering log output.
+ */
+export const LOG_LEVEL_ORDER: McpLogLevel[] = [
+   'debug',
+   'info',
+   'notice',
+   'warning',
+   'error',
+   'critical',
+   'alert',
+   'emergency',
+];
+
+/**
+ * Determines whether a log message at `messageLevel` should be
+ * emitted when the server's log threshold is `threshold`.
+ *
+ * Returns `true` when `messageLevel` is at the same severity as
+ * `threshold` or higher. Returns `false` when the message level is
+ * below the threshold.
+ *
+ * @param messageLevel - severity of the log message to evaluate
+ * @param threshold - minimum severity level required to emit
+ * @returns `true` if the message meets or exceeds the threshold
+ */
+export function shouldEmitLog(
+   messageLevel: McpLogLevel,
+   threshold: McpLogLevel,
+): boolean {
+   const messageIndex = LOG_LEVEL_ORDER.indexOf(messageLevel);
+   const thresholdIndex = LOG_LEVEL_ORDER.indexOf(threshold);
+   return messageIndex >= thresholdIndex;
+}

package/src/shared/mcp/index.ts

@@ -0,0 +1,28 @@
+export { McpServer } from './classes/mcp-server.class.ts';
+export { createMcpServer } from './functions/create-mcp-server.function.ts';
+export { createToolDefinitions } from './functions/create-tool-definitions.function.ts';
+export { createResourceTemplates } from './functions/create-resource-templates.function.ts';
+export { handleToolCall } from './functions/handle-tool-call.function.ts';
+export { handleResourceRead } from './functions/handle-resource-read.function.ts';
+export {
+   PARSE_ERROR,
+   METHOD_NOT_FOUND,
+   INVALID_PARAMS,
+   INTERNAL_ERROR,
+   RESOURCE_NOT_FOUND,
+} from './constants/mcp-error-codes.constant.ts';
+export type {
+   McpRequest,
+   McpResponse,
+   McpNotification,
+   McpToolDefinition,
+   McpResourceTemplate,
+   McpServerInfo,
+   McpCapabilities,
+   McpToolResult,
+   McpResourceResult,
+} from './typings/mcp-types.interface.ts';
+export type {
+   McpWorkerClient,
+   RemoveSectionResult,
+} from './typings/mcp-client.interface.ts';

package/src/shared/mcp/typings/agent-types.interface.ts

@@ -0,0 +1,39 @@
+/**
+ * A reference from an agent document to a skill section,
+ * carrying the skill's position within the agent's ordered
+ * skill list.
+ */
+export interface AgentSkillRef {
+   /** Knowledge-base identifier of the referenced skill section. */
+   readonly kbid: string;
+   /**
+    * Human-readable name of the skill, or `null` when the
+    * referenced section no longer exists (dangling reference).
+    */
+   readonly name: string | null;
+   /** Zero-based position of this skill within the agent's list. */
+   readonly position: number;
+}
+
+/**
+ * Full definition of an agent, including its persona text and
+ * ordered list of skill references.
+ */
+export interface AgentDefinition {
+   /** Unique document identifier for the agent. */
+   readonly docid: string;
+   /** Human-readable name of the agent. */
+   readonly name: string;
+   /**
+    * Short description of what the agent does, used for discovery
+    * and disambiguation.
+    */
+   readonly description: string;
+   /**
+    * Persona text that governs how the agent behaves when
+    * executing tasks.
+    */
+   readonly persona: string;
+   /** Ordered list of skill references the agent can delegate to. */
+   readonly skills: readonly AgentSkillRef[];
+}

package/src/shared/mcp/typings/log-types.interface.ts

@@ -0,0 +1,26 @@
+/**
+ * Severity levels for MCP log messages, ordered from least severe
+ * (`debug`) to most severe (`emergency`).
+ */
+export type McpLogLevel =
+   | 'debug'
+   | 'info'
+   | 'notice'
+   | 'warning'
+   | 'error'
+   | 'critical'
+   | 'alert'
+   | 'emergency';
+
+/**
+ * A structured log message emitted by the MCP server via the
+ * `notifications/message` notification method.
+ */
+export interface McpLogMessage {
+   /** Severity level of the log entry. */
+   readonly level: McpLogLevel;
+   /** Optional logger name identifying the source component. */
+   readonly logger?: string;
+   /** Optional structured payload associated with the log entry. */
+   readonly data?: unknown;
+}