alepha 0.22.0 → 0.24.0

package/src/mcp/__tests__/McpServerProvider.spec.ts

@@ -1,4 +1,4 @@
-import { Alepha, t } from "alepha";
+import { Alepha, z } from "alepha";
 import { describe, expect, test } from "vitest";
 import {
   $prompt,
@@ -163,13 +163,13 @@ describe("McpServerProvider", () => {
       class Calculator {
         add = $tool({
           description: "Add numbers",
-          schema: { params: t.object({ a: t.number(), b: t.number() }) },
+          schema: { params: z.object({ a: z.number(), b: z.number() }) },
           handler: async ({ params }) => params.a + params.b,
         });
 
         subtract = $tool({
           description: "Subtract numbers",
-          schema: { params: t.object({ a: t.number(), b: t.number() }) },
+          schema: { params: z.object({ a: z.number(), b: z.number() }) },
           handler: async ({ params }) => params.a - params.b,
         });
       }
@@ -201,8 +201,8 @@ describe("McpServerProvider", () => {
         multiply = $tool({
           description: "Multiply",
           schema: {
-            params: t.object({ a: t.number(), b: t.number() }),
-            result: t.number(),
+            params: z.object({ a: z.number(), b: z.number() }),
+            result: z.number(),
           },
           handler: async ({ params }) => params.a * params.b,
         });
@@ -230,6 +230,77 @@ describe("McpServerProvider", () => {
       expect(result.content[0].text).toBe("42");
     });
 
+    test("passes raw MCP content (e.g. image) through verbatim when the tool has no output schema", async () => {
+      const alepha = Alepha.create();
+
+      class ImageTools {
+        screenshot = $tool({
+          description: "Return a tiny image",
+          // No `result` schema — handler returns raw MCP content blocks.
+          handler: async () => ({
+            content: [
+              {
+                type: "image",
+                data: "aGVsbG8=",
+                mimeType: "image/png",
+              },
+            ],
+          }),
+        });
+      }
+
+      alepha.with(AlephaMcp).with(ImageTools);
+      await alepha.start();
+
+      const provider = alepha.inject(McpServerProvider);
+      const response = await provider.handleMessage({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: { name: "screenshot", arguments: {} },
+      });
+
+      const result = response?.result as {
+        content: Array<{ type: string; data?: string; mimeType?: string }>;
+        structuredContent?: unknown;
+      };
+      expect(result.content).toHaveLength(1);
+      expect(result.content[0].type).toBe("image");
+      expect(result.content[0].data).toBe("aGVsbG8=");
+      expect(result.content[0].mimeType).toBe("image/png");
+      // Raw content is NOT double-wrapped into a JSON text block.
+      expect(result.structuredContent).toBeUndefined();
+    });
+
+    test("a plain object result (no content array) still serializes to a JSON text block", async () => {
+      const alepha = Alepha.create();
+
+      class PlainTools {
+        info = $tool({
+          description: "Return a plain object",
+          // No `result` schema, but the object is not raw MCP content.
+          handler: async () => ({ hello: "world" }),
+        });
+      }
+
+      alepha.with(AlephaMcp).with(PlainTools);
+      await alepha.start();
+
+      const provider = alepha.inject(McpServerProvider);
+      const response = await provider.handleMessage({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: { name: "info", arguments: {} },
+      });
+
+      const result = response?.result as {
+        content: Array<{ type: string; text: string }>;
+      };
+      expect(result.content[0].type).toBe("text");
+      expect(JSON.parse(result.content[0].text)).toEqual({ hello: "world" });
+    });
+
     test("should return error for unknown tool", async () => {
       const alepha = Alepha.create();
       alepha.with(AlephaMcp);
@@ -411,7 +482,7 @@ describe("McpServerProvider", () => {
       class Prompts {
         greeting = $prompt({
           description: "Generate greeting",
-          args: t.object({ name: t.text() }),
+          args: z.object({ name: z.text() }),
           handler: async () => [],
         });
 
@@ -445,7 +516,7 @@ describe("McpServerProvider", () => {
       class Prompts {
         greeting = $prompt({
           description: "Generate greeting",
-          args: t.object({ name: t.text() }),
+          args: z.object({ name: z.text() }),
           handler: async ({ args }) => [
             { role: "user", content: `Say hello to ${args.name}` },
           ],
@@ -591,8 +662,8 @@ describe("McpServerProvider", () => {
         contextTool = $tool({
           description: "Tool that receives context",
           schema: {
-            params: t.object({ value: t.text() }),
-            result: t.text(),
+            params: z.object({ value: z.text() }),
+            result: z.text(),
           },
           handler: async ({ params, context }) => {
             receivedContext = context;
@@ -677,7 +748,7 @@ describe("McpServerProvider", () => {
       class Prompts {
         contextPrompt = $prompt({
           description: "Prompt that receives context",
-          args: t.object({ name: t.text() }),
+          args: z.object({ name: z.text() }),
           handler: async ({ args, context }) => {
             receivedContext = context;
             return [{ role: "user", content: `Hello ${args.name}` }];
@@ -748,7 +819,7 @@ describe("McpServerProvider", () => {
       class Tools {
         protected = $tool({
           description: "Protected tool",
-          schema: { result: t.text() },
+          schema: { result: z.text() },
           handler: async ({ context }) => {
             const auth = context?.headers?.authorization;
             if (!auth?.toString().startsWith("Bearer ")) {

package/src/mcp/__tests__/StreamableHttpMcpTransport.spec.ts

@@ -1,4 +1,4 @@
-import { Alepha, t } from "alepha";
+import { Alepha, z } from "alepha";
 import { ServerProvider } from "alepha/server";
 import { describe, expect, it } from "vitest";
 import { AlephaMcp, MCP_PROTOCOL_VERSION } from "../index.ts";
@@ -17,7 +17,7 @@ import {
 class PingTool {
   ping = $tool({
     description: "Ping",
-    schema: { params: t.object({}), result: t.text() },
+    schema: { params: z.object({}), result: z.text() },
     handler: async () => "pong",
   });
 }

package/src/mcp/__tests__/integration.spec.ts

@@ -1,4 +1,4 @@
-import { Alepha, t } from "alepha";
+import { Alepha, z } from "alepha";
 import { describe, expect, test } from "vitest";
 import {
   $prompt,
@@ -19,11 +19,11 @@ describe("MCP Integration", () => {
       add = $tool({
         description: "Add two numbers",
         schema: {
-          params: t.object({
-            a: t.number(),
-            b: t.number(),
+          params: z.object({
+            a: z.number(),
+            b: z.number(),
           }),
-          result: t.number(),
+          result: z.number(),
         },
         handler: async ({ params }) => params.a + params.b,
       });
@@ -47,7 +47,7 @@ describe("MCP Integration", () => {
     });
 
     expect(initResponse?.result).toBeDefined();
-    const initResult = initResponse?.result as {
+    const initResult = initResponse!.result as {
       capabilities: { tools?: object };
     };
     expect(initResult.capabilities.tools).toBeDefined();
@@ -66,7 +66,7 @@ describe("MCP Integration", () => {
       method: "tools/list",
     });
 
-    const tools = (listResponse?.result as { tools: Array<{ name: string }> })
+    const tools = (listResponse!.result as { tools: Array<{ name: string }> })
       .tools;
     expect(tools).toHaveLength(1);
     expect(tools[0].name).toBe("add");
@@ -82,7 +82,7 @@ describe("MCP Integration", () => {
       },
     });
 
-    const result = callResponse?.result as { content: Array<{ text: string }> };
+    const result = callResponse!.result as { content: Array<{ text: string }> };
     expect(result.content[0].text).toBe("30");
   });
 
@@ -129,7 +129,7 @@ describe("MCP Integration", () => {
     });
 
     const resources = (
-      listResponse?.result as {
+      listResponse!.result as {
         resources: Array<{ uri: string; name: string }>;
       }
     ).resources;
@@ -145,7 +145,7 @@ describe("MCP Integration", () => {
       params: { uri: "file:///README.md" },
     });
 
-    const content1 = (read1?.result as { contents: Array<{ text: string }> })
+    const content1 = (read1!.result as { contents: Array<{ text: string }> })
       .contents[0];
     expect(content1.text).toContain("Read count: 1");
 
@@ -156,7 +156,7 @@ describe("MCP Integration", () => {
       params: { uri: "file:///README.md" },
     });
 
-    const content2 = (read2?.result as { contents: Array<{ text: string }> })
+    const content2 = (read2!.result as { contents: Array<{ text: string }> })
       .contents[0];
     expect(content2.text).toContain("Read count: 2");
   });
@@ -168,10 +168,10 @@ describe("MCP Integration", () => {
       codeReview = $prompt({
         name: "code-review",
         description: "Request a code review for the given code",
-        args: t.object({
-          language: t.text({ description: "Programming language" }),
-          code: t.text({ description: "Code to review" }),
-          focus: t.optional(t.text({ description: "Focus areas for review" })),
+        args: z.object({
+          language: z.text({ description: "Programming language" }),
+          code: z.text({ description: "Code to review" }),
+          focus: z.text({ description: "Focus areas for review" }).optional(),
         }),
         handler: async ({ args }) => {
           const messages = [
@@ -218,7 +218,7 @@ describe("MCP Integration", () => {
     });
 
     const prompts = (
-      listResponse?.result as {
+      listResponse!.result as {
         prompts: Array<{
           name: string;
           arguments?: Array<{ name: string; required?: boolean }>;
@@ -244,7 +244,7 @@ describe("MCP Integration", () => {
     });
 
     const messages1 = (
-      get1?.result as {
+      get1!.result as {
         messages: Array<{ role: string; content: { text: string } }>;
       }
     ).messages;
@@ -267,7 +267,7 @@ describe("MCP Integration", () => {
     });
 
     const messages2 = (
-      get2?.result as { messages: Array<{ content: { text: string } }> }
+      get2!.result as { messages: Array<{ content: { text: string } }> }
     ).messages;
     expect(messages2).toHaveLength(2);
     expect(messages2[1].content.text).toContain("performance");
@@ -281,12 +281,12 @@ describe("MCP Integration", () => {
       calculator = $tool({
         description: "Basic calculator",
         schema: {
-          params: t.object({
-            op: t.enum(["add", "sub", "mul", "div"]),
-            a: t.number(),
-            b: t.number(),
+          params: z.object({
+            op: z.enum(["add", "sub", "mul", "div"]),
+            a: z.number(),
+            b: z.number(),
           }),
-          result: t.number(),
+          result: z.number(),
         },
         handler: async ({ params }) => {
           switch (params.op) {
@@ -305,8 +305,8 @@ describe("MCP Integration", () => {
       echo = $tool({
         description: "Echo the input",
         schema: {
-          params: t.object({ message: t.text() }),
-          result: t.text(),
+          params: z.object({ message: z.text() }),
+          result: z.text(),
         },
         handler: async ({ params }) => params.message,
       });
@@ -324,7 +324,7 @@ describe("MCP Integration", () => {
       // Prompts
       greeting = $prompt({
         description: "Generate a greeting",
-        args: t.object({ name: t.text() }),
+        args: z.object({ name: z.text() }),
         handler: async ({ args }) => [
           { role: "user", content: `Say hello to ${args.name}` },
         ],
@@ -349,7 +349,7 @@ describe("MCP Integration", () => {
     });
 
     const caps = (
-      init?.result as {
+      init!.result as {
         capabilities: { tools?: object; resources?: object; prompts?: object };
       }
     ).capabilities;
@@ -365,7 +365,7 @@ describe("MCP Integration", () => {
       params: { name: "calculator", arguments: { op: "mul", a: 7, b: 8 } },
     });
     expect(
-      (calc?.result as { content: Array<{ text: string }> }).content[0].text,
+      (calc!.result as { content: Array<{ text: string }> }).content[0].text,
     ).toBe("56");
 
     // Read version resource
@@ -376,7 +376,7 @@ describe("MCP Integration", () => {
       params: { uri: "app://version" },
     });
     const versionData = JSON.parse(
-      (ver?.result as { contents: Array<{ text: string }> }).contents[0].text,
+      (ver!.result as { contents: Array<{ text: string }> }).contents[0].text,
     );
     expect(versionData.version).toBe("1.0.0");
 
@@ -388,7 +388,7 @@ describe("MCP Integration", () => {
       params: { name: "greeting", arguments: { name: "Alice" } },
     });
     expect(
-      (greet?.result as { messages: Array<{ content: { text: string } }> })
+      (greet!.result as { messages: Array<{ content: { text: string } }> })
         .messages[0].content.text,
     ).toContain("Alice");
   });
@@ -424,7 +424,7 @@ describe("MCP Integration", () => {
       params: { name: "flaky", arguments: {} },
     });
     expect(
-      (r1?.result as { content: Array<{ text: string }> }).content[0].text,
+      (r1!.result as { content: Array<{ text: string }> }).content[0].text,
     ).toBe("success");
 
     // Second call - failure
@@ -434,7 +434,7 @@ describe("MCP Integration", () => {
       method: "tools/call",
       params: { name: "flaky", arguments: {} },
     });
-    expect((r2?.result as { isError?: boolean }).isError).toBe(true);
+    expect((r2!.result as { isError?: boolean }).isError).toBe(true);
 
     // Third call - success (server should still work)
     const r3 = await provider.handleMessage({
@@ -444,7 +444,7 @@ describe("MCP Integration", () => {
       params: { name: "flaky", arguments: {} },
     });
     expect(
-      (r3?.result as { content: Array<{ text: string }> }).content[0].text,
+      (r3!.result as { content: Array<{ text: string }> }).content[0].text,
     ).toBe("success");
   });
 });

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

@@ -6,7 +6,7 @@ import {
   Primitive,
   type Static,
   type TObject,
-  t,
+  z,
 } from "alepha";
 import type {
   McpContext,
@@ -32,9 +32,9 @@ import { McpServerProvider } from "../providers/McpServerProvider.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"])),
+ *     args: z.object({
+ *       name: z.text({ description: "Name of the person to greet" }),
+ *       style: z.enum(["formal", "casual"]).optional(),
  *     }),
  *     handler: async ({ args }) => [
  *       {
@@ -48,9 +48,9 @@ import { McpServerProvider } from "../providers/McpServerProvider.ts";
  *
  *   codeReview = $prompt({
  *     description: "Request a code review",
- *     args: t.object({
- *       code: t.text({ description: "The code to review" }),
- *       language: t.text({ description: "Programming language" }),
+ *     args: z.object({
+ *       code: z.text({ description: "The code to review" }),
+ *       language: z.text({ description: "Programming language" }),
  *     }),
  *     handler: async ({ args }) => [
  *       {
@@ -190,11 +190,13 @@ export class PromptPrimitive<T extends TObject> extends Primitive<
     const args: McpPromptArgument[] = [];
 
     for (const [name, propSchema] of Object.entries(schema.properties)) {
-      const prop = propSchema as Record<string, unknown>;
+      // The description lives on the inner schema; peel optional/nullable/default
+      // wrappers so `z.number({ description }).optional()` still surfaces it.
+      const prop = z.schema.unwrap(propSchema) as Record<string, unknown>;
       args.push({
         name,
         description: prop.description as string | undefined,
-        required: !t.schema.isOptional(propSchema),
+        required: !z.schema.isOptional(propSchema),
       });
     }
 

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

@@ -6,7 +6,7 @@ import {
   Primitive,
   type TObject,
   type TSchema,
-  t,
+  z,
 } from "alepha";
 import type {
   McpContext,
@@ -40,11 +40,11 @@ import { McpServerProvider } from "../providers/McpServerProvider.ts";
  *   add = $tool({
  *     description: "Add two numbers together",
  *     schema: {
- *       params: t.object({
- *         a: t.number(),
- *         b: t.number(),
+ *       params: z.object({
+ *         a: z.number(),
+ *         b: z.number(),
  *       }),
- *       result: t.number(),
+ *       result: z.number(),
  *     },
  *     handler: async ({ params }) => {
  *       return params.a + params.b;
@@ -54,10 +54,10 @@ import { McpServerProvider } from "../providers/McpServerProvider.ts";
  *   greet = $tool({
  *     description: "Generate a greeting message",
  *     schema: {
- *       params: t.object({
- *         name: t.text(),
+ *       params: z.object({
+ *         name: z.text(),
  *       }),
- *       result: t.text(),
+ *       result: z.text(),
  *     },
  *     handler: async ({ params }) => {
  *       return `Hello, ${params.name}!`;
@@ -267,94 +267,35 @@ export class ToolPrimitive<T extends ToolPrimitiveSchema> extends Primitive<
     schema: TObject,
     options?: { root?: boolean },
   ): 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);
-      }
+    let json: any;
+    try {
+      json = z.toJSONSchema(schema as any);
+    } catch {
+      json = { type: "object", properties: {}, required: [] };
     }
 
-    const result: McpJsonSchema = {
-      type: "object",
-      properties,
-      required,
-    };
-
-    // Annotate the dialect on the root schema only (avoid noise on nested
-    // sub-schemas where MCP doesn't expect $schema).
-    if (options?.root !== false) {
-      result.$schema = "https://json-schema.org/draft/2020-12/schema";
+    // Annotate the 2020-12 dialect on the root schema only (avoid noise on
+    // nested sub-schemas where MCP doesn't expect $schema).
+    if (options?.root === false) {
+      json.$schema = undefined;
+    } else {
+      json.$schema = "https://json-schema.org/draft/2020-12/schema";
     }
 
-    return result;
+    return json as McpJsonSchema;
   }
 
   /**
-   * Convert a single property schema to JSON Schema format.
+   * Convert a single property schema to JSON Schema format (zod-native).
    */
   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;
+    try {
+      const json: any = z.toJSONSchema(schema as any);
+      json.$schema = undefined;
+      return json;
+    } catch {
+      return { type: "string" };
     }
-
-    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, { root: false }));
-    } 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;
   }
 }
 

package/src/mcp/providers/McpServerProvider.ts

@@ -19,6 +19,7 @@ import type {
   JsonRpcRequest,
   JsonRpcResponse,
   McpCapabilities,
+  McpContent,
   McpContext,
   McpInitializeResult,
   McpPromptDescriptor,
@@ -309,6 +310,20 @@ export class McpServerProvider {
     try {
       const result = await tool.execute(args, context);
 
+      // A tool WITHOUT an output schema may return raw MCP content blocks
+      // (e.g. an `image` block) instead of JSON — used for binary payloads
+      // like attachment previews. Recognized by the CallToolResult shape
+      // (`{ content: McpContent[] }`); passed through verbatim. Tools that
+      // declare an output schema always go through the structured path
+      // below, so a JSON result that happens to carry a `content` array is
+      // never mistaken for raw content.
+      if (!tool.hasOutputSchema()) {
+        const raw = this.asRawToolContent(result);
+        if (raw) {
+          return raw;
+        }
+      }
+
       const callResult: McpToolCallResult = {
         content: [
           {
@@ -364,6 +379,46 @@ export class McpServerProvider {
     }
   }
 
+  /**
+   * Recognize a tool handler's return value as a pre-built MCP tool result —
+   * i.e. it already carries a `content` array of content blocks (text, image,
+   * audio, resource, resource_link). Returns the normalized
+   * {@link McpToolCallResult} when matched, or `undefined` to fall back to the
+   * default JSON/text encoding. Only ever consulted for tools that did NOT
+   * declare an output schema (see {@link handleToolCall}).
+   */
+  protected asRawToolContent(result: unknown): McpToolCallResult | undefined {
+    if (!result || typeof result !== "object") {
+      return undefined;
+    }
+    const candidate = result as {
+      content?: unknown;
+      isError?: unknown;
+      _meta?: unknown;
+    };
+    if (!Array.isArray(candidate.content) || candidate.content.length === 0) {
+      return undefined;
+    }
+    const allBlocks = candidate.content.every(
+      (block): block is McpContent =>
+        !!block &&
+        typeof block === "object" &&
+        typeof (block as { type?: unknown }).type === "string",
+    );
+    if (!allBlocks) {
+      return undefined;
+    }
+    return {
+      content: candidate.content as McpContent[],
+      isError:
+        typeof candidate.isError === "boolean" ? candidate.isError : undefined,
+      _meta:
+        candidate._meta && typeof candidate._meta === "object"
+          ? (candidate._meta as Record<string, unknown>)
+          : undefined,
+    };
+  }
+
   protected handleResourcesList(): { resources: McpResourceDescriptor[] } {
     return {
       resources: Array.from(this.resources.values()).map((r) =>