alepha 0.20.2 → 0.20.4

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

@@ -25,7 +25,7 @@ describe("jsonrpc constants", () => {
   });
 
   test("MCP_PROTOCOL_VERSION should be defined", () => {
-    expect(MCP_PROTOCOL_VERSION).toBe("2024-11-05");
+    expect(MCP_PROTOCOL_VERSION).toBe("2025-11-25");
   });
 
   test("JsonRpcErrorCodes should have correct values", () => {

package/src/mcp/helpers/jsonrpc.ts

@@ -12,7 +12,32 @@ import type {
 
 export const JSONRPC_VERSION = "2.0" as const;
 
-export const MCP_PROTOCOL_VERSION = "2024-11-05" as const;
+/**
+ * The latest MCP protocol revision Alepha targets.
+ * See {@link SUPPORTED_PROTOCOL_VERSIONS} for the full negotiation list.
+ */
+export const MCP_PROTOCOL_VERSION = "2025-11-25" as const;
+
+/**
+ * Protocol versions Alepha will accept during `initialize` negotiation,
+ * highest preference first. The server echoes back whichever version the
+ * client requested if it appears here, otherwise picks the first entry.
+ */
+export const SUPPORTED_PROTOCOL_VERSIONS = [
+  "2025-11-25",
+  "2025-06-18",
+  "2025-03-26",
+  "2024-11-05",
+] as const;
+
+export type SupportedProtocolVersion =
+  (typeof SUPPORTED_PROTOCOL_VERSIONS)[number];
+
+export const isSupportedProtocolVersion = (
+  v: unknown,
+): v is SupportedProtocolVersion =>
+  typeof v === "string" &&
+  (SUPPORTED_PROTOCOL_VERSIONS as readonly string[]).includes(v);
 
 export const JsonRpcErrorCodes = {
   PARSE_ERROR: -32700,

package/src/mcp/index.ts

@@ -3,7 +3,7 @@ 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 { StreamableHttpMcpTransport } from "./transports/StreamableHttpMcpTransport.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
@@ -28,12 +28,15 @@ export {
   createParseError,
   createResponse,
   isNotification,
+  isSupportedProtocolVersion,
   isValidJsonRpcRequest,
   JSONRPC_VERSION,
   JsonRpcErrorCodes,
   JsonRpcParseError,
   MCP_PROTOCOL_VERSION,
   parseMessage,
+  SUPPORTED_PROTOCOL_VERSIONS,
+  type SupportedProtocolVersion,
 } from "./helpers/jsonrpc.ts";
 export type {
   JsonRpcError,
@@ -88,8 +91,10 @@ export { $tool, ToolPrimitive } from "./primitives/$tool.ts";
 export { McpServerProvider } from "./providers/McpServerProvider.ts";
 export {
   mcpSseOptions,
+  mcpStreamableHttpOptions,
   SseMcpTransport,
-} from "./transports/SseMcpTransport.ts";
+  StreamableHttpMcpTransport,
+} from "./transports/StreamableHttpMcpTransport.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
@@ -101,7 +106,7 @@ export {
  * - MCP tool definitions
  * - MCP prompt definitions
  * - JSON-RPC protocol
- * - SSE and Stdio transports
+ * - Streamable HTTP transport (spec 2025-03-26+)
  *
  * @module alepha.mcp
  */
@@ -109,6 +114,6 @@ export const AlephaMcp = $module({
   name: "alepha.mcp",
   primitives: [$tool, $resource, $prompt],
   services: [McpServerProvider],
-  // Transports are opt-in — user wires the one(s) they need via alepha.with(SseMcpTransport).
-  variants: [SseMcpTransport],
+  // Transports are opt-in — user wires the one(s) they need via alepha.with(StreamableHttpMcpTransport).
+  variants: [StreamableHttpMcpTransport],
 });

package/src/mcp/interfaces/McpTypes.ts

@@ -40,14 +40,48 @@ export interface McpCapabilities {
   prompts?: Record<string, never>;
 }
 
+/**
+ * Spec 2025-11-25: optional `description` aligns with the MCP registry's
+ * `server.json` format and provides human-readable context during init.
+ */
 export interface McpServerInfo {
   name: string;
   version: string;
+  description?: string;
 }
 
 export interface McpClientInfo {
   name: string;
   version: string;
+  description?: string;
+}
+
+/**
+ * Icon descriptor (spec 2025-11-25 / SEP-973). Mirrors web app manifest
+ * icon shape — clients render these in tool palettes / picker UIs.
+ */
+export interface McpIcon {
+  src: string;
+  mimeType?: string;
+  sizes?: string;
+}
+
+/**
+ * Tool annotations (spec 2025-03-26+). Hints to the client about how to
+ * present and gate the tool. None are guarantees — the client uses these
+ * heuristically (e.g. to show a confirmation prompt for destructive tools).
+ */
+export interface McpToolAnnotations {
+  /** Human-friendly display title (distinct from `name`, the programmatic id). */
+  title?: string;
+  /** Tool reads only; safe to auto-approve. */
+  readOnlyHint?: boolean;
+  /** Tool may delete or overwrite data; client should require confirmation. */
+  destructiveHint?: boolean;
+  /** Calling the tool with the same args twice yields the same end state. */
+  idempotentHint?: boolean;
+  /** Tool interacts with the open world (network, etc.) vs. a closed system. */
+  openWorldHint?: boolean;
 }
 
 export interface McpInitializeParams {
@@ -68,14 +102,27 @@ export interface McpInitializeResult {
 
 export interface McpToolDescriptor {
   name: string;
+  /** Human-friendly display label (spec 2025-11-25). Distinct from `name`. */
+  title?: string;
   description: string;
   inputSchema: McpJsonSchema;
+  /** Output schema enabling `structuredContent` on call results (spec 2025-06-18). */
+  outputSchema?: McpJsonSchema;
+  /** Behavior hints (spec 2025-03-26+). */
+  annotations?: McpToolAnnotations;
+  /** Optional icons (spec 2025-11-25 / SEP-973). */
+  icons?: McpIcon[];
+  /** Arbitrary metadata passthrough (spec 2025-06-18+). */
+  _meta?: Record<string, unknown>;
 }
 
 export interface McpJsonSchema {
   type: string;
   properties?: Record<string, unknown>;
   required?: string[];
+  /** JSON Schema dialect (spec 2025-11-25 / SEP-1613 — defaults to 2020-12). */
+  $schema?: string;
+  [key: string]: unknown;
 }
 
 export interface McpToolCallParams {
@@ -85,15 +132,33 @@ export interface McpToolCallParams {
 
 export interface McpToolCallResult {
   content: McpContent[];
+  /**
+   * Structured tool output (spec 2025-06-18). When the tool declares an
+   * `outputSchema`, the server MUST populate `structuredContent`; the
+   * `content` array carrying a JSON-stringified text block is kept as
+   * a back-compat fallback for older clients.
+   */
+  structuredContent?: unknown;
   isError?: boolean;
+  _meta?: Record<string, unknown>;
 }
 
-export interface McpContent {
-  type: "text" | "image" | "resource";
-  text?: string;
-  data?: string;
-  mimeType?: string;
-}
+/**
+ * Discriminated content union covering text, image, audio (added 2025-03-26),
+ * inlined resources, and resource links (added 2025-06-18).
+ */
+export type McpContent =
+  | { type: "text"; text: string }
+  | { type: "image"; data: string; mimeType: string }
+  | { type: "audio"; data: string; mimeType: string }
+  | { type: "resource"; resource: McpResourceContent }
+  | {
+      type: "resource_link";
+      uri: string;
+      name: string;
+      description?: string;
+      mimeType?: string;
+    };
 
 // ---------------------------------------------------------------------------------------------------------------------
 // Resource Types
@@ -102,8 +167,14 @@ export interface McpContent {
 export interface McpResourceDescriptor {
   uri: string;
   name: string;
+  /** Human-friendly display label (spec 2025-11-25). Distinct from `name`. */
+  title?: string;
   description?: string;
   mimeType?: string;
+  /** Optional icons (spec 2025-11-25 / SEP-973). */
+  icons?: McpIcon[];
+  /** Arbitrary metadata passthrough (spec 2025-06-18+). */
+  _meta?: Record<string, unknown>;
 }
 
 export interface McpResourceReadParams {
@@ -127,8 +198,14 @@ export interface McpResourceContent {
 
 export interface McpPromptDescriptor {
   name: string;
+  /** Human-friendly display label (spec 2025-11-25). Distinct from `name`. */
+  title?: string;
   description?: string;
   arguments?: McpPromptArgument[];
+  /** Optional icons (spec 2025-11-25 / SEP-973). */
+  icons?: McpIcon[];
+  /** Arbitrary metadata passthrough (spec 2025-06-18+). */
+  _meta?: Record<string, unknown>;
 }
 
 export interface McpPromptArgument {

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

@@ -10,6 +10,7 @@ import {
 } from "alepha";
 import type {
   McpContext,
+  McpIcon,
   McpPromptArgument,
   McpPromptDescriptor,
   PromptHandlerArgs,
@@ -80,6 +81,12 @@ export interface PromptPrimitiveOptions<T extends TObject> {
    */
   name?: string;
 
+  /**
+   * Human-friendly display title (spec 2025-11-25). Distinct from `name`,
+   * which remains the programmatic identifier.
+   */
+  title?: string;
+
   /**
    * Description of what this prompt does.
    *
@@ -89,6 +96,11 @@ export interface PromptPrimitiveOptions<T extends TObject> {
    */
   description?: string;
 
+  /**
+   * Optional icons surfaced in client UIs (spec 2025-11-25 / SEP-973).
+   */
+  icons?: McpIcon[];
+
   /**
    * TypeBox schema defining the prompt arguments.
    *
@@ -157,13 +169,18 @@ export class PromptPrimitive<T extends TObject> extends Primitive<
    * Convert the prompt to an MCP prompt descriptor for protocol messages.
    */
   public toDescriptor(): McpPromptDescriptor {
-    return {
+    const descriptor: McpPromptDescriptor = {
       name: this.name,
       description: this.description,
       arguments: this.options.args
         ? this.schemaToArguments(this.options.args)
         : [],
     };
+    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/$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: [
           {