up

Author: pi0

AGENTS.md

@@ -80,6 +80,7 @@ src/
 │   ├── proxy.ts          # proxy, proxyRequest, fetchWithEvent
 │   ├── ws.ts             # defineWebSocketHandler, defineWebSocket
 │   ├── json-rpc.ts       # defineJsonRpcHandler, defineJsonRpcWebSocketHandler
+│   ├── mcp.ts            # defineMcpHandler, defineMcpTool, defineMcpResource, defineMcpPrompt
 │   ├── event-stream.ts   # createEventStream (SSE)
 │   ├── static.ts         # serveStatic
 │   ├── cache.ts          # handleCacheHeaders
@@ -89,6 +90,7 @@ src/
 │   └── internal/         # Internal helpers (not exported)
 │       ├── auth.ts, body.ts, cors.ts, encoding.ts, ...
 │       ├── iron-crypto.ts    # Session sealing crypto
+│       ├── mcp.ts            # MCP internal handler logic (handleMcpRequest, resolveMcpOptions)
 │       ├── standard-schema.ts # Standard schema validation
 │       └── validate.ts
 ├── _entries/             # Platform-specific entry points
@@ -226,6 +228,30 @@ h3/tracing   → Tracing plugin
 | `srvx`    | Server abstraction (multi-runtime)        |
 | `crossws` | WebSocket abstraction (optional peer dep) |
 
+## MCP (Model Context Protocol)
+
+h3 implements MCP as a built-in utility — no SDK dependency. Wire format is JSON-RPC 2.0 over HTTP. Protocol version: `"2025-06-18"` (also accepts `"2025-03-26"`).
+
+### Architecture
+
+- **Public API** (`src/utils/mcp.ts`): Types + `defineMcpHandler`, `defineMcpTool`, `defineMcpResource`, `defineMcpPrompt`
+- **Internal handler** (`src/utils/internal/mcp.ts`): `handleMcpRequest` processes HTTP → JSON-RPC, `resolveMcpOptions` handles lazy resolution
+- Built on top of `src/utils/json-rpc.ts` (`processJsonRpcBody`, `createMethodMap`)
+
+### Key patterns
+
+- **`MaybeLazy<T>`**: `tools`, `resources`, `prompts` accept `T | (() => T | Promise<T>)`. Lazy values are resolved once and cached via `_resolveLazy()`. For static handler options, caching persists across requests. For dynamic `(event) => options`, each request gets fresh resolution.
+- **`McpResolvedOptions`**: Internal type with pre-bound lazy resolvers. Created by `resolveMcpOptions()` and passed to `handleMcpRequest()`.
+- `defineMcpHandler` supports both static options and `(event: H3Event) => McpHandlerOptions` for per-request config.
+
+### MCP methods implemented
+
+`initialize`, `ping`, `notifications/initialized`, `tools/list`, `tools/call`, `resources/list`, `resources/read`, `prompts/list`, `prompts/get`
+
+### Tests
+
+`test/mcp.test.ts` — unit tests for define helpers + integration tests via `describeMatrix` (web + node).
+
 ## Best Practices for Contributing
 
 - Prefer web standard APIs over runtime-specific ones

src/index.ts

@@ -236,6 +236,7 @@ export {
   type McpPromptCallback,
   type McpPromptArgument,
   type McpPromptDefinition,
+  type MaybeLazy,
   type McpHandlerOptions,
   defineMcpHandler,
   defineMcpTool,

src/utils/internal/mcp.ts

@@ -1,13 +1,37 @@
 import type { H3Event } from "../../event.ts";
 import type { JsonRpcMethod, JsonRpcRequest } from "../json-rpc.ts";
-import type { McpHandlerOptions } from "../mcp.ts";
+import type { MaybeLazy, McpHandlerOptions } from "../mcp.ts";
+import type { McpToolDefinition, McpResourceDefinition, McpPromptDefinition } from "../mcp.ts";
 import { processJsonRpcBody, createJsonRpcError, createMethodMap } from "../json-rpc.ts";
 import { HTTPError } from "../../error.ts";
 
-const MCP_PROTOCOL_VERSION = "2025-03-26";
+const MCP_PROTOCOL_VERSION = "2025-06-18";
+const SUPPORTED_PROTOCOL_VERSIONS = new Set(["2025-06-18", "2025-03-26"]);
+
+export interface McpResolvedOptions {
+  name: string;
+  version: string;
+  title?: string;
+  instructions?: string;
+  tools: () => Promise<McpToolDefinition<any>[] | undefined>;
+  resources: () => Promise<McpResourceDefinition[] | undefined>;
+  prompts: () => Promise<McpPromptDefinition[] | undefined>;
+}
+
+export function resolveMcpOptions(options: McpHandlerOptions): McpResolvedOptions {
+  return {
+    name: options.name,
+    version: options.version,
+    title: options.title,
+    instructions: options.instructions,
+    tools: _resolveLazyArray(options.tools),
+    resources: _resolveLazyArray(options.resources),
+    prompts: _resolveLazyArray(options.prompts),
+  };
+}
 
 export async function handleMcpRequest(
-  options: McpHandlerOptions,
+  options: McpResolvedOptions,
   event: H3Event,
 ): Promise<Response> {
   const method = event.req.method;
@@ -23,6 +47,13 @@ export async function handleMcpRequest(
     });
   }
 
+  const protocolVersion = event.req.headers.get("mcp-protocol-version");
+  if (protocolVersion && !SUPPORTED_PROTOCOL_VERSIONS.has(protocolVersion)) {
+    return new Response(`Unsupported MCP protocol version: ${protocolVersion}`, {
+      status: 400,
+    });
+  }
+
   const methods = buildMcpMethodMap(options);
   const methodMap = createMethodMap(methods);
 
@@ -50,26 +81,57 @@ export async function handleMcpRequest(
 
 // --- Internal helpers ---
 
-function buildMcpMethodMap(options: McpHandlerOptions): Record<string, JsonRpcMethod> {
+function _resolveLazyArray<T>(items: MaybeLazy<T>[] | undefined): () => Promise<T[] | undefined> {
+  if (!items?.length) {
+    return () => Promise.resolve(undefined);
+  }
+  let cached: Promise<T[]> | undefined;
+  return () => {
+    if (!cached) {
+      cached = Promise.all(
+        items.map((item) => (typeof item === "function" ? (item as () => T | Promise<T>)() : item)),
+      );
+    }
+    return cached;
+  };
+}
+
+function buildMcpMethodMap(options: McpResolvedOptions): Record<string, JsonRpcMethod> {
   const methods: Record<string, JsonRpcMethod> = {};
 
   // initialize
-  methods["initialize"] = () => {
+  methods["initialize"] = async () => {
     const capabilities: Record<string, unknown> = {};
-    if (options.tools?.length) {
+    const [tools, resources, prompts] = await Promise.all([
+      options.tools(),
+      options.resources(),
+      options.prompts(),
+    ]);
+    if (tools?.length) {
       capabilities.tools = {};
     }
-    if (options.resources?.length) {
+    if (resources?.length) {
       capabilities.resources = {};
     }
-    if (options.prompts?.length) {
+    if (prompts?.length) {
       capabilities.prompts = {};
     }
-    return {
+    const serverInfo: Record<string, string> = {
+      name: options.name,
+      version: options.version,
+    };
+    if (options.title !== undefined) {
+      serverInfo.title = options.title;
+    }
+    const result: Record<string, unknown> = {
       protocolVersion: MCP_PROTOCOL_VERSION,
-      serverInfo: { name: options.name, version: options.version },
+      serverInfo,
       capabilities,
     };
+    if (options.instructions !== undefined) {
+      result.instructions = options.instructions;
+    }
+    return result;
   };
 
   // ping
@@ -79,79 +141,80 @@ function buildMcpMethodMap(options: McpHandlerOptions): Record<string, JsonRpcMe
   methods["notifications/initialized"] = () => undefined;
 
   // tools
-  if (options.tools?.length) {
-    const tools = options.tools;
-
-    methods["tools/list"] = () => ({
-      tools: tools.map((tool) => {
+  methods["tools/list"] = async () => {
+    const tools = await options.tools();
+    return {
+      tools: (tools ?? []).map((tool) => {
         const entry: Record<string, unknown> = {
           name: tool.name,
           inputSchema: tool.inputSchema ?? { type: "object" },
         };
         if (tool.title !== undefined) entry.title = tool.title;
         if (tool.description !== undefined) entry.description = tool.description;
+        if (tool.outputSchema !== undefined) entry.outputSchema = tool.outputSchema;
         if (tool.annotations !== undefined) entry.annotations = tool.annotations;
         return entry;
       }),
-    });
-
-    methods["tools/call"] = async (req: JsonRpcRequest, event: H3Event) => {
-      const params = req.params as Record<string, unknown> | undefined;
-      const name = params?.name as string;
-      const args = (params?.arguments ?? {}) as Record<string, unknown>;
-
-      const tool = tools.find((t) => t.name === name);
-      if (!tool) {
-        throw new HTTPError({ status: 404, message: `Tool not found: ${name}` });
-      }
-
-      if (tool.inputSchema) {
-        return await (tool.handler as (args: Record<string, unknown>, event: H3Event) => unknown)(
-          args,
-          event,
-        );
-      }
-      return await (tool.handler as (event: H3Event) => unknown)(event);
     };
-  }
+  };
 
-  // resources
-  if (options.resources?.length) {
-    const resources = options.resources;
+  methods["tools/call"] = async (req: JsonRpcRequest, event: H3Event) => {
+    const tools = await options.tools();
+    const params = req.params as Record<string, unknown> | undefined;
+    const name = params?.name as string;
+    const args = (params?.arguments ?? {}) as Record<string, unknown>;
+
+    const tool = tools?.find((t) => t.name === name);
+    if (!tool) {
+      throw new HTTPError({ status: 404, message: `Tool not found: ${name}` });
+    }
 
-    methods["resources/list"] = () => ({
-      resources: resources.map((r) => {
+    if (tool.inputSchema) {
+      return await (tool.handler as (args: Record<string, unknown>, event: H3Event) => unknown)(
+        args,
+        event,
+      );
+    }
+    return await (tool.handler as (event: H3Event) => unknown)(event);
+  };
+
+  // resources
+  methods["resources/list"] = async () => {
+    const resources = await options.resources();
+    return {
+      resources: (resources ?? []).map((r) => {
         const entry: Record<string, unknown> = {
           name: r.name,
           uri: r.uri,
         };
         if (r.title !== undefined) entry.title = r.title;
         if (r.description !== undefined) entry.description = r.description;
         if (r.mimeType !== undefined) entry.mimeType = r.mimeType;
+        if (r.size !== undefined) entry.size = r.size;
         return entry;
       }),
-    });
+    };
+  };
 
-    methods["resources/read"] = async (req: JsonRpcRequest, event: H3Event) => {
-      const params = req.params as Record<string, unknown> | undefined;
-      const uriStr = params?.uri as string;
-      const uri = new URL(uriStr);
+  methods["resources/read"] = async (req: JsonRpcRequest, event: H3Event) => {
+    const resources = await options.resources();
+    const params = req.params as Record<string, unknown> | undefined;
+    const uriStr = params?.uri as string;
+    const uri = new URL(uriStr);
 
-      const resource = resources.find((r) => r.uri === uri.toString());
-      if (!resource) {
-        throw new HTTPError({ status: 404, message: `Resource not found: ${uriStr}` });
-      }
+    const resource = resources?.find((r) => r.uri === uri.toString());
+    if (!resource) {
+      throw new HTTPError({ status: 404, message: `Resource not found: ${uriStr}` });
+    }
 
-      return await resource.handler(uri, event);
-    };
-  }
+    return await resource.handler(uri, event);
+  };
 
   // prompts
-  if (options.prompts?.length) {
-    const prompts = options.prompts;
-
-    methods["prompts/list"] = () => ({
-      prompts: prompts.map((p) => {
+  methods["prompts/list"] = async () => {
+    const prompts = await options.prompts();
+    return {
+      prompts: (prompts ?? []).map((p) => {
         const entry: Record<string, unknown> = {
           name: p.name,
         };
@@ -160,27 +223,28 @@ function buildMcpMethodMap(options: McpHandlerOptions): Record<string, JsonRpcMe
         if (p.args?.length) entry.arguments = p.args;
         return entry;
       }),
-    });
-
-    methods["prompts/get"] = async (req: JsonRpcRequest, event: H3Event) => {
-      const params = req.params as Record<string, unknown> | undefined;
-      const name = params?.name as string;
-      const args = (params?.arguments ?? {}) as Record<string, string>;
-
-      const prompt = prompts.find((p) => p.name === name);
-      if (!prompt) {
-        throw new HTTPError({ status: 404, message: `Prompt not found: ${name}` });
-      }
-
-      if (prompt.args?.length) {
-        return await (prompt.handler as (args: Record<string, string>, event: H3Event) => unknown)(
-          args,
-          event,
-        );
-      }
-      return await (prompt.handler as (event: H3Event) => unknown)(event);
     };
-  }
+  };
+
+  methods["prompts/get"] = async (req: JsonRpcRequest, event: H3Event) => {
+    const prompts = await options.prompts();
+    const params = req.params as Record<string, unknown> | undefined;
+    const name = params?.name as string;
+    const args = (params?.arguments ?? {}) as Record<string, string>;
+
+    const prompt = prompts?.find((p) => p.name === name);
+    if (!prompt) {
+      throw new HTTPError({ status: 404, message: `Prompt not found: ${name}` });
+    }
+
+    if (prompt.args?.length) {
+      return await (prompt.handler as (args: Record<string, string>, event: H3Event) => unknown)(
+        args,
+        event,
+      );
+    }
+    return await (prompt.handler as (event: H3Event) => unknown)(event);
+  };
 
   return methods;
 }