alepha 0.13.8 → 0.14.1

package/src/core/Alepha.ts

@@ -1016,7 +1016,7 @@ export interface Env {
   /**
    * Optional environment variable that indicates the current environment.
    */
-  NODE_ENV?: "dev" | "test" | "production";
+  NODE_ENV?: string;
 
   /**
    * Optional name of the application.

package/src/core/providers/SchemaValidator.ts

@@ -1,10 +1,12 @@
 import type { TSchema } from "typebox";
 import { Compile, type Validator } from "typebox/compile";
 import { TypeBoxError } from "../errors/TypeBoxError.ts";
-import type { Static } from "./TypeProvider.ts";
+import { $hook } from "../primitives/$hook.ts";
+import { type Static, t, Value } from "./TypeProvider.ts";
 
 export class SchemaValidator {
   protected cache = new Map<TSchema, Validator>();
+  protected useEval: boolean = true;
 
   /**
    * Validate the value against the provided schema.
@@ -23,6 +25,10 @@ export class SchemaValidator {
     });
 
     try {
+      //
+      if (!this.useEval) {
+        return Value.Parse(schema, newValue);
+      }
       return this.getValidator(schema).Parse(newValue) as Static<T>;
     } catch (error: any) {
       if (error.cause?.errors?.[0]) {
@@ -130,6 +136,22 @@ export class SchemaValidator {
     }
     return false;
   };
+
+  protected onConfigure = $hook({
+    on: "configure",
+    handler: () => {
+      this.useEval = this.canEval();
+    },
+  });
+
+  protected canEval(): boolean {
+    try {
+      Compile(t.object({ test: t.string() })).Parse({ test: "value" });
+      return true;
+    } catch {
+      return false;
+    }
+  }
 }
 
 export interface ValidateOptions {

package/src/file/providers/NodeFileSystemProvider.ts

@@ -548,7 +548,9 @@ export class NodeFileSystemProvider implements FileSystemProvider {
     const stream = new PassThrough();
 
     fetch(url)
-      .then((res) => Readable.fromWeb(res.body as NodeWebStream).pipe(stream))
+      .then((res) =>
+        Readable.fromWeb(res.body as unknown as NodeWebStream).pipe(stream),
+      )
       .catch((err) => stream.destroy(err));
 
     return stream;

package/src/mcp/errors/McpError.ts

@@ -0,0 +1,72 @@
+import { JsonRpcErrorCodes } from "../helpers/jsonrpc.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export class McpError extends Error {
+  name = "McpError";
+  code: number;
+
+  constructor(
+    message: string,
+    code: number = JsonRpcErrorCodes.INTERNAL_ERROR,
+  ) {
+    super(message);
+    this.code = code;
+  }
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export class McpMethodNotFoundError extends McpError {
+  name = "McpMethodNotFoundError";
+
+  constructor(method: string) {
+    super(`Method not found: ${method}`, JsonRpcErrorCodes.METHOD_NOT_FOUND);
+  }
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export class McpToolNotFoundError extends McpError {
+  name = "McpToolNotFoundError";
+  tool: string;
+
+  constructor(tool: string) {
+    super(`Tool not found: ${tool}`, JsonRpcErrorCodes.METHOD_NOT_FOUND);
+    this.tool = tool;
+  }
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export class McpResourceNotFoundError extends McpError {
+  name = "McpResourceNotFoundError";
+  uri: string;
+
+  constructor(uri: string) {
+    super(`Resource not found: ${uri}`, JsonRpcErrorCodes.METHOD_NOT_FOUND);
+    this.uri = uri;
+  }
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export class McpPromptNotFoundError extends McpError {
+  name = "McpPromptNotFoundError";
+  prompt: string;
+
+  constructor(prompt: string) {
+    super(`Prompt not found: ${prompt}`, JsonRpcErrorCodes.METHOD_NOT_FOUND);
+    this.prompt = prompt;
+  }
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export class McpInvalidParamsError extends McpError {
+  name = "McpInvalidParamsError";
+
+  constructor(message: string) {
+    super(message, JsonRpcErrorCodes.INVALID_PARAMS);
+  }
+}

package/src/mcp/helpers/jsonrpc.ts

@@ -0,0 +1,163 @@
+import { AlephaError } from "alepha";
+import type {
+  JsonRpcError,
+  JsonRpcNotification,
+  JsonRpcRequest,
+  JsonRpcResponse,
+} from "../interfaces/McpTypes.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------------------------------------------------
+
+export const JSONRPC_VERSION = "2.0" as const;
+
+export const MCP_PROTOCOL_VERSION = "2024-11-05" as const;
+
+export const JsonRpcErrorCodes = {
+  PARSE_ERROR: -32700,
+  INVALID_REQUEST: -32600,
+  METHOD_NOT_FOUND: -32601,
+  INVALID_PARAMS: -32602,
+  INTERNAL_ERROR: -32603,
+} as const;
+
+// ---------------------------------------------------------------------------------------------------------------------
+// Response Builders
+// ---------------------------------------------------------------------------------------------------------------------
+
+export function createResponse(
+  id: string | number,
+  result: unknown,
+): JsonRpcResponse {
+  return {
+    jsonrpc: JSONRPC_VERSION,
+    id,
+    result,
+  };
+}
+
+export function createErrorResponse(
+  id: string | number,
+  error: JsonRpcError,
+): JsonRpcResponse {
+  return {
+    jsonrpc: JSONRPC_VERSION,
+    id,
+    error,
+  };
+}
+
+export function createNotification(
+  method: string,
+  params?: Record<string, unknown>,
+): JsonRpcNotification {
+  return {
+    jsonrpc: JSONRPC_VERSION,
+    method,
+    params,
+  };
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+// Error Builders
+// ---------------------------------------------------------------------------------------------------------------------
+
+export function createParseError(message = "Parse error"): JsonRpcError {
+  return {
+    code: JsonRpcErrorCodes.PARSE_ERROR,
+    message,
+  };
+}
+
+export function createInvalidRequestError(
+  message = "Invalid request",
+): JsonRpcError {
+  return {
+    code: JsonRpcErrorCodes.INVALID_REQUEST,
+    message,
+  };
+}
+
+export function createMethodNotFoundError(method: string): JsonRpcError {
+  return {
+    code: JsonRpcErrorCodes.METHOD_NOT_FOUND,
+    message: `Method not found: ${method}`,
+  };
+}
+
+export function createInvalidParamsError(message: string): JsonRpcError {
+  return {
+    code: JsonRpcErrorCodes.INVALID_PARAMS,
+    message,
+  };
+}
+
+export function createInternalError(message: string): JsonRpcError {
+  return {
+    code: JsonRpcErrorCodes.INTERNAL_ERROR,
+    message,
+  };
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+// Message Parsing
+// ---------------------------------------------------------------------------------------------------------------------
+
+export function parseMessage(data: string): JsonRpcRequest {
+  let parsed: unknown;
+
+  try {
+    parsed = JSON.parse(data);
+  } catch {
+    throw new JsonRpcParseError("Invalid JSON");
+  }
+
+  if (!isValidJsonRpcRequest(parsed)) {
+    throw new JsonRpcParseError("Invalid JSON-RPC request");
+  }
+
+  return parsed;
+}
+
+export function isValidJsonRpcRequest(value: unknown): value is JsonRpcRequest {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+
+  const obj = value as Record<string, unknown>;
+
+  if (obj.jsonrpc !== JSONRPC_VERSION) {
+    return false;
+  }
+
+  if (typeof obj.method !== "string") {
+    return false;
+  }
+
+  if (
+    obj.id !== undefined &&
+    typeof obj.id !== "string" &&
+    typeof obj.id !== "number"
+  ) {
+    return false;
+  }
+
+  if (obj.params !== undefined && typeof obj.params !== "object") {
+    return false;
+  }
+
+  return true;
+}
+
+export function isNotification(request: JsonRpcRequest): boolean {
+  return request.id === undefined;
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------------------------------------------------
+
+export class JsonRpcParseError extends AlephaError {
+  name = "JsonRpcParseError";
+}

package/src/mcp/index.ts

@@ -0,0 +1,132 @@
+import { $module } from "alepha";
+import { $prompt } from "./primitives/$prompt.ts";
+import { $resource } from "./primitives/$resource.ts";
+import { $tool } from "./primitives/$tool.ts";
+import { McpServerProvider } from "./providers/McpServerProvider.ts";
+import { SseMcpTransport } from "./transports/SseMcpTransport.ts";
+import { StdioMcpTransport } from "./transports/StdioMcpTransport.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export {
+  McpError,
+  McpInvalidParamsError,
+  McpMethodNotFoundError,
+  McpPromptNotFoundError,
+  McpResourceNotFoundError,
+  McpToolNotFoundError,
+} from "./errors/McpError.ts";
+export {
+  createErrorResponse,
+  createInternalError,
+  createInvalidParamsError,
+  createInvalidRequestError,
+  createMethodNotFoundError,
+  createNotification,
+  createParseError,
+  createResponse,
+  isNotification,
+  isValidJsonRpcRequest,
+  JSONRPC_VERSION,
+  JsonRpcErrorCodes,
+  JsonRpcParseError,
+  MCP_PROTOCOL_VERSION,
+  parseMessage,
+} from "./helpers/jsonrpc.ts";
+export type {
+  JsonRpcError,
+  JsonRpcNotification,
+  // JSON-RPC types
+  JsonRpcRequest,
+  JsonRpcResponse,
+  // MCP protocol types
+  McpCapabilities,
+  McpClientInfo,
+  McpContent,
+  // Context type for auth/headers
+  McpContext,
+  McpInitializeParams,
+  McpInitializeResult,
+  McpJsonSchema,
+  McpPromptArgument,
+  McpPromptContent,
+  // Prompt types
+  McpPromptDescriptor,
+  McpPromptGetParams,
+  McpPromptGetResult,
+  McpPromptMessage,
+  McpResourceContent,
+  // Resource types
+  McpResourceDescriptor,
+  McpResourceReadParams,
+  McpResourceReadResult,
+  McpServerInfo,
+  McpToolCallParams,
+  McpToolCallResult,
+  // Tool types
+  McpToolDescriptor,
+  PromptHandler,
+  PromptHandlerArgs,
+  PromptMessage,
+  ResourceContent,
+  ResourceHandler,
+  ResourceHandlerArgs,
+  ToolHandler,
+  ToolHandlerArgs,
+  ToolHandlerResult,
+  // Handler types
+  ToolPrimitiveSchema,
+} from "./interfaces/McpTypes.ts";
+export type { PromptPrimitiveOptions } from "./primitives/$prompt.ts";
+export { $prompt, PromptPrimitive } from "./primitives/$prompt.ts";
+export type { ResourcePrimitiveOptions } from "./primitives/$resource.ts";
+export { $resource, ResourcePrimitive } from "./primitives/$resource.ts";
+export type { ToolPrimitiveOptions } from "./primitives/$tool.ts";
+export { $tool, ToolPrimitive } from "./primitives/$tool.ts";
+export { McpServerProvider } from "./providers/McpServerProvider.ts";
+export { SseMcpTransport } from "./transports/SseMcpTransport.ts";
+export { StdioMcpTransport } from "./transports/StdioMcpTransport.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";
+ *
+ * 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,
+ *   });
+ * }
+ *
+ * run(
+ *   Alepha.create()
+ *     .with(AlephaMcp)
+ *     .with(AlephaMcpStdio)
+ *     .with(MyMcpServer)
+ * );
+ * ```
+ *
+ * @module alepha.mcp
+ */
+export const AlephaMcp = $module({
+  name: "alepha.mcp",
+  primitives: [$tool, $resource, $prompt],
+  services: [McpServerProvider, SseMcpTransport, StdioMcpTransport],
+  register: (alepha) => {
+    alepha.with(McpServerProvider);
+  },
+});

package/src/mcp/interfaces/McpTypes.ts

@@ -0,0 +1,248 @@
+import type { Async, Static, TObject, TSchema } from "alepha";
+
+// ---------------------------------------------------------------------------------------------------------------------
+// JSON-RPC 2.0 Types
+// ---------------------------------------------------------------------------------------------------------------------
+
+export interface JsonRpcRequest {
+  jsonrpc: "2.0";
+  id?: string | number;
+  method: string;
+  params?: Record<string, unknown>;
+}
+
+export interface JsonRpcResponse {
+  jsonrpc: "2.0";
+  id: string | number;
+  result?: unknown;
+  error?: JsonRpcError;
+}
+
+export interface JsonRpcNotification {
+  jsonrpc: "2.0";
+  method: string;
+  params?: Record<string, unknown>;
+}
+
+export interface JsonRpcError {
+  code: number;
+  message: string;
+  data?: unknown;
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+// MCP Protocol Types
+// ---------------------------------------------------------------------------------------------------------------------
+
+export interface McpCapabilities {
+  tools?: Record<string, never>;
+  resources?: Record<string, never>;
+  prompts?: Record<string, never>;
+}
+
+export interface McpServerInfo {
+  name: string;
+  version: string;
+}
+
+export interface McpClientInfo {
+  name: string;
+  version: string;
+}
+
+export interface McpInitializeParams {
+  protocolVersion: string;
+  capabilities: McpCapabilities;
+  clientInfo: McpClientInfo;
+}
+
+export interface McpInitializeResult {
+  protocolVersion: string;
+  capabilities: McpCapabilities;
+  serverInfo: McpServerInfo;
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+// Tool Types
+// ---------------------------------------------------------------------------------------------------------------------
+
+export interface McpToolDescriptor {
+  name: string;
+  description: string;
+  inputSchema: McpJsonSchema;
+}
+
+export interface McpJsonSchema {
+  type: string;
+  properties?: Record<string, unknown>;
+  required?: string[];
+}
+
+export interface McpToolCallParams {
+  name: string;
+  arguments?: Record<string, unknown>;
+}
+
+export interface McpToolCallResult {
+  content: McpContent[];
+  isError?: boolean;
+}
+
+export interface McpContent {
+  type: "text" | "image" | "resource";
+  text?: string;
+  data?: string;
+  mimeType?: string;
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+// Resource Types
+// ---------------------------------------------------------------------------------------------------------------------
+
+export interface McpResourceDescriptor {
+  uri: string;
+  name: string;
+  description?: string;
+  mimeType?: string;
+}
+
+export interface McpResourceReadParams {
+  uri: string;
+}
+
+export interface McpResourceReadResult {
+  contents: McpResourceContent[];
+}
+
+export interface McpResourceContent {
+  uri: string;
+  mimeType?: string;
+  text?: string;
+  blob?: string;
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+// Prompt Types
+// ---------------------------------------------------------------------------------------------------------------------
+
+export interface McpPromptDescriptor {
+  name: string;
+  description?: string;
+  arguments?: McpPromptArgument[];
+}
+
+export interface McpPromptArgument {
+  name: string;
+  description?: string;
+  required?: boolean;
+}
+
+export interface McpPromptGetParams {
+  name: string;
+  arguments?: Record<string, string>;
+}
+
+export interface McpPromptGetResult {
+  description?: string;
+  messages: McpPromptMessage[];
+}
+
+export interface McpPromptMessage {
+  role: "user" | "assistant";
+  content: McpPromptContent;
+}
+
+export interface McpPromptContent {
+  type: "text" | "image" | "resource";
+  text?: string;
+  data?: string;
+  mimeType?: string;
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+// Primitive Schema Types
+// ---------------------------------------------------------------------------------------------------------------------
+
+export interface ToolPrimitiveSchema {
+  params?: TObject;
+  result?: TSchema;
+}
+
+export interface ResourcePrimitiveSchema {
+  contents?: TSchema;
+}
+
+export interface PromptPrimitiveSchema {
+  args?: TObject;
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+// Context Types
+// ---------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Context passed to MCP handlers from the transport layer.
+ *
+ * This allows tools, resources, and prompts to access request-level
+ * information like headers for authentication.
+ */
+export 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;
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+// Handler Types
+// ---------------------------------------------------------------------------------------------------------------------
+
+export type ToolHandler<T extends ToolPrimitiveSchema, TContext = unknown> = (
+  args: ToolHandlerArgs<T, TContext>,
+) => Async<ToolHandlerResult<T>>;
+
+export interface ToolHandlerArgs<
+  T extends ToolPrimitiveSchema,
+  TContext = unknown,
+> {
+  params: T["params"] extends TObject
+    ? Static<T["params"]>
+    : Record<string, never>;
+  context?: McpContext<TContext>;
+}
+
+export type ToolHandlerResult<T extends ToolPrimitiveSchema> =
+  T["result"] extends TSchema ? Static<T["result"]> : unknown;
+
+export type ResourceHandler<TContext = unknown> = (
+  args: ResourceHandlerArgs<TContext>,
+) => Async<ResourceContent>;
+
+export interface ResourceHandlerArgs<TContext = unknown> {
+  context?: McpContext<TContext>;
+}
+
+export interface ResourceContent {
+  text?: string;
+  blob?: Uint8Array;
+}
+
+export type PromptHandler<T extends TObject, TContext = unknown> = (
+  args: PromptHandlerArgs<T, TContext>,
+) => Async<PromptMessage[]>;
+
+export interface PromptHandlerArgs<T extends TObject, TContext = unknown> {
+  args: Static<T>;
+  context?: McpContext<TContext>;
+}
+
+export interface PromptMessage {
+  role: "user" | "assistant";
+  content: string;
+}