alepha 0.13.7 → 0.14.0

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;
+}

package/src/mcp/primitives/$prompt.ts

@@ -0,0 +1,188 @@
+import {
+  $inject,
+  type Async,
+  createPrimitive,
+  KIND,
+  Primitive,
+  type Static,
+  type TObject,
+  t,
+} from "alepha";
+import type {
+  McpContext,
+  McpPromptArgument,
+  McpPromptDescriptor,
+  PromptHandlerArgs,
+  PromptMessage,
+} from "../interfaces/McpTypes.ts";
+import { McpServerProvider } from "../providers/McpServerProvider.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: t.object({
+ *       name: t.text({ description: "Name of the person to greet" }),
+ *       style: t.optional(t.enum(["formal", "casual"])),
+ *     }),
+ *     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: t.object({
+ *       code: t.text({ description: "The code to review" }),
+ *       language: t.text({ description: "Programming language" }),
+ *     }),
+ *     handler: async ({ args }) => [
+ *       {
+ *         role: "user",
+ *         content: `Please review this ${args.language} code:\n\n${args.code}`,
+ *       },
+ *     ],
+ *   });
+ * }
+ * ```
+ */
+export const $prompt = <T extends TObject>(
+  options: PromptPrimitiveOptions<T>,
+): PromptPrimitive<T> => {
+  return createPrimitive(PromptPrimitive<T>, options);
+};
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export 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;
+
+  /**
+   * 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.
+   */
+  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[]>;
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export class PromptPrimitive<T extends TObject> extends Primitive<
+  PromptPrimitiveOptions<T>
+> {
+  protected readonly mcpServer = $inject(McpServerProvider);
+
+  /**
+   * Returns the name of the prompt.
+   */
+  public get name(): string {
+    return this.options.name ?? this.config.propertyKey;
+  }
+
+  /**
+   * Returns the description of the prompt.
+   */
+  public get description(): string | undefined {
+    return this.options.description;
+  }
+
+  protected onInit(): void {
+    this.mcpServer.registerPrompt(this);
+  }
+
+  /**
+   * 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
+   */
+  public async get(
+    rawArgs: unknown,
+    context?: McpContext,
+  ): Promise<PromptMessage[]> {
+    let args = (rawArgs ?? {}) as Static<T>;
+
+    if (this.options.args) {
+      args = this.alepha.codec.decode(this.options.args, rawArgs ?? {});
+    }
+
+    return this.options.handler({ args, context });
+  }
+
+  /**
+   * Convert the prompt to an MCP prompt descriptor for protocol messages.
+   */
+  public toDescriptor(): McpPromptDescriptor {
+    return {
+      name: this.name,
+      description: this.description,
+      arguments: this.options.args
+        ? this.schemaToArguments(this.options.args)
+        : [],
+    };
+  }
+
+  /**
+   * Convert a TypeBox schema to an array of prompt arguments.
+   */
+  protected schemaToArguments(schema: TObject): McpPromptArgument[] {
+    const args: McpPromptArgument[] = [];
+
+    for (const [name, propSchema] of Object.entries(schema.properties)) {
+      const prop = propSchema as Record<string, unknown>;
+      args.push({
+        name,
+        description: prop.description as string | undefined,
+        required: !t.schema.isOptional(propSchema),
+      });
+    }
+
+    return args;
+  }
+}
+
+$prompt[KIND] = PromptPrimitive;