import type { ToolDefinition } from '../types/messages.js';
import type { McpToolAnnotations } from './client.js';
import { type JsonRpcMessage, type McpElicitationRequest, type McpElicitationResult, type McpRoot, type McpSamplingContent, type McpSamplingRequest, type McpSamplingResult, type McpTransport } from './protocol.js';
/** A resource a server exposes, read by its URI. */
export interface McpServerResource {
    /** Its URI. */
    uri: string;
    /** A name for it. */
    name?: string;
    /** What it holds. */
    description?: string;
    /** Its MIME type. Defaults to `text/plain`. */
    mimeType?: string;
    /** Reads it: text as it is, anything else as JSON. */
    read(): Promise<unknown> | unknown;
}
/** One argument a prompt takes. */
export interface McpPromptArgument {
    /** Its name. */
    name: string;
    /** What it is for. */
    description?: string;
    /** Whether \`prompts/get\` must give it. */
    required?: boolean;
}
/** One message of a rendered prompt. */
export interface McpPromptMessage {
    /** Who says it. */
    role: 'user' | 'assistant';
    /** What is said. */
    content: McpSamplingContent;
}
/** A prompt a server offers: a template a client renders with its arguments. */
export interface McpServerPrompt {
    /** Its name. */
    name: string;
    /** A title for people. */
    title?: string;
    /** What it does. */
    description?: string;
    /** The arguments it takes. */
    arguments?: McpPromptArgument[];
    /** Renders it: text, which is one user message, or the messages themselves. */
    get(args: Record<string, string>): string | McpPromptMessage[] | Promise<string | McpPromptMessage[]>;
}
/** Options for an MCP server. */
export interface McpServerOptions {
    /** Server name reported to clients. Defaults to `nexus-ai-pro`. */
    name?: string;
    /** Server version reported to clients. Defaults to `1.x`. */
    version?: string;
    /** Tools the server exposes. */
    tools?: ToolDefinition[];
    /** Resources the server exposes, read by URI. */
    resources?: McpServerResource[];
    /** Prompts the server offers. */
    prompts?: McpServerPrompt[];
    /** How long a request this server sends a client waits for its answer, in milliseconds. Defaults to 60 seconds. */
    timeoutMs?: number;
}
/**
 * The annotations a tool is served with, from the capabilities it declares, read so a client is never
 * told less than the tool may do:
 * - read-only only when every capability reads, `filesystem:read` or `mcp.read`, or there are none;
 * - not destructive only when everything else it does is `mcp.write`;
 * - closed to the world only when every capability is the filesystem's or an MCP tool's effect.
 *
 * A tool whose capabilities depend on its arguments, or that declares none, is served without
 * annotations, which a client reads as the specification's defaults: it may do anything.
 */
export declare function mcpToolAnnotations(tool: Pick<ToolDefinition, 'capabilities'>): McpToolAnnotations | undefined;
/**
 * Exposes tools, resources, and prompts over MCP, so other assistants can use them.
 *
 * The other direction of the same bridge: the client borrows an ecosystem's tools, the server lends
 * this application's. A tool written once with `tool()` can serve an agent here and an editor
 * elsewhere, and while it runs, ask the client that called it for a completion from its model or an
 * answer from its person, through `context.mcp`. One server serves every client connected to it, each
 * on its own transport, such as each session of `mcpHttpHandler()`.
 */
export declare class McpServer {
    private readonly options;
    private readonly tools;
    private readonly resources;
    private readonly prompts;
    private readonly sessions;
    /** The session \`handle()\` answers on, when a host drives the server itself. */
    private latest;
    private readonly rootsListeners;
    constructor(options?: McpServerOptions);
    /** Adds a tool, and tells every connected client its tools changed. Returns the server, for chaining. */
    register(tool: ToolDefinition): this;
    /** Adds a prompt, and tells every connected client its prompts changed. Returns the server, for chaining. */
    registerPrompt(prompt: McpServerPrompt): this;
    /** Adds a resource, and tells every connected client its resources changed. Returns the server, for chaining. */
    registerResource(resource: McpServerResource): this;
    /** Tells each client subscribed to a resource that it changed, so it reads it again. */
    resourceUpdated(uri: string): void;
    /** Hears each client's \`notifications/roots/list_changed\`. Returns a function that stops hearing. */
    onRootsChanged(handler: () => void): () => void;
    /**
     * Asks the connected client's model to continue a conversation. With several clients connected,
     * ask through a tool's \`context.mcp\`, which names the client that called it.
     */
    createMessage(request: McpSamplingRequest, options?: {
        signal?: AbortSignal;
    }): Promise<McpSamplingResult>;
    /** Asks the connected client's person a question, with the form of its answer. */
    elicit(request: McpElicitationRequest, options?: {
        signal?: AbortSignal;
    }): Promise<McpElicitationResult>;
    /** Lists the roots the connected client lets this server work within. */
    listRoots(options?: {
        signal?: AbortSignal;
    }): Promise<McpRoot[]>;
    /** Starts serving a client over a transport. Each transport is one client; several may be connected at once. */
    connect(transport: McpTransport): Promise<void>;
    /** Closes every client's transport. */
    close(): Promise<void>;
    /** Handles one message. Exposed so a host can drive the server without a transport. */
    handle(message: JsonRpcMessage): Promise<void>;
    private receive;
    private dispatch;
    private callTool;
    /** What may be asked of one client, each request stopped by \`signal\` as well as its own. */
    private callerOf;
    /** Sends a client a request and waits for its answer, if it declared it answers that kind. */
    private ask;
    /** The only connected client; asking without naming one needs exactly one. */
    private only;
    private broadcast;
    private send;
    /** Forgets a client whose transport closed: its waiting requests fail, and its running calls stop. */
    private drop;
}
/**
 * Serves MCP over this process's stdin and stdout.
 *
 * The transport an editor or desktop assistant launches: it runs the process and speaks JSON-RPC to
 * it, so nothing may be written to stdout except protocol messages.
 */
export declare function createStdioServerTransport(streams?: {
    input?: NodeJS.ReadableStream;
    output?: {
        write(chunk: string): void;
    };
}): McpTransport;