@dikolab/kbdb 0.3.2 → 0.4.0

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

@@ -1,480 +0,0 @@
-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,
-      });
-
-      let pending = Promise.resolve();
-      await new Promise<void>((resolve) => {
-         rl.on('line', (line) => {
-            pending = pending.then(() => this.dispatchLine(line));
-         });
-
-         rl.on('close', () => {
-            void pending.then(() => {
-               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
-            ) {
-               this.initialized = true;
-               void this.runStartupHealthCheck();
-            }
-         }
-         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');
-   }
-
-   /**
-    * Runs an integrity check immediately after the MCP handshake
-    * completes. Emits a `notifications/message` warning when the
-    * check detects issues so the connected agent is aware before
-    * making requests. The server continues operating regardless of
-    * the result.
-    */
-   private async runStartupHealthCheck(): Promise<void> {
-      try {
-         const report = await this.client.integrityCheck();
-         if (!report.ok) {
-            const summary = report.errors
-               .map((e) => `${e.type}: ${e.entity} -- ${e.detail}`)
-               .join('; ');
-            this.notify('notifications/message', {
-               level: 'warning',
-               logger: 'kbdb',
-               data: `Database integrity issues detected: ${summary}`,
-            });
-         }
-      } catch {
-         // Health check failure is non-fatal -- server continues
-      }
-   }
-}

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

@@ -1,30 +0,0 @@
-/**
- * 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/constants/tool-agent-create.constant.ts

@@ -1,39 +0,0 @@
-import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
-
-/** MCP tool definition for the `agent-create` operation. */
-export const TOOL_AGENT_CREATE: McpToolDefinition = {
-   name: 'agent-create',
-   description:
-      'Create an AI agent with a persona and' +
-      ' optional skill references.',
-   inputSchema: {
-      type: 'object',
-      properties: {
-         name: {
-            type: 'string',
-            description: 'Agent name',
-         },
-         description: {
-            type: 'string',
-            description: 'Agent description',
-         },
-         persona: {
-            type: 'string',
-            description: 'Agent persona prompt',
-         },
-         skills: {
-            type: 'array',
-            items: { type: 'string' },
-            description: 'Skill kbid references to attach',
-         },
-      },
-      required: ['name', 'persona'],
-   },
-   annotations: {
-      title: 'Create Agent',
-      readOnlyHint: false,
-      destructiveHint: false,
-      idempotentHint: true,
-      openWorldHint: false,
-   },
-};

package/src/shared/mcp/constants/tool-agent-delete.constant.ts

@@ -1,26 +0,0 @@
-import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
-
-/** MCP tool definition for the `agent-delete` operation. */
-export const TOOL_AGENT_DELETE: McpToolDefinition = {
-   name: 'agent-delete',
-   description:
-      'Delete an agent by its document ID.' +
-      ' Skill sections are not removed.',
-   inputSchema: {
-      type: 'object',
-      properties: {
-         docid: {
-            type: 'string',
-            description: 'Document ID of the agent',
-         },
-      },
-      required: ['docid'],
-   },
-   annotations: {
-      title: 'Delete Agent',
-      readOnlyHint: false,
-      destructiveHint: true,
-      idempotentHint: true,
-      openWorldHint: false,
-   },
-};

package/src/shared/mcp/constants/tool-agent-get.constant.ts

@@ -1,24 +0,0 @@
-import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
-
-/** MCP tool definition for the `agent-get` operation. */
-export const TOOL_AGENT_GET: McpToolDefinition = {
-   name: 'agent-get',
-   description: 'Get an agent definition by document ID.',
-   inputSchema: {
-      type: 'object',
-      properties: {
-         docid: {
-            type: 'string',
-            description: 'Document ID of the agent',
-         },
-      },
-      required: ['docid'],
-   },
-   annotations: {
-      title: 'Get Agent',
-      readOnlyHint: true,
-      destructiveHint: false,
-      idempotentHint: true,
-      openWorldHint: false,
-   },
-};

package/src/shared/mcp/constants/tool-agent-list.constant.ts

@@ -1,18 +0,0 @@
-import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
-
-/** MCP tool definition for the `agent-list` operation. */
-export const TOOL_AGENT_LIST: McpToolDefinition = {
-   name: 'agent-list',
-   description: 'List all agents in the knowledge base.',
-   inputSchema: {
-      type: 'object',
-      properties: {},
-   },
-   annotations: {
-      title: 'List Agents',
-      readOnlyHint: true,
-      destructiveHint: false,
-      idempotentHint: true,
-      openWorldHint: false,
-   },
-};

package/src/shared/mcp/constants/tool-auto-capture-review.constant.ts

@@ -1,32 +0,0 @@
-import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
-
-/**
- * MCP tool definition for the `auto-capture-review` operation.
- *
- * Allows agents to list, approve, or reject pending
- * auto-captured knowledge entries before they are persisted.
- */
-export const TOOL_AUTO_CAPTURE_REVIEW: McpToolDefinition = {
-   name: 'auto-capture-review',
-   description:
-      'Review and approve pending auto-captured knowledge' +
-      ' before storage. Use list to see pending captures,' +
-      ' approve or reject to act on them.',
-   inputSchema: {
-      type: 'object',
-      properties: {
-         action: {
-            type: 'string',
-            enum: ['list', 'approve', 'reject'],
-            description: 'Action to perform on pending captures.',
-         },
-      },
-   },
-   annotations: {
-      title: 'Auto-Capture Review',
-      readOnlyHint: false,
-      destructiveHint: false,
-      idempotentHint: false,
-      openWorldHint: false,
-   },
-};

package/src/shared/mcp/constants/tool-check.constant.ts

@@ -1,21 +0,0 @@
-import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
-
-/** MCP tool definition for the `check` operation. */
-export const TOOL_CHECK: McpToolDefinition = {
-   name: 'check',
-   description:
-      'Verify the integrity of the knowledge base.' +
-      ' Reports checksum mismatches, orphan sections,' +
-      ' broken references, and circular reference chains.',
-   inputSchema: {
-      type: 'object',
-      properties: {},
-   },
-   annotations: {
-      title: 'Integrity Check',
-      readOnlyHint: true,
-      destructiveHint: false,
-      idempotentHint: true,
-      openWorldHint: false,
-   },
-};