@dikolab/kbdb 0.3.1 → 0.4.0

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

@@ -1,50 +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-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 }),
-         },
-      ],
-   };
-}

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

@@ -1,160 +0,0 @@
-import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
-import type { AgentDefinition } from '../typings/agent-types.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-get 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;
-}
-
-/** Parsed shape of an agent document section list entry. */
-interface DocumentSection {
-   /** Knowledge-base identifier of the section. */
-   readonly kbid: string;
-   /** Zero-based position of the section within the document. */
-   readonly position: number;
-}
-
-/** Parsed shape of a retrieved agent document. */
-interface AgentDocument {
-   /** Document identifier. */
-   readonly docid: string;
-   /** Document title used as agent name fallback. */
-   readonly title: string;
-   /** Ordered list of sections in the document. */
-   readonly sections: DocumentSection[];
-}
-
-/**
- * Reads the metadata JSON stored in the first section of an agent
- * document and extracts `name`, `description`, and `persona`.
- */
-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: '' };
-   }
-}
-
-/**
- * Resolves skill names for a list of section references by reading
- * each section's JSON content and extracting the `name` field.
- * Returns `null` for skill references where the section no longer
- * exists (dangling references).
- */
-async function resolveSkillRefs(
-   client: McpWorkerClient,
-   skillRefs: DocumentSection[],
-): 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 };
-      }
-   });
-}
-
-/**
- * Handles the `agent:get` MCP tool call.
- *
- * Retrieves an agent document by its `docid`, reads the metadata
- * section and skill references, and returns a full `AgentDefinition`.
- * Dangling skill references (sections that no longer exist) appear
- * with `name: null` in the skills list.
- *
- * @param client - the worker client used to execute operations
- * @param args - tool arguments; must include a `docid` string
- * @returns content items containing the serialised `AgentDefinition`
- */
-export async function handleAgentGet(
-   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,
-      };
-   }
-
-   const doc = (await client.retrieveDocument(docid)) as AgentDocument;
-   const metaKbid = doc.sections[0]?.kbid;
-   const skillRefs = doc.sections.slice(1);
-
-   const { name, description, persona } = metaKbid
-      ? await readAgentMeta(client, metaKbid, doc.title)
-      : { name: doc.title, description: '', persona: '' };
-
-   const skills = await resolveSkillRefs(client, skillRefs);
-
-   const agent: AgentDefinition = {
-      docid,
-      name,
-      description,
-      persona,
-      skills,
-   };
-
-   return {
-      content: [
-         {
-            type: 'text',
-            text: JSON.stringify(agent, null, 2),
-         },
-      ],
-   };
-}

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

@@ -1,50 +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-list 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:list` MCP tool call.
- *
- * Retrieves all documents with `doc_type: 'agent'` and returns a
- * summary list containing each agent's document identifier, name,
- * and skill count.
- *
- * The `skillCount` is `Math.max(0, sections.length - 1)` because
- * the first section of an agent document always holds the metadata
- * JSON and does not count as a skill reference.
- *
- * @param client - the worker client used to execute operations
- * @returns content items with the serialised agent list
- */
-export async function handleAgentList(
-   client: McpWorkerClient,
-): Promise<ToolCallResult> {
-   const docs = await client.listDocumentsByType('agent');
-   const items = docs.map((d) => ({
-      docid: d.docid,
-      name: d.title,
-      skillCount: Math.max(0, d.sections.length - 1),
-   }));
-   return {
-      content: [
-         {
-            type: 'text',
-            text: JSON.stringify(items, null, 2),
-         },
-      ],
-   };
-}

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

@@ -1,68 +0,0 @@
-import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
-import type { McpPromptMessage } from '../typings/prompt-types.interface.ts';
-import { parseAgentMeta } from './parse-agent-meta.function.ts';
-import { buildSkillsText } from './build-skills-text.function.ts';
-
-/** Minimal agent document shape returned by retrieveDocument. */
-interface AgentDocument {
-   /** Document identifier. */
-   readonly docid: string;
-   /** Document title. */
-   readonly title: string;
-   /** Ordered section references. */
-   readonly sections: readonly {
-      readonly kbid: string;
-      readonly position: number;
-   }[];
-}
-
-/**
- * Handles an MCP `prompts/get` request for an agent prompt.
- *
- * Reads the agent document, extracts its persona from the metadata
- * section, then reads all skill sections and composes the response.
- * Returns an assistant message with the persona and, when skills
- * exist, a user message listing them.
- *
- * @param name - prompt name with `agent:` prefix
- * @param client - worker client used to access the knowledge base
- */
-export async function handleAgentPrompt(
-   name: string,
-   client: McpWorkerClient,
-): Promise<McpPromptMessage[]> {
-   const docid = name.slice(6);
-   const doc = (await client.retrieveDocument(docid)) as AgentDocument;
-   const metaSection = doc.sections.at(0);
-   const skillRefs = doc.sections.slice(1);
-
-   let persona = '';
-   if (metaSection !== undefined) {
-      const metaSections = await client.readSections([
-         metaSection.kbid,
-      ]);
-      const metaContent = metaSections.at(0);
-      if (metaContent !== undefined) {
-         persona = parseAgentMeta(metaContent.content).persona;
-      }
-   }
-
-   const messages: McpPromptMessage[] = [
-      { role: 'assistant', content: { type: 'text', text: persona } },
-   ];
-
-   if (skillRefs.length === 0) return messages;
-
-   const skillKbids = skillRefs.map((s) => s.kbid);
-   const skillSections = await client.readSections(skillKbids);
-   const skillsText = buildSkillsText(skillSections);
-
-   if (skillsText !== null) {
-      messages.push({
-         role: 'user',
-         content: { type: 'text', text: skillsText },
-      });
-   }
-
-   return messages;
-}

package/src/shared/mcp/functions/handle-completion.function.ts

@@ -1,114 +0,0 @@
-import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
-
-/**
- * Discriminated reference used in MCP completion requests.
- * Identifies whether the completion target is a prompt or a resource.
- */
-export interface McpCompletionRef {
-   /**
-    * The reference type: `'ref/prompt'` for named prompts (skills
-    * and agents) or `'ref/resource'` for resource URIs.
-    */
-   readonly type: 'ref/prompt' | 'ref/resource';
-   /** Prompt name, present when `type` is `'ref/prompt'`. */
-   readonly name?: string;
-   /** Resource URI, present when `type` is `'ref/resource'`. */
-   readonly uri?: string;
-}
-
-/**
- * Completion argument supplied by the client, describing which
- * argument is being completed and the current partial value.
- */
-export interface McpCompletionArgument {
-   /** The argument name being completed. */
-   readonly name: string;
-   /** The partial value typed so far; used for prefix filtering. */
-   readonly value: string;
-}
-
-/**
- * Result returned by `handleCompletion`, containing the list of
- * matching completion values and pagination metadata.
- */
-export interface McpCompletionResult {
-   /** Completion payload. */
-   readonly completion: {
-      /** Matching completion strings for the given prefix. */
-      readonly values: string[];
-      /**
-       * Whether more results are available beyond what is returned.
-       * Always `false` in this implementation.
-       */
-      readonly hasMore: boolean;
-      /** Total number of values returned. */
-      readonly total: number;
-   };
-}
-
-/**
- * Handles an MCP `completion/complete` request.
- *
- * For `ref/prompt` references, builds a list of all skill titles and
- * agent titles (prefixed with `agent:`) and filters by the supplied
- * argument value prefix. For `ref/resource` references, returns an
- * empty result — resource completion is not implemented.
- *
- * @param ref - discriminated reference identifying the completion target
- * @param argument - current argument name and partial value
- * @param client - worker client used to fetch skills and agents
- * @returns matching completion values with pagination metadata
- */
-export async function handleCompletion(
-   ref: McpCompletionRef,
-   argument: McpCompletionArgument,
-   client: McpWorkerClient,
-): Promise<McpCompletionResult> {
-   if (ref.type !== 'ref/prompt') {
-      return { completion: { values: [], hasMore: false, total: 0 } };
-   }
-
-   const [skills, agents] = await Promise.all([
-      client.listByType('skill'),
-      client.listDocumentsByType('agent'),
-   ]);
-
-   const names: string[] = [];
-
-   for (const skill of skills) {
-      if (skill.title !== null) {
-         names.push(skill.title);
-      }
-   }
-
-   for (const agent of agents) {
-      names.push(`agent:${agent.title}`);
-   }
-
-   const prefix = argument.value;
-
-   function matchesPrefix(candidate: string): boolean {
-      if (prefix.length === 0) {
-         return true;
-      }
-      if (candidate.startsWith(prefix)) {
-         return true;
-      }
-      // For agent-prefixed names, also match against the title portion.
-      const AGENT_PREFIX = 'agent:';
-      if (candidate.startsWith(AGENT_PREFIX)) {
-         return candidate.slice(AGENT_PREFIX.length).startsWith(prefix);
-      }
-      return false;
-   }
-
-   const values = names.filter(matchesPrefix);
-
-   return {
-      completion: {
-         values,
-         hasMore: false,
-         total: values.length,
-      },
-   };
-}

package/src/shared/mcp/functions/handle-mcp-request.function.ts

@@ -1,202 +0,0 @@
-import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
-import type {
-   McpRequest,
-   McpResponse,
-} from '../typings/mcp-types.interface.ts';
-import type { McpLogLevel } from '../typings/log-types.interface.ts';
-import type {
-   McpCompletionRef,
-   McpCompletionArgument,
-} from '../typings/mcp-completion.interface.ts';
-import type { McpServerState } from '../typings/mcp-server-state.interface.ts';
-import { createToolDefinitions } from './create-tool-definitions.function.ts';
-import { createResourceTemplates } from './create-resource-templates.function.ts';
-import { handleToolCall } from './handle-tool-call.function.ts';
-import { handleResourceRead } from './handle-resource-read.function.ts';
-import { createPromptDefinitions } from './create-prompt-definitions.function.ts';
-import { handlePromptGet } from './handle-prompt-get.function.ts';
-import { handleCompletion } from './handle-completion.function.ts';
-import { handleRootsList } from './handle-roots-list.function.ts';
-import {
-   METHOD_NOT_FOUND,
-   RESOURCE_NOT_FOUND,
-} from '../constants/mcp-error-codes.constant.ts';
-
-/**
- * Routes an MCP JSON-RPC request to the appropriate handler and
- * returns the JSON-RPC response. Mutates `state` for methods that
- * update server-side configuration (logging level, subscriptions,
- * capabilities).
- *
- * @param request - the parsed MCP request
- * @param client - worker client for knowledge-base operations
- * @param state - mutable server state shared with `McpServer`
- */
-export async function handleMcpRequest(
-   request: McpRequest,
-   client: McpWorkerClient,
-   state: McpServerState,
-): Promise<McpResponse> {
-   const id = request.id as number | string;
-
-   switch (request.method) {
-      case 'initialize': {
-         const params = request.params ?? {};
-         const caps = params['capabilities'];
-         state.hostCapabilities = caps
-            ? (caps as Record<string, unknown>)
-            : null;
-         return {
-            jsonrpc: '2.0',
-            id,
-            result: {
-               protocolVersion: '2025-11-25',
-               serverInfo: { name: 'kbdb', version: '0.1.0' },
-               capabilities: {
-                  tools: {},
-                  resources: { subscribe: true },
-                  prompts: {},
-                  logging: {},
-                  completions: {},
-               },
-            },
-         };
-      }
-
-      case 'ping':
-         return { jsonrpc: '2.0', id, result: {} };
-
-      case 'tools/list':
-         return {
-            jsonrpc: '2.0',
-            id,
-            result: { tools: createToolDefinitions() },
-         };
-
-      case 'resources/list':
-         return { jsonrpc: '2.0', id, result: { resources: [] } };
-
-      case 'resources/templates/list':
-         return {
-            jsonrpc: '2.0',
-            id,
-            result: { resourceTemplates: createResourceTemplates() },
-         };
-
-      case 'tools/call': {
-         const params = request.params ?? {};
-         const rawName = params['name'];
-         const name = typeof rawName === 'string' ? rawName : '';
-         const args = (params['arguments'] ?? {}) as Record<
-            string,
-            unknown
-         >;
-         const result = await handleToolCall(client, name, args);
-         return { jsonrpc: '2.0', id, result };
-      }
-
-      case 'resources/read': {
-         const params = request.params ?? {};
-         const rawUri = params['uri'];
-         const uri = typeof rawUri === 'string' ? rawUri : '';
-         try {
-            const result = await handleResourceRead(client, uri);
-            return { jsonrpc: '2.0', id, result };
-         } catch (err) {
-            return {
-               jsonrpc: '2.0',
-               id,
-               error: {
-                  code: RESOURCE_NOT_FOUND,
-                  message:
-                     err instanceof Error ? err.message : String(err),
-               },
-            };
-         }
-      }
-
-      case 'prompts/list': {
-         const skills = await client.listByType('skill');
-         const agents = await client.listDocumentsByType('agent');
-         const prompts = createPromptDefinitions(skills, agents);
-         return { jsonrpc: '2.0', id, result: { prompts } };
-      }
-
-      case 'prompts/get': {
-         const params = request.params ?? {};
-         const name =
-            typeof params['name'] === 'string' ? params['name'] : '';
-         const promptArgs = (params['arguments'] ?? {}) as Record<
-            string,
-            string
-         >;
-         try {
-            const messages = await handlePromptGet(
-               name,
-               promptArgs,
-               client,
-            );
-            return { jsonrpc: '2.0', id, result: { messages } };
-         } catch (err) {
-            return {
-               jsonrpc: '2.0',
-               id,
-               error: {
-                  code: RESOURCE_NOT_FOUND,
-                  message:
-                     err instanceof Error ? err.message : String(err),
-               },
-            };
-         }
-      }
-
-      case 'completion/complete': {
-         const params = request.params ?? {};
-         const ref = params['ref'] as McpCompletionRef;
-         const argument = (params['argument'] ?? {
-            name: '',
-            value: '',
-         }) as McpCompletionArgument;
-         const result = await handleCompletion(ref, argument, client);
-         return { jsonrpc: '2.0', id, result };
-      }
-
-      case 'roots/list': {
-         const roots = handleRootsList(state.contextPath);
-         return { jsonrpc: '2.0', id, result: { roots } };
-      }
-
-      case 'logging/setLevel': {
-         const params = request.params ?? {};
-         const level = params['level'] as McpLogLevel | undefined;
-         state.logLevel = level ?? null;
-         return { jsonrpc: '2.0', id, result: {} };
-      }
-
-      case 'resources/subscribe': {
-         const params = request.params ?? {};
-         const uri =
-            typeof params['uri'] === 'string' ? params['uri'] : '';
-         state.subscriptions.add(uri);
-         return { jsonrpc: '2.0', id, result: {} };
-      }
-
-      case 'resources/unsubscribe': {
-         const params = request.params ?? {};
-         const uri =
-            typeof params['uri'] === 'string' ? params['uri'] : '';
-         state.subscriptions.delete(uri);
-         return { jsonrpc: '2.0', id, result: {} };
-      }
-
-      default:
-         return {
-            jsonrpc: '2.0',
-            id,
-            error: {
-               code: METHOD_NOT_FOUND,
-               message: `Method not found: ` + request.method,
-            },
-         };
-   }
-}