@dikolab/kbdb 0.1.0

package/src/shared/mcp/classes/mcp-server.class.ts

@@ -0,0 +1,448 @@
+import { createInterface } from 'node:readline';
+import { createToolDefinitions } from '../functions/create-tool-definitions.function.ts';
+import { createResourceTemplates } from '../functions/create-resource-templates.function.ts';
+import { handleToolCall } from '../functions/handle-tool-call.function.ts';
+import { handleResourceRead } from '../functions/handle-resource-read.function.ts';
+import { createPromptDefinitions } from '../functions/create-prompt-definitions.function.ts';
+import { handlePromptGet } from '../functions/handle-prompt-get.function.ts';
+import { handleCompletion } from '../functions/handle-completion.function.ts';
+import { handleRootsList } from '../functions/handle-roots-list.function.ts';
+import { shouldEmitLog } from '../functions/should-emit-log.function.ts';
+import {
+   PARSE_ERROR,
+   METHOD_NOT_FOUND,
+   RESOURCE_NOT_FOUND,
+} from '../constants/mcp-error-codes.constant.ts';
+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 '../functions/handle-completion.function.ts';
+
+/**
+ * MCP server that speaks JSON-RPC 2.0 over stdio. Listens for
+ * newline-delimited requests on `process.stdin`, dispatches each
+ * to the appropriate knowledge-base operation via
+ * `McpWorkerClient`, and writes JSON-RPC responses to
+ * `process.stdout`.
+ */
+export class McpServer {
+   private readonly client: McpWorkerClient;
+   private readonly contextPath: string;
+   private initialized = false;
+   private hostCapabilities: Record<string, unknown> | null = null;
+   private logLevel: McpLogLevel | null = null;
+   private readonly subscriptions = new Set<string>();
+   private nextRequestId = 1;
+   private readonly pendingRequests = new Map<
+      number,
+      {
+         resolve: (value: unknown) => void;
+         reject: (reason: unknown) => void;
+         timer: ReturnType<typeof setTimeout>;
+      }
+   >();
+
+   constructor(client: McpWorkerClient, contextPath?: string) {
+      this.client = client;
+      this.contextPath = contextPath ?? '';
+   }
+
+   async listen(): Promise<void> {
+      const rl = createInterface({
+         input: process.stdin,
+         terminal: false,
+      });
+
+      await new Promise<void>((resolve) => {
+         rl.on('line', (line) => {
+            void this.dispatchLine(line);
+         });
+
+         rl.on('close', () => {
+            this.client.disconnect();
+            resolve();
+         });
+      });
+   }
+
+   async handleLineForTest(line: string): Promise<McpResponse | null> {
+      return this.processLine(line);
+   }
+
+   /**
+    * Sends a JSON-RPC notification (no `id`, no response
+    * expected) to stdout.
+    */
+   notify(method: string, params?: Record<string, unknown>): void {
+      const notification: Record<string, unknown> = {
+         jsonrpc: '2.0',
+         method,
+      };
+      if (params !== undefined) {
+         notification['params'] = params;
+      }
+      process.stdout.write(JSON.stringify(notification) + '\n');
+   }
+
+   /**
+    * Emits a log notification if the message severity meets or
+    * exceeds the configured log level threshold.
+    */
+   log(level: McpLogLevel, message: unknown, logger?: string): void {
+      if (this.logLevel === null) return;
+      if (!shouldEmitLog(level, this.logLevel)) return;
+      this.notify('notifications/message', {
+         level,
+         logger: logger ?? 'kbdb',
+         data: message,
+      });
+   }
+
+   /**
+    * Sends a JSON-RPC request to the host (server-to-client)
+    * and returns a Promise that resolves with the response
+    * result. Times out after 30 seconds.
+    */
+   sendRequest(
+      method: string,
+      params: Record<string, unknown>,
+   ): Promise<unknown> {
+      const id = this.nextRequestId++;
+      const request = { jsonrpc: '2.0', id, method, params };
+      process.stdout.write(JSON.stringify(request) + '\n');
+      return new Promise((resolve, reject) => {
+         const timer = setTimeout(() => {
+            this.pendingRequests.delete(id);
+            reject(new Error(`Request ${method} timed out`));
+         }, 30000);
+         this.pendingRequests.set(id, {
+            resolve,
+            reject,
+            timer,
+         });
+      });
+   }
+
+   /**
+    * Requests the host to generate text via the sampling
+    * capability. Throws if the host did not advertise sampling
+    * support during initialization.
+    */
+   async requestSampling(
+      messages: {
+         role: string;
+         content: { type: string; text: string };
+      }[],
+      maxTokens: number,
+   ): Promise<unknown> {
+      if (!this.hostCapabilities?.['sampling']) {
+         throw new Error('Host does not support sampling');
+      }
+      return this.sendRequest('sampling/createMessage', {
+         messages,
+         maxTokens,
+      });
+   }
+
+   private async dispatchLine(line: string): Promise<void> {
+      const response = await this.processLine(line);
+      if (response !== null) {
+         this.send(response);
+      }
+   }
+
+   private async processLine(
+      line: string,
+   ): Promise<McpResponse | null> {
+      if (!line.trim()) return null;
+
+      let parsed: Record<string, unknown>;
+      try {
+         parsed = JSON.parse(line) as Record<string, unknown>;
+      } catch {
+         return {
+            jsonrpc: '2.0',
+            id: 0,
+            error: {
+               code: PARSE_ERROR,
+               message: 'Parse error',
+            },
+         };
+      }
+
+      // Incoming response to an outgoing request (sampling)
+      if (
+         parsed['id'] !== undefined &&
+         typeof parsed['method'] !== 'string'
+      ) {
+         const responseId = parsed['id'] as number;
+         const pending = this.pendingRequests.get(responseId);
+         if (pending) {
+            this.pendingRequests.delete(responseId);
+            clearTimeout(pending.timer);
+            if (parsed['error']) {
+               const err = parsed['error'] as {
+                  message?: string;
+               };
+               pending.reject(
+                  new Error(err.message ?? 'Request failed'),
+               );
+            } else {
+               pending.resolve(parsed['result']);
+            }
+         }
+         return null;
+      }
+
+      const request = parsed as unknown as McpRequest;
+
+      if (request.id === undefined) {
+         if (
+            request.method === 'notifications/initialized' ||
+            request.method === 'notifications/cancelled'
+         ) {
+            if (request.method === 'notifications/initialized') {
+               this.initialized = true;
+            }
+         }
+         return null;
+      }
+
+      const id = request.id;
+
+      if (
+         !this.initialized &&
+         request.method !== 'initialize' &&
+         request.method !== 'ping'
+      ) {
+         return {
+            jsonrpc: '2.0',
+            id,
+            error: {
+               code: RESOURCE_NOT_FOUND,
+               message: 'Server not initialized',
+            },
+         };
+      }
+
+      const response = await this.handleRequest(request);
+      return response;
+   }
+
+   private async handleRequest(
+      request: McpRequest,
+   ): Promise<McpResponse> {
+      const id = request.id as number | string;
+
+      switch (request.method) {
+         case 'initialize': {
+            const params = request.params ?? {};
+            const caps = params['capabilities'];
+            this.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(
+               this.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(
+                  this.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 this.client.listByType('skill');
+            const agents =
+               await this.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,
+                  this.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,
+               this.client,
+            );
+            return { jsonrpc: '2.0', id, result };
+         }
+
+         case 'roots/list': {
+            const roots = handleRootsList(this.contextPath);
+            return {
+               jsonrpc: '2.0',
+               id,
+               result: { roots },
+            };
+         }
+
+         case 'logging/setLevel': {
+            const params = request.params ?? {};
+            const level = params['level'] as McpLogLevel | undefined;
+            this.logLevel = level ?? null;
+            return { jsonrpc: '2.0', id, result: {} };
+         }
+
+         case 'resources/subscribe': {
+            const params = request.params ?? {};
+            const uri =
+               typeof params['uri'] === 'string' ? params['uri'] : '';
+            this.subscriptions.add(uri);
+            return { jsonrpc: '2.0', id, result: {} };
+         }
+
+         case 'resources/unsubscribe': {
+            const params = request.params ?? {};
+            const uri =
+               typeof params['uri'] === 'string' ? params['uri'] : '';
+            this.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,
+               },
+            };
+      }
+   }
+
+   private send(response: McpResponse): void {
+      const json = JSON.stringify(response);
+      process.stdout.write(json + '\n');
+   }
+}

package/src/shared/mcp/constants/mcp-error-codes.constant.ts

@@ -0,0 +1,30 @@
+/**
+ * JSON-RPC 2.0 parse error code. Returned when the
+ * server receives malformed JSON.
+ */
+export const PARSE_ERROR = -32700;
+
+/**
+ * JSON-RPC 2.0 method not found error code. Returned
+ * when the requested method does not exist.
+ */
+export const METHOD_NOT_FOUND = -32601;
+
+/**
+ * JSON-RPC 2.0 invalid params error code. Returned
+ * when method parameters are invalid or missing.
+ */
+export const INVALID_PARAMS = -32602;
+
+/**
+ * JSON-RPC 2.0 internal error code. Returned when an
+ * unexpected server-side error occurs.
+ */
+export const INTERNAL_ERROR = -32603;
+
+/**
+ * MCP-specific resource not found error code. Returned
+ * when a well-formed URI does not match any resource
+ * in the knowledge base.
+ */
+export const RESOURCE_NOT_FOUND = -32002;

package/src/shared/mcp/functions/create-mcp-server.function.ts

@@ -0,0 +1,14 @@
+import { McpServer } from '../classes/mcp-server.class.ts';
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+
+/**
+ * Factory that constructs a new `McpServer` bound to the given
+ * worker client. Call `server.listen()` on the returned instance
+ * to start processing stdio input.
+ *
+ * @param client - worker client providing knowledge-base operations
+ * @returns a configured `McpServer` ready to listen
+ */
+export function createMcpServer(client: McpWorkerClient): McpServer {
+   return new McpServer(client);
+}

package/src/shared/mcp/functions/create-prompt-definitions.function.ts

@@ -0,0 +1,102 @@
+import type { McpPrompt } from '../typings/prompt-types.interface.ts';
+import type { McpPromptArgument } from '../typings/prompt-types.interface.ts';
+
+/** Minimal skill section record shape required by this function. */
+interface SkillSectionRecord {
+   /** Knowledge-base identifier of the section. */
+   readonly kbid: string;
+   /** Human-readable section title used as the prompt name. */
+   readonly title: string | null;
+   /** JSON-encoded skill definition content. */
+   readonly content: string;
+   /** Optional human-readable section description. */
+   readonly description?: string | null;
+}
+
+/** Minimal document manifest shape required by this function. */
+interface AgentDocumentRecord {
+   /** Unique document identifier. */
+   readonly docid: string;
+   /** Human-readable document title used in the prompt name. */
+   readonly title: string;
+   /** Ordered section references belonging to the document. */
+   readonly sections: readonly {
+      readonly kbid: string;
+      readonly position: number;
+   }[];
+}
+
+/**
+ * Parses the `arguments` field from a skill's JSON content string.
+ *
+ * Returns the array of prompt argument definitions when the content
+ * is valid JSON with an `arguments` array, or `undefined` when JSON
+ * parsing fails or the field is absent.
+ */
+function parseSkillArguments(
+   content: string,
+): readonly McpPromptArgument[] | undefined {
+   try {
+      const parsed = JSON.parse(content) as Record<string, unknown>;
+      if (!Array.isArray(parsed['arguments'])) {
+         return undefined;
+      }
+      return (parsed['arguments'] as Record<string, unknown>[]).map(
+         (arg) => ({
+            name: typeof arg['name'] === 'string' ? arg['name'] : '',
+            description:
+               typeof arg['description'] === 'string'
+                  ? arg['description']
+                  : undefined,
+            required:
+               typeof arg['required'] === 'boolean'
+                  ? arg['required']
+                  : undefined,
+         }),
+      );
+   } catch {
+      return undefined;
+   }
+}
+
+/**
+ * Builds the list of MCP prompt definitions from skill sections and
+ * agent document manifests stored in the knowledge base.
+ *
+ * Skills are mapped first (in input order), followed by agents.
+ * Each skill becomes a prompt whose name is the section title and
+ * whose arguments are extracted from the JSON content. Each agent
+ * becomes a prompt prefixed with `"agent:"` and carries an empty
+ * arguments array.
+ *
+ * @param skills - skill section records from `listByType('skill')`
+ * @param agents - agent document manifests from
+ *   `listDocumentsByType('agent')`
+ * @returns ordered list of MCP prompt definitions
+ */
+export function createPromptDefinitions(
+   skills: readonly SkillSectionRecord[],
+   agents: readonly AgentDocumentRecord[],
+): McpPrompt[] {
+   const skillPrompts: McpPrompt[] = skills
+      .filter(
+         (r): r is SkillSectionRecord & { title: string } =>
+            r.title !== null,
+      )
+      .map((record) => {
+         const args = parseSkillArguments(record.content);
+         const prompt: McpPrompt = {
+            name: record.title,
+            description: record.description ?? undefined,
+            arguments: args,
+         };
+         return prompt;
+      });
+
+   const agentPrompts: McpPrompt[] = agents.map((doc) => ({
+      name: `agent:${doc.title}`,
+      arguments: [],
+   }));
+
+   return [...skillPrompts, ...agentPrompts];
+}

package/src/shared/mcp/functions/create-resource-templates.function.ts

@@ -0,0 +1,23 @@
+import type { McpResourceTemplate } from '../typings/mcp-types.interface.ts';
+
+/**
+ * Returns the list of MCP resource URI templates served by the
+ * knowledge-base server. Each template describes the URI pattern,
+ * human-readable metadata, and the MIME type of the resource body.
+ */
+export function createResourceTemplates(): McpResourceTemplate[] {
+   return [
+      {
+         uriTemplate: 'kbdb://section/{kb_id}',
+         name: 'Section',
+         description: 'A knowledge base section by its kb-id.',
+         mimeType: 'text/plain',
+      },
+      {
+         uriTemplate: 'kbdb://document/{doc_id}',
+         name: 'Document',
+         description: 'A document with its ordered sections.',
+         mimeType: 'application/json',
+      },
+   ];
+}