import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
import type { ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
import type { ServerRequest, ServerNotification } from '@modelcontextprotocol/sdk/types.js';
import type { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';
import type { ZodRawShapeCompat, ShapeOutput } from '@modelcontextprotocol/sdk/server/zod-compat.js';
import type { McpSdkServerConfigWithInstance } from '../types/mcp.js';
/**
 * A loose Zod-like raw shape, compatible with both Zod 3 and Zod 4.
 * Each value must be a Zod schema object (Zod 3 `ZodTypeAny` or Zod 4 `$ZodType`).
 *
 * @deprecated Use `ZodRawShapeCompat` from `@modelcontextprotocol/sdk/server/zod-compat.js` instead.
 */
export type AnyZodRawShape = ZodRawShapeCompat;
/**
 * Infer the TypeScript type for a Zod raw shape.
 *
 * Given `{ name: z.string(), age: z.number() }`, produces
 * `{ name: string; age: number }`.
 *
 * Supports both Zod 3 and Zod 4 via the MCP SDK's `ShapeOutput` type.
 *
 * @deprecated Use `ShapeOutput` from `@modelcontextprotocol/sdk/server/zod-compat.js` instead.
 */
export type InferShape<T extends AnyZodRawShape> = ShapeOutput<T>;
/**
 * A complete tool definition for use with `createSdkMcpServer`.
 *
 * Contains the tool's name, description, Zod-based input schema, handler
 * function, and optional MCP annotations / metadata.
 */
export type SdkMcpToolDefinition<Schema extends AnyZodRawShape = AnyZodRawShape> = {
    /** Unique tool name (must be unique within the MCP server). */
    name: string;
    /** Human-readable description shown to the model. */
    description: string;
    /** Zod raw shape describing the tool's input parameters. */
    inputSchema: Schema;
    /**
     * Optional MCP tool annotations.
     *
     * `readOnlyHint` is consumed by qodercli as a read-only scheduling hint,
     * allowing the CLI to treat matching tools as eligible for concurrent
     * execution. It does not grant or deny permission. `destructiveHint` and
     * `openWorldHint` reach the wire protocol and are currently used as UI / SDK
     * display metadata. Other annotation fields (`idempotentHint`, `title`) are
     * stripped at the protocol boundary.
     */
    annotations?: ToolAnnotations;
    /** Optional model-facing name. Requires `alwaysLoad: true`. */
    exposedName?: string;
    /** Keep this tool directly available when MCP lazy loading is enabled. */
    alwaysLoad?: boolean;
    /** Optional default permission policy for this MCP tool. */
    permissionPolicy?: 'always_allow' | 'always_ask' | 'always_deny';
    /** Async handler invoked when the tool is called. */
    handler: (args: InferShape<Schema>, extra: RequestHandlerExtra<ServerRequest, ServerNotification>) => Promise<CallToolResult>;
};
export type CreateSdkMcpServerOptions = {
    /** Display name for the MCP server. */
    name: string;
    /** Server version (defaults to `'1.0.0'`). */
    version?: string;
    /** Tools to register on the server at creation time. */
    tools?: Array<SdkMcpToolDefinition<any>>;
};
/**
 * Creates an MCP server instance that runs in the same process as the SDK.
 *
 * Tools defined here are accessible to qodercli without spawning a separate
 * server process. The returned config object can be passed directly to the
 * SDK's `mcpServers` option.
 *
 * NOTE: this factory does **not** call `instance.connect(transport)` itself
 * — that wiring lives in `query.ts`, where the
 * per-query SdkMcpTransport (with its `sendMcpMessage` callback bound to
 * the query's pending-response map) is constructed. Adding a transport
 * here would either be wrong (no callback to bind to) or would force every
 * caller to re-wire it, which is exactly the bug the previous "simplified
 * implementation" stub created.
 *
 * @example
 * ```ts
 * const server = createSdkMcpServer({
 *   name: 'my-tools',
 *   tools: [
 *     tool('greet', 'Say hello', { name: z.string() }, async ({ name }) => ({
 *       content: [{ type: 'text', text: `Hello, ${name}!` }],
 *     })),
 *   ],
 * });
 * ```
 */
export declare function createSdkMcpServer(options: CreateSdkMcpServerOptions): McpSdkServerConfigWithInstance;
export type ToolExtras = {
    /**
     * MCP tool annotations. `readOnlyHint` is a concurrency scheduling hint, not
     * a permission control. See the doc comment on
     * `SdkMcpToolDefinition.annotations` for the full coverage matrix.
     */
    annotations?: ToolAnnotations;
    /** Optional model-facing name. Requires `alwaysLoad: true`. */
    exposedName?: string;
    /** Keep this tool directly available when MCP lazy loading is enabled. */
    alwaysLoad?: boolean;
    /** Optional default permission policy for this tool. */
    permissionPolicy?: 'always_allow' | 'always_ask' | 'always_deny';
};
/**
 * Helper to define a single tool for use with `createSdkMcpServer`.
 *
 * Provides a concise factory that constructs a `SdkMcpToolDefinition`
 * with proper typing.
 *
 * @param name - Unique tool name
 * @param description - Human-readable description for the model
 * @param inputSchema - Zod raw shape describing the tool's inputs
 * @param handler - Async function invoked when the tool is called
 * @param extras - Optional annotations (see `ToolExtras`)
 *
 * @example
 * ```ts
 * const greetTool = tool(
 *   'greet',
 *   'Say hello to someone',
 *   { name: z.string() },
 *   async ({ name }) => ({
 *     content: [{ type: 'text', text: `Hello, ${name}!` }],
 *   }),
 *   { annotations: { readOnlyHint: true } },
 * );
 * ```
 */
export declare function tool<Schema extends AnyZodRawShape>(name: string, description: string, inputSchema: Schema, handler: (args: InferShape<Schema>, extra: RequestHandlerExtra<ServerRequest, ServerNotification>) => Promise<CallToolResult>, extras?: ToolExtras): SdkMcpToolDefinition<Schema>;