import type { Annotations } from '@modelcontextprotocol/sdk/types.js';
import { McpError } from '@modelcontextprotocol/sdk/types.js';
/**
 * The MCP content shapes this server emits. Defined here rather than reusing
 * the SDK's union, so an SDK addition cannot widen handler signatures.
 */
export type RagTextContentBlock = {
    type: 'text';
    text: string;
    annotations?: Annotations;
};
export type RagImageContentBlock = {
    type: 'image';
    data: string;
    mimeType: 'image/png' | 'image/jpeg';
    annotations?: Annotations;
};
export type RagContentBlock = RagTextContentBlock | RagImageContentBlock;
/**
 * 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<T extends RagContentBlock[]>(content: T, warnings: readonly string[]): T;
/**
 * Diagnostic block exposing a config error, so `status` can report a degraded
 * server over MCP without the user inspecting stderr.
 */
export declare function buildConfigErrorBlock(message: string): RagTextContentBlock;
/**
 * Each handler's client-message policy. `prefix` applies to the native-error
 * fallback message only; prefix-less handlers omit it.
 */
export type ToMcpErrorContext = {
    prefix?: string;
};
/**
 * The controlled message sent to the MCP client: only `.message`, regardless
 * of `NODE_ENV`, so no stack or cause chain can leak even in development.
 */
export declare function formatErrorForClient(error: unknown): string;
/**
 * Full diagnostic string for stderr: every `.cause` link with its stack. Never
 * sent to the client — 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 a handler error to an `McpError` for the client boundary.
 *
 * An existing `McpError` passes through, preserving hand-built validation
 * codes. A recognized `AppError` maps by `kind` — `validation`/`config` to
 * `InvalidParams`, else `InternalError` — and keeps its own message raw, with
 * NO operation prefix even when `context.prefix` is set. Anything else becomes
 * `InternalError` with the prefix applied. The cause chain is never included.
 */
export declare function toMcpError(error: unknown, context: ToMcpErrorContext): McpError;
//# sourceMappingURL=error-utils.d.ts.map