@dikolab/kbdb 0.2.2 → 0.3.1

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

@@ -15,10 +15,8 @@ interface ReadSection {
    readonly content: string;
 }
 
-/** Minimal agent document shape returned by retrieveDocument. */
+/** Minimal agent document shape from listDocumentsByType. */
 interface AgentDocument {
-   /** Document identifier. */
-   readonly docid: string;
    /** Document title. */
    readonly title: string;
    /** Ordered section references. */
@@ -86,17 +84,24 @@ function buildSkillsText(skillSections: ReadSection[]): string | null {
 /**
  * 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.
+ * 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 docid = name.slice(6);
-   const doc = (await client.retrieveDocument(docid)) as AgentDocument;
+   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);
@@ -192,9 +197,10 @@ async function handleSkillPrompt(
  * substitutes `{{argName}}` placeholders in the body, and returns a
  * single user message.
  *
- * For agent prompts: reads the agent document via `retrieveDocument`,
- * builds an assistant message from the persona section, and (when
- * skills exist) a user message listing their names and descriptions.
+ * 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

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

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

@@ -0,0 +1,24 @@
+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.',
+         },
+      ],
+   });
+}

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

@@ -32,6 +32,30 @@ function asString(value: unknown, fallback: string): string {
    return typeof value === 'string' ? value : fallback;
 }
 
+/**
+ * Narrows an `unknown` value to a boolean, returning `undefined`
+ * when the value is not a boolean.
+ */
+function asBooleanOrUndefined(value: unknown): boolean | undefined {
+   return typeof value === 'boolean' ? value : undefined;
+}
+
+/**
+ * Narrows an `unknown` value to a `string[]`, returning `undefined`
+ * when the value is not an array of strings.
+ */
+function asStringArrayOrUndefined(
+   value: unknown,
+): string[] | undefined {
+   if (
+      Array.isArray(value) &&
+      value.every((item) => typeof item === 'string')
+   ) {
+      return value;
+   }
+   return undefined;
+}
+
 /**
  * Narrows an `unknown` value to a `string[]`, returning an empty
  * array when the value is not an array of strings.
@@ -82,6 +106,8 @@ export async function handleToolCall(
             return await handleGc(client);
          case 'rebuild':
             return await handleRebuild(client);
+         case 'export':
+            return await handleExport(client, args);
          case 'skill-learn':
             return await handleSkillLearn(client, args);
          case 'skill-list':
@@ -98,6 +124,8 @@ export async function handleToolCall(
             return await handleAgentGet(client, args);
          case 'agent-delete':
             return await handleAgentDelete(client, args);
+         case 'auto-capture-review':
+            return handleAutoCaptureReview();
          default:
             return {
                content: [
@@ -131,11 +159,20 @@ async function handleSearch(
       mode: args['mode'] as string | undefined,
       limit: args['limit'] as number | undefined,
       offset: args['offset'] as number | undefined,
+      algo: args['algo'] as string | undefined,
    });
 
    const stripped = {
       ...results,
-      items: results.items.map(({ score: _score, ...rest }) => rest),
+      items: results.items.map(
+         ({
+            score: _score,
+            confidence: _confidence,
+            ...rest
+         }: (typeof results.items)[number] & {
+            confidence?: number;
+         }) => rest,
+      ),
    };
 
    return {
@@ -161,6 +198,8 @@ async function handleLearn(
          : undefined;
    const docid =
       typeof args['docid'] === 'string' ? args['docid'] : undefined;
+   const tags = asStringArrayOrUndefined(args['tags']);
+   const replace = asBooleanOrUndefined(args['replace']);
    if (sectionType.startsWith('image/') && !title) {
       return {
          content: [
@@ -178,12 +217,26 @@ async function handleLearn(
       title,
       description,
       docid,
+      tags,
+      replace,
    });
+   const normalized = {
+      kbid: result.kbid,
+      indexed_terms_count: result.indexed_terms_count ?? 0,
+      elapsed_ms: result.elapsed_ms ?? 0,
+      superseded: result.superseded ?? null,
+      warnings: result.warnings ?? [],
+      near_duplicates: (result.near_duplicates ?? []).map((d) => ({
+         kbid: d.kbid,
+         similarity: d.similarity,
+         ...(d.method !== undefined ? { method: d.method } : {}),
+      })),
+   };
    return {
       content: [
          {
             type: 'text',
-            text: JSON.stringify(result),
+            text: JSON.stringify(normalized),
          },
       ],
    };
@@ -472,3 +525,36 @@ async function handleSkillDelete(
       ],
    };
 }
+
+function handleAutoCaptureReview(): ToolCallResult {
+   return {
+      content: [
+         {
+            type: 'text',
+            text: JSON.stringify({
+               pending: [],
+               message: 'No pending auto-captured knowledge entries.',
+            }),
+         },
+      ],
+   };
+}
+
+async function handleExport(
+   client: McpWorkerClient,
+   args: Record<string, unknown>,
+): Promise<ToolCallResult> {
+   const path =
+      typeof args['path'] === 'string' ? args['path'] : undefined;
+   const result = await client.export(
+      path !== undefined ? { path } : {},
+   );
+   return {
+      content: [
+         {
+            type: 'text',
+            text: JSON.stringify(result),
+         },
+      ],
+   };
+}

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

@@ -0,0 +1,21 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
+
+/**
+ * Handles the `check` MCP tool call.
+ *
+ * Runs an integrity check on the knowledge base and returns the
+ * report as formatted JSON.
+ *
+ * @param client - the worker client used to execute operations
+ */
+export async function handleToolCheck(
+   client: McpWorkerClient,
+): Promise<ToolCallResult> {
+   const report = await client.integrityCheck();
+   return {
+      content: [
+         { type: 'text', text: JSON.stringify(report, null, 2) },
+      ],
+   };
+}

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

@@ -0,0 +1,23 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
+import { asStringArray } from './as-string-array.function.ts';
+
+/**
+ * Handles the `content` MCP tool call.
+ *
+ * Composes a rendered Markdown document from the given identifiers
+ * and returns the result as JSON.
+ *
+ * @param client - the worker client used to execute operations
+ * @param args - tool arguments from the MCP request
+ */
+export async function handleToolContent(
+   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) }],
+   };
+}

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

@@ -0,0 +1,25 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
+
+/**
+ * Handles the `export` MCP tool call.
+ *
+ * Exports the database as a self-contained directory snapshot.
+ * Passes the optional `path` argument when supplied.
+ *
+ * @param client - the worker client used to execute operations
+ * @param args - tool arguments from the MCP request
+ */
+export async function handleToolExport(
+   client: McpWorkerClient,
+   args: Record<string, unknown>,
+): Promise<ToolCallResult> {
+   const path =
+      typeof args['path'] === 'string' ? args['path'] : undefined;
+   const result = await client.export(
+      path !== undefined ? { path } : {},
+   );
+   return {
+      content: [{ type: 'text', text: JSON.stringify(result) }],
+   };
+}

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

@@ -0,0 +1,21 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
+
+/**
+ * Handles the `gc` MCP tool call.
+ *
+ * Removes unreferenced sections from the knowledge base and returns
+ * the collection report as formatted JSON.
+ *
+ * @param client - the worker client used to execute operations
+ */
+export async function handleToolGc(
+   client: McpWorkerClient,
+): Promise<ToolCallResult> {
+   const report = await client.gc();
+   return {
+      content: [
+         { type: 'text', text: JSON.stringify(report, null, 2) },
+      ],
+   };
+}

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

@@ -0,0 +1,69 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
+import { asString } from './as-string.function.ts';
+import { asStringArrayOrUndefined } from './as-string-array-or-undefined.function.ts';
+import { asBooleanOrUndefined } from './as-boolean-or-undefined.function.ts';
+
+/**
+ * Handles the `learn` MCP tool call.
+ *
+ * Validates that image content includes a title, then imports the
+ * content into the knowledge base via the worker client.
+ *
+ * @param client - the worker client used to execute operations
+ * @param args - tool arguments from the MCP request
+ */
+export async function handleToolLearn(
+   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;
+   const tags = asStringArrayOrUndefined(args['tags']);
+   const replace = asBooleanOrUndefined(args['replace']);
+
+   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,
+      tags,
+      replace,
+   });
+
+   const normalized = {
+      kbid: result.kbid,
+      indexed_terms_count: result.indexed_terms_count ?? 0,
+      elapsed_ms: result.elapsed_ms ?? 0,
+      superseded: result.superseded ?? null,
+      warnings: result.warnings ?? [],
+      near_duplicates: (result.near_duplicates ?? []).map((d) => ({
+         kbid: d.kbid,
+         similarity: d.similarity,
+      })),
+   };
+
+   return {
+      content: [{ type: 'text', text: JSON.stringify(normalized) }],
+   };
+}

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

@@ -0,0 +1,21 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
+
+/**
+ * Handles the `rebuild` MCP tool call.
+ *
+ * Reconstructs all index files from section and document files and
+ * returns the rebuild report as formatted JSON.
+ *
+ * @param client - the worker client used to execute operations
+ */
+export async function handleToolRebuild(
+   client: McpWorkerClient,
+): Promise<ToolCallResult> {
+   const report = await client.rebuildIndexes();
+   return {
+      content: [
+         { type: 'text', text: JSON.stringify(report, null, 2) },
+      ],
+   };
+}

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

@@ -0,0 +1,40 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
+
+/**
+ * Handles the `retrieve` MCP tool call.
+ *
+ * Fetches a section by `kbid` or a document by `docid`. Returns an
+ * error when neither identifier is supplied.
+ *
+ * @param client - the worker client used to execute operations
+ * @param args - tool arguments from the MCP request
+ */
+export async function handleToolRetrieve(
+   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,
+   };
+}

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

@@ -0,0 +1,47 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
+
+/**
+ * Handles the `search` MCP tool call.
+ *
+ * Forwards query parameters to the worker client and strips internal
+ * scoring fields (`score`, `confidence`) from each result item before
+ * returning.
+ *
+ * @param client - the worker client used to execute operations
+ * @param args - tool arguments from the MCP request
+ */
+export async function handleToolSearch(
+   client: McpWorkerClient,
+   args: Record<string, unknown>,
+): Promise<ToolCallResult> {
+   const query = typeof args['query'] === 'string' ? args['query'] : '';
+   const algo =
+      typeof args['algo'] === 'string' ? args['algo'] : undefined;
+   const results = await client.search({
+      query,
+      mode: args['mode'] as string | undefined,
+      ...(algo !== undefined ? { algo } : {}),
+      limit: args['limit'] as number | undefined,
+      offset: args['offset'] as number | undefined,
+   });
+
+   const stripped = {
+      ...results,
+      items: results.items.map(
+         ({
+            score: _score,
+            confidence: _confidence,
+            ...rest
+         }: (typeof results.items)[number] & {
+            confidence?: number;
+         }) => rest,
+      ),
+   };
+
+   return {
+      content: [
+         { type: 'text', text: JSON.stringify(stripped, null, 2) },
+      ],
+   };
+}

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

@@ -0,0 +1,34 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
+import { asString } from './as-string.function.ts';
+
+/**
+ * Handles the `skill-delete` MCP tool call.
+ *
+ * Removes the skill section identified by `kbid` from the knowledge
+ * base and returns the result.
+ *
+ * @param client - the worker client used to execute operations
+ * @param args - tool arguments from the MCP request
+ */
+export async function handleToolSkillDelete(
+   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/handle-tool-skill-get.function.ts

@@ -0,0 +1,59 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
+import { parseSkillContent } from './parse-skill-content.function.ts';
+
+/**
+ * Handles the `skill-get` MCP tool call.
+ *
+ * Looks up a skill by `kbid` first, then falls back to searching by
+ * `name`. Returns an error when neither identifier resolves to a
+ * known skill.
+ *
+ * @param client - the worker client used to execute operations
+ * @param args - tool arguments from the MCP request
+ */
+export async function handleToolSkillGet(
+   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) }],
+   };
+}