@dikolab/kbdb 0.3.0 → 0.3.2

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

@@ -0,0 +1,16 @@
+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 declare function handleSkillPrompt(name: string, promptArgs: Record<string, string>, client: McpWorkerClient): Promise<McpPromptMessage[]>;

package/dist/src/shared/mcp/functions/handle-tool-auto-capture-review.function.d.ts

@@ -0,0 +1,12 @@
+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 declare function handleToolAutoCaptureReview(_args: Record<string, unknown>): Promise<ToolCallResult>;

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

@@ -0,0 +1,11 @@
+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 declare function handleToolCheck(client: McpWorkerClient): Promise<ToolCallResult>;

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

@@ -0,0 +1,12 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { ToolCallResult } from '../typings/tool-call-result.model.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 declare function handleToolContent(client: McpWorkerClient, args: Record<string, unknown>): Promise<ToolCallResult>;

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

@@ -0,0 +1,12 @@
+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 declare function handleToolExport(client: McpWorkerClient, args: Record<string, unknown>): Promise<ToolCallResult>;

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

@@ -0,0 +1,11 @@
+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 declare function handleToolGc(client: McpWorkerClient): Promise<ToolCallResult>;

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

@@ -0,0 +1,12 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { ToolCallResult } from '../typings/tool-call-result.model.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 declare function handleToolLearn(client: McpWorkerClient, args: Record<string, unknown>): Promise<ToolCallResult>;

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

@@ -0,0 +1,11 @@
+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 declare function handleToolRebuild(client: McpWorkerClient): Promise<ToolCallResult>;

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

@@ -0,0 +1,12 @@
+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 declare function handleToolRetrieve(client: McpWorkerClient, args: Record<string, unknown>): Promise<ToolCallResult>;

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

@@ -0,0 +1,13 @@
+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 declare function handleToolSearch(client: McpWorkerClient, args: Record<string, unknown>): Promise<ToolCallResult>;

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

@@ -0,0 +1,12 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { ToolCallResult } from '../typings/tool-call-result.model.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 declare function handleToolSkillDelete(client: McpWorkerClient, args: Record<string, unknown>): Promise<ToolCallResult>;

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

@@ -0,0 +1,13 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { ToolCallResult } from '../typings/tool-call-result.model.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 declare function handleToolSkillGet(client: McpWorkerClient, args: Record<string, unknown>): Promise<ToolCallResult>;

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

@@ -0,0 +1,13 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
+/**
+ * Handles the `skill-learn` MCP tool call.
+ *
+ * Validates required arguments, extracts template placeholders from
+ * the body, serialises the skill, and stores it as a knowledge-base
+ * section.
+ *
+ * @param client - the worker client used to execute operations
+ * @param args - tool arguments from the MCP request
+ */
+export declare function handleToolSkillLearn(client: McpWorkerClient, args: Record<string, unknown>): Promise<ToolCallResult>;

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

@@ -0,0 +1,11 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
+/**
+ * Handles the `skill-list` MCP tool call.
+ *
+ * Lists all skills stored in the knowledge base, including the
+ * argument count extracted from each skill's JSON content.
+ *
+ * @param client - the worker client used to execute operations
+ */
+export declare function handleToolSkillList(client: McpWorkerClient): Promise<ToolCallResult>;

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

@@ -0,0 +1,11 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
+/**
+ * Handles the `status` MCP tool call.
+ *
+ * Fetches database metadata from the worker client and returns it as
+ * formatted JSON.
+ *
+ * @param client - the worker client used to execute operations
+ */
+export declare function handleToolStatus(client: McpWorkerClient): Promise<ToolCallResult>;

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

@@ -0,0 +1,12 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
+/**
+ * Handles the `unlearn` MCP tool call.
+ *
+ * Removes the section identified by `kbid` from the knowledge base
+ * and returns the removal result as JSON.
+ *
+ * @param client - the worker client used to execute operations
+ * @param args - tool arguments from the MCP request
+ */
+export declare function handleToolUnlearn(client: McpWorkerClient, args: Record<string, unknown>): Promise<ToolCallResult>;

package/dist/src/shared/mcp/functions/parse-agent-meta.function.d.ts

@@ -0,0 +1,14 @@
+/** Parsed shape of an agent metadata section. */
+export interface AgentMeta {
+    /** Agent persona text. */
+    readonly persona: string;
+}
+/**
+ * Parses agent metadata from a raw JSON content string.
+ *
+ * Returns an object with an empty `persona` when parsing fails or
+ * the required field is absent or not a string.
+ *
+ * @param content - raw JSON content string of the agent metadata section
+ */
+export declare function parseAgentMeta(content: string): AgentMeta;

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

@@ -0,0 +1,11 @@
+import type { McpPromptArgument } from '../typings/prompt-types.interface.ts';
+/**
+ * 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.
+ *
+ * @param content - raw JSON string of the skill section content
+ */
+export declare function parseSkillArguments(content: string): readonly McpPromptArgument[] | undefined;

package/dist/src/shared/mcp/functions/read-agent-meta.function.d.ts

@@ -0,0 +1,17 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+/**
+ * Reads the metadata JSON stored in the first section of an agent
+ * document and extracts `name`, `description`, and `persona`.
+ *
+ * Returns defaults when the section is absent or its content is
+ * not parseable as JSON.
+ *
+ * @param client - the worker client used to read sections
+ * @param metaKbid - kbid of the agent metadata section
+ * @param fallbackName - name returned when `name` is absent from JSON
+ */
+export declare function readAgentMeta(client: McpWorkerClient, metaKbid: string, fallbackName: string): Promise<{
+    name: string;
+    description: string;
+    persona: string;
+}>;

package/dist/src/shared/mcp/functions/resolve-skill-refs.function.d.ts

@@ -0,0 +1,23 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+/** A section reference within an agent document. */
+export interface AgentSectionRef {
+    /** Knowledge-base identifier of the section. */
+    readonly kbid: string;
+    /** Zero-based position of the section within the document. */
+    readonly position: number;
+}
+/**
+ * Resolves skill names for a list of section references by reading
+ * each section's JSON content and extracting the `name` field.
+ *
+ * Returns `name: null` for references where the section no longer
+ * exists (dangling references) or whose content is not valid JSON.
+ *
+ * @param client - the worker client used to read sections
+ * @param skillRefs - ordered list of section references to resolve
+ */
+export declare function resolveSkillRefs(client: McpWorkerClient, skillRefs: AgentSectionRef[]): Promise<{
+    kbid: string;
+    name: string | null;
+    position: number;
+}[]>;

package/dist/src/shared/mcp/functions/run-startup-health-check.function.d.ts

@@ -0,0 +1,14 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+/**
+ * Runs an integrity check immediately after the MCP handshake
+ * completes.
+ *
+ * Calls `notify` with a `notifications/message` warning when the
+ * check detects issues so the connected agent is aware before making
+ * requests. Errors from the check itself are swallowed -- the server
+ * continues operating regardless.
+ *
+ * @param client - the worker client used to run the integrity check
+ * @param notify - callback used to send notifications to the host
+ */
+export declare function runStartupHealthCheck(client: McpWorkerClient, notify: (method: string, params: Record<string, unknown>) => void): Promise<void>;

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

@@ -0,0 +1,16 @@
+/** MCP capability flags advertised during initialization. */
+export interface McpCapabilities {
+    /** Indicates the server supports the tools capability. */
+    readonly tools?: Record<string, unknown>;
+    /** Indicates the server supports the resources capability. */
+    readonly resources?: Record<string, unknown>;
+    /** Indicates the server supports the prompts capability. */
+    readonly prompts?: Record<string, unknown>;
+    /** Indicates the server supports the logging capability. */
+    readonly logging?: Record<string, unknown>;
+    /**
+     * Indicates the server supports the completions capability,
+     * providing argument auto-completion for prompts and resources.
+     */
+    readonly completions?: Record<string, unknown>;
+}

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

@@ -92,6 +92,8 @@ export interface McpWorkerClient {
         readonly limit?: number;
         /** Number of results to skip for pagination. */
         readonly offset?: number;
+        /** Search algorithm: 'lexical', 'vector', or 'hybrid'. */
+        readonly algo?: string;
     }): Promise<{
         readonly items: readonly {
             readonly kbid: string;

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

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

package/dist/src/shared/mcp/typings/mcp-content-result.model.d.ts

@@ -0,0 +1,9 @@
+/** Result returned by content composition. */
+export interface McpContentResult {
+    /** MIME type of the composed output, always `'text/markdown'`. */
+    readonly type: 'text/markdown';
+    /** The composed Markdown string. */
+    readonly data: string;
+    /** Character count of `data` (not byte count). */
+    readonly total: number;
+}

package/dist/src/shared/mcp/typings/mcp-export-result.model.d.ts

@@ -0,0 +1,11 @@
+/** Export report returned by the daemon. */
+export interface McpExportResult {
+    /** Absolute path to the directory where files were written. */
+    readonly path: string;
+    /** Number of section files copied to the export directory. */
+    readonly sections_exported: number;
+    /** Number of document manifest files copied. */
+    readonly documents_exported: number;
+    /** Time taken to complete the export, in milliseconds. */
+    readonly elapsed_ms: number;
+}

package/dist/src/shared/mcp/typings/mcp-gc-result.model.d.ts

@@ -0,0 +1,15 @@
+/** Garbage collection report returned by the daemon. */
+export interface McpGcResult {
+    /** Number of unreferenced sections removed. */
+    readonly removed_sections: number;
+    /** Total bytes freed by removing unreferenced sections. */
+    readonly removed_bytes: number;
+    /** Time taken to complete garbage collection, in milliseconds. */
+    readonly elapsed_ms: number;
+    /**
+     * Number of sections whose source_path file no longer contains
+     * their heading text. Advisory; not auto-removed by gc.
+     * Absent on older daemon versions.
+     */
+    readonly stale_sources?: number;
+}

package/dist/src/shared/mcp/typings/mcp-integrity-check-result.model.d.ts

@@ -0,0 +1,16 @@
+import type { McpIntegrityError } from './mcp-integrity-error.model.ts';
+/** Integrity check report returned by the daemon. */
+export interface McpIntegrityCheckResult {
+    /** `true` when all checks passed and no errors were found. */
+    readonly ok: boolean;
+    /** All integrity errors found; empty when `ok` is `true`. */
+    readonly errors: McpIntegrityError[];
+    /** Total number of sections examined. */
+    readonly sections_checked: number;
+    /** Total number of documents examined. */
+    readonly documents_checked: number;
+    /** Total number of marker references checked. */
+    readonly references_checked: number;
+    /** Time taken to complete the check, in milliseconds. */
+    readonly elapsed_ms: number;
+}

package/dist/src/shared/mcp/typings/mcp-integrity-error.model.d.ts

@@ -0,0 +1,9 @@
+/** A single integrity error found during a database check. */
+export interface McpIntegrityError {
+    /** The category of integrity violation detected. */
+    readonly type: 'checksum_mismatch' | 'orphan_section' | 'orphan_document' | 'broken_reference' | 'type_mismatch' | 'circular_reference';
+    /** Identifier of the entity (kbid or docid) that has the issue. */
+    readonly entity: string;
+    /** Human-readable description of the specific problem. */
+    readonly detail: string;
+}

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

@@ -0,0 +1,9 @@
+/** A JSON-RPC 2.0 notification with no expected response. */
+export interface McpNotification {
+    /** JSON-RPC protocol version. Must always be '2.0'. */
+    readonly jsonrpc: '2.0';
+    /** Notification method name. */
+    readonly method: string;
+    /** Optional notification parameters. */
+    readonly params?: Record<string, unknown>;
+}

package/dist/src/shared/mcp/typings/mcp-rebuild-result.model.d.ts

@@ -0,0 +1,9 @@
+/** Index rebuild report returned by the daemon. */
+export interface McpRebuildResult {
+    /** Number of text and code sections that were re-indexed. */
+    readonly sections_reindexed: number;
+    /** Total number of unique terms written to the rebuilt indexes. */
+    readonly terms_indexed: number;
+    /** Time taken to complete the rebuild, in milliseconds. */
+    readonly elapsed_ms: number;
+}

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

@@ -0,0 +1,11 @@
+/** A JSON-RPC 2.0 request message sent to the MCP server. */
+export interface McpRequest {
+    /** JSON-RPC protocol version. Must always be '2.0'. */
+    readonly jsonrpc: '2.0';
+    /** Request identifier; absent for notifications. */
+    readonly id?: number | string;
+    /** RPC method name. */
+    readonly method: string;
+    /** Optional method parameters. */
+    readonly params?: Record<string, unknown>;
+}

package/dist/src/shared/mcp/typings/mcp-resource-result.interface.d.ts

@@ -0,0 +1,12 @@
+/** Result returned by `handleResourceRead`. */
+export interface McpResourceResult {
+    /** One or more content items for the requested resource URI. */
+    readonly contents: readonly {
+        /** 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;
+    }[];
+}

package/dist/src/shared/mcp/typings/mcp-resource-template.interface.d.ts

@@ -0,0 +1,11 @@
+/** A URI template describing an MCP resource the server serves. */
+export interface McpResourceTemplate {
+    /** RFC 6570 URI template for the resource. */
+    readonly uriTemplate: string;
+    /** Human-readable resource name. */
+    readonly name: string;
+    /** Human-readable description of the resource. */
+    readonly description: string;
+    /** Optional MIME type for the resource content. */
+    readonly mimeType?: string;
+}

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

@@ -0,0 +1,18 @@
+/** A JSON-RPC 2.0 response message sent from the MCP server. */
+export interface McpResponse {
+    /** JSON-RPC protocol version. Must always be '2.0'. */
+    readonly jsonrpc: '2.0';
+    /** Echoes the request identifier. */
+    readonly id: number | string;
+    /** Successful result payload; absent when error is set. */
+    readonly result?: unknown;
+    /** Error payload; absent when result is set. */
+    readonly error?: {
+        /** Numeric error code as defined by JSON-RPC or MCP. */
+        readonly code: number;
+        /** Human-readable error message. */
+        readonly message: string;
+        /** Optional additional error data. */
+        readonly data?: unknown;
+    };
+}

package/dist/src/shared/mcp/typings/mcp-server-info.interface.d.ts

@@ -0,0 +1,7 @@
+/** Identity information for the MCP server. */
+export interface McpServerInfo {
+    /** Server name reported during MCP initialization. */
+    readonly name: string;
+    /** Server version string reported during MCP initialization. */
+    readonly version: string;
+}

package/dist/src/shared/mcp/typings/mcp-server-state.interface.d.ts

@@ -0,0 +1,16 @@
+import type { McpLogLevel } from './log-types.interface.ts';
+/**
+ * Mutable runtime state shared by `McpServer` and its request
+ * handler. Extracted as an interface so the handler can be
+ * tested independently of the full server class.
+ */
+export interface McpServerState {
+    /** Advertised capabilities received from the MCP host. */
+    hostCapabilities: Record<string, unknown> | null;
+    /** Currently configured log level, or `null` when unset. */
+    logLevel: McpLogLevel | null;
+    /** Set of URI strings that the host has subscribed to. */
+    readonly subscriptions: Set<string>;
+    /** Filesystem path used as the KB context root. */
+    readonly contextPath: string;
+}

package/dist/src/shared/mcp/typings/mcp-tool-annotations.interface.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Optional behavioral hints for an MCP tool, used by clients to
+ * decide how to present or invoke the tool safely.
+ */
+export interface McpToolAnnotations {
+    /**
+     * Human-readable title for the tool, suitable for display
+     * in client UIs.
+     */
+    readonly title?: string;
+    /**
+     * When `true`, the tool only reads data and does not modify
+     * any server-side state.
+     */
+    readonly readOnlyHint?: boolean;
+    /**
+     * When `true`, the tool may cause data loss or irreversible
+     * changes.
+     */
+    readonly destructiveHint?: boolean;
+    /**
+     * When `true`, calling the tool multiple times with the same
+     * arguments produces the same result with no additional side
+     * effects.
+     */
+    readonly idempotentHint?: boolean;
+    /**
+     * When `true`, the tool may interact with systems or data
+     * outside the immediate knowledge base context.
+     */
+    readonly openWorldHint?: boolean;
+}

package/dist/src/shared/mcp/typings/mcp-tool-definition.interface.d.ts

@@ -0,0 +1,15 @@
+import type { McpToolAnnotations } from './mcp-tool-annotations.interface.ts';
+/** Definition of a single MCP tool exposed by the server. */
+export interface McpToolDefinition {
+    /** Unique tool name used to invoke it. */
+    readonly name: string;
+    /** Human-readable description of what the tool does. */
+    readonly description: string;
+    /** JSON Schema object describing the tool's input parameters. */
+    readonly inputSchema: Record<string, unknown>;
+    /**
+     * Optional behavioral hints that describe how the tool
+     * interacts with state.
+     */
+    readonly annotations?: McpToolAnnotations;
+}

package/dist/src/shared/mcp/typings/mcp-tool-result.interface.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Result returned by `handleToolCall`. Successful tool responses
+ * carry `isError: true` for application-level failures rather than
+ * using JSON-RPC error responses.
+ */
+export interface McpToolResult {
+    /** One or more text content items describing the result. */
+    readonly content: readonly {
+        /** Content type identifier, always 'text'. */
+        readonly type: string;
+        /** Text payload of the content item. */
+        readonly text: string;
+    }[];
+    /**
+     * Set to `true` when the tool encountered an application-level
+     * error. Absent or `false` on success.
+     */
+    readonly isError?: boolean;
+}