alepha 0.20.3 → 0.20.4

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

@@ -1,6 +1,7 @@
 import { $inject, createPrimitive, KIND, Primitive } from "alepha";
 import type {
   McpContext,
+  McpIcon,
   McpResourceDescriptor,
   ResourceContent,
   ResourceHandler,
@@ -78,6 +79,17 @@ export interface ResourcePrimitiveOptions {
    */
   name?: string;
 
+  /**
+   * Human-friendly display title (spec 2025-11-25). Distinct from `name`,
+   * which remains the programmatic identifier.
+   */
+  title?: string;
+
+  /**
+   * Optional icons surfaced in client UIs (spec 2025-11-25 / SEP-973).
+   */
+  icons?: McpIcon[];
+
   /**
    * Description of what this resource contains.
    *
@@ -159,12 +171,17 @@ export class ResourcePrimitive extends Primitive<ResourcePrimitiveOptions> {
    * Convert the resource to an MCP resource descriptor for protocol messages.
    */
   public toDescriptor(): McpResourceDescriptor {
-    return {
+    const descriptor: McpResourceDescriptor = {
       uri: this.uri,
       name: this.name,
       description: this.description,
       mimeType: this.mimeType,
     };
+    if (this.options.title) descriptor.title = this.options.title;
+    if (this.options.icons && this.options.icons.length > 0) {
+      descriptor.icons = this.options.icons;
+    }
+    return descriptor;
   }
 }
 

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

@@ -10,7 +10,9 @@ import {
 } from "alepha";
 import type {
   McpContext,
+  McpIcon,
   McpJsonSchema,
+  McpToolAnnotations,
   McpToolDescriptor,
   ToolHandlerArgs,
   ToolHandlerResult,
@@ -84,6 +86,15 @@ export interface ToolPrimitiveOptions<T extends ToolPrimitiveSchema> {
    */
   name?: string;
 
+  /**
+   * Human-friendly display title (spec 2025-11-25). Distinct from `name`,
+   * which remains the programmatic identifier. Clients use `title` in
+   * tool palettes / picker UIs.
+   *
+   * @example "Search Lore"
+   */
+  title?: string;
+
   /**
    * A human-readable description of what the tool does.
    *
@@ -95,6 +106,18 @@ export interface ToolPrimitiveOptions<T extends ToolPrimitiveSchema> {
    */
   description: string;
 
+  /**
+   * Behavior hints (spec 2025-03-26+). Clients use these to gate UI prompts
+   * (e.g. require confirmation before a tool with `destructiveHint: true`).
+   * None are guarantees — they are heuristics for the client, not the model.
+   */
+  annotations?: McpToolAnnotations;
+
+  /**
+   * Icons surfaced in client tool palettes / picker UIs (spec 2025-11-25).
+   */
+  icons?: McpIcon[];
+
   /**
    * TypeBox schema defining the tool's parameters and result type.
    *
@@ -141,6 +164,15 @@ export class ToolPrimitive<T extends ToolPrimitiveSchema> extends Primitive<
     return this.options.description;
   }
 
+  /**
+   * Whether the tool declared a result schema. When true, `tools/call`
+   * responses include `structuredContent` populated with the validated
+   * result (spec 2025-06-18).
+   */
+  public hasOutputSchema(): boolean {
+    return !!this.options.schema?.result;
+  }
+
   protected onInit(): void {
     this.mcpServer.registerTool(this);
   }
@@ -184,21 +216,57 @@ export class ToolPrimitive<T extends ToolPrimitiveSchema> extends Primitive<
 
   /**
    * Convert the tool to an MCP tool descriptor for protocol messages.
+   *
+   * Emits the spec 2025-11-25 surface: `title`, `annotations`, `icons`,
+   * and (when `schema.result` is defined) `outputSchema` so the server
+   * can populate `structuredContent` on call results.
    */
   public toDescriptor(): McpToolDescriptor {
-    return {
+    const inputSchema: McpJsonSchema = this.options.schema?.params
+      ? this.schemaToJsonSchema(this.options.schema.params)
+      : { type: "object", properties: {}, required: [] };
+
+    const descriptor: McpToolDescriptor = {
       name: this.name,
       description: this.description,
-      inputSchema: this.options.schema?.params
-        ? this.schemaToJsonSchema(this.options.schema.params)
-        : { type: "object", properties: {}, required: [] },
+      inputSchema,
     };
+
+    if (this.options.title) descriptor.title = this.options.title;
+    if (this.options.annotations)
+      descriptor.annotations = this.options.annotations;
+    if (this.options.icons && this.options.icons.length > 0) {
+      descriptor.icons = this.options.icons;
+    }
+
+    // Output schema is emitted when the tool declares `schema.result`,
+    // unlocking structured content on tools/call responses.
+    if (this.options.schema?.result) {
+      const out = this.propertyToJsonSchema(this.options.schema.result);
+      // The result schema may be a primitive — wrap so the descriptor
+      // value is always a JSON Schema object with `type`.
+      descriptor.outputSchema = (
+        typeof out === "object" && out !== null && "type" in out
+          ? out
+          : { type: "object", properties: {}, required: [] }
+      ) as McpJsonSchema;
+    }
+
+    return descriptor;
   }
 
   /**
    * Convert a TypeBox schema to JSON Schema format.
+   *
+   * Emits the 2020-12 dialect annotation at the root (spec 2025-11-25 /
+   * SEP-1613 — JSON Schema 2020-12 is the default dialect for MCP).
+   * The TypeBox shapes Alepha emits today are already 2020-12-compatible;
+   * this is just the dialect declaration.
    */
-  protected schemaToJsonSchema(schema: TObject): McpJsonSchema {
+  protected schemaToJsonSchema(
+    schema: TObject,
+    options?: { root?: boolean },
+  ): McpJsonSchema {
     const properties: Record<string, unknown> = {};
     const required: string[] = [];
 
@@ -211,11 +279,19 @@ export class ToolPrimitive<T extends ToolPrimitiveSchema> extends Primitive<
       }
     }
 
-    return {
+    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";
+    }
+
+    return result;
   }
 
   /**
@@ -251,7 +327,7 @@ export class ToolPrimitive<T extends ToolPrimitiveSchema> extends Primitive<
         result.items = this.propertyToJsonSchema(schema.items as TSchema);
       }
     } else if (t.schema.isObject(schema)) {
-      Object.assign(result, this.schemaToJsonSchema(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[] };

package/src/mcp/providers/McpServerProvider.ts

@@ -1,4 +1,4 @@
-import { $inject, Alepha } from "alepha";
+import { $inject, Alepha, TypeBoxError } from "alepha";
 import { $logger } from "alepha/logger";
 import {
   McpError,
@@ -11,13 +11,14 @@ import {
   createErrorResponse,
   createInternalError,
   createResponse,
+  isSupportedProtocolVersion,
   MCP_PROTOCOL_VERSION,
+  SUPPORTED_PROTOCOL_VERSIONS,
 } from "../helpers/jsonrpc.ts";
 import type {
   JsonRpcRequest,
   JsonRpcResponse,
   McpCapabilities,
-  McpContent,
   McpContext,
   McpInitializeResult,
   McpPromptDescriptor,
@@ -55,7 +56,20 @@ export class McpServerProvider {
 
   protected initialized = false;
 
-  protected serverInfo: McpServerInfo = {
+  /**
+   * Protocol version negotiated with the client during `initialize`.
+   * Used by transports to validate the `MCP-Protocol-Version` header on
+   * subsequent HTTP requests (per spec 2025-06-18+).
+   */
+  public negotiatedVersion: string = MCP_PROTOCOL_VERSION;
+
+  /**
+   * Server identity returned during `initialize`. Consumers may override
+   * fields directly (e.g. `mcpServer.serverInfo = { name: "roadmap-mcp",
+   * version: "0.20.3", description: "..." }`) — the `description` field
+   * is supported per spec 2025-11-25 (minor change #2).
+   */
+  public serverInfo: McpServerInfo = {
     name: "alepha-mcp",
     version: "1.0.0",
   };
@@ -243,15 +257,25 @@ export class McpServerProvider {
   protected handleInitialize(
     params: Record<string, unknown>,
   ): McpInitializeResult {
+    const requested = params.protocolVersion;
+    // Echo the client's version when supported, otherwise reply with our
+    // preferred version (highest entry in SUPPORTED_PROTOCOL_VERSIONS).
+    // The client can then decide to retry, downgrade, or disconnect.
+    const negotiated = isSupportedProtocolVersion(requested)
+      ? requested
+      : SUPPORTED_PROTOCOL_VERSIONS[0];
+
     this.log.info("MCP client initializing", {
       clientInfo: params.clientInfo,
-      protocolVersion: params.protocolVersion,
+      requestedProtocolVersion: requested,
+      negotiatedProtocolVersion: negotiated,
     });
 
     this.initialized = true;
+    this.negotiatedVersion = negotiated;
 
     return {
-      protocolVersion: MCP_PROTOCOL_VERSION,
+      protocolVersion: negotiated,
       capabilities: this.getCapabilities(),
       serverInfo: this.serverInfo,
     };
@@ -276,24 +300,58 @@ export class McpServerProvider {
 
     const tool = this.tools.get(name);
     if (!tool) {
+      // McpToolNotFoundError is intentionally a JSON-RPC protocol error,
+      // not a tool execution error — see SEP-1303 (only validation/runtime
+      // failures of an existing tool are reported via isError: true).
       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 };
+      const callResult: McpToolCallResult = {
+        content: [
+          {
+            type: "text",
+            text:
+              typeof result === "string"
+                ? result
+                : JSON.stringify(result ?? null),
+          },
+        ],
+      };
+
+      // Spec 2025-06-18: when the tool declares an outputSchema, the server
+      // MUST populate `structuredContent` with the validated result. The
+      // text-stringified `content` block remains as a back-compat fallback.
+      if (tool.hasOutputSchema() && result !== undefined) {
+        callResult.structuredContent = result;
+      }
+
+      return callResult;
     } catch (error) {
+      // Spec 2025-11-25 / SEP-1303: input-validation failures (and other
+      // tool-runtime errors) are returned as Tool Execution Errors, not
+      // JSON-RPC protocol errors, so the model can self-correct.
+      // For TypeBox validation errors we surface the failing path so the
+      // model knows which argument was malformed.
+      if (error instanceof TypeBoxError) {
+        const path = error.value?.path || "/";
+        const message = error.value?.message || error.message;
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Validation error at ${path}: ${message}`,
+            },
+          ],
+          structuredContent: {
+            errors: [{ path, message }],
+          },
+          isError: true,
+        };
+      }
+
       return {
         content: [
           {

package/src/mcp/transports/StreamableHttpMcpTransport.ts

@@ -0,0 +1,226 @@
+import { $atom, $inject, $state, t } from "alepha";
+import { $logger } from "alepha/logger";
+import { $route } from "alepha/server";
+import {
+  createErrorResponse,
+  createParseError,
+  JsonRpcParseError,
+  parseMessage,
+} from "../helpers/jsonrpc.ts";
+import type { McpContext } from "../interfaces/McpTypes.ts";
+import { McpServerProvider } from "../providers/McpServerProvider.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export const mcpStreamableHttpOptions = $atom({
+  name: "alepha.mcp.streamableHttp.options",
+  description: "Configuration options for the MCP Streamable HTTP transport.",
+  schema: t.object({
+    /**
+     * Path for the MCP endpoint. Single endpoint for both requests and
+     * (optional) server-streamed responses, per spec 2025-03-26+.
+     */
+    path: t.text({ default: "/mcp" }),
+    /**
+     * Allow-list of `Origin` header values accepted on incoming requests.
+     * Empty array (default) means "allow any". When set, browser-originated
+     * requests with a non-matching `Origin` are rejected with 403 Forbidden,
+     * blocking DNS-rebinding attacks against localhost MCP servers.
+     *
+     * Server-to-server callers (no `Origin` header) are always allowed.
+     *
+     * Spec 2025-11-25, PR #1439.
+     */
+    allowedOrigins: t.array(t.text(), { default: [] }),
+  }),
+  default: {
+    path: "/mcp",
+    allowedOrigins: [],
+  },
+});
+
+// Backward-compat alias for the legacy atom name. Prefer
+// `mcpStreamableHttpOptions` going forward; this re-export keeps existing
+// consumer imports compiling and will be removed once they migrate.
+export const mcpSseOptions = mcpStreamableHttpOptions;
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Streamable HTTP transport for MCP communication.
+ *
+ * Implements the 2025-03-26+ Streamable HTTP transport: a single `/mcp`
+ * endpoint that accepts JSON-RPC over POST and returns either
+ * `application/json` (single response, the default) or
+ * `text/event-stream` (when the server wants to stream multiple messages).
+ *
+ * Designed for serverless deployment (Cloudflare Workers, etc.) — there is
+ * no long-lived GET stream. GET on the endpoint returns 405 Method Not
+ * Allowed; clients that want server-initiated push must rely on the POST
+ * response stream when the server upgrades to SSE for that particular call.
+ *
+ * Spec compliance:
+ * - 2025-06-18: validates `MCP-Protocol-Version` header on every request
+ *   after `initialize` against the version negotiated and stored on
+ *   `McpServerProvider`.
+ * - 2025-11-25: rejects requests with a non-allow-listed `Origin` header
+ *   (PR #1439). See {@link mcpStreamableHttpOptions.allowedOrigins}.
+ *
+ * @example
+ * ```ts
+ * import { Alepha, run } from "alepha";
+ * import { AlephaServer } from "alepha/server";
+ * import { AlephaMcp, StreamableHttpMcpTransport } from "alepha/mcp";
+ *
+ * class MyTools {
+ *   // ... tool definitions
+ * }
+ *
+ * run(
+ *   Alepha.create()
+ *     .with(AlephaServer)
+ *     .with(AlephaMcp)
+ *     .with(StreamableHttpMcpTransport)
+ *     .with(MyTools)
+ * );
+ * ```
+ */
+export class StreamableHttpMcpTransport {
+  protected readonly log = $logger();
+  protected readonly options = $state(mcpStreamableHttpOptions);
+  protected readonly mcpServer = $inject(McpServerProvider);
+
+  /**
+   * GET on the MCP endpoint is not supported in this transport. Returning
+   * 405 (rather than serving the legacy two-endpoint SSE pattern) is the
+   * spec-allowed response for servers that don't offer server-initiated
+   * push outside of an active POST.
+   */
+  notAllowed = $route({
+    method: "GET",
+    path: this.options.path,
+    handler: (request) => {
+      request.reply.status = 405;
+      request.reply.headers.allow = "POST";
+      request.reply.headers["content-type"] = "application/json";
+      request.reply.body = JSON.stringify({
+        error: "Method Not Allowed. Use POST for MCP messages.",
+      });
+    },
+  });
+
+  /**
+   * POST endpoint for client-to-server JSON-RPC messages.
+   * Returns `application/json` for single responses; tools that need to
+   * stream progress would upgrade to `text/event-stream` (deferred until a
+   * concrete need exists).
+   */
+  message = $route({
+    method: "POST",
+    path: this.options.path,
+    schema: {
+      body: t.json(),
+    },
+    handler: async (request) => {
+      try {
+        // Origin allow-list check (spec 2025-11-25 / PR #1439).
+        const originRaw = request.headers.origin;
+        const origin = Array.isArray(originRaw) ? originRaw[0] : originRaw;
+        if (
+          origin &&
+          this.options.allowedOrigins.length > 0 &&
+          !this.options.allowedOrigins.includes(origin)
+        ) {
+          this.log.warn("Rejected MCP request with non-allowed Origin", {
+            origin,
+            allowed: this.options.allowedOrigins,
+          });
+          request.reply.status = 403;
+          request.reply.headers["content-type"] = "application/json";
+          request.reply.body = JSON.stringify({
+            error: "Forbidden: Origin not allowed",
+          });
+          return;
+        }
+
+        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 headers = { ...request.headers } as Record<
+          string,
+          string | string[] | undefined
+        >;
+
+        // Spec 2025-06-18+: every HTTP request after `initialize` MUST carry
+        // an `MCP-Protocol-Version` header matching the negotiated version.
+        // Reject mismatches with 400 so the client doesn't silently drift.
+        if (rpcRequest.method !== "initialize") {
+          const headerRaw = headers["mcp-protocol-version"];
+          const headerVersion = Array.isArray(headerRaw)
+            ? headerRaw[0]
+            : headerRaw;
+          if (
+            headerVersion &&
+            headerVersion !== this.mcpServer.negotiatedVersion
+          ) {
+            this.log.warn("MCP-Protocol-Version header mismatch", {
+              header: headerVersion,
+              negotiated: this.mcpServer.negotiatedVersion,
+            });
+            request.reply.status = 400;
+            request.reply.headers["content-type"] = "application/json";
+            request.reply.body = JSON.stringify({
+              error: `MCP-Protocol-Version mismatch: expected ${this.mcpServer.negotiatedVersion}, got ${headerVersion}`,
+            });
+            return;
+          }
+        }
+
+        const context: McpContext = { headers };
+
+        const response = await this.mcpServer.handleMessage(
+          rpcRequest,
+          context,
+        );
+
+        if (response) {
+          request.reply.headers["content-type"] = "application/json";
+          request.reply.body = JSON.stringify(response);
+        } else {
+          request.reply.status = 204;
+        }
+      } 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,
+          });
+        }
+      }
+    },
+  });
+}
+
+/**
+ * @deprecated Use {@link StreamableHttpMcpTransport}. The 2024-11-05
+ * two-endpoint HTTP+SSE pattern was replaced by Streamable HTTP in spec
+ * 2025-03-26. This alias is preserved for one release to ease migration.
+ */
+export const SseMcpTransport = StreamableHttpMcpTransport;