alepha 0.13.8 → 0.14.1

package/src/mcp/providers/McpServerProvider.ts

@@ -0,0 +1,382 @@
+import { $inject, Alepha } from "alepha";
+import { $logger } from "alepha/logger";
+import {
+  McpError,
+  McpMethodNotFoundError,
+  McpPromptNotFoundError,
+  McpResourceNotFoundError,
+  McpToolNotFoundError,
+} from "../errors/McpError.ts";
+import {
+  createErrorResponse,
+  createInternalError,
+  createResponse,
+  MCP_PROTOCOL_VERSION,
+} from "../helpers/jsonrpc.ts";
+import type {
+  JsonRpcRequest,
+  JsonRpcResponse,
+  McpCapabilities,
+  McpContent,
+  McpContext,
+  McpInitializeResult,
+  McpPromptDescriptor,
+  McpPromptGetResult,
+  McpPromptMessage,
+  McpResourceContent,
+  McpResourceDescriptor,
+  McpResourceReadResult,
+  McpServerInfo,
+  McpToolCallResult,
+  McpToolDescriptor,
+} from "../interfaces/McpTypes.ts";
+import type { PromptPrimitive } from "../primitives/$prompt.ts";
+import type { ResourcePrimitive } from "../primitives/$resource.ts";
+import type { ToolPrimitive } from "../primitives/$tool.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.
+ */
+export class McpServerProvider {
+  protected readonly log = $logger();
+  protected readonly alepha = $inject(Alepha);
+
+  protected readonly tools = new Map<string, ToolPrimitive<any>>();
+  protected readonly resources = new Map<string, ResourcePrimitive>();
+  protected readonly prompts = new Map<string, PromptPrimitive<any>>();
+
+  protected initialized = false;
+
+  protected serverInfo: McpServerInfo = {
+    name: "alepha-mcp",
+    version: "1.0.0",
+  };
+
+  // -----------------------------------------------------------------------------------------------------------------
+  // Registration Methods
+  // -----------------------------------------------------------------------------------------------------------------
+
+  /**
+   * Register a tool with the MCP server.
+   */
+  public registerTool(tool: ToolPrimitive<any>): void {
+    this.log.trace(`Registering MCP tool: ${tool.name}`);
+    this.tools.set(tool.name, tool);
+  }
+
+  /**
+   * Register a resource with the MCP server.
+   */
+  public registerResource(resource: ResourcePrimitive): void {
+    this.log.trace(`Registering MCP resource: ${resource.uri}`);
+    this.resources.set(resource.uri, resource);
+  }
+
+  /**
+   * Register a prompt with the MCP server.
+   */
+  public registerPrompt(prompt: PromptPrimitive<any>): void {
+    this.log.trace(`Registering MCP prompt: ${prompt.name}`);
+    this.prompts.set(prompt.name, prompt);
+  }
+
+  // -----------------------------------------------------------------------------------------------------------------
+  // Getters
+  // -----------------------------------------------------------------------------------------------------------------
+
+  /**
+   * Get the server capabilities based on registered primitives.
+   */
+  public getCapabilities(): McpCapabilities {
+    return {
+      tools: this.tools.size > 0 ? {} : undefined,
+      resources: this.resources.size > 0 ? {} : undefined,
+      prompts: this.prompts.size > 0 ? {} : undefined,
+    };
+  }
+
+  /**
+   * Get all registered tools.
+   */
+  public getTools(): ToolPrimitive<any>[] {
+    return Array.from(this.tools.values());
+  }
+
+  /**
+   * Get all registered resources.
+   */
+  public getResources(): ResourcePrimitive[] {
+    return Array.from(this.resources.values());
+  }
+
+  /**
+   * Get all registered prompts.
+   */
+  public getPrompts(): PromptPrimitive<any>[] {
+    return Array.from(this.prompts.values());
+  }
+
+  /**
+   * Get a tool by name.
+   */
+  public getTool(name: string): ToolPrimitive<any> | undefined {
+    return this.tools.get(name);
+  }
+
+  /**
+   * Get a resource by URI.
+   */
+  public getResource(uri: string): ResourcePrimitive | undefined {
+    return this.resources.get(uri);
+  }
+
+  /**
+   * Get a prompt by name.
+   */
+  public getPrompt(name: string): PromptPrimitive<any> | undefined {
+    return this.prompts.get(name);
+  }
+
+  // -----------------------------------------------------------------------------------------------------------------
+  // Message Handling
+  // -----------------------------------------------------------------------------------------------------------------
+
+  /**
+   * 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
+   */
+  public async handleMessage(
+    request: JsonRpcRequest,
+    context?: McpContext,
+  ): Promise<JsonRpcResponse | null> {
+    const id = request.id;
+
+    // Notifications have no id and expect no response
+    if (id === undefined) {
+      await this.handleNotification(request);
+      return null;
+    }
+
+    try {
+      const result = await this.handleRequest(request, context);
+      return createResponse(id, result);
+    } catch (error) {
+      this.log.error("MCP request failed", error);
+      // Preserve error code from McpError instances
+      if (error instanceof McpError) {
+        return createErrorResponse(id, {
+          code: error.code,
+          message: error.message,
+        });
+      }
+      return createErrorResponse(
+        id,
+        createInternalError((error as Error).message),
+      );
+    }
+  }
+
+  /**
+   * Handle a JSON-RPC request that expects a response.
+   */
+  protected async handleRequest(
+    request: JsonRpcRequest,
+    context?: McpContext,
+  ): Promise<unknown> {
+    const { method, params = {} } = request;
+
+    switch (method) {
+      case "initialize":
+        return this.handleInitialize(params);
+      case "ping":
+        return this.handlePing();
+      case "tools/list":
+        return this.handleToolsList();
+      case "tools/call":
+        return this.handleToolsCall(params, context);
+      case "resources/list":
+        return this.handleResourcesList();
+      case "resources/read":
+        return this.handleResourcesRead(params, context);
+      case "prompts/list":
+        return this.handlePromptsList();
+      case "prompts/get":
+        return this.handlePromptsGet(params, context);
+      default:
+        throw new McpMethodNotFoundError(method);
+    }
+  }
+
+  /**
+   * Handle a notification (no response expected).
+   */
+  protected async handleNotification(request: JsonRpcRequest): Promise<void> {
+    const { method } = request;
+
+    switch (method) {
+      case "notifications/initialized":
+        this.log.debug("MCP client initialized");
+        break;
+      case "notifications/cancelled":
+        this.log.debug("MCP request cancelled", request.params);
+        break;
+      default:
+        this.log.debug(`Unknown MCP notification: ${method}`);
+    }
+  }
+
+  // -----------------------------------------------------------------------------------------------------------------
+  // Protocol Handlers
+  // -----------------------------------------------------------------------------------------------------------------
+
+  protected handleInitialize(
+    params: Record<string, unknown>,
+  ): McpInitializeResult {
+    this.log.info("MCP client initializing", {
+      clientInfo: params.clientInfo,
+      protocolVersion: params.protocolVersion,
+    });
+
+    this.initialized = true;
+
+    return {
+      protocolVersion: MCP_PROTOCOL_VERSION,
+      capabilities: this.getCapabilities(),
+      serverInfo: this.serverInfo,
+    };
+  }
+
+  protected handlePing(): Record<string, never> {
+    return {};
+  }
+
+  protected handleToolsList(): { tools: McpToolDescriptor[] } {
+    return {
+      tools: Array.from(this.tools.values()).map((t) => t.toDescriptor()),
+    };
+  }
+
+  protected async handleToolsCall(
+    params: Record<string, unknown>,
+    context?: McpContext,
+  ): Promise<McpToolCallResult> {
+    const name = params.name as string;
+    const args = (params.arguments ?? {}) as Record<string, unknown>;
+
+    const tool = this.tools.get(name);
+    if (!tool) {
+      throw new McpToolNotFoundError(name);
+    }
+
+    try {
+      const result = await tool.execute(args, context);
+
+      const content: McpContent[] = [
+        {
+          type: "text",
+          text:
+            typeof result === "string"
+              ? result
+              : JSON.stringify(result ?? null),
+        },
+      ];
+
+      return { content };
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Error: ${(error as Error).message}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+  }
+
+  protected handleResourcesList(): { resources: McpResourceDescriptor[] } {
+    return {
+      resources: Array.from(this.resources.values()).map((r) =>
+        r.toDescriptor(),
+      ),
+    };
+  }
+
+  protected async handleResourcesRead(
+    params: Record<string, unknown>,
+    context?: McpContext,
+  ): Promise<McpResourceReadResult> {
+    const uri = params.uri as string;
+
+    const resource = this.resources.get(uri);
+    if (!resource) {
+      throw new McpResourceNotFoundError(uri);
+    }
+
+    const content = await resource.read(context);
+
+    const resourceContent: McpResourceContent = {
+      uri,
+      mimeType: resource.mimeType,
+    };
+
+    if (content.text !== undefined) {
+      resourceContent.text = content.text;
+    }
+
+    if (content.blob !== undefined) {
+      // Convert binary to base64 for transport
+      resourceContent.blob = Buffer.from(content.blob).toString("base64");
+    }
+
+    return {
+      contents: [resourceContent],
+    };
+  }
+
+  protected handlePromptsList(): { prompts: McpPromptDescriptor[] } {
+    return {
+      prompts: Array.from(this.prompts.values()).map((p) => p.toDescriptor()),
+    };
+  }
+
+  protected async handlePromptsGet(
+    params: Record<string, unknown>,
+    context?: McpContext,
+  ): Promise<McpPromptGetResult> {
+    const name = params.name as string;
+    const args = (params.arguments ?? {}) as Record<string, string>;
+
+    const prompt = this.prompts.get(name);
+    if (!prompt) {
+      throw new McpPromptNotFoundError(name);
+    }
+
+    const messages = await prompt.get(args, context);
+
+    const mcpMessages: McpPromptMessage[] = messages.map((msg) => ({
+      role: msg.role,
+      content: {
+        type: "text" as const,
+        text: msg.content,
+      },
+    }));
+
+    return {
+      description: prompt.description,
+      messages: mcpMessages,
+    };
+  }
+}

package/src/mcp/transports/SseMcpTransport.ts

@@ -0,0 +1,172 @@
+import { $env, $inject, t } from "alepha";
+import { $logger } from "alepha/logger";
+import { $route } from "alepha/server";
+import {
+  createErrorResponse,
+  createNotification,
+  createParseError,
+  JsonRpcParseError,
+  parseMessage,
+} from "../helpers/jsonrpc.ts";
+import type { McpContext } from "../interfaces/McpTypes.ts";
+import { McpServerProvider } from "../providers/McpServerProvider.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+const envSchema = t.object({
+  MCP_SSE_PATH: t.text({
+    description: "Path for MCP SSE endpoint",
+    default: "/mcp",
+  }),
+});
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+/**
+ * SSE (Server-Sent Events) transport for MCP communication.
+ *
+ * This transport uses HTTP with SSE for server-to-client messages
+ * and POST requests for client-to-server messages.
+ *
+ * Endpoints:
+ * - GET /mcp - SSE stream for server events
+ * - POST /mcp - JSON-RPC request endpoint
+ *
+ * @example
+ * ```ts
+ * import { Alepha, run } from "alepha";
+ * import { AlephaServer } from "alepha/server";
+ * import { AlephaMcp, AlephaMcpSse } from "alepha/mcp";
+ *
+ * class MyTools {
+ *   // ... tool definitions
+ * }
+ *
+ * run(
+ *   Alepha.create()
+ *     .with(AlephaServer)
+ *     .with(AlephaMcp)
+ *     .with(AlephaMcpSse)
+ *     .with(MyTools)
+ * );
+ * ```
+ */
+export class SseMcpTransport {
+  protected readonly log = $logger();
+  protected readonly env = $env(envSchema);
+  protected readonly mcpServer = $inject(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 = $route({
+    method: "GET",
+    path: this.env.MCP_SSE_PATH,
+    handler: async (request) => {
+      this.log.debug("MCP SSE connection established");
+
+      const encoder = new TextEncoder();
+
+      // Create SSE stream
+      const stream = new ReadableStream({
+        start: (controller) => {
+          // Send initial endpoint info
+          const endpointEvent = this.formatSseEvent(
+            "endpoint",
+            `${this.env.MCP_SSE_PATH}`,
+          );
+          controller.enqueue(encoder.encode(endpointEvent));
+
+          // Send capabilities notification
+          const capabilitiesNotification = createNotification(
+            "notifications/capabilities",
+            { capabilities: this.mcpServer.getCapabilities() },
+          );
+          const capabilitiesEvent = this.formatSseEvent(
+            "message",
+            JSON.stringify(capabilitiesNotification),
+          );
+          controller.enqueue(encoder.encode(capabilitiesEvent));
+        },
+        cancel: () => {
+          this.log.debug("MCP SSE connection closed");
+        },
+      });
+
+      request.reply.status = 200;
+      request.reply.headers = {
+        "content-type": "text/event-stream",
+        "cache-control": "no-cache",
+        connection: "keep-alive",
+      };
+      request.reply.body = stream;
+    },
+  });
+
+  /**
+   * POST endpoint for client-to-server JSON-RPC messages.
+   */
+  message = $route({
+    method: "POST",
+    path: this.env.MCP_SSE_PATH,
+    secure: false,
+    schema: {
+      body: t.json(),
+    },
+    handler: async (request) => {
+      try {
+        const body =
+          typeof request.body === "string"
+            ? request.body
+            : JSON.stringify(request.body);
+
+        this.log.debug("MCP request body", {
+          body,
+          bodyType: typeof request.body,
+        });
+
+        const rpcRequest = parseMessage(body);
+
+        // Build context from request headers
+        const context: McpContext = {
+          headers: request.headers as Record<
+            string,
+            string | string[] | undefined
+          >,
+        };
+
+        const response = await this.mcpServer.handleMessage(
+          rpcRequest,
+          context,
+        );
+
+        request.reply.headers["content-type"] = "application/json";
+        request.reply.body = response ? JSON.stringify(response) : "";
+      } catch (error) {
+        if (error instanceof JsonRpcParseError) {
+          request.reply.status = 400;
+          request.reply.headers["content-type"] = "application/json";
+          request.reply.body = JSON.stringify(
+            createErrorResponse(0, createParseError(error.message)),
+          );
+        } else {
+          this.log.error("Failed to process MCP message", error);
+          request.reply.status = 500;
+          request.reply.body = JSON.stringify({
+            error: (error as Error).message,
+          });
+        }
+      }
+    },
+  });
+
+  /**
+   * Format a message as an SSE event.
+   */
+  protected formatSseEvent(event: string, data: string): string {
+    return `event: ${event}\ndata: ${data}\n\n`;
+  }
+}

package/src/mcp/transports/StdioMcpTransport.ts

@@ -0,0 +1,126 @@
+import * as readline from "node:readline";
+import { $hook, $inject } from "alepha";
+import { $logger } from "alepha/logger";
+import {
+  createErrorResponse,
+  createParseError,
+  JsonRpcParseError,
+  parseMessage,
+} from "../helpers/jsonrpc.ts";
+import { McpServerProvider } from "../providers/McpServerProvider.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Stdio transport for MCP communication.
+ *
+ * This transport uses stdin/stdout for JSON-RPC message exchange,
+ * which is the standard transport for local MCP servers.
+ *
+ * Messages are newline-delimited JSON objects.
+ *
+ * @example
+ * ```ts
+ * import { Alepha, run } from "alepha";
+ * import { AlephaMcp, AlephaMcpStdio } from "alepha/mcp";
+ *
+ * class MyTools {
+ *   // ... tool definitions
+ * }
+ *
+ * run(
+ *   Alepha.create()
+ *     .with(AlephaMcp)
+ *     .with(AlephaMcpStdio)
+ *     .with(MyTools)
+ * );
+ * ```
+ */
+export class StdioMcpTransport {
+  protected readonly log = $logger();
+  protected readonly mcpServer = $inject(McpServerProvider);
+
+  protected rl?: readline.Interface;
+  protected started = false;
+
+  onStart = $hook({
+    on: "start",
+    handler: () => this.start(),
+  });
+
+  onStop = $hook({
+    on: "stop",
+    handler: () => this.stop(),
+  });
+
+  /**
+   * Start the stdio transport.
+   */
+  protected start(): void {
+    if (this.started) return;
+    this.started = true;
+
+    this.rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+      terminal: false,
+    });
+
+    this.rl.on("line", (line) => this.handleLine(line));
+    this.rl.on("close", () => this.handleClose());
+
+    this.log.info("MCP stdio transport started");
+  }
+
+  /**
+   * Stop the stdio transport.
+   */
+  protected stop(): void {
+    if (!this.started) return;
+    this.started = false;
+
+    this.rl?.close();
+    this.rl = undefined;
+
+    this.log.info("MCP stdio transport stopped");
+  }
+
+  /**
+   * Handle an incoming line from stdin.
+   */
+  protected async handleLine(line: string): Promise<void> {
+    // Skip empty lines
+    if (!line.trim()) return;
+
+    try {
+      const request = parseMessage(line);
+      const response = await this.mcpServer.handleMessage(request);
+
+      if (response) {
+        this.send(response);
+      }
+    } catch (error) {
+      if (error instanceof JsonRpcParseError) {
+        // Send parse error response
+        this.send(createErrorResponse(0, createParseError(error.message)));
+      } else {
+        this.log.error("Failed to process MCP message", error);
+      }
+    }
+  }
+
+  /**
+   * Handle stdin close event.
+   */
+  protected handleClose(): void {
+    this.log.debug("MCP stdio input closed");
+  }
+
+  /**
+   * Send a message to stdout.
+   */
+  protected send(message: object): void {
+    const json = JSON.stringify(message);
+    process.stdout.write(json + "\n");
+  }
+}