/**
 * Tool Converter Utilities
 *
 * Converts between NeuroLink tool format and MCP tool format.
 * Enables seamless interoperability between NeuroLink's internal
 * tool representation and the MCP protocol specification.
 *
 * @module mcp/toolConverter
 * @since 8.39.0
 */
import type { JsonObject, JsonValue } from "../types/common.js";
import type { NeuroLinkExecutionContext, ToolResult } from "../types/mcpTypes.js";
import type { MCPServerTool, MCPToolAnnotations } from "./toolAnnotations.js";
/**
 * NeuroLink internal tool format
 */
export type NeuroLinkTool = {
    /**
     * Tool name
     */
    name: string;
    /**
     * Tool description
     */
    description: string;
    /**
     * Input parameters schema
     */
    parameters?: JsonObject;
    /**
     * Tool execution function
     */
    execute: (params: unknown, context?: NeuroLinkExecutionContext) => Promise<ToolResult | unknown>;
    /**
     * Category for organization
     */
    category?: string;
    /**
     * Tags for filtering
     */
    tags?: string[];
    /**
     * Whether the tool is async
     */
    isAsync?: boolean;
    /**
     * Custom metadata
     */
    metadata?: Record<string, JsonValue>;
};
/**
 * MCP protocol tool format (from @modelcontextprotocol/sdk)
 */
export type MCPProtocolTool = {
    /**
     * Tool name
     */
    name: string;
    /**
     * Tool description
     */
    description?: string;
    /**
     * JSON Schema for input
     */
    inputSchema: {
        type: "object";
        properties?: Record<string, JsonObject>;
        required?: string[];
    };
    /**
     * Optional annotations (MCP 2024-11-05+)
     */
    annotations?: {
        title?: string;
        readOnlyHint?: boolean;
        destructiveHint?: boolean;
        idempotentHint?: boolean;
        openWorldHint?: boolean;
    };
};
/**
 * Tool converter options
 */
export type ToolConverterOptions = {
    /**
     * Automatically infer annotations from tool definition
     */
    inferAnnotations?: boolean;
    /**
     * Default annotations to apply
     */
    defaultAnnotations?: MCPToolAnnotations;
    /**
     * Whether to preserve original metadata
     */
    preserveMetadata?: boolean;
    /**
     * Namespace prefix for tool names
     */
    namespacePrefix?: string;
};
/**
 * Convert NeuroLink tool to MCP server tool format
 */
export declare function neuroLinkToolToMCP(tool: NeuroLinkTool, options?: ToolConverterOptions): MCPServerTool;
/**
 * Convert MCP server tool to NeuroLink tool format
 */
export declare function mcpToolToNeuroLink(tool: MCPServerTool, options?: {
    removeNamespacePrefix?: string;
}): NeuroLinkTool;
/**
 * Convert MCP protocol tool to MCPServerTool
 * (For tools received from external MCP servers)
 */
export declare function mcpProtocolToolToServerTool(protocolTool: MCPProtocolTool, executor: (params: unknown, context?: NeuroLinkExecutionContext) => Promise<ToolResult | unknown>, options?: ToolConverterOptions): MCPServerTool;
/**
 * Convert MCPServerTool to MCP protocol tool format
 * (For exposing tools to external MCP clients)
 */
export declare function serverToolToMCPProtocol(tool: MCPServerTool): MCPProtocolTool;
/**
 * Batch convert NeuroLink tools to MCP format
 */
export declare function batchConvertToMCP(tools: NeuroLinkTool[], options?: ToolConverterOptions): MCPServerTool[];
/**
 * Batch convert MCP tools to NeuroLink format
 */
export declare function batchConvertToNeuroLink(tools: MCPServerTool[], options?: {
    removeNamespacePrefix?: string;
}): NeuroLinkTool[];
/**
 * Create a tool from a function with automatic schema inference
 */
export declare function createToolFromFunction<TParams extends Record<string, unknown>>(name: string, description: string, fn: (params: TParams, context?: NeuroLinkExecutionContext) => Promise<unknown>, options?: {
    parameters?: JsonObject;
    annotations?: MCPToolAnnotations;
    metadata?: Record<string, unknown>;
}): MCPServerTool;
/**
 * Validate tool name according to MCP specification
 */
export declare function validateToolName(name: string): {
    valid: boolean;
    errors: string[];
};
/**
 * Sanitize tool name for MCP compatibility
 */
export declare function sanitizeToolName(name: string): string;
/**
 * Tool compatibility matrix
 */
export declare const TOOL_COMPATIBILITY: {
    /**
     * Features supported by MCP 2024-11-05 specification
     */
    readonly MCP_2024_11_05: {
        readonly annotations: true;
        readonly inputSchema: true;
        readonly outputSchema: false;
        readonly streamingResults: false;
        readonly batchExecution: false;
    };
    /**
     * Features supported by NeuroLink
     */
    readonly NEUROLINK: {
        readonly annotations: true;
        readonly inputSchema: true;
        readonly outputSchema: true;
        readonly streamingResults: true;
        readonly batchExecution: true;
        readonly categories: true;
        readonly tags: true;
    };
};
