@dikolab/kbdb 0.1.0

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

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

@@ -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-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-completion.function.ts

@@ -0,0 +1,114 @@
+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-prompt-get.function.ts

@@ -0,0 +1,214 @@
+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 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;
+   }[];
+}
+
+/**
+ * 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.
+ *
+ * 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.
+ */
+async function handleAgentPrompt(
+   name: string,
+   client: McpWorkerClient,
+): Promise<McpPromptMessage[]> {
+   const docid = name.slice(6);
+   const doc = (await client.retrieveDocument(docid)) as AgentDocument;
+   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: 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.
+ *
+ * @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-resource-read.function.ts

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

@@ -0,0 +1,29 @@
+/**
+ * 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',
+      },
+   ];
+}