@dikolab/kbdb 0.1.0

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

@@ -0,0 +1,41 @@
+import type { McpPrompt } 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;
+    }[];
+}
+/**
+ * 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 declare function createPromptDefinitions(skills: readonly SkillSectionRecord[], agents: readonly AgentDocumentRecord[]): McpPrompt[];
+export {};

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

@@ -0,0 +1,7 @@
+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 declare function createResourceTemplates(): McpResourceTemplate[];

package/dist/src/shared/mcp/functions/create-tool-definitions.function.d.ts

@@ -0,0 +1,7 @@
+import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
+/**
+ * Returns the full list of MCP tool definitions exposed by the
+ * knowledge-base server. Each definition includes the tool name,
+ * a human-readable description, and a JSON Schema for its inputs.
+ */
+export declare function createToolDefinitions(): McpToolDefinition[];

package/dist/src/shared/mcp/functions/extract-skill-arguments.function.d.ts

@@ -0,0 +1,13 @@
+import type { SkillArgument } from '../typings/skill-types.interface.ts';
+/**
+ * Extracts `{{argName}}` placeholder names from a skill body string
+ * and returns them as `SkillArgument` objects marked as required.
+ *
+ * Each placeholder is included only once regardless of how many
+ * times it appears, and the returned array preserves the order of
+ * first occurrence.
+ *
+ * @param body - skill body template text to scan for placeholders
+ * @returns ordered, deduplicated list of argument definitions
+ */
+export declare function extractSkillArguments(body: string): SkillArgument[];

package/dist/src/shared/mcp/functions/handle-agent-create.function.d.ts

@@ -0,0 +1,29 @@
+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-create 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:create` MCP tool call.
+ *
+ * Validates required arguments, verifies that referenced skill kbids
+ * exist, stores agent metadata as a JSON section, groups all sections
+ * into a single document, and returns the resulting document
+ * identifier.
+ *
+ * @param client - the worker client used to execute operations
+ * @param args - tool arguments from the MCP request
+ * @returns content items with optional `isError` flag
+ */
+export declare function handleAgentCreate(client: McpWorkerClient, args: Record<string, unknown>): Promise<ToolCallResult>;
+export {};

package/dist/src/shared/mcp/functions/handle-agent-delete.function.d.ts

@@ -0,0 +1,28 @@
+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-delete 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:delete` MCP tool call.
+ *
+ * Removes the document grouping identified by `docid`. The skill
+ * sections referenced by the agent are not deleted; only the grouping
+ * record is removed.
+ *
+ * @param client - the worker client used to execute operations
+ * @param args - tool arguments; must include a `docid` string
+ * @returns content items confirming removal, or an error item
+ */
+export declare function handleAgentDelete(client: McpWorkerClient, args: Record<string, unknown>): Promise<ToolCallResult>;
+export {};

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

@@ -0,0 +1,29 @@
+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-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;
+}
+/**
+ * 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 declare function handleAgentGet(client: McpWorkerClient, args: Record<string, unknown>): Promise<ToolCallResult>;
+export {};

package/dist/src/shared/mcp/functions/handle-agent-list.function.d.ts

@@ -0,0 +1,31 @@
+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 declare function handleAgentList(client: McpWorkerClient): Promise<ToolCallResult>;
+export {};

package/dist/src/shared/mcp/functions/handle-completion.function.d.ts

@@ -0,0 +1,58 @@
+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 declare function handleCompletion(ref: McpCompletionRef, argument: McpCompletionArgument, client: McpWorkerClient): Promise<McpCompletionResult>;

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

@@ -0,0 +1,23 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { McpPromptMessage } from '../typings/prompt-types.interface.ts';
+/**
+ * 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 declare function handlePromptGet(name: string, promptArgs: Record<string, string>, client: McpWorkerClient): Promise<McpPromptMessage[]>;

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

@@ -0,0 +1,26 @@
+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 declare function handleResourceRead(client: McpWorkerClient, uri: string): Promise<ResourceReadResult>;
+export {};

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

@@ -0,0 +1,21 @@
+/**
+ * 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 declare function handleRootsList(contextPath: string): McpRoot[];

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

@@ -0,0 +1,26 @@
+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;
+}
+/**
+ * Dispatches an MCP tool call to the appropriate knowledge-base
+ * operation and returns the result formatted as MCP content.
+ *
+ * @param client - the worker client used to execute operations
+ * @param name - the tool name to invoke
+ * @param args - tool arguments from the MCP request
+ * @returns content items with optional isError flag
+ */
+export declare function handleToolCall(client: McpWorkerClient, name: string, args: Record<string, unknown>): Promise<ToolCallResult>;
+export {};

package/dist/src/shared/mcp/functions/parse-skill-content.function.d.ts

@@ -0,0 +1,15 @@
+import type { SkillDefinition } from '../typings/skill-types.interface.ts';
+/**
+ * Parses a JSON string into a `SkillDefinition`.
+ *
+ * Validates that the required `name` and `body` fields are present
+ * and are non-empty strings, then returns the full definition
+ * including optional `description` and `arguments`.
+ *
+ * @param json - JSON string representing a serialized skill
+ * @returns the parsed skill definition
+ * @throws {SyntaxError} when `json` is not valid JSON
+ * @throws {Error} when `name` is missing or empty
+ * @throws {Error} when `body` is missing or not a string
+ */
+export declare function parseSkillContent(json: string): SkillDefinition;

package/dist/src/shared/mcp/functions/serialize-skill-content.function.d.ts

@@ -0,0 +1,9 @@
+import type { SkillDefinition } from '../typings/skill-types.interface.ts';
+/**
+ * Serializes a `SkillDefinition` to a JSON string suitable for
+ * storage as a knowledge-base section's `content` field.
+ *
+ * @param skill - skill definition to serialize
+ * @returns JSON string representation of the skill
+ */
+export declare function serializeSkillContent(skill: SkillDefinition): string;

package/dist/src/shared/mcp/functions/should-emit-log.function.d.ts

@@ -0,0 +1,20 @@
+import type { McpLogLevel } from '../typings/log-types.interface.ts';
+/**
+ * Ordered list of MCP log severity levels, from least severe
+ * (`debug`) to most severe (`emergency`). Used to compare levels
+ * when filtering log output.
+ */
+export declare const LOG_LEVEL_ORDER: McpLogLevel[];
+/**
+ * Determines whether a log message at `messageLevel` should be
+ * emitted when the server's log threshold is `threshold`.
+ *
+ * Returns `true` when `messageLevel` is at the same severity as
+ * `threshold` or higher. Returns `false` when the message level is
+ * below the threshold.
+ *
+ * @param messageLevel - severity of the log message to evaluate
+ * @param threshold - minimum severity level required to emit
+ * @returns `true` if the message meets or exceeds the threshold
+ */
+export declare function shouldEmitLog(messageLevel: McpLogLevel, threshold: McpLogLevel): boolean;

package/dist/src/shared/mcp/index.d.ts

@@ -0,0 +1,9 @@
+export { McpServer } from './classes/mcp-server.class.ts';
+export { createMcpServer } from './functions/create-mcp-server.function.ts';
+export { createToolDefinitions } from './functions/create-tool-definitions.function.ts';
+export { createResourceTemplates } from './functions/create-resource-templates.function.ts';
+export { handleToolCall } from './functions/handle-tool-call.function.ts';
+export { handleResourceRead } from './functions/handle-resource-read.function.ts';
+export { PARSE_ERROR, METHOD_NOT_FOUND, INVALID_PARAMS, INTERNAL_ERROR, RESOURCE_NOT_FOUND, } from './constants/mcp-error-codes.constant.ts';
+export type { McpRequest, McpResponse, McpNotification, McpToolDefinition, McpResourceTemplate, McpServerInfo, McpCapabilities, McpToolResult, McpResourceResult, } from './typings/mcp-types.interface.ts';
+export type { McpWorkerClient, RemoveSectionResult, } from './typings/mcp-client.interface.ts';

package/dist/src/shared/mcp/typings/agent-types.interface.d.ts

@@ -0,0 +1,38 @@
+/**
+ * A reference from an agent document to a skill section,
+ * carrying the skill's position within the agent's ordered
+ * skill list.
+ */
+export interface AgentSkillRef {
+    /** Knowledge-base identifier of the referenced skill section. */
+    readonly kbid: string;
+    /**
+     * Human-readable name of the skill, or `null` when the
+     * referenced section no longer exists (dangling reference).
+     */
+    readonly name: string | null;
+    /** Zero-based position of this skill within the agent's list. */
+    readonly position: number;
+}
+/**
+ * Full definition of an agent, including its persona text and
+ * ordered list of skill references.
+ */
+export interface AgentDefinition {
+    /** Unique document identifier for the agent. */
+    readonly docid: string;
+    /** Human-readable name of the agent. */
+    readonly name: string;
+    /**
+     * Short description of what the agent does, used for discovery
+     * and disambiguation.
+     */
+    readonly description: string;
+    /**
+     * Persona text that governs how the agent behaves when
+     * executing tasks.
+     */
+    readonly persona: string;
+    /** Ordered list of skill references the agent can delegate to. */
+    readonly skills: readonly AgentSkillRef[];
+}

package/dist/src/shared/mcp/typings/log-types.interface.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Severity levels for MCP log messages, ordered from least severe
+ * (`debug`) to most severe (`emergency`).
+ */
+export type McpLogLevel = 'debug' | 'info' | 'notice' | 'warning' | 'error' | 'critical' | 'alert' | 'emergency';
+/**
+ * A structured log message emitted by the MCP server via the
+ * `notifications/message` notification method.
+ */
+export interface McpLogMessage {
+    /** Severity level of the log entry. */
+    readonly level: McpLogLevel;
+    /** Optional logger name identifying the source component. */
+    readonly logger?: string;
+    /** Optional structured payload associated with the log entry. */
+    readonly data?: unknown;
+}