alepha 0.13.8 → 0.14.0

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;

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

@@ -0,0 +1,171 @@
+import { $inject, createPrimitive, KIND, Primitive } from "alepha";
+import type {
+  McpContext,
+  McpResourceDescriptor,
+  ResourceContent,
+  ResourceHandler,
+} from "../interfaces/McpTypes.ts";
+import { McpServerProvider } from "../providers/McpServerProvider.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()),
+ *     }),
+ *   });
+ * }
+ * ```
+ */
+export const $resource = (
+  options: ResourcePrimitiveOptions,
+): ResourcePrimitive => {
+  return createPrimitive(ResourcePrimitive, options);
+};
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export 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;
+
+  /**
+   * 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;
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export class ResourcePrimitive extends Primitive<ResourcePrimitiveOptions> {
+  protected readonly mcpServer = $inject(McpServerProvider);
+
+  /**
+   * Returns the name of the resource.
+   */
+  public get name(): string {
+    return this.options.name ?? this.config.propertyKey;
+  }
+
+  /**
+   * Returns the URI of the resource.
+   */
+  public get uri(): string {
+    return this.options.uri;
+  }
+
+  /**
+   * Returns the description of the resource.
+   */
+  public get description(): string | undefined {
+    return this.options.description;
+  }
+
+  /**
+   * Returns the MIME type of the resource.
+   */
+  public get mimeType(): string {
+    return this.options.mimeType ?? "text/plain";
+  }
+
+  protected onInit(): void {
+    this.mcpServer.registerResource(this);
+  }
+
+  /**
+   * Read the resource content.
+   *
+   * @param context - Optional context from the transport layer
+   * @returns The resource content
+   */
+  public async read(context?: McpContext): Promise<ResourceContent> {
+    return this.options.handler({ context });
+  }
+
+  /**
+   * Convert the resource to an MCP resource descriptor for protocol messages.
+   */
+  public toDescriptor(): McpResourceDescriptor {
+    return {
+      uri: this.uri,
+      name: this.name,
+      description: this.description,
+      mimeType: this.mimeType,
+    };
+  }
+}
+
+$resource[KIND] = ResourcePrimitive;

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

@@ -0,0 +1,285 @@
+import {
+  $inject,
+  type Async,
+  createPrimitive,
+  KIND,
+  Primitive,
+  type TObject,
+  type TSchema,
+  t,
+} from "alepha";
+import type {
+  McpContext,
+  McpJsonSchema,
+  McpToolDescriptor,
+  ToolHandlerArgs,
+  ToolHandlerResult,
+  ToolPrimitiveSchema,
+} from "../interfaces/McpTypes.ts";
+import { McpServerProvider } from "../providers/McpServerProvider.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: t.object({
+ *         a: t.number(),
+ *         b: t.number(),
+ *       }),
+ *       result: t.number(),
+ *     },
+ *     handler: async ({ params }) => {
+ *       return params.a + params.b;
+ *     },
+ *   });
+ *
+ *   greet = $tool({
+ *     description: "Generate a greeting message",
+ *     schema: {
+ *       params: t.object({
+ *         name: t.text(),
+ *       }),
+ *       result: t.text(),
+ *     },
+ *     handler: async ({ params }) => {
+ *       return `Hello, ${params.name}!`;
+ *     },
+ *   });
+ * }
+ * ```
+ */
+export const $tool = <T extends ToolPrimitiveSchema>(
+  options: ToolPrimitiveOptions<T>,
+): ToolPrimitive<T> => {
+  return createPrimitive(ToolPrimitive<T>, options);
+};
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export 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;
+
+  /**
+   * 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
+   */
+  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>>;
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export class ToolPrimitive<T extends ToolPrimitiveSchema> extends Primitive<
+  ToolPrimitiveOptions<T>
+> {
+  protected readonly mcpServer = $inject(McpServerProvider);
+
+  /**
+   * Returns the name of the tool.
+   */
+  public get name(): string {
+    return this.options.name ?? this.config.propertyKey;
+  }
+
+  /**
+   * Returns the description of the tool.
+   */
+  public get description(): string {
+    return this.options.description;
+  }
+
+  protected onInit(): void {
+    this.mcpServer.registerTool(this);
+  }
+
+  /**
+   * 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
+   */
+  public async execute(
+    params: unknown,
+    context?: McpContext,
+  ): Promise<ToolHandlerResult<T>> {
+    let validatedParams: any = params ?? {};
+
+    // Validate params using alepha.codec if schema provided
+    if (this.options.schema?.params) {
+      validatedParams = this.alepha.codec.decode(
+        this.options.schema.params,
+        validatedParams,
+      );
+    }
+
+    const result = await this.options.handler({
+      params: validatedParams,
+      context,
+    });
+
+    // Validate and encode result if schema provided
+    if (this.options.schema?.result && result !== undefined) {
+      return this.alepha.codec.encode(
+        this.options.schema.result,
+        result,
+      ) as ToolHandlerResult<T>;
+    }
+
+    return result as ToolHandlerResult<T>;
+  }
+
+  /**
+   * Convert the tool to an MCP tool descriptor for protocol messages.
+   */
+  public toDescriptor(): McpToolDescriptor {
+    return {
+      name: this.name,
+      description: this.description,
+      inputSchema: this.options.schema?.params
+        ? this.schemaToJsonSchema(this.options.schema.params)
+        : { type: "object", properties: {}, required: [] },
+    };
+  }
+
+  /**
+   * Convert a TypeBox schema to JSON Schema format.
+   */
+  protected schemaToJsonSchema(schema: TObject): McpJsonSchema {
+    const properties: Record<string, unknown> = {};
+    const required: string[] = [];
+
+    for (const [key, propSchema] of Object.entries(schema.properties)) {
+      properties[key] = this.propertyToJsonSchema(propSchema as TSchema);
+
+      // Check if property is required (not optional)
+      if (!t.schema.isOptional(propSchema as TSchema)) {
+        required.push(key);
+      }
+    }
+
+    return {
+      type: "object",
+      properties,
+      required,
+    };
+  }
+
+  /**
+   * Convert a single property schema to JSON Schema format.
+   */
+  protected propertyToJsonSchema(schema: TSchema): Record<string, unknown> {
+    const result: Record<string, unknown> = {};
+
+    // Check for description on all types
+    if ("description" in schema) {
+      result.description = schema.description;
+    }
+
+    if (t.schema.isString(schema)) {
+      result.type = "string";
+      if ("minLength" in schema) result.minLength = schema.minLength;
+      if ("maxLength" in schema) result.maxLength = schema.maxLength;
+      if ("pattern" in schema) result.pattern = schema.pattern;
+      if ("enum" in schema) result.enum = schema.enum;
+    } else if (t.schema.isNumber(schema)) {
+      result.type = "number";
+      if ("minimum" in schema) result.minimum = schema.minimum;
+      if ("maximum" in schema) result.maximum = schema.maximum;
+    } else if (t.schema.isInteger(schema)) {
+      result.type = "integer";
+      if ("minimum" in schema) result.minimum = schema.minimum;
+      if ("maximum" in schema) result.maximum = schema.maximum;
+    } else if (t.schema.isBoolean(schema)) {
+      result.type = "boolean";
+    } else if (t.schema.isArray(schema)) {
+      result.type = "array";
+      if ("items" in schema) {
+        result.items = this.propertyToJsonSchema(schema.items as TSchema);
+      }
+    } else if (t.schema.isObject(schema)) {
+      Object.assign(result, this.schemaToJsonSchema(schema));
+    } else if (t.schema.isUnsafe(schema) || t.schema.isOptional(schema)) {
+      // Handle Unsafe types (like t.enum) and optional wrappers by checking the underlying type property
+      const schemaAny = schema as { type?: string; enum?: unknown[] };
+      if (schemaAny.type === "string") {
+        result.type = "string";
+        if ("enum" in schema) result.enum = schema.enum;
+        if ("pattern" in schema) result.pattern = schema.pattern;
+      } else if (schemaAny.type === "number") {
+        result.type = "number";
+      } else if (schemaAny.type === "integer") {
+        result.type = "integer";
+      } else if (schemaAny.type === "boolean") {
+        result.type = "boolean";
+      } else if (schemaAny.type === "array") {
+        result.type = "array";
+      } else if (schemaAny.type === "object") {
+        result.type = "object";
+      } else {
+        // Fallback
+        result.type = "string";
+      }
+    } else {
+      // Fallback for other types
+      result.type = "string";
+    }
+
+    return result;
+  }
+}
+
+$tool[KIND] = ToolPrimitive;