alepha 0.15.0 → 0.15.2

package/dist/mcp/index.d.ts

@@ -1,10 +1,17 @@
-import * as alepha3 from "alepha";
+import * as alepha1 from "alepha";
 import { Alepha, AlephaError, Async, KIND, Primitive, Static, TObject, TSchema } from "alepha";
 import * as alepha_logger0 from "alepha/logger";
 import * as alepha_server0 from "alepha/server";
 import * as readline from "node:readline";
 
 //#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;
@@ -33,6 +40,14 @@ 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 {
@@ -162,13 +177,13 @@ interface ToolPrimitiveSchema {
  */
 interface McpContext<T = unknown> {
   /**
-       * HTTP headers from the request (for SSE transport).
-       */
+   * 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.
-       */
+   * 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>>;
@@ -262,84 +277,84 @@ declare const $resource: {
 };
 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"
-       */
+   * 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"
-       */
+   * 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;
   /**
-       * 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 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"
-       */
+   * 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 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.
-       */
+   * Returns the name of the resource.
+   */
   get name(): string;
   /**
-       * Returns the URI of the resource.
-       */
+   * Returns the URI of the resource.
+   */
   get uri(): string;
   /**
-       * Returns the description of the resource.
-       */
+   * Returns the description of the resource.
+   */
   get description(): string | undefined;
   /**
-       * Returns the MIME type of the resource.
-       */
+   * 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 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.
-       */
+   * Convert the resource to an MCP resource descriptor for protocol messages.
+   */
   toDescriptor(): McpResourceDescriptor;
 }
 //#endregion
@@ -394,78 +409,78 @@ declare const $tool: {
 };
 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"
-       */
+   * 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;
   /**
-       * 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"
-       */
+   * 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;
   /**
-       * 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
-       */
+   * 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)
-       */
+   * 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.
-       */
+   * Returns the name of the tool.
+   */
   get name(): string;
   /**
-       * Returns the description of the tool.
-       */
+   * Returns the description of the tool.
+   */
   get description(): string;
   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 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.
-       */
+   * Convert the tool to an MCP tool descriptor for protocol messages.
+   */
   toDescriptor(): McpToolDescriptor;
   /**
-       * Convert a TypeBox schema to JSON Schema format.
-       */
+   * Convert a TypeBox schema to JSON Schema format.
+   */
   protected schemaToJsonSchema(schema: TObject): McpJsonSchema;
   /**
-       * Convert a single property schema to JSON Schema format.
-       */
+   * Convert a single property schema to JSON Schema format.
+   */
   protected propertyToJsonSchema(schema: TSchema): Record<string, unknown>;
 }
 //#endregion
@@ -488,60 +503,60 @@ declare class McpServerProvider {
   protected initialized: boolean;
   protected serverInfo: McpServerInfo;
   /**
-       * Register a tool with the MCP server.
-       */
+   * Register a tool with the MCP server.
+   */
   registerTool(tool: ToolPrimitive<any>): void;
   /**
-       * Register a resource with the MCP server.
-       */
+   * Register a resource with the MCP server.
+   */
   registerResource(resource: ResourcePrimitive): void;
   /**
-       * Register a prompt with the MCP server.
-       */
+   * Register a prompt with the MCP server.
+   */
   registerPrompt(prompt: PromptPrimitive<any>): void;
   /**
-       * Get the server capabilities based on registered primitives.
-       */
+   * Get the server capabilities based on registered primitives.
+   */
   getCapabilities(): McpCapabilities;
   /**
-       * Get all registered tools.
-       */
+   * Get all registered tools.
+   */
   getTools(): ToolPrimitive<any>[];
   /**
-       * Get all registered resources.
-       */
+   * Get all registered resources.
+   */
   getResources(): ResourcePrimitive[];
   /**
-       * Get all registered prompts.
-       */
+   * Get all registered prompts.
+   */
   getPrompts(): PromptPrimitive<any>[];
   /**
-       * Get a tool by name.
-       */
+   * Get a tool by name.
+   */
   getTool(name: string): ToolPrimitive<any> | undefined;
   /**
-       * Get a resource by URI.
-       */
+   * Get a resource by URI.
+   */
   getResource(uri: string): ResourcePrimitive | undefined;
   /**
-       * Get a prompt by name.
-       */
+   * 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
-       */
+   * 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.
-       */
+   * Handle a JSON-RPC request that expects a response.
+   */
   protected handleRequest(request: JsonRpcRequest, context?: McpContext): Promise<unknown>;
   /**
-       * Handle a notification (no response expected).
-       */
+   * Handle a notification (no response expected).
+   */
   protected handleNotification(request: JsonRpcRequest): Promise<void>;
   protected handleInitialize(params: Record<string, unknown>): McpInitializeResult;
   protected handlePing(): Record<string, never>;
@@ -608,65 +623,65 @@ declare const $prompt: {
 };
 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"
-       */
+   * 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;
   /**
-       * Description of what this prompt does.
-       *
-       * Helps users understand the purpose of the prompt.
-       *
-       * @example "Generate a personalized greeting message"
-       */
+   * Description of what this prompt does.
+   *
+   * Helps users understand the purpose of the prompt.
+   *
+   * @example "Generate a personalized greeting message"
+   */
   description?: string;
   /**
-       * TypeBox schema defining the prompt arguments.
-       *
-       * Each property in the schema becomes an argument that can be
-       * filled in when the prompt is used.
-       */
+   * 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 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.
-       */
+   * Returns the name of the prompt.
+   */
   get name(): string;
   /**
-       * Returns the description of the prompt.
-       */
+   * 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 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.
-       */
+   * Convert the prompt to an MCP prompt descriptor for protocol messages.
+   */
   toDescriptor(): McpPromptDescriptor;
   /**
-       * Convert a TypeBox schema to an array of prompt arguments.
-       */
+   * Convert a TypeBox schema to an array of prompt arguments.
+   */
   protected schemaToArguments(schema: TObject): McpPromptArgument[];
 }
 //#endregion
@@ -707,21 +722,21 @@ declare class SseMcpTransport {
   };
   protected readonly mcpServer: McpServerProvider;
   /**
-       * SSE endpoint for server-to-client messages.
-       *
-       * Returns a text/event-stream response with server capabilities
-       * and keeps the connection open for notifications.
-       */
+   * SSE endpoint for server-to-client messages.
+   *
+   * Returns a text/event-stream response with server capabilities
+   * and keeps the connection open for notifications.
+   */
   sse: alepha_server0.RoutePrimitive<alepha_server0.RequestConfigSchema>;
   /**
-       * POST endpoint for client-to-server JSON-RPC messages.
-       */
+   * POST endpoint for client-to-server JSON-RPC messages.
+   */
   message: alepha_server0.RoutePrimitive<{
-    body: alepha3.TRecord<string, alepha3.TAny>;
+    body: alepha1.TRecord<string, alepha1.TAny>;
   }>;
   /**
-       * Format a message as an SSE event.
-       */
+   * Format a message as an SSE event.
+   */
   protected formatSseEvent(event: string, data: string): string;
 }
 //#endregion
@@ -756,65 +771,48 @@ declare class StdioMcpTransport {
   protected readonly mcpServer: McpServerProvider;
   protected rl?: readline.Interface;
   protected started: boolean;
-  onStart: alepha3.HookPrimitive<"start">;
-  onStop: alepha3.HookPrimitive<"stop">;
+  onStart: alepha1.HookPrimitive<"start">;
+  onStop: alepha1.HookPrimitive<"stop">;
   /**
-       * Start the stdio transport.
-       */
+   * Start the stdio transport.
+   */
   protected start(): void;
   /**
-       * Stop the stdio transport.
-       */
+   * Stop the stdio transport.
+   */
   protected stop(): void;
   /**
-       * Handle an incoming line from stdin.
-       */
+   * Handle an incoming line from stdin.
+   */
   protected handleLine(line: string): Promise<void>;
   /**
-       * Handle stdin close event.
-       */
+   * Handle stdin close event.
+   */
   protected handleClose(): void;
   /**
-       * Send a message to stdout.
-       */
+   * Send a message to stdout.
+   */
   protected send(message: object): void;
 }
 //#endregion
 //#region ../../src/mcp/index.d.ts
 /**
- * Core MCP module with primitives and server provider.
- *
- * This module registers the $tool, $resource, and $prompt primitives
- * and the McpServerProvider. You need to add a transport module
- * (AlephaMcpStdio or AlephaMcpSse) for actual communication.
- *
- * @example
- * ```ts
- * import { Alepha, run } from "alepha";
- * import { AlephaMcp, AlephaMcpStdio, $tool, t } from "alepha/mcp";
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | standard | stable |
  *
- * class MyMcpServer {
- *   add = $tool({
- *     description: "Add two numbers",
- *     schema: {
- *       params: t.object({ a: t.number(), b: t.number() }),
- *       result: t.number(),
- *     },
- *     handler: async ({ params }) => params.a + params.b,
- *   });
- * }
+ * Model Context Protocol for AI tool integration.
  *
- * run(
- *   Alepha.create()
- *     .with(AlephaMcp)
- *     .with(AlephaMcpStdio)
- *     .with(MyMcpServer)
- * );
- * ```
+ * **Features:**
+ * - MCP resource definitions
+ * - MCP tool definitions
+ * - MCP prompt definitions
+ * - JSON-RPC protocol
+ * - SSE and Stdio transports
  *
  * @module alepha.mcp
  */
-declare const AlephaMcp: alepha3.Service<alepha3.Module>;
+declare const AlephaMcp: alepha1.Service<alepha1.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, 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, type PromptHandler, type PromptHandlerArgs, type PromptMessage, PromptPrimitive, type PromptPrimitiveOptions, type ResourceContent, type ResourceHandler, type ResourceHandlerArgs, ResourcePrimitive, type ResourcePrimitiveOptions, SseMcpTransport, StdioMcpTransport, type ToolHandler, type ToolHandlerArgs, type ToolHandlerResult, ToolPrimitive, type ToolPrimitiveOptions, type ToolPrimitiveSchema, createErrorResponse, createInternalError, createInvalidParamsError, createInvalidRequestError, createMethodNotFoundError, createNotification, createParseError, createResponse, isNotification, isValidJsonRpcRequest, parseMessage };
+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, SseMcpTransport, StdioMcpTransport, type ToolHandler, type ToolHandlerArgs, type ToolHandlerResult, ToolPrimitive, type ToolPrimitiveOptions, type ToolPrimitiveSchema, createErrorResponse, createInternalError, createInvalidParamsError, createInvalidRequestError, createMethodNotFoundError, createNotification, createParseError, createResponse, isNotification, isValidJsonRpcRequest, parseMessage };
 //# sourceMappingURL=index.d.ts.map