@emseepea/server 0.6.1 → 0.8.1

package/dist/index.js

@@ -1,7 +1,7 @@
 import { createMcpFastifyApp } from "@modelcontextprotocol/fastify";
 import { GetPromptResultSchema, ReadResourceResultSchema, } from "@modelcontextprotocol/core";
 import { toNodeHandler } from "@modelcontextprotocol/node";
-import { McpServer, OAuthError, OAuthErrorCode, ProtocolError, ProtocolErrorCode, ResourceTemplate, bearerAuthChallengeResponse, buildOAuthProtectedResourceMetadata, checkResourceAllowed, completable, createMcpHandler, getOAuthProtectedResourceMetadataUrl, inputRequired as sdkInputRequired, acceptedContent as sdkAcceptedContent, inputResponse as sdkInputResponse, isInputRequiredResult, oauthMetadataResponse, specTypeSchemas, verifyBearerToken, } from "@modelcontextprotocol/server";
+import { McpServer, InMemoryServerEventBus, OAuthError, OAuthErrorCode, ProtocolError, ProtocolErrorCode, ResourceTemplate, bearerAuthChallengeResponse, buildOAuthProtectedResourceMetadata, checkResourceAllowed, classifyInboundRequest, completable, createMcpHandler, createRequestStateCodec, getOAuthProtectedResourceMetadataUrl, inputRequired as sdkInputRequired, acceptedContent as sdkAcceptedContent, inputResponse as sdkInputResponse, isInputRequiredResult, oauthMetadataResponse, specTypeSchemas, verifyBearerToken, } from "@modelcontextprotocol/server";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { createHash } from "node:crypto";
 import { readdir, realpath } from "node:fs/promises";
@@ -12,7 +12,7 @@ import { z } from "zod";
 import { installObservability, } from "./telemetry.js";
 export { openTelemetry, structuredLogging, } from "./telemetry.js";
 export * from "./ui.js";
-export const inputRequired = Object.assign((spec) => sdkInputRequired({ inputRequests: spec.inputRequests }), {
+export const inputRequired = Object.assign((spec) => sdkInputRequired(spec), {
     elicit: sdkInputRequired.elicit,
     elicitUrl: sdkInputRequired.elicitUrl,
 });
@@ -24,6 +24,14 @@ export function inputResponse(responses, key) {
     return response.kind === "elicit" ? response : { kind: "missing" };
 }
 const PROTOCOL_VERSION = "2026-07-28";
+const LEGACY_PROTOCOL_VERSIONS = Object.freeze([
+    "2025-11-25",
+    "2025-06-18",
+    "2025-03-26",
+    "2024-11-05",
+    "2024-10-07",
+]);
+const SUPPORTED_PROTOCOLS = Object.freeze([PROTOCOL_VERSION, ...LEGACY_PROTOCOL_VERSIONS]);
 const REGISTER = Symbol("register");
 const DISCOVERABLE = Symbol("discoverable");
 const TOOL_NAME = Symbol("toolName");
@@ -51,6 +59,45 @@ const CACHEABLE_METHODS = [
 ];
 const runtimes = new WeakMap();
 const requestOperations = new AsyncLocalStorage();
+function createRequestStateRuntime(options) {
+    if (typeof options.key !== "string" && !(options.key instanceof Uint8Array)) {
+        throw new TypeError("requestState.key must be a string or Uint8Array");
+    }
+    const ttlSeconds = positiveInteger("requestState.ttlSeconds", options.ttlSeconds);
+    const maxBytes = positiveInteger("requestState.maxBytes", options.maxBytes ?? 4 * 1024);
+    const codec = createRequestStateCodec({
+        key: typeof options.key === "string" ? options.key : Uint8Array.from(options.key),
+        ttlSeconds,
+        bind(context) {
+            const operation = requestOperations.getStore();
+            if (!operation?.capability)
+                throw new Error("request state has no capability binding");
+            const principal = operation.principal;
+            return JSON.stringify([
+                context.mcpReq.method,
+                operation.capability,
+                principal
+                    ? [principal.clientId, [...principal.permissions].sort(), principal.resource ?? null]
+                    : null,
+            ]);
+        },
+    });
+    const assertWireSize = (state) => {
+        if (Buffer.byteLength(state, "utf8") > maxBytes)
+            throw new Error("request state is oversized");
+    };
+    return Object.freeze({
+        async mint(payload, context) {
+            const state = await codec.mint(payload, context);
+            assertWireSize(state);
+            return state;
+        },
+        async verify(state, context) {
+            assertWireSize(state);
+            return codec.verify(state, context);
+        },
+    });
+}
 export function defineTool(definition) {
     const handler = definition.handler;
     return createCheckedTool(definition, handler, false, true);
@@ -126,21 +173,16 @@ export function defineResource(definition) {
             value: listing,
         }),
         [HAS_COMPLETION]: false,
-        [REGISTER](server, timeoutMs, maxApplicationResultBytes) {
+        [REGISTER](server, timeoutMs, maxApplicationResultBytes, requestState) {
             server.registerResource(name, uri, cacheHint ? { ...metadata, cacheHint } : metadata, async (_requestedUri, context) => {
                 try {
                     const deadlineMs = requestOperations.getStore()?.deadlineMs ?? Date.now() + timeoutMs;
                     return await runWithDeadline(context.mcpReq.signal, deadlineMs, async (signal) => {
                         signal.throwIfAborted();
-                        const result = await handler({
-                            signal,
-                            deadlineMs,
-                            principal: access === "public" ? undefined : principalFrom(context.http?.authInfo),
-                            inputResponses: checkedInputResponses(context.mcpReq.inputResponses),
-                        });
+                        const result = await handler(directHandlerContext(access, context, signal, deadlineMs, requestState));
                         signal.throwIfAborted();
                         if (isInputRequiredResult(result)) {
-                            assertStatelessInputRequired(result);
+                            await assertInputRequired(result, requestState, context);
                             assertResultSize(result, maxApplicationResultBytes, deadlineMs, signal);
                             return result;
                         }
@@ -203,7 +245,7 @@ export function defineResourceTemplate(definition) {
             value: listing,
         }),
         [HAS_COMPLETION]: completions.size > 0,
-        [REGISTER](server, timeoutMs, maxApplicationResultBytes) {
+        [REGISTER](server, timeoutMs, maxApplicationResultBytes, requestState) {
             const registeredTemplate = completions.size === 0
                 ? template
                 : new ResourceTemplate(uriTemplate, {
@@ -218,15 +260,10 @@ export function defineResourceTemplate(definition) {
                     const deadlineMs = requestOperations.getStore()?.deadlineMs ?? Date.now() + timeoutMs;
                     return await runWithDeadline(context.mcpReq.signal, deadlineMs, async (signal) => {
                         signal.throwIfAborted();
-                        const result = await handler({ uri: requestedUri.href, variables }, {
-                            signal,
-                            deadlineMs,
-                            principal: access === "public" ? undefined : principalFrom(context.http?.authInfo),
-                            inputResponses: checkedInputResponses(context.mcpReq.inputResponses),
-                        });
+                        const result = await handler({ uri: requestedUri.href, variables }, directHandlerContext(access, context, signal, deadlineMs, requestState));
                         signal.throwIfAborted();
                         if (isInputRequiredResult(result)) {
-                            assertStatelessInputRequired(result);
+                            await assertInputRequired(result, requestState, context);
                             assertResultSize(result, maxApplicationResultBytes, deadlineMs, signal);
                             return result;
                         }
@@ -274,7 +311,7 @@ export function definePrompt(definition) {
         [PROMPT_ACCESS]: access,
         [HAS_COMPLETION]: completions.size > 0,
         [PROMPT_LISTING]: listing,
-        [REGISTER](server, timeoutMs, maxApplicationResultBytes) {
+        [REGISTER](server, timeoutMs, maxApplicationResultBytes, requestState) {
             server.registerPrompt(name, {
                 ...metadata,
                 argsSchema: sdkPromptMetadataSchema(argsSchema, completions, argumentNames, timeoutMs, maxApplicationResultBytes),
@@ -286,15 +323,10 @@ export function definePrompt(definition) {
                         if (!parsedArgs.success)
                             throw new Error("Prompt received invalid arguments");
                         signal.throwIfAborted();
-                        const result = await handler(parsedArgs.data, {
-                            signal,
-                            deadlineMs,
-                            principal: access === "public" ? undefined : principalFrom(context.http?.authInfo),
-                            inputResponses: checkedInputResponses(context.mcpReq.inputResponses),
-                        });
+                        const result = await handler(parsedArgs.data, directHandlerContext(access, context, signal, deadlineMs, requestState));
                         signal.throwIfAborted();
                         if (isInputRequiredResult(result)) {
-                            assertStatelessInputRequired(result);
+                            await assertInputRequired(result, requestState, context);
                             assertResultSize(result, maxApplicationResultBytes, deadlineMs, signal);
                             return result;
                         }
@@ -464,7 +496,7 @@ function createCheckedTool(definition, execute, streaming, allowsInputRequired)
         [TOOL_ACCESS]: access,
         [TOOL_STREAMING]: streaming,
         [TOOL_LISTING]: listing,
-        [REGISTER](server, timeoutMs, maxApplicationResultBytes, maxProgressEvents, maxProgressEventBytes) {
+        [REGISTER](server, timeoutMs, maxApplicationResultBytes, maxProgressEvents, maxProgressEventBytes, requestState) {
             server.registerTool(name, metadata, async (input, context) => {
                 try {
                     const deadlineMs = requestOperations.getStore()?.deadlineMs ?? Date.now() + timeoutMs;
@@ -480,14 +512,15 @@ function createCheckedTool(definition, execute, streaming, allowsInputRequired)
                         let result;
                         try {
                             result = await execute(parsedInput.data, {
-                                signal,
-                                deadlineMs,
-                                principal: access === "public" ? undefined : principalFrom(context.http?.authInfo),
                                 ...(allowsInputRequired
-                                    ? {
-                                        inputResponses: checkedInputResponses(context.mcpReq.inputResponses),
-                                    }
-                                    : {}),
+                                    ? directHandlerContext(access, context, signal, deadlineMs, requestState)
+                                    : {
+                                        signal,
+                                        deadlineMs,
+                                        principal: access === "public"
+                                            ? undefined
+                                            : principalFrom(context.http?.authInfo),
+                                    }),
                                 ...(reporter ? { reportProgress: reporter.report } : {}),
                             });
                         }
@@ -497,7 +530,7 @@ function createCheckedTool(definition, execute, streaming, allowsInputRequired)
                         reporter?.throwIfFailed();
                         if (allowsInputRequired && isInputRequiredResult(result)) {
                             signal.throwIfAborted();
-                            assertStatelessInputRequired(result);
+                            await assertInputRequired(result, requestState, context);
                             assertResultSize(result, maxApplicationResultBytes, deadlineMs, signal);
                             return result;
                         }
@@ -745,10 +778,20 @@ export function createEmseepea(options) {
         ? normalizeListPagination(options.listPagination)
         : undefined;
     const maxRequestBytes = positiveInteger("maxRequestBytes", options.maxRequestBytes ?? 1024 * 1024);
+    const requestState = options.requestState
+        ? createRequestStateRuntime(options.requestState)
+        : undefined;
     const maxApplicationResultBytes = positiveInteger("maxApplicationResultBytes", options.maxApplicationResultBytes ?? 1024 * 1024);
     const maxProgressEvents = positiveInteger("maxProgressEvents", options.maxProgressEvents ?? 32);
     const maxProgressEventBytes = positiveInteger("maxProgressEventBytes", options.maxProgressEventBytes ?? 8 * 1024);
     const operationTimeoutMs = positiveInteger("operationTimeoutMs", options.operationTimeoutMs ?? 30_000);
+    const resourceSubscriptions = options.resourceSubscriptions && Object.freeze({
+        maxActive: positiveInteger("resourceSubscriptions.maxActive", options.resourceSubscriptions.maxActive ?? 16),
+        maxEvents: positiveInteger("resourceSubscriptions.maxEvents", options.resourceSubscriptions.maxEvents ?? 256),
+        maxEventBytes: positiveInteger("resourceSubscriptions.maxEventBytes", options.resourceSubscriptions.maxEventBytes ?? 8 * 1024),
+        maxUriBytes: positiveInteger("resourceSubscriptions.maxUriBytes", options.resourceSubscriptions.maxUriBytes ?? 512),
+        lifetimeMs: positiveInteger("resourceSubscriptions.lifetimeMs", options.resourceSubscriptions.lifetimeMs ?? 30_000),
+    });
     const deployment = normalizeDeployment(options.deployment ?? { mode: "loopback" });
     const authentication = options.authentication
         ? normalizeAuthentication(options.authentication)
@@ -775,6 +818,8 @@ export function createEmseepea(options) {
     if (resources.some((resource) => resource[RESOURCE_KIND] === "template")) {
         enabledMethods.add("resources/templates/list");
     }
+    if (resourceSubscriptions && resources.length)
+        enabledMethods.add("subscriptions/listen");
     if (prompts.length)
         enabledMethods.add("prompts/list").add("prompts/get");
     const hasCompletion = resources.some((resource) => resource[HAS_COMPLETION]) ||
@@ -792,6 +837,8 @@ export function createEmseepea(options) {
         : hasSuppressedCapabilities
             ? compileUnpaginatedCatalogue(baseCatalogues)
             : undefined;
+    const resourceEvents = resourceSubscriptions ? new InMemoryServerEventBus() : undefined;
+    const activeSubscriptions = new Set();
     const sdkHandler = createMcpHandler(() => {
         const request = requestOperations.getStore();
         const activeTools = request?.filterCatalogues
@@ -817,21 +864,29 @@ export function createEmseepea(options) {
         const server = new McpServer(serverInfo, {
             capabilities: {
                 ...(activeTools.length ? { tools: { listChanged: false } } : {}),
-                ...(activeResources.length ? { resources: { subscribe: false, listChanged: false } } : {}),
+                ...(activeResources.length ? {
+                    resources: {
+                        subscribe: Boolean(resourceSubscriptions) && !request?.legacy,
+                        listChanged: false,
+                    },
+                } : {}),
                 ...(activePrompts.length ? { prompts: { listChanged: false } } : {}),
                 ...(activeHasCompletion ? { completions: {} } : {}),
             },
             instructions: options.instructions,
-            cacheHints: request?.filterCatalogues ? undefined : cacheHints,
-            supportedProtocolVersions: [PROTOCOL_VERSION],
+            cacheHints: request?.filterCatalogues || request?.legacy ? undefined : cacheHints,
+            supportedProtocolVersions: [...SUPPORTED_PROTOCOLS],
+            ...(requestState && !request?.legacy ? { requestState: { verify: requestState.verify } } : {}),
         });
         for (const tool of activeTools) {
-            tool[REGISTER](server, operationTimeoutMs, maxApplicationResultBytes, maxProgressEvents, maxProgressEventBytes);
+            tool[REGISTER](server, operationTimeoutMs, maxApplicationResultBytes, maxProgressEvents, maxProgressEventBytes, requestState);
+        }
+        for (const resource of activeResources) {
+            resource[REGISTER](server, operationTimeoutMs, maxApplicationResultBytes, requestState);
+        }
+        for (const prompt of activePrompts) {
+            prompt[REGISTER](server, operationTimeoutMs, maxApplicationResultBytes, requestState);
         }
-        for (const resource of activeResources)
-            resource[REGISTER](server, operationTimeoutMs, maxApplicationResultBytes);
-        for (const prompt of activePrompts)
-            prompt[REGISTER](server, operationTimeoutMs, maxApplicationResultBytes);
         const filteredCatalogues = request?.filterCatalogues
             ? catalogueListings(activeDiscoverableTools, activeDiscoverableResources, activeDiscoverablePrompts, activeTools, activeResources, activePrompts)
             : undefined;
@@ -848,12 +903,85 @@ export function createEmseepea(options) {
             installListPagination(server, pagination);
         return server;
     }, {
-        legacy: "reject",
-        responseMode: hasStreaming ? "auto" : "json",
+        responseMode: hasStreaming || resourceSubscriptions ? "auto" : "json",
         keepAliveMs: 0,
     });
     const nodeHandler = toNodeHandler(sdkHandler);
     const app = createMcpFastifyApp({ host: deployment.mode === "loopback" ? "127.0.0.1" : "0.0.0.0" });
+    async function serveResourceSubscription(request, reply, uri) {
+        if (!resourceSubscriptions || !resourceEvents)
+            return;
+        if (activeSubscriptions.size >= resourceSubscriptions.maxActive) {
+            await sendRpcError(reply, 503, -32603, "Subscription capacity is exhausted", requestId(isRecord(request.body) ? request.body.id : undefined));
+            return;
+        }
+        const subscriptionId = requestId(isRecord(request.body) ? request.body.id : undefined);
+        const totalByteLimit = Math.min(Number.MAX_SAFE_INTEGER, resourceSubscriptions.maxEvents * resourceSubscriptions.maxEventBytes);
+        let admitted = 0;
+        let admittedBytes = 0;
+        let detach = () => { };
+        let ended = false;
+        const boundedBus = {
+            publish: (event) => resourceEvents.publish(event),
+            subscribe(listener) {
+                detach = resourceEvents.subscribe((event) => {
+                    if (ended || event.kind !== "resource_updated" || event.uri !== uri)
+                        return;
+                    const frameBytes = Buffer.byteLength(`event: message\ndata: ${JSON.stringify({
+                        jsonrpc: "2.0",
+                        method: "notifications/resources/updated",
+                        params: {
+                            uri,
+                            _meta: { "io.modelcontextprotocol/subscriptionId": subscriptionId },
+                        },
+                    })}\n\n`, "utf8");
+                    if (frameBytes > resourceSubscriptions.maxEventBytes ||
+                        admitted >= resourceSubscriptions.maxEvents ||
+                        admittedBytes + frameBytes > totalByteLimit) {
+                        ended = true;
+                        detach();
+                        reply.raw.destroy();
+                        return;
+                    }
+                    admitted += 1;
+                    admittedBytes += frameBytes;
+                    listener(event);
+                });
+                return () => {
+                    ended = true;
+                    detach();
+                };
+            },
+        };
+        const handler = createMcpHandler(() => new McpServer(serverInfo, {
+            capabilities: { resources: { subscribe: true, listChanged: false } },
+            supportedProtocolVersions: [PROTOCOL_VERSION],
+        }), {
+            legacy: "reject",
+            responseMode: "sse",
+            bus: boundedBus,
+            maxSubscriptions: 1,
+            keepAliveMs: 0,
+        });
+        activeSubscriptions.add(handler);
+        const lifetime = setTimeout(() => { void handler.close(); }, resourceSubscriptions.lifetimeMs);
+        lifetime.unref();
+        const closeDisconnected = () => {
+            activeSubscriptions.delete(handler);
+            void handler.close();
+        };
+        reply.raw.once("close", closeDisconnected);
+        reply.hijack();
+        try {
+            await toNodeHandler(handler)(request.raw, reply.raw, request.body);
+        }
+        finally {
+            reply.raw.off("close", closeDisconnected);
+            clearTimeout(lifetime);
+            activeSubscriptions.delete(handler);
+            await handler.close();
+        }
+    }
     const observabilityLimits = observability.length ? { deliveryTimeoutMs: 1_000 } : undefined;
     const finishObservability = observabilityLimits
         ? installObservability(app, observability, (body) => capabilityNameForRequest(body, toolsByName, resourcesByUri, resourceTemplates, promptsByName), observabilityLimits)
@@ -867,7 +995,10 @@ export function createEmseepea(options) {
         await reply.header("cache-control", "no-store").type("text/plain; charset=utf-8")
             .code(available ? 200 : 503).send(available ? "ready\n" : "not ready\n");
     });
-    app.addHook("preClose", async () => { stopping.abort(); });
+    app.addHook("preClose", async () => {
+        stopping.abort();
+        await Promise.all([...activeSubscriptions].map((handler) => handler.close()));
+    });
     if (authentication) {
         app.all("/.well-known/*", async (request, reply) => {
             const response = oauthMetadataResponse(new Request(new URL(request.url, authentication.metadata.resourceServerUrl.origin), {
@@ -889,15 +1020,53 @@ export function createEmseepea(options) {
         if (deployment.mode === "production-behind-proxy" &&
             !validateProductionRequest(request, reply, deployment, limiter))
             return;
-        if (!await validateMcpRequestHeaders(request, reply))
+        const protocolVersionHeader = singleHeader(request.raw.rawHeaders, "mcp-protocol-version");
+        const mcpMethodHeader = singleHeader(request.raw.rawHeaders, "mcp-method");
+        const mcpNameHeader = singleHeader(request.raw.rawHeaders, "mcp-name");
+        if (protocolVersionHeader === null || mcpMethodHeader === null || mcpNameHeader === null) {
+            await sendRpcError(reply, 400, -32020, "Conflicting MCP headers", requestId(isRecord(request.body) ? request.body.id : undefined));
+            return;
+        }
+        const classification = classifyInboundRequest({
+            httpMethod: request.method,
+            ...(protocolVersionHeader ? { protocolVersionHeader } : {}),
+            ...(mcpMethodHeader ? { mcpMethodHeader } : {}),
+            ...(mcpNameHeader ? { mcpNameHeader } : {}),
+            body: request.body,
+        });
+        if (classification.kind === "reject") {
+            await sendRpcError(reply, classification.httpStatus, classification.code, classification.message, requestId(isRecord(request.body) ? request.body.id : undefined), isRecord(classification.data) ? classification.data : undefined);
+            return;
+        }
+        const legacy = classification.kind === "legacy";
+        if (legacy && classification.requestedVersion &&
+            !LEGACY_PROTOCOL_VERSIONS.includes(classification.requestedVersion)) {
+            await sendRpcError(reply, 400, ProtocolErrorCode.UnsupportedProtocolVersion, `Unsupported protocol version: ${classification.requestedVersion}`, requestId(isRecord(request.body) ? request.body.id : undefined), { requested: classification.requestedVersion, supported: [...SUPPORTED_PROTOCOLS] });
+            return;
+        }
+        if (!await validateMcpRequestHeaders(request, reply, legacy))
             return;
-        if (isRecord(request.body) && typeof request.body.method === "string" &&
+        if (!legacy && isRecord(request.body) && typeof request.body.method === "string" &&
             !enabledMethods.has(request.body.method)) {
             await sendRpcError(reply, 404, -32601, "Method not found", requestId(request.body.id));
             return;
         }
-        const access = capabilityAccessForRequest(request.body, toolsByName, resourcesByUri, resourceTemplates, promptsByName);
         const protectsCatalogue = authentication?.discovery === "protected";
+        let subscriptionTarget;
+        if (!legacy && isRecord(request.body) && request.body.method === "subscriptions/listen") {
+            try {
+                subscriptionTarget = resourceSubscriptionTarget(request.body, resourceSubscriptions.maxUriBytes, resourcesByUri, resourceTemplates);
+            }
+            catch {
+                await sendRpcError(reply, 400, -32602, "Invalid resource subscription", requestId(request.body.id));
+                return;
+            }
+            if (!subscriptionTarget.resource && !protectsCatalogue) {
+                await sendRpcError(reply, 200, -32602, "Capability not found", requestId(request.body.id));
+                return;
+            }
+        }
+        const access = subscriptionTarget?.resource?.[RESOURCE_ACCESS] ?? capabilityAccessForRequest(request.body, toolsByName, resourcesByUri, resourceTemplates, promptsByName);
         let authInfo;
         if (authentication && (protectsCatalogue || access && access !== "public")) {
             try {
@@ -922,6 +1091,11 @@ export function createEmseepea(options) {
             await sendRpcError(reply, 200, -32602, "Capability not found", requestId(isRecord(request.body) ? request.body.id : undefined));
             return;
         }
+        if (subscriptionTarget) {
+            await serveResourceSubscription(request, reply, subscriptionTarget.uri);
+            return;
+        }
+        const capability = capabilityNameForRequest(request.body, toolsByName, resourcesByUri, resourceTemplates, promptsByName);
         const disconnected = new AbortController();
         const abort = () => disconnected.abort();
         request.raw.once("aborted", abort);
@@ -935,6 +1109,8 @@ export function createEmseepea(options) {
                 signal: disconnected.signal,
                 principal,
                 filterCatalogues: protectsCatalogue,
+                capability,
+                legacy,
             }, () => nodeHandler(request.raw, reply.raw, request.body));
         }
         finally {
@@ -960,9 +1136,26 @@ export function createEmseepea(options) {
         stopping,
         observabilityLimits,
         finishObservability,
+        ...(resourceEvents ? {
+            notifyResourceUpdated(uri) {
+                if (stopping.signal.aborted)
+                    throw new Error("Cannot notify from a stopped Em See Pea app");
+                if (typeof uri !== "string" || Buffer.byteLength(uri, "utf8") > resourceSubscriptions.maxUriBytes ||
+                    !(resourcesByUri.has(uri) || resourceTemplates.some((resource) => resource[RESOURCE_MATCHES]?.(uri)))) {
+                    throw new TypeError("Resource update URI must match a registered resource");
+                }
+                resourceEvents.publish({ kind: "resource_updated", uri });
+            },
+        } : {}),
     });
     return app;
 }
+export function notifyResourceUpdated(app, uri) {
+    const notify = runtimes.get(app)?.notifyResourceUpdated;
+    if (!notify)
+        throw new TypeError("notifyResourceUpdated requires resourceSubscriptions");
+    notify(uri);
+}
 function safeOAuthError(error) {
     if (!(error instanceof OAuthError))
         return error;
@@ -1040,9 +1233,29 @@ function capabilityAccessForRequest(body, toolsByName, resourcesByUri, resourceT
     }
     return undefined;
 }
+function resourceSubscriptionTarget(body, maxUriBytes, resourcesByUri, resourceTemplates) {
+    if (!isRecord(body) || body.method !== "subscriptions/listen" || !isRecord(body.params) ||
+        !isRecord(body.params.notifications)) {
+        throw new TypeError("Invalid resource subscription");
+    }
+    const notifications = body.params.notifications;
+    if (Object.keys(notifications).some((key) => key !== "resourceSubscriptions") ||
+        !Array.isArray(notifications.resourceSubscriptions) ||
+        notifications.resourceSubscriptions.length !== 1 ||
+        typeof notifications.resourceSubscriptions[0] !== "string" ||
+        Buffer.byteLength(notifications.resourceSubscriptions[0], "utf8") > maxUriBytes) {
+        throw new TypeError("Invalid resource subscription");
+    }
+    const uri = notifications.resourceSubscriptions[0];
+    return {
+        uri,
+        resource: resourcesByUri.get(uri) ?? resourceTemplates.find((candidate) => candidate[RESOURCE_MATCHES]?.(uri)),
+    };
+}
 function isCapabilityInvocation(body) {
     return isRecord(body) && (body.method === "tools/call" || body.method === "resources/read" ||
-        body.method === "prompts/get" || body.method === "completion/complete");
+        body.method === "prompts/get" || body.method === "completion/complete" ||
+        body.method === "subscriptions/listen");
 }
 function capabilityNameForRequest(body, toolsByName, resourcesByUri, resourceTemplates, promptsByName) {
     if (!isRecord(body) || !isRecord(body.params))
@@ -1055,6 +1268,12 @@ function capabilityNameForRequest(body, toolsByName, resourcesByUri, resourceTem
         const resource = resourcesByUri.get(params.uri) ?? resourceTemplates.find((candidate) => candidate[RESOURCE_MATCHES]?.(params.uri));
         return resource?.[RESOURCE_NAME];
     }
+    if (body.method === "subscriptions/listen" && isRecord(params.notifications) &&
+        Array.isArray(params.notifications.resourceSubscriptions) &&
+        typeof params.notifications.resourceSubscriptions[0] === "string") {
+        const uri = params.notifications.resourceSubscriptions[0];
+        return (resourcesByUri.get(uri) ?? resourceTemplates.find((candidate) => candidate[RESOURCE_MATCHES]?.(uri)))?.[RESOURCE_NAME];
+    }
     if (body.method === "prompts/get" && typeof params.name === "string") {
         return promptsByName.has(params.name) ? params.name : undefined;
     }
@@ -1352,14 +1571,14 @@ function singleHeader(rawHeaders, name) {
     }
     return values.length === 0 ? undefined : values.length === 1 ? values[0] : null;
 }
-async function validateMcpRequestHeaders(request, reply) {
+async function validateMcpRequestHeaders(request, reply, legacy) {
     const body = request.body;
     const id = isRecord(body) ? requestId(body.id) : null;
     if (!acceptsMcpResponses(request.headers.accept)) {
         await sendRpcError(reply, 406, -32000, "Not Acceptable: Client must accept both application/json and text/event-stream", id);
         return false;
     }
-    if (!isRecord(body) || typeof body.method !== "string")
+    if (legacy || !isRecord(body) || typeof body.method !== "string")
         return true;
     const header = (name) => singleHeader(request.raw.rawHeaders, name);
     const rejectMismatch = async (name) => {
@@ -1864,13 +2083,30 @@ function nonNegativePort(value) {
     }
     return value;
 }
-function assertStatelessInputRequired(result) {
-    if (!result.inputRequests || result.requestState !== undefined) {
-        throw new Error("Client-input requests must be stateless");
+function directHandlerContext(access, context, signal, deadlineMs, requestState) {
+    return {
+        signal,
+        deadlineMs,
+        principal: access === "public" ? undefined : principalFrom(context.http?.authInfo),
+        inputResponses: checkedInputResponses(context.mcpReq.inputResponses),
+        ...(requestState ? {
+            requestState: context.mcpReq.requestState(),
+            mintRequestState: (payload) => requestState.mint(payload, context),
+        } : {}),
+    };
+}
+async function assertInputRequired(result, requestState, context) {
+    if (!result.inputRequests && result.requestState === undefined) {
+        throw new Error("Client-input result must include requests or state");
     }
-    if (Object.values(result.inputRequests).some((request) => request.method !== "elicitation/create")) {
+    if (result.inputRequests && Object.values(result.inputRequests).some((request) => request.method !== "elicitation/create")) {
         throw new Error("Client-input request kind is not supported");
     }
+    if (result.requestState !== undefined) {
+        if (!requestState)
+            throw new Error("Client-input request state is not configured");
+        await requestState.verify(result.requestState, context);
+    }
 }
 function assertResultSize(result, maxApplicationResultBytes, deadlineMs, signal) {
     let serialized;