/**
 * Helper functions for MCP tool handlers.
 *
 * Extracted from server.ts to reduce file size and improve maintainability.
 */
/**
 * Format an error response in German.
 */
export declare function formatErrorResponse(error: unknown): string;
/** A plain text content block. */
export interface TextContent {
    type: 'text';
    text: string;
}
/**
 * A pointer to a resource the client can fetch itself instead of re-parsing text.
 *
 * No handler emits one at the moment: `ris_dokument` dropped its block because
 * claude.ai delivers a widget no tool-result event at all for a result that
 * carries one (#52, see DECISIONS.md). The type stays because that is a host
 * bug and the block is meant to come back once it is fixed.
 */
export interface ResourceLinkContent {
    type: 'resource_link';
    uri: string;
    name: string;
    mimeType?: string;
}
export type McpContent = TextContent | ResourceLinkContent;
/**
 * MCP tool response type with index signature for SDK compatibility.
 *
 * The content type is a parameter so the text-only helpers keep returning a
 * single-element tuple — callers can still reach `content[0].text` without
 * narrowing — while handlers that add further blocks use the default.
 */
export type McpToolResponse<C extends McpContent[] = McpContent[]> = {
    [x: string]: unknown;
    content: C;
    structuredContent?: Record<string, unknown>;
    isError?: boolean;
};
/**
 * Create a standard MCP text response.
 */
export declare function createMcpResponse(text: string): McpToolResponse<[TextContent]>;
/**
 * Create an MCP error response.
 *
 * Per the MCP spec, errors during tool execution are reported inside the result
 * with `isError: true` (not as JSON-RPC protocol errors), so the model sees the
 * message and can self-correct. A search without hits is not an error.
 */
export declare function createErrorResponse(text: string): McpToolResponse<[TextContent]>;
/**
 * Create a validation error response listing required parameters.
 */
export declare function createValidationErrorResponse(requiredParams: string[]): McpToolResponse<[TextContent]>;
/**
 * Check if any of the specified parameters has a truthy value.
 */
export declare function hasAnyParam(args: Record<string, unknown>, keys: string[]): boolean;
/**
 * Build base API parameters common to all search requests.
 */
export declare function buildBaseParams(applikation: string, limit: number, seite: number): Record<string, unknown>;
/**
 * Add optional parameters to the params object.
 * Only adds values that are truthy (not undefined, null, or empty string).
 */
export declare function addOptionalParams(params: Record<string, unknown>, mappings: [value: unknown, key: string][]): void;
/**
 * Build the `query` echo returned alongside a search result.
 *
 * Carries the tool's own name plus its validated arguments (Zod defaults
 * included), which is everything a client needs to re-issue the same search for
 * another page. Arguments the caller omitted are dropped rather than echoed as
 * `undefined`, so the echo only ever describes the search that actually ran.
 */
export declare function buildQueryEcho(tool: string, args: Record<string, unknown>): Record<string, unknown>;
/** Search function type for API calls */
export type SearchFunction = (params: Record<string, unknown>, timeout?: number, signal?: AbortSignal) => Promise<unknown>;
/**
 * Execute a search tool and return formatted results.
 * Handles the common try-catch, parsing, formatting, and truncation logic.
 *
 * The formatted text stays the complete rendering; the parsed result is
 * attached as `structuredContent` in the lean shape of `StructuredDocumentSchema`
 * (see structured-search.ts) so clients can consume the hits without re-parsing
 * prose.
 * Error results carry no structured payload — there is no result to describe.
 *
 * `signal` is the MCP request's cancellation signal (`extra.signal`). It reaches
 * the outbound RIS request so an abandoned call stops upstream too; a cancelled
 * request then propagates the abort instead of being reported as a tool error,
 * since nobody is waiting to read it.
 *
 * `queryEcho` (see {@link buildQueryEcho}) is attached to the structured payload
 * so a client can page through the results without reconstructing the call. It is
 * required, not optional: a search tool added later could otherwise omit it and
 * silently strand its clients without pagination for that one tool.
 *
 * The page is fitted into the structured-content budget *before* it is
 * formatted (see `fitStructuredSearchPage`), so the text block and the
 * structured payload always describe the same page; a downgrade notice is
 * appended to the text after truncation so it can never be cut off, and
 * travels as `structuredContent.notice` for the clients that show the model
 * the structured payload instead of the text (#106).
 */
export declare function executeSearchTool(searchFn: SearchFunction, params: Record<string, unknown>, responseFormat: 'markdown' | 'json', signal: AbortSignal | undefined, queryEcho: Record<string, unknown>): Promise<McpToolResponse<[TextContent]>>;
//# sourceMappingURL=helpers.d.ts.map