alepha/dist/mcp/index.d.ts

Easy-to-use modern TypeScript framework for building many kind of applications.

import { Alepha, AlephaError, Async, KIND, Primitive, Static, TObject, TSchema } from "alepha";
//#region ../../src/mcp/errors/McpError.d.ts
/**
 * MCP-specific error codes (application-specific codes in the -32000 to -32099 range).
 */
declare const McpErrorCodes: {
  readonly UNAUTHORIZED: -32001;
  readonly FORBIDDEN: -32003;
};
declare class McpError extends Error {
  name: string;
  code: number;
  constructor(message: string, code?: number);
}
declare class McpMethodNotFoundError extends McpError {
  name: string;
  constructor(method: string);
}
declare class McpToolNotFoundError extends McpError {
  name: string;
  tool: string;
  constructor(tool: string);
}
declare class McpResourceNotFoundError extends McpError {
  name: string;
  uri: string;
  constructor(uri: string);
}
declare class McpPromptNotFoundError extends McpError {
  name: string;
  prompt: string;
  constructor(prompt: string);
}
declare class McpInvalidParamsError extends McpError {
  name: string;
  constructor(message: string);
}
declare class McpUnauthorizedError extends McpError {
  name: string;
  constructor(message?: string);
}
declare class McpForbiddenError extends McpError {
  name: string;
  constructor(message?: string);
}
//#endregion
//#region ../../src/mcp/interfaces/McpTypes.d.ts
interface JsonRpcRequest {
  jsonrpc: "2.0";
  id?: string | number;
  method: string;
  params?: Record<string, unknown>;
}
interface JsonRpcResponse {
  jsonrpc: "2.0";
  id: string | number;
  result?: unknown;
  error?: JsonRpcError;
}
interface JsonRpcNotification {
  jsonrpc: "2.0";
  method: string;
  params?: Record<string, unknown>;
}
interface JsonRpcError {
  code: number;
  message: string;
  data?: unknown;
}
interface McpCapabilities {
  tools?: Record<string, never>;
  resources?: Record<string, never>;
  prompts?: Record<string, never>;
}
/**
 * Spec 2025-11-25: optional `description` aligns with the MCP registry's
 * `server.json` format and provides human-readable context during init.
 */
interface McpServerInfo {
  name: string;
  version: string;
  description?: string;
}
interface McpClientInfo {
  name: string;
  version: string;
  description?: string;
}
/**
 * Icon descriptor (spec 2025-11-25 / SEP-973). Mirrors web app manifest
 * icon shape — clients render these in tool palettes / picker UIs.
 */
interface McpIcon {
  src: string;
  mimeType?: string;
  sizes?: string;
}
/**
 * Tool annotations (spec 2025-03-26+). Hints to the client about how to
 * present and gate the tool. None are guarantees — the client uses these
 * heuristically (e.g. to show a confirmation prompt for destructive tools).
 */
interface McpToolAnnotations {
  /** Human-friendly display title (distinct from `name`, the programmatic id). */
  title?: string;
  /** Tool reads only; safe to auto-approve. */
  readOnlyHint?: boolean;
  /** Tool may delete or overwrite data; client should require confirmation. */
  destructiveHint?: boolean;
  /** Calling the tool with the same args twice yields the same end state. */
  idempotentHint?: boolean;
  /** Tool interacts with the open world (network, etc.) vs. a closed system. */
  openWorldHint?: boolean;
}
interface McpInitializeParams {
  protocolVersion: string;
  capabilities: McpCapabilities;
  clientInfo: McpClientInfo;
}
interface McpInitializeResult {
  protocolVersion: string;
  capabilities: McpCapabilities;
  serverInfo: McpServerInfo;
}
interface McpToolDescriptor {
  name: string;
  /** Human-friendly display label (spec 2025-11-25). Distinct from `name`. */
  title?: string;
  description: string;
  inputSchema: McpJsonSchema;
  /** Output schema enabling `structuredContent` on call results (spec 2025-06-18). */
  outputSchema?: McpJsonSchema;
  /** Behavior hints (spec 2025-03-26+). */
  annotations?: McpToolAnnotations;
  /** Optional icons (spec 2025-11-25 / SEP-973). */
  icons?: McpIcon[];
  /** Arbitrary metadata passthrough (spec 2025-06-18+). */
  _meta?: Record<string, unknown>;
}
interface McpJsonSchema {
  type: string;
  properties?: Record<string, unknown>;
  required?: string[];
  /** JSON Schema dialect (spec 2025-11-25 / SEP-1613 — defaults to 2020-12). */
  $schema?: string;
  [key: string]: unknown;
}
interface McpToolCallParams {
  name: string;
  arguments?: Record<string, unknown>;
}
interface McpToolCallResult {
  content: McpContent[];
  /**
   * Structured tool output (spec 2025-06-18). When the tool declares an
   * `outputSchema`, the server MUST populate `structuredContent`; the
   * `content` array carrying a JSON-stringified text block is kept as
   * a back-compat fallback for older clients.
   */
  structuredContent?: unknown;
  isError?: boolean;
  _meta?: Record<string, unknown>;
}
/**
 * Discriminated content union covering text, image, audio (added 2025-03-26),
 * inlined resources, and resource links (added 2025-06-18).
 */
type McpContent = {
  type: "text";
  text: string;
} | {
  type: "image";
  data: string;
  mimeType: string;
} | {
  type: "audio";
  data: string;
  mimeType: string;
} | {
  type: "resource";
  resource: McpResourceContent;
} | {
  type: "resource_link";
  uri: string;
  name: string;
  description?: string;
  mimeType?: string;
};
interface McpResourceDescriptor {
  uri: string;
  name: string;
  /** Human-friendly display label (spec 2025-11-25). Distinct from `name`. */
  title?: string;
  description?: string;
  mimeType?: string;
  /** Optional icons (spec 2025-11-25 / SEP-973). */
  icons?: McpIcon[];
  /** Arbitrary metadata passthrough (spec 2025-06-18+). */
  _meta?: Record<string, unknown>;
}
interface McpResourceReadParams {
  uri: string;
}
interface McpResourceReadResult {
  contents: McpResourceContent[];
}
interface McpResourceContent {
  uri: string;
  mimeType?: string;
  text?: string;
  blob?: string;
}
interface McpPromptDescriptor {
  name: string;
  /** Human-friendly display label (spec 2025-11-25). Distinct from `name`. */
  title?: string;
  description?: string;
  arguments?: McpPromptArgument[];
  /** Optional icons (spec 2025-11-25 / SEP-973). */
  icons?: McpIcon[];
  /** Arbitrary metadata passthrough (spec 2025-06-18+). */
  _meta?: Record<string, unknown>;
}
interface McpPromptArgument {
  name: string;
  description?: string;
  required?: boolean;
}
interface McpPromptGetParams {
  name: string;
  arguments?: Record<string, string>;
}
interface McpPromptGetResult {
  description?: string;
  messages: McpPromptMessage[];
}
interface McpPromptMessage {
  role: "user" | "assistant";
  content: McpPromptContent;
}
interface McpPromptContent {
  type: "text" | "image" | "resource";
  text?: string;
  data?: string;
  mimeType?: string;
}
interface ToolPrimitiveSchema {
  params?: TObject;
  result?: TSchema;
}
/**
 * Context passed to MCP handlers from the transport layer.
 *
 * This allows tools, resources, and prompts to access request-level
 * information like headers for authentication.
 */
interface McpContext<T = unknown> {
  /**
   * HTTP headers from the request (for SSE transport).
   */
  headers?: Record<string, string | string[] | undefined>;
  /**
   * Custom context data set by transport or middleware.
   * Can be used to pass authenticated user, project scope, etc.
   */
  data?: T;
}
type ToolHandler<T extends ToolPrimitiveSchema, TContext = unknown> = (args: ToolHandlerArgs<T, TContext>) => Async<ToolHandlerResult<T>>;
interface ToolHandlerArgs<T extends ToolPrimitiveSchema, TContext = unknown> {
  params: T["params"] extends TObject ? Static<T["params"]> : Record<string, never>;
  context?: McpContext<TContext>;
}
type ToolHandlerResult<T extends ToolPrimitiveSchema> = T["result"] extends TSchema ? Static<T["result"]> : unknown;
type ResourceHandler<TContext = unknown> = (args: ResourceHandlerArgs<TContext>) => Async<ResourceContent>;
interface ResourceHandlerArgs<TContext = unknown> {
  context?: McpContext<TContext>;
}
interface ResourceContent {
  text?: string;
  blob?: Uint8Array;
}
type PromptHandler<T extends TObject, TContext = unknown> = (args: PromptHandlerArgs<T, TContext>) => Async<PromptMessage[]>;
interface PromptHandlerArgs<T extends TObject, TContext = unknown> {
  args: Static<T>;
  context?: McpContext<TContext>;
}
interface PromptMessage {
  role: "user" | "assistant";
  content: string;
}
//#endregion
//#region ../../src/mcp/helpers/jsonrpc.d.ts
declare const JSONRPC_VERSION: "2.0";
/**
 * The latest MCP protocol revision Alepha targets.
 * See {@link SUPPORTED_PROTOCOL_VERSIONS} for the full negotiation list.
 */
declare const MCP_PROTOCOL_VERSION: "2025-11-25";
/**
 * Protocol versions Alepha will accept during `initialize` negotiation,
 * highest preference first. The server echoes back whichever version the
 * client requested if it appears here, otherwise picks the first entry.
 */
declare const SUPPORTED_PROTOCOL_VERSIONS: readonly ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"];
type SupportedProtocolVersion = (typeof SUPPORTED_PROTOCOL_VERSIONS)[number];
declare const isSupportedProtocolVersion: (v: unknown) => v is SupportedProtocolVersion;
declare const JsonRpcErrorCodes: {
  readonly PARSE_ERROR: -32700;
  readonly INVALID_REQUEST: -32600;
  readonly METHOD_NOT_FOUND: -32601;
  readonly INVALID_PARAMS: -32602;
  readonly INTERNAL_ERROR: -32603;
};
declare function createResponse(id: string | number, result: unknown): JsonRpcResponse;
declare function createErrorResponse(id: string | number, error: JsonRpcError): JsonRpcResponse;
declare function createNotification(method: string, params?: Record<string, unknown>): JsonRpcNotification;
declare function createParseError(message?: string): JsonRpcError;
declare function createInvalidRequestError(message?: string): JsonRpcError;
declare function createMethodNotFoundError(method: string): JsonRpcError;
declare function createInvalidParamsError(message: string): JsonRpcError;
declare function createInternalError(message: string): JsonRpcError;
declare function parseMessage(data: string): JsonRpcRequest;
declare function isValidJsonRpcRequest(value: unknown): value is JsonRpcRequest;
declare function isNotification(request: JsonRpcRequest): boolean;
declare class JsonRpcParseError extends AlephaError {
  name: string;
}
//#endregion
//#region ../../src/mcp/primitives/$resource.d.ts
/**
 * Creates an MCP resource primitive for exposing read-only data.
 *
 * Resources represent any kind of data that an LLM might want to read,
 * such as files, database records, API responses, or computed data.
 *
 * **Key Features**
 * - URI-based identification for resources
 * - Support for text and binary content
 * - MIME type specification
 * - Lazy loading via handler function
 *
 * @example
 * ```ts
 * class ProjectResources {
 *   readme = $resource({
 *     uri: "file:///readme",
 *     description: "Project README file",
 *     mimeType: "text/markdown",
 *     handler: async () => ({
 *       text: await fs.readFile("README.md", "utf-8"),
 *     }),
 *   });
 *
 *   config = $resource({
 *     uri: "config://app",
 *     name: "Application Configuration",
 *     mimeType: "application/json",
 *     handler: async () => ({
 *       text: JSON.stringify(this.configService.getConfig()),
 *     }),
 *   });
 * }
 * ```
 */
declare const $resource: {
  (options: ResourcePrimitiveOptions): ResourcePrimitive;
  [KIND]: typeof ResourcePrimitive;
};
interface ResourcePrimitiveOptions {
  /**
   * The URI that identifies this resource.
   *
   * URIs should follow a consistent scheme for your application.
   * Common patterns:
   * - `file:///path/to/file` - File system resources
   * - `db://table/id` - Database records
   * - `api://endpoint` - API responses
   * - `config://name` - Configuration values
   *
   * @example "file:///readme.md"
   * @example "db://users/123"
   */
  uri: string;
  /**
   * Human-readable name for the resource.
   *
   * If not provided, defaults to the property key where the resource is declared.
   *
   * @example "Project README"
   * @example "User Profile"
   */
  name?: string;
  /**
   * Human-friendly display title (spec 2025-11-25). Distinct from `name`,
   * which remains the programmatic identifier.
   */
  title?: string;
  /**
   * Optional icons surfaced in client UIs (spec 2025-11-25 / SEP-973).
   */
  icons?: McpIcon[];
  /**
   * Description of what this resource contains.
   *
   * Helps the LLM understand the purpose and content of the resource.
   *
   * @example "The main README file for the project"
   */
  description?: string;
  /**
   * MIME type of the resource content.
   *
   * Helps clients understand how to interpret the content.
   *
   * @default "text/plain"
   * @example "text/markdown"
   * @example "application/json"
   */
  mimeType?: string;
  /**
   * Handler function that returns the resource content.
   *
   * Called when the resource is read. Can return text or binary content.
   *
   * @returns Resource content with either `text` or `blob` property
   */
  handler: ResourceHandler;
}
declare class ResourcePrimitive extends Primitive<ResourcePrimitiveOptions> {
  protected readonly mcpServer: McpServerProvider;
  /**
   * Returns the name of the resource.
   */
  get name(): string;
  /**
   * Returns the URI of the resource.
   */
  get uri(): string;
  /**
   * Returns the description of the resource.
   */
  get description(): string | undefined;
  /**
   * Returns the MIME type of the resource.
   */
  get mimeType(): string;
  protected onInit(): void;
  /**
   * Read the resource content.
   *
   * @param context - Optional context from the transport layer
   * @returns The resource content
   */
  read(context?: McpContext): Promise<ResourceContent>;
  /**
   * Convert the resource to an MCP resource descriptor for protocol messages.
   */
  toDescriptor(): McpResourceDescriptor;
}
//#endregion
//#region ../../src/mcp/primitives/$tool.d.ts
/**
 * Creates an MCP tool primitive for defining callable functions.
 *
 * Tools are the primary way for LLMs to interact with external systems through MCP.
 * Each tool has a name, description, typed parameters, and a handler function.
 *
 * **Key Features**
 * - Full TypeScript inference for parameters and results
 * - Automatic schema validation using TypeBox
 * - JSON Schema generation for MCP protocol
 * - Integration with MCP server provider
 *
 * @example
 * ```ts
 * class CalculatorTools {
 *   add = $tool({
 *     description: "Add two numbers together",
 *     schema: {
 *       params: z.object({
 *         a: z.number(),
 *         b: z.number(),
 *       }),
 *       result: z.number(),
 *     },
 *     handler: async ({ params }) => {
 *       return params.a + params.b;
 *     },
 *   });
 *
 *   greet = $tool({
 *     description: "Generate a greeting message",
 *     schema: {
 *       params: z.object({
 *         name: z.text(),
 *       }),
 *       result: z.text(),
 *     },
 *     handler: async ({ params }) => {
 *       return `Hello, ${params.name}!`;
 *     },
 *   });
 * }
 * ```
 */
declare const $tool: {
  <T extends ToolPrimitiveSchema>(options: ToolPrimitiveOptions<T>): ToolPrimitive<T>;
  [KIND]: typeof ToolPrimitive;
};
interface ToolPrimitiveOptions<T extends ToolPrimitiveSchema> {
  /**
   * The name of the tool.
   *
   * If not provided, defaults to the property key where the tool is declared.
   * Names should be descriptive and use kebab-case or snake_case.
   *
   * @example "calculate-sum"
   * @example "get_weather"
   */
  name?: string;
  /**
   * Human-friendly display title (spec 2025-11-25). Distinct from `name`,
   * which remains the programmatic identifier. Clients use `title` in
   * tool palettes / picker UIs.
   *
   * @example "Search Lore"
   */
  title?: string;
  /**
   * A human-readable description of what the tool does.
   *
   * This description is sent to the LLM to help it understand
   * when and how to use the tool. Be clear and specific.
   *
   * @example "Calculate the sum of two numbers"
   * @example "Retrieve current weather data for a given location"
   */
  description: string;
  /**
   * Behavior hints (spec 2025-03-26+). Clients use these to gate UI prompts
   * (e.g. require confirmation before a tool with `destructiveHint: true`).
   * None are guarantees — they are heuristics for the client, not the model.
   */
  annotations?: McpToolAnnotations;
  /**
   * Icons surfaced in client tool palettes / picker UIs (spec 2025-11-25).
   */
  icons?: McpIcon[];
  /**
   * TypeBox schema defining the tool's parameters and result type.
   *
   * - **params**: TObject schema for input parameters (optional)
   * - **result**: TSchema for the return value (optional)
   *
   * Schemas provide:
   * - Type inference for handler function
   * - Runtime validation of inputs
   * - JSON Schema generation for MCP protocol
   */
  schema?: T;
  /**
   * The handler function that executes when the tool is called.
   *
   * Receives validated parameters and returns the result.
   * Errors thrown here are caught and returned as MCP errors.
   *
   * @param args - Object containing validated params
   * @returns The tool result (can be async)
   */
  handler: (args: ToolHandlerArgs<T>) => Async<ToolHandlerResult<T>>;
}
declare class ToolPrimitive<T extends ToolPrimitiveSchema> extends Primitive<ToolPrimitiveOptions<T>> {
  protected readonly mcpServer: McpServerProvider;
  /**
   * Returns the name of the tool.
   */
  get name(): string;
  /**
   * Returns the description of the tool.
   */
  get description(): string;
  /**
   * Whether the tool declared a result schema. When true, `tools/call`
   * responses include `structuredContent` populated with the validated
   * result (spec 2025-06-18).
   */
  hasOutputSchema(): boolean;
  protected onInit(): void;
  /**
   * Execute the tool with the given parameters.
   *
   * @param params - Raw parameters to validate and pass to the handler
   * @param context - Optional context from the transport layer
   * @returns The tool result
   */
  execute(params: unknown, context?: McpContext): Promise<ToolHandlerResult<T>>;
  /**
   * Convert the tool to an MCP tool descriptor for protocol messages.
   *
   * Emits the spec 2025-11-25 surface: `title`, `annotations`, `icons`,
   * and (when `schema.result` is defined) `outputSchema` so the server
   * can populate `structuredContent` on call results.
   */
  toDescriptor(): McpToolDescriptor;
  /**
   * Convert a TypeBox schema to JSON Schema format.
   *
   * Emits the 2020-12 dialect annotation at the root (spec 2025-11-25 /
   * SEP-1613 — JSON Schema 2020-12 is the default dialect for MCP).
   * The TypeBox shapes Alepha emits today are already 2020-12-compatible;
   * this is just the dialect declaration.
   */
  protected schemaToJsonSchema(schema: TObject, options?: {
    root?: boolean;
  }): McpJsonSchema;
  /**
   * Convert a single property schema to JSON Schema format (zod-native).
   */
  protected propertyToJsonSchema(schema: TSchema): Record<string, unknown>;
}
//#endregion
//#region ../../src/mcp/providers/McpServerProvider.d.ts
/**
 * Core MCP server provider that handles protocol messages.
 *
 * This provider maintains registries of tools, resources, and prompts,
 * and routes incoming JSON-RPC requests to the appropriate handlers.
 *
 * It is transport-agnostic - actual communication is handled by
 * transport providers like StdioMcpTransport or SseMcpTransport.
 */
declare class McpServerProvider {
  protected readonly log: import("alepha/logger").Logger;
  protected readonly alepha: Alepha;
  protected readonly tools: Map<string, ToolPrimitive<any>>;
  protected readonly resources: Map<string, ResourcePrimitive>;
  protected readonly prompts: Map<string, PromptPrimitive<any>>;
  protected initialized: boolean;
  /**
   * Protocol version negotiated with the client during `initialize`.
   * Used by transports to validate the `MCP-Protocol-Version` header on
   * subsequent HTTP requests (per spec 2025-06-18+).
   */
  negotiatedVersion: string;
  /**
   * Server identity returned during `initialize`. Consumers may override
   * fields directly (e.g. `mcpServer.serverInfo = { name: "lore-mcp",
   * version: "0.20.3", description: "..." }`) — the `description` field
   * is supported per spec 2025-11-25 (minor change #2).
   */
  serverInfo: McpServerInfo;
  /**
   * Register a tool with the MCP server.
   */
  registerTool(tool: ToolPrimitive<any>): void;
  /**
   * Register a resource with the MCP server.
   */
  registerResource(resource: ResourcePrimitive): void;
  /**
   * Register a prompt with the MCP server.
   */
  registerPrompt(prompt: PromptPrimitive<any>): void;
  /**
   * Get the server capabilities based on registered primitives.
   */
  getCapabilities(): McpCapabilities;
  /**
   * Get all registered tools.
   */
  getTools(): ToolPrimitive<any>[];
  /**
   * Get all registered resources.
   */
  getResources(): ResourcePrimitive[];
  /**
   * Get all registered prompts.
   */
  getPrompts(): PromptPrimitive<any>[];
  /**
   * Get a tool by name.
   */
  getTool(name: string): ToolPrimitive<any> | undefined;
  /**
   * Get a resource by URI.
   */
  getResource(uri: string): ResourcePrimitive | undefined;
  /**
   * Get a prompt by name.
   */
  getPrompt(name: string): PromptPrimitive<any> | undefined;
  /**
   * Handle an incoming JSON-RPC request.
   *
   * @param request - The parsed JSON-RPC request
   * @param context - Optional context from the transport layer (headers, auth, etc.)
   * @returns The JSON-RPC response, or null for notifications
   */
  handleMessage(request: JsonRpcRequest, context?: McpContext): Promise<JsonRpcResponse | null>;
  /**
   * Handle a JSON-RPC request that expects a response.
   */
  protected handleRequest(request: JsonRpcRequest, context?: McpContext): Promise<unknown>;
  /**
   * Handle a notification (no response expected).
   */
  protected handleNotification(request: JsonRpcRequest): Promise<void>;
  protected handleInitialize(params: Record<string, unknown>): McpInitializeResult;
  protected handlePing(): Record<string, never>;
  protected handleToolsList(): {
    tools: McpToolDescriptor[];
  };
  protected handleToolsCall(params: Record<string, unknown>, context?: McpContext): Promise<McpToolCallResult>;
  /**
   * Recognize a tool handler's return value as a pre-built MCP tool result —
   * i.e. it already carries a `content` array of content blocks (text, image,
   * audio, resource, resource_link). Returns the normalized
   * {@link McpToolCallResult} when matched, or `undefined` to fall back to the
   * default JSON/text encoding. Only ever consulted for tools that did NOT
   * declare an output schema (see {@link handleToolCall}).
   */
  protected asRawToolContent(result: unknown): McpToolCallResult | undefined;
  protected handleResourcesList(): {
    resources: McpResourceDescriptor[];
  };
  protected handleResourcesRead(params: Record<string, unknown>, context?: McpContext): Promise<McpResourceReadResult>;
  protected handlePromptsList(): {
    prompts: McpPromptDescriptor[];
  };
  protected handlePromptsGet(params: Record<string, unknown>, context?: McpContext): Promise<McpPromptGetResult>;
}
//#endregion
//#region ../../src/mcp/primitives/$prompt.d.ts
/**
 * Creates an MCP prompt primitive for defining reusable prompt templates.
 *
 * Prompts allow you to define templated messages that can be filled in
 * with arguments at runtime. They're useful for creating consistent
 * interaction patterns.
 *
 * @example
 * ```ts
 * class Prompts {
 *   greeting = $prompt({
 *     description: "Generate a personalized greeting",
 *     args: z.object({
 *       name: z.text({ description: "Name of the person to greet" }),
 *       style: z.enum(["formal", "casual"]).optional(),
 *     }),
 *     handler: async ({ args }) => [
 *       {
 *         role: "user",
 *         content: args.style === "formal"
 *           ? `Please greet ${args.name} in a formal manner.`
 *           : `Say hi to ${args.name}!`,
 *       },
 *     ],
 *   });
 *
 *   codeReview = $prompt({
 *     description: "Request a code review",
 *     args: z.object({
 *       code: z.text({ description: "The code to review" }),
 *       language: z.text({ description: "Programming language" }),
 *     }),
 *     handler: async ({ args }) => [
 *       {
 *         role: "user",
 *         content: `Please review this ${args.language} code:\n\n${args.code}`,
 *       },
 *     ],
 *   });
 * }
 * ```
 */
declare const $prompt: {
  <T extends TObject>(options: PromptPrimitiveOptions<T>): PromptPrimitive<T>;
  [KIND]: typeof PromptPrimitive;
};
interface PromptPrimitiveOptions<T extends TObject> {
  /**
   * The name of the prompt.
   *
   * If not provided, defaults to the property key where the prompt is declared.
   *
   * @example "greeting"
   * @example "code-review"
   */
  name?: string;
  /**
   * Human-friendly display title (spec 2025-11-25). Distinct from `name`,
   * which remains the programmatic identifier.
   */
  title?: string;
  /**
   * Description of what this prompt does.
   *
   * Helps users understand the purpose of the prompt.
   *
   * @example "Generate a personalized greeting message"
   */
  description?: string;
  /**
   * Optional icons surfaced in client UIs (spec 2025-11-25 / SEP-973).
   */
  icons?: McpIcon[];
  /**
   * TypeBox schema defining the prompt arguments.
   *
   * Each property in the schema becomes an argument that can be
   * filled in when the prompt is used.
   */
  args?: T;
  /**
   * Handler function that generates the prompt messages.
   *
   * Receives the validated arguments and returns an array of messages.
   *
   * @param args - Object containing validated arguments
   * @returns Array of prompt messages
   */
  handler: (args: PromptHandlerArgs<T>) => Async<PromptMessage[]>;
}
declare class PromptPrimitive<T extends TObject> extends Primitive<PromptPrimitiveOptions<T>> {
  protected readonly mcpServer: McpServerProvider;
  /**
   * Returns the name of the prompt.
   */
  get name(): string;
  /**
   * Returns the description of the prompt.
   */
  get description(): string | undefined;
  protected onInit(): void;
  /**
   * Get the prompt messages with the given arguments.
   *
   * @param rawArgs - Raw arguments to validate and pass to the handler
   * @param context - Optional context from the transport layer
   * @returns Array of prompt messages
   */
  get(rawArgs: unknown, context?: McpContext): Promise<PromptMessage[]>;
  /**
   * Convert the prompt to an MCP prompt descriptor for protocol messages.
   */
  toDescriptor(): McpPromptDescriptor;
  /**
   * Convert a TypeBox schema to an array of prompt arguments.
   */
  protected schemaToArguments(schema: TObject): McpPromptArgument[];
}
//#endregion
//#region ../../src/mcp/transports/StreamableHttpMcpTransport.d.ts
declare const mcpStreamableHttpOptions: import("alepha").Atom<import("zod").ZodObject<{
  path: import("zod").ZodString;
  allowedOrigins: import("zod").ZodDefault<import("zod").ZodArray<import("zod").ZodString>>;
  requireAuth: import("zod").ZodDefault<import("zod").ZodBoolean>;
  resourceMetadataPath: import("zod").ZodString;
}, import("zod/v4/core").$strip>, "alepha.mcp.streamableHttp.options">;
declare const mcpSseOptions: import("alepha").Atom<import("zod").ZodObject<{
  path: import("zod").ZodString;
  allowedOrigins: import("zod").ZodDefault<import("zod").ZodArray<import("zod").ZodString>>;
  requireAuth: import("zod").ZodDefault<import("zod").ZodBoolean>;
  resourceMetadataPath: import("zod").ZodString;
}, import("zod/v4/core").$strip>, "alepha.mcp.streamableHttp.options">;
/**
 * Streamable HTTP transport for MCP communication.
 *
 * Implements the 2025-03-26+ Streamable HTTP transport: a single `/mcp`
 * endpoint that accepts JSON-RPC over POST and returns either
 * `application/json` (single response, the default) or
 * `text/event-stream` (when the server wants to stream multiple messages).
 *
 * Designed for serverless deployment (Cloudflare Workers, etc.) — there is
 * no long-lived GET stream. GET on the endpoint returns 405 Method Not
 * Allowed; clients that want server-initiated push must rely on the POST
 * response stream when the server upgrades to SSE for that particular call.
 *
 * Spec compliance:
 * - 2025-06-18: validates `MCP-Protocol-Version` header on every request
 *   after `initialize` against the version negotiated and stored on
 *   `McpServerProvider`.
 * - 2025-11-25: rejects requests with a non-allow-listed `Origin` header
 *   (PR #1439). See {@link mcpStreamableHttpOptions.allowedOrigins}.
 *
 * @example
 * ```ts
 * import { Alepha, run } from "alepha";
 * import { AlephaServer } from "alepha/server";
 * import { AlephaMcp, StreamableHttpMcpTransport } from "alepha/mcp";
 *
 * class MyTools {
 *   // ... tool definitions
 * }
 *
 * run(
 *   Alepha.create()
 *     .with(AlephaServer)
 *     .with(AlephaMcp)
 *     .with(StreamableHttpMcpTransport)
 *     .with(MyTools)
 * );
 * ```
 */
declare class StreamableHttpMcpTransport {
  protected readonly log: import("alepha/logger").Logger;
  protected readonly options: Readonly<{
    path: string;
    allowedOrigins: string[];
    requireAuth: boolean;
    resourceMetadataPath: string;
  }>;
  protected readonly mcpServer: McpServerProvider;
  /**
   * GET on the MCP endpoint is not supported in this transport. Returning
   * 405 (rather than serving the legacy two-endpoint SSE pattern) is the
   * spec-allowed response for servers that don't offer server-initiated
   * push outside of an active POST.
   */
  notAllowed: import("alepha/server").RoutePrimitive<import("alepha/server").RequestConfigSchema>;
  /**
   * POST endpoint for client-to-server JSON-RPC messages.
   * Returns `application/json` for single responses; tools that need to
   * stream progress would upgrade to `text/event-stream` (deferred until a
   * concrete need exists).
   */
  message: import("alepha/server").RoutePrimitive<{
    body: import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodAny>;
  }>;
}
/**
 * @deprecated Use {@link StreamableHttpMcpTransport}. The 2024-11-05
 * two-endpoint HTTP+SSE pattern was replaced by Streamable HTTP in spec
 * 2025-03-26. This alias is preserved for one release to ease migration.
 */
declare const SseMcpTransport: typeof StreamableHttpMcpTransport;
//#endregion
//#region ../../src/mcp/index.d.ts
/**
 * Model Context Protocol for AI tool integration.
 *
 * **Features:**
 * - MCP resource definitions
 * - MCP tool definitions
 * - MCP prompt definitions
 * - JSON-RPC protocol
 * - Streamable HTTP transport (spec 2025-03-26+)
 *
 * @module alepha.mcp
 */
declare const AlephaMcp: import("alepha").Service<import("alepha").Module>;
//#endregion
export { $prompt, $resource, $tool, AlephaMcp, JSONRPC_VERSION, type JsonRpcError, JsonRpcErrorCodes, type JsonRpcNotification, JsonRpcParseError, type JsonRpcRequest, type JsonRpcResponse, MCP_PROTOCOL_VERSION, type McpCapabilities, type McpClientInfo, type McpContent, type McpContext, McpError, McpErrorCodes, McpForbiddenError, type McpInitializeParams, type McpInitializeResult, McpInvalidParamsError, type McpJsonSchema, McpMethodNotFoundError, type McpPromptArgument, type McpPromptContent, type McpPromptDescriptor, type McpPromptGetParams, type McpPromptGetResult, type McpPromptMessage, McpPromptNotFoundError, type McpResourceContent, type McpResourceDescriptor, McpResourceNotFoundError, type McpResourceReadParams, type McpResourceReadResult, type McpServerInfo, McpServerProvider, type McpToolCallParams, type McpToolCallResult, type McpToolDescriptor, McpToolNotFoundError, McpUnauthorizedError, type PromptHandler, type PromptHandlerArgs, type PromptMessage, PromptPrimitive, type PromptPrimitiveOptions, type ResourceContent, type ResourceHandler, type ResourceHandlerArgs, ResourcePrimitive, type ResourcePrimitiveOptions, SUPPORTED_PROTOCOL_VERSIONS, SseMcpTransport, StreamableHttpMcpTransport, type SupportedProtocolVersion, type ToolHandler, type ToolHandlerArgs, type ToolHandlerResult, ToolPrimitive, type ToolPrimitiveOptions, type ToolPrimitiveSchema, createErrorResponse, createInternalError, createInvalidParamsError, createInvalidRequestError, createMethodNotFoundError, createNotification, createParseError, createResponse, isNotification, isSupportedProtocolVersion, isValidJsonRpcRequest, mcpSseOptions, mcpStreamableHttpOptions, parseMessage };
//# sourceMappingURL=index.d.ts.map