import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
import type { ServiceResult } from '../../models/service-result.js';
import type { PaginationMetadata } from '../config/pagination.js';
import type { McpAdapters } from '../config/mcp-config.js';
import { type McpErrorCode } from '../errors.js';
/**
 * Creates a typed MCP tool handler that narrows `unknown` input to type `T`.
 *
 * The McpServer SDK validates input via Zod schemas before calling handlers,
 * so the cast from `unknown` to `T` is runtime-safe. This wrapper centralizes
 * the single cast point instead of scattering `input as T` across 18 handlers.
 *
 * @template T The validated input type (inferred from the handler parameter)
 * @param handler - Typed handler function accepting validated input
 * @returns Untyped handler matching the ToolHandler signature
 */
export declare function typedHandler<T>(handler: (adapters: McpAdapters, input: T) => Promise<CallToolResult>): (adapters: McpAdapters, input: unknown) => Promise<CallToolResult>;
/**
 * Converts a ServiceResult to MCP CallToolResult format.
 *
 * Maps success/failure to MCP's content/isError structure.
 * Preserves warnings and metadata in the response.
 *
 * @template T The type of the service result data
 * @param result - ServiceResult from a service call
 * @returns MCP-formatted CallToolResult
 *
 * @example
 * ```typescript
 * const serviceResult = await orgInfoService.getOrgIdentity();
 * return serviceResultToMcp(serviceResult);
 * ```
 */
export declare function serviceResultToMcp<T>(result: ServiceResult<T>): CallToolResult;
/**
 * Converts a ServiceResult to a paginated MCP CallToolResult.
 *
 * Includes `_pagination` metadata in the response envelope for
 * cursor-based pagination through large result sets.
 *
 * @template T The type of the service result data
 * @param result - ServiceResult from a service call
 * @param pagination - Pagination metadata for the response
 * @returns MCP-formatted CallToolResult with pagination envelope
 */
export declare function serviceResultToMcpPaginated<T>(result: ServiceResult<T>, pagination: PaginationMetadata): CallToolResult;
/**
 * Extracts a user-facing error message from a caught error and logs the
 * full stack trace to stderr for post-mortem debugging.
 *
 * @param error - The caught error (may be Error or non-Error value)
 * @param context - Tool/handler name for the log prefix
 * @returns The error message string
 */
export declare function extractErrorMessage(error: unknown, context: string): string;
/**
 * Creates an MCP error response.
 *
 * @param errorCode - MCP error code
 * @param message - Error message
 * @returns MCP-formatted error CallToolResult
 */
export declare function createMcpError(errorCode: McpErrorCode, message: string): CallToolResult;