@dikolab/kbdb 0.3.2 → 0.4.1

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

@@ -1,220 +0,0 @@
-import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
-import type { McpPromptMessage } from '../typings/prompt-types.interface.ts';
-
-/** Parsed shape of an agent metadata section. */
-interface AgentMeta {
-   /** Agent persona text. */
-   readonly persona: string;
-}
-
-/** Minimal section shape returned by readSections. */
-interface ReadSection {
-   /** Knowledge-base identifier. */
-   readonly kbid: string;
-   /** Raw text content. */
-   readonly content: string;
-}
-
-/** Minimal agent document shape from listDocumentsByType. */
-interface AgentDocument {
-   /** Document title. */
-   readonly title: string;
-   /** Ordered section references. */
-   readonly sections: readonly {
-      readonly kbid: string;
-      readonly position: number;
-   }[];
-}
-
-/**
- * Parses agent metadata from a raw JSON content string.
- *
- * Returns default values when parsing fails or required fields are
- * absent.
- */
-function parseAgentMeta(content: string): AgentMeta {
-   try {
-      const parsed = JSON.parse(content) as Record<string, unknown>;
-      return {
-         persona:
-            typeof parsed['persona'] === 'string'
-               ? parsed['persona']
-               : '',
-      };
-   } catch {
-      return { persona: '' };
-   }
-}
-
-/**
- * Builds the skills listing user message text from an array of
- * skill section content strings. Sections whose JSON is not parseable
- * or whose name cannot be determined are omitted silently.
- *
- * Returns `null` when no valid skills remain after filtering.
- */
-function buildSkillsText(skillSections: ReadSection[]): 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')}`;
-}
-
-/**
- * Handles an MCP `prompts/get` request for an agent prompt.
- *
- * Looks up the agent by title via `listDocumentsByType('agent')`,
- * 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.
- */
-async function handleAgentPrompt(
-   name: string,
-   client: McpWorkerClient,
-): Promise<McpPromptMessage[]> {
-   const agentName = name.slice(6);
-   const agents = await client.listDocumentsByType('agent');
-   const doc = agents.find((a) => a.title === agentName) as
-      | AgentDocument
-      | undefined;
-   if (!doc) {
-      throw new Error('agent not found: ' + agentName);
-   }
-   const sections = doc.sections;
-
-   const metaSection = sections.at(0);
-   const skillRefs = 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;
-}
-
-/**
- * Handles an MCP `prompts/get` request for a skill prompt.
- *
- * Looks up the skill by name in the `listByType('skill')` results,
- * picks the most recent match (last occurrence), parses its body,
- * and substitutes `{{argName}}` placeholders from `promptArgs`.
- * Unresolved placeholders are left as-is.
- *
- * @throws {Error} when no skill with the given name is found
- */
-async function handleSkillPrompt(
-   name: string,
-   promptArgs: Record<string, string>,
-   client: McpWorkerClient,
-): Promise<McpPromptMessage[]> {
-   const sections = await client.listByType('skill');
-   let matchContent: string | undefined;
-   for (const sec of sections) {
-      if (sec.title === name) {
-         matchContent = sec.content;
-      }
-   }
-   if (matchContent === undefined) {
-      throw new Error(`Prompt not found: ${name}`);
-   }
-
-   const parsed = JSON.parse(matchContent) as Record<string, unknown>;
-   const body =
-      typeof parsed['body'] === 'string' ? parsed['body'] : '';
-
-   const rendered = body.replace(
-      /\{\{(\w+)\}\}/g,
-      (_match, key: string) =>
-         key in promptArgs ? (promptArgs[key] ?? _match) : _match,
-   );
-
-   return [
-      {
-         role: 'user',
-         content: { type: 'text', text: rendered },
-      },
-   ];
-}
-
-/**
- * Handles an MCP `prompts/get` request.
- *
- * Dispatches to the agent handler when `name` starts with `"agent:"`,
- * otherwise treats the name as a skill prompt.
- *
- * For skill prompts: looks up by title using `listByType('skill')`,
- * substitutes `{{argName}}` placeholders in the body, and returns a
- * single user message.
- *
- * For agent prompts: looks up the agent by title via
- * `listDocumentsByType('agent')`, builds an assistant message from
- * the persona section, and (when skills exist) a user message
- * listing their names and descriptions.
- *
- * @param name - prompt name from the MCP request
- * @param promptArgs - argument key-value map from the MCP request
- * @param client - worker client used to access the knowledge base
- * @returns ordered list of prompt messages to return to the caller
- * @throws {Error} when a skill prompt name is not found in the store
- */
-export async function handlePromptGet(
-   name: string,
-   promptArgs: Record<string, string>,
-   client: McpWorkerClient,
-): Promise<McpPromptMessage[]> {
-   if (name.startsWith('agent:')) {
-      return handleAgentPrompt(name, client);
-   }
-   return handleSkillPrompt(name, promptArgs, client);
-}

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

@@ -1,66 +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 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;
-}
-
-/**
- * Handles the MCP `recall` tool call.
- *
- * Retrieves full content and context for one or more knowledge-base
- * sections by identifier. At least one of `kbid` or `kbids` must be
- * present in `args`; omitting both returns an error result.
- *
- * @param client - the worker client used to execute the operation
- * @param args - tool arguments from the MCP request
- * @returns content with JSON-stringified recall result, or an error
- *   content item when required arguments are missing
- */
-export async function handleRecall(
-   client: McpWorkerClient,
-   args: Record<string, unknown>,
-): Promise<ToolCallResult> {
-   const kbid =
-      typeof args['kbid'] === 'string' ? args['kbid'] : undefined;
-   const kbids =
-      Array.isArray(args['kbids']) &&
-      args['kbids'].every((item: unknown) => typeof item === 'string')
-         ? args['kbids']
-         : undefined;
-
-   if (!kbid && !kbids) {
-      return {
-         content: [
-            {
-               type: 'text',
-               text: 'Provide kbid or kbids',
-            },
-         ],
-         isError: true,
-      };
-   }
-
-   const depth = typeof args['depth'] === 'number' ? args['depth'] : 0;
-
-   const result = await client.recall({ kbid, kbids, depth });
-   return {
-      content: [
-         {
-            type: 'text',
-            text: JSON.stringify(result, null, 2),
-         },
-      ],
-   };
-}

package/src/shared/mcp/functions/handle-resource-read.function.ts

@@ -1,56 +0,0 @@
-import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
-
-/** A single content item in an MCP resource read response. */
-interface ResourceContent {
-   /** The resource URI that was read. */
-   readonly uri: string;
-   /** MIME type of the content body. */
-   readonly mimeType: string;
-   /** Text body of the resource. */
-   readonly text: string;
-}
-
-/** Result returned by a resource read operation. */
-interface ResourceReadResult {
-   /** One or more content items for the requested URI. */
-   readonly contents: ResourceContent[];
-}
-
-/**
- * Handles an MCP `resources/read` request by dispatching to the
- * appropriate knowledge-base operation based on the resource URI.
- *
- * @param client - the worker client used to fetch the resource
- * @param uri - the resource URI from the MCP request
- * @returns contents array for the MCP response
- * @throws {Error} when the URI does not match any known pattern
- */
-export async function handleResourceRead(
-   client: McpWorkerClient,
-   uri: string,
-): Promise<ResourceReadResult> {
-   const sectionMatch = uri.match(/^kbdb:\/\/section\/(.+)$/);
-   if (sectionMatch) {
-      const sections = await client.readSections([sectionMatch[1]]);
-      const text = sections.length > 0 ? sections[0].content : '';
-      return {
-         contents: [{ uri, mimeType: 'text/plain', text }],
-      };
-   }
-
-   const docMatch = uri.match(/^kbdb:\/\/document\/(.+)$/);
-   if (docMatch) {
-      const doc = await client.retrieveDocument(docMatch[1]);
-      return {
-         contents: [
-            {
-               uri,
-               mimeType: 'application/json',
-               text: JSON.stringify(doc, null, 2),
-            },
-         ],
-      };
-   }
-
-   throw new Error(`Unknown resource URI: ${uri}`);
-}

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

@@ -1,29 +0,0 @@
-/**
- * Represents a single file-system root entry advertised to MCP
- * clients via the `roots/list` response.
- */
-export interface McpRoot {
-   /** Absolute file URI for the root directory. */
-   readonly uri: string;
-   /** Human-readable label for the root. */
-   readonly name: string;
-}
-
-/**
- * Returns the list of MCP roots for the given database context path.
- *
- * Produces a single root entry whose URI is `file://` concatenated
- * with the supplied `contextPath`. This tells MCP clients which
- * file-system directory the server is authoritative for.
- *
- * @param contextPath - absolute path to the kbdb database directory
- * @returns array containing a single root for the context path
- */
-export function handleRootsList(contextPath: string): McpRoot[] {
-   return [
-      {
-         uri: `file://${contextPath}`,
-         name: 'kbdb database',
-      },
-   ];
-}

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

@@ -1,44 +0,0 @@
-import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
-import type { McpPromptMessage } from '../typings/prompt-types.interface.ts';
-
-/**
- * Handles an MCP `prompts/get` request for a skill prompt.
- *
- * Looks up the skill by name in the `listByType('skill')` results,
- * picks the most recent match (last occurrence), parses its body,
- * and substitutes `{{argName}}` placeholders from `promptArgs`.
- * Unresolved placeholders are left as-is.
- *
- * @param name - skill prompt name to look up
- * @param promptArgs - argument key-value map from the MCP request
- * @param client - worker client used to access the knowledge base
- * @throws {Error} when no skill with the given name is found
- */
-export async function handleSkillPrompt(
-   name: string,
-   promptArgs: Record<string, string>,
-   client: McpWorkerClient,
-): Promise<McpPromptMessage[]> {
-   const sections = await client.listByType('skill');
-   let matchContent: string | undefined;
-   for (const sec of sections) {
-      if (sec.title === name) {
-         matchContent = sec.content;
-      }
-   }
-   if (matchContent === undefined) {
-      throw new Error(`Prompt not found: ${name}`);
-   }
-
-   const parsed = JSON.parse(matchContent) as Record<string, unknown>;
-   const body =
-      typeof parsed['body'] === 'string' ? parsed['body'] : '';
-
-   const rendered = body.replace(
-      /\{\{(\w+)\}\}/g,
-      (_match, key: string) =>
-         key in promptArgs ? (promptArgs[key] ?? _match) : _match,
-   );
-
-   return [{ role: 'user', content: { type: 'text', text: rendered } }];
-}

package/src/shared/mcp/functions/handle-tool-auto-capture-review.function.ts

@@ -1,24 +0,0 @@
-import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
-
-/**
- * Handles the `auto-capture-review` MCP tool call.
- *
- * Returns a stub response indicating no pending captures are
- * available. Full implementation requires wiring the auto-capture
- * controller into the MCP server state.
- *
- * @param _args - tool arguments; `action` may be list, approve,
- *   or reject
- */
-export function handleToolAutoCaptureReview(
-   _args: Record<string, unknown>,
-): Promise<ToolCallResult> {
-   return Promise.resolve({
-      content: [
-         {
-            type: 'text' as const,
-            text: 'No pending auto-captured knowledge entries.',
-         },
-      ],
-   });
-}