import type { Annotations } from '@modelcontextprotocol/sdk/types.js';
import { McpError } from '@modelcontextprotocol/sdk/types.js';
/**
 * Shape of a single MCP content block used by RAG server handlers. Mirrors
 * the SDK's `TextContent` minus the strictly internal fields — defined here
 * (rather than imported) because the SDK exposes the type through a
 * widely-imported union; using a local alias keeps handler signatures stable
 * if the SDK widens the union later.
 */
export type RagContentBlock = {
    type: 'text';
    text: string;
    annotations?: Annotations;
};
/**
 * Append config-warning blocks to an existing content array. Returns the
 * same `content` reference for chainability (handlers typically build the
 * array first, then call this once before returning).
 */
export declare function appendConfigWarnings(content: RagContentBlock[], warnings: readonly string[]): RagContentBlock[];
/**
 * Build a diagnostic content block exposing the supplied config-error
 * message. Used by `status` when the server is in degraded mode (invalid
 * `BASE_DIRS`) so the user can read the error via the MCP response without
 * inspecting stderr.
 */
export declare function buildConfigErrorBlock(message: string): RagContentBlock;
/**
 * Context supplied by each handler to {@link toMcpError}, encoding that
 * handler's client-message policy. `prefix` is the operation prefix applied to
 * the generic/native fallback message (e.g. `'Failed to ingest file'`).
 * Prefix-less handlers (`query_documents`/`list_files`/`status`) omit it.
 */
export type ToMcpErrorContext = {
    prefix?: string;
};
/**
 * Build the controlled, type-appropriate message sent to the MCP client.
 *
 * Returns only the error's `.message`, regardless of `NODE_ENV`: the client
 * boundary never receives a stack trace or the raw `.cause` chain, so internal
 * details cannot leak to the client even in development. Full diagnostics
 * (stack + cause chain) belong in {@link formatErrorForLog} (stderr only).
 */
export declare function formatErrorForClient(error: unknown): string;
/**
 * Build the full diagnostic string for stderr logging: every link of the
 * `.cause` chain (via {@link getCauseChain}) followed by its stack. Never sent
 * to the client — this is the log-side counterpart of
 * {@link formatErrorForClient}.
 */
export declare function formatErrorForLog(error: unknown): string;
/**
 * Log an error to stderr with its operation context and full cause chain.
 * The only side-effecting boundary function — the formatters are pure so they
 * can be composed without emitting logs.
 */
export declare function logError(context: string, error: unknown): void;
/**
 * Map an arbitrary handler error to an `McpError` for the client boundary.
 *
 * - An existing `McpError` passes through unchanged (preserves hand-built
 *   input-validation codes).
 * - A recognized `AppError` maps by its `kind`: `validation`/`config` →
 *   `InvalidParams`, everything else → `InternalError`. Its own message is used
 *   raw — **no** operation prefix is applied, even when `context.prefix` is set
 *   (e.g. `DatabaseError` stays prefix-less).
 * - Any other value (native `Error` or non-`Error`) maps to `InternalError`,
 *   and `context.prefix`, when present, is prepended to the controlled
 *   client message. The raw cause chain is never included.
 */
export declare function toMcpError(error: unknown, context: ToMcpErrorContext): McpError;
//# sourceMappingURL=error-utils.d.ts.map