@emseepea/server 0.0.2 → 0.0.3

package/dist/index.js

@@ -1,32 +1,56 @@
 import { createMcpFastifyApp } from "@modelcontextprotocol/fastify";
 import { GetPromptResultSchema, ReadResourceResultSchema, } from "@modelcontextprotocol/core";
 import { toNodeHandler } from "@modelcontextprotocol/node";
-import { McpServer, OAuthError, OAuthErrorCode, ResourceTemplate, bearerAuthChallengeResponse, buildOAuthProtectedResourceMetadata, checkResourceAllowed, completable, createMcpHandler, getOAuthProtectedResourceMetadataUrl, oauthMetadataResponse, verifyBearerToken, } from "@modelcontextprotocol/server";
+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 { AsyncLocalStorage } from "node:async_hooks";
+import { createHash } from "node:crypto";
 import { isIP } from "node:net";
 import { z } from "zod";
+import { installRequestTelemetry } from "./telemetry.js";
 export * from "./ui.js";
+export const inputRequired = Object.assign((spec) => sdkInputRequired({ inputRequests: spec.inputRequests }), {
+    elicit: sdkInputRequired.elicit,
+    elicitUrl: sdkInputRequired.elicitUrl,
+});
+export function acceptedContent(responses, key, schema) {
+    return sdkAcceptedContent(checkedInputResponses(responses), key, schema);
+}
+export function inputResponse(responses, key) {
+    const response = sdkInputResponse(checkedInputResponses(responses), key);
+    return response.kind === "elicit" ? response : { kind: "missing" };
+}
 const PROTOCOL_VERSION = "2026-07-28";
 const REGISTER = Symbol("register");
 const TOOL_NAME = Symbol("toolName");
 const TOOL_ACCESS = Symbol("toolAccess");
 const TOOL_STREAMING = Symbol("toolStreaming");
+const TOOL_LISTING = Symbol("toolListing");
 const RESOURCE_NAME = Symbol("resourceName");
 const RESOURCE_URI = Symbol("resourceUri");
 const RESOURCE_KIND = Symbol("resourceKind");
 const RESOURCE_MATCHES = Symbol("resourceMatches");
 const RESOURCE_ROUTE = Symbol("resourceRoute");
+const RESOURCE_LISTING = Symbol("resourceListing");
 const PROMPT_NAME = Symbol("promptName");
 const HAS_COMPLETION = Symbol("hasCompletion");
+const PROMPT_LISTING = Symbol("promptListing");
+const CACHEABLE_METHODS = [
+    "tools/list",
+    "prompts/list",
+    "resources/list",
+    "resources/templates/list",
+    "resources/read",
+    "server/discover",
+];
 const runtimes = new WeakMap();
 const requestOperations = new AsyncLocalStorage();
 export function defineTool(definition) {
     const handler = definition.handler;
-    return createCheckedTool(definition, handler, false);
+    return createCheckedTool(definition, handler, false, true);
 }
 export function defineStreamingTool(definition) {
     const handler = definition.handler;
-    return createCheckedTool(definition, handler, true);
+    return createCheckedTool(definition, handler, true, false);
 }
 export function defineMappedTool(definition) {
     const { backendInputSchema, backendOutputSchema, isAvailable, adapter } = definition;
@@ -54,29 +78,61 @@ export function defineMappedTool(definition) {
         context.signal.throwIfAborted();
         return mapOutput(parsedBackendResult.data);
     };
-    return createCheckedTool(definition, execute, false);
+    return createCheckedTool(definition, execute, false, false);
 }
 export function defineResource(definition) {
-    const { name, title, description, mimeType, handler } = definition;
+    const { name, handler } = definition;
     assertRegistrationName("Resource", name);
     const uri = canonicalResourceUri(definition.uri);
+    const listing = checkedProtocolValue("Resource", {
+        name,
+        uri,
+        title: definition.title,
+        description: definition.description,
+        mimeType: definition.mimeType,
+        icons: definition.icons,
+        annotations: definition.annotations,
+        size: definition.size,
+        _meta: definition._meta,
+    });
+    const metadata = Object.freeze({
+        title: listing.title,
+        description: listing.description,
+        mimeType: listing.mimeType,
+        icons: listing.icons,
+        annotations: listing.annotations,
+        size: listing.size,
+        _meta: listing._meta,
+    });
+    const cacheHint = definition.cacheHint === undefined
+        ? undefined
+        : normalizeCacheHint(definition.cacheHint, `resource ${name}`);
     const registration = {
         [RESOURCE_NAME]: name,
         [RESOURCE_URI]: uri,
         [RESOURCE_KIND]: "static",
+        [RESOURCE_LISTING]: Object.freeze({
+            method: "resources/list",
+            value: listing,
+        }),
         [HAS_COMPLETION]: false,
         [REGISTER](server, timeoutMs, maxApplicationResultBytes) {
-            server.registerResource(name, uri, {
-                title,
-                description,
-                mimeType,
-            }, async (_requestedUri, context) => {
+            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 });
+                        const result = await handler({
+                            signal,
+                            deadlineMs,
+                            inputResponses: checkedInputResponses(context.mcpReq.inputResponses),
+                        });
                         signal.throwIfAborted();
+                        if (isInputRequiredResult(result)) {
+                            assertStatelessInputRequired(result);
+                            assertResultSize(result, maxApplicationResultBytes, deadlineMs, signal);
+                            return result;
+                        }
                         const parsed = await ReadResourceResultSchema.safeParseAsync(result);
                         if (!parsed.success || parsed.data.contents.some((content) => content.uri !== uri)) {
                             throw new Error("Resource returned an invalid result");
@@ -95,10 +151,31 @@ export function defineResource(definition) {
     return Object.freeze(registration);
 }
 export function defineResourceTemplate(definition) {
-    const { name, title, description, mimeType, handler } = definition;
+    const { name, handler } = definition;
     assertRegistrationName("Resource template", name);
     const { template, route } = checkedResourceTemplate(definition.uriTemplate);
     const uriTemplate = template.uriTemplate.toString();
+    const listing = checkedProtocolValue("ResourceTemplate", {
+        name,
+        uriTemplate,
+        title: definition.title,
+        description: definition.description,
+        mimeType: definition.mimeType,
+        icons: definition.icons,
+        annotations: definition.annotations,
+        _meta: definition._meta,
+    });
+    const metadata = Object.freeze({
+        title: listing.title,
+        description: listing.description,
+        mimeType: listing.mimeType,
+        icons: listing.icons,
+        annotations: listing.annotations,
+        _meta: listing._meta,
+    });
+    const cacheHint = definition.cacheHint === undefined
+        ? undefined
+        : normalizeCacheHint(definition.cacheHint, `resource template ${name}`);
     const variableNames = [...template.uriTemplate.variableNames];
     const completions = checkedCompletionHandlers("Resource template", definition.complete, variableNames);
     const registration = {
@@ -107,6 +184,10 @@ export function defineResourceTemplate(definition) {
         [RESOURCE_KIND]: "template",
         [RESOURCE_MATCHES]: (uri) => template.uriTemplate.match(uri) !== null,
         [RESOURCE_ROUTE]: route,
+        [RESOURCE_LISTING]: Object.freeze({
+            method: "resources/templates/list",
+            value: listing,
+        }),
         [HAS_COMPLETION]: completions.size > 0,
         [REGISTER](server, timeoutMs, maxApplicationResultBytes) {
             const registeredTemplate = completions.size === 0
@@ -118,13 +199,22 @@ export function defineResourceTemplate(definition) {
                         completionCallback(complete, variable, variableNames, timeoutMs, maxApplicationResultBytes),
                     ])),
                 });
-            server.registerResource(name, registeredTemplate, { title, description, mimeType }, async (requestedUri, variables, context) => {
+            server.registerResource(name, registeredTemplate, cacheHint ? { ...metadata, cacheHint } : metadata, async (requestedUri, variables, 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({ uri: requestedUri.href, variables }, { signal, deadlineMs });
+                        const result = await handler({ uri: requestedUri.href, variables }, {
+                            signal,
+                            deadlineMs,
+                            inputResponses: checkedInputResponses(context.mcpReq.inputResponses),
+                        });
                         signal.throwIfAborted();
+                        if (isInputRequiredResult(result)) {
+                            assertStatelessInputRequired(result);
+                            assertResultSize(result, maxApplicationResultBytes, deadlineMs, signal);
+                            return result;
+                        }
                         const parsed = await ReadResourceResultSchema.safeParseAsync(result);
                         if (!parsed.success ||
                             parsed.data.contents.some((content) => content.uri !== requestedUri.href)) {
@@ -144,17 +234,31 @@ export function defineResourceTemplate(definition) {
     return Object.freeze(registration);
 }
 export function definePrompt(definition) {
-    const { name, title, description, argsSchema, handler } = definition;
+    const { name, argsSchema, handler } = definition;
     assertRegistrationName("Prompt", name);
     const argumentNames = Object.keys(argsSchema.shape);
     const completions = checkedCompletionHandlers("Prompt", definition.complete, argumentNames);
+    const listing = checkedProtocolValue("Prompt", {
+        name,
+        title: definition.title,
+        description: definition.description,
+        icons: definition.icons,
+        _meta: definition._meta,
+        arguments: promptArguments(argsSchema),
+    });
+    const metadata = Object.freeze({
+        title: listing.title,
+        description: listing.description,
+        icons: listing.icons,
+        _meta: listing._meta,
+    });
     const registration = {
         [PROMPT_NAME]: name,
         [HAS_COMPLETION]: completions.size > 0,
+        [PROMPT_LISTING]: listing,
         [REGISTER](server, timeoutMs, maxApplicationResultBytes) {
             server.registerPrompt(name, {
-                title,
-                description,
+                ...metadata,
                 argsSchema: sdkPromptMetadataSchema(argsSchema, completions, argumentNames, timeoutMs, maxApplicationResultBytes),
             }, async (args, context) => {
                 try {
@@ -164,8 +268,17 @@ export function definePrompt(definition) {
                         if (!parsedArgs.success)
                             throw new Error("Prompt received invalid arguments");
                         signal.throwIfAborted();
-                        const result = await handler(parsedArgs.data, { signal, deadlineMs });
+                        const result = await handler(parsedArgs.data, {
+                            signal,
+                            deadlineMs,
+                            inputResponses: checkedInputResponses(context.mcpReq.inputResponses),
+                        });
                         signal.throwIfAborted();
+                        if (isInputRequiredResult(result)) {
+                            assertStatelessInputRequired(result);
+                            assertResultSize(result, maxApplicationResultBytes, deadlineMs, signal);
+                            return result;
+                        }
                         const parsedResult = await GetPromptResultSchema.safeParseAsync(result);
                         if (!parsedResult.success)
                             throw new Error("Prompt returned an invalid result");
@@ -187,26 +300,45 @@ const progressUpdateSchema = z.strictObject({
     total: z.number().positive().optional(),
     message: z.string().optional(),
 });
-function createCheckedTool(definition, execute, streaming) {
-    const { name, title, description, inputSchema, outputSchema } = definition;
+function createCheckedTool(definition, execute, streaming, allowsInputRequired) {
+    const { name, inputSchema, outputSchema } = definition;
     assertRegistrationName("Tool", name);
+    assertValidMcpHeaderAnnotations(inputSchema);
     const access = normalizeToolAccess(definition.access, definition.requiredScopes);
+    const publicAccess = access === "public"
+        ? Object.freeze({ type: "public" })
+        : Object.freeze({ type: "protected", requiredScopes: [...access.requiredScopes] });
+    const sdkInputSchema = sdkMetadataSchema(inputSchema);
+    const sdkOutputSchema = sdkMetadataSchema(outputSchema);
+    const listing = checkedProtocolValue("Tool", {
+        name,
+        title: definition.title,
+        description: definition.description,
+        icons: definition.icons,
+        annotations: definition.annotations,
+        inputSchema: jsonMetadataSchema(inputSchema, "input"),
+        outputSchema: jsonMetadataSchema(outputSchema, "output"),
+        _meta: {
+            ...definition._meta,
+            "io.emseepea/access": publicAccess,
+        },
+    });
+    const metadata = Object.freeze({
+        title: listing.title,
+        description: listing.description,
+        icons: listing.icons,
+        annotations: listing.annotations,
+        inputSchema: sdkInputSchema,
+        outputSchema: sdkOutputSchema,
+        _meta: listing._meta,
+    });
     const registration = {
         [TOOL_NAME]: name,
         [TOOL_ACCESS]: access,
         [TOOL_STREAMING]: streaming,
+        [TOOL_LISTING]: listing,
         [REGISTER](server, timeoutMs, maxApplicationResultBytes, maxProgressEvents, maxProgressEventBytes) {
-            server.registerTool(name, {
-                title,
-                description,
-                inputSchema: sdkMetadataSchema(inputSchema),
-                outputSchema: sdkMetadataSchema(outputSchema),
-                _meta: {
-                    "io.emseepea/access": access === "public"
-                        ? { type: "public" }
-                        : { type: "protected", requiredScopes: [...access.requiredScopes] },
-                },
-            }, async (input, context) => {
+            server.registerTool(name, metadata, async (input, context) => {
                 try {
                     const deadlineMs = requestOperations.getStore()?.deadlineMs ?? Date.now() + timeoutMs;
                     return await runWithDeadline(context.mcpReq.signal, deadlineMs, async (signal) => {
@@ -224,6 +356,11 @@ function createCheckedTool(definition, execute, streaming) {
                                 signal,
                                 deadlineMs,
                                 principal: access === "public" ? undefined : principalFrom(context.http?.authInfo),
+                                ...(allowsInputRequired
+                                    ? {
+                                        inputResponses: checkedInputResponses(context.mcpReq.inputResponses),
+                                    }
+                                    : {}),
                                 ...(reporter ? { reportProgress: reporter.report } : {}),
                             });
                         }
@@ -231,6 +368,12 @@ function createCheckedTool(definition, execute, streaming) {
                             await reporter?.finish();
                         }
                         reporter?.throwIfFailed();
+                        if (allowsInputRequired && isInputRequiredResult(result)) {
+                            signal.throwIfAborted();
+                            assertStatelessInputRequired(result);
+                            assertResultSize(result, maxApplicationResultBytes, deadlineMs, signal);
+                            return result;
+                        }
                         if (!isRecord(result) || typeof result.text !== "string" || !("data" in result)) {
                             throw new Error("Tool returned an invalid result");
                         }
@@ -311,15 +454,142 @@ function progressReporter(context, signal, maxEvents, maxEventBytes) {
             throw failure; },
     };
 }
+function normalizeListPagination(options) {
+    const pageSize = positiveInteger("listPagination.pageSize", options.pageSize);
+    if (pageSize > 100)
+        throw new TypeError("listPagination.pageSize must not exceed 100");
+    return Object.freeze({
+        pageSize,
+        maxPageBytes: positiveInteger("listPagination.maxPageBytes", options.maxPageBytes ?? 1024 * 1024),
+    });
+}
+function compileListPagination(options, catalogues) {
+    const compiled = new Map();
+    for (const [method, entries] of catalogues) {
+        if (entries.length === 0)
+            continue;
+        const resultKey = method === "tools/list"
+            ? "tools"
+            : method === "prompts/list"
+                ? "prompts"
+                : method === "resources/templates/list"
+                    ? "resourceTemplates"
+                    : "resources";
+        compiled.set(method, compileCataloguePages(method, resultKey, entries, options));
+    }
+    return compiled;
+}
+function compileCataloguePages(method, resultKey, entries, options) {
+    const groups = [];
+    for (let index = 0; index < entries.length;) {
+        const group = [];
+        while (group.length < options.pageSize && index < entries.length) {
+            const candidate = [...group, entries[index]];
+            const hasNext = index + 1 < entries.length;
+            if (cataloguePageBytes(resultKey, candidate, hasNext) > options.maxPageBytes) {
+                if (group.length === 0) {
+                    throw new TypeError(`${method} has an entry larger than listPagination.maxPageBytes`);
+                }
+                break;
+            }
+            group.push(entries[index]);
+            index += 1;
+        }
+        groups.push(group);
+    }
+    const catalogueDigest = createHash("sha256").update(JSON.stringify(entries)).digest("base64url");
+    const cursorFor = (page) => createHash("sha256").update([
+        "emseepea-list-cursor-v1",
+        method,
+        String(page),
+        String(options.pageSize),
+        String(options.maxPageBytes),
+        catalogueDigest,
+    ].join("\n")).digest("base64url");
+    const pages = groups.map((group, index) => Object.freeze({
+        [resultKey]: Object.freeze([...group]),
+        ...(index + 1 < groups.length ? { nextCursor: cursorFor(index + 1) } : {}),
+    }));
+    const byCursor = new Map();
+    for (let index = 1; index < pages.length; index += 1) {
+        byCursor.set(cursorFor(index), pages[index]);
+    }
+    return Object.freeze({ first: pages[0], byCursor });
+}
+function cataloguePageBytes(resultKey, entries, hasNext) {
+    return Buffer.byteLength(JSON.stringify({
+        [resultKey]: entries,
+        ...(hasNext ? { nextCursor: "x".repeat(43) } : {}),
+    }), "utf8");
+}
+function paginationPage(pages, cursor) {
+    if (cursor === undefined)
+        return pages.first;
+    const page = /^[A-Za-z0-9_-]{43}$/.test(cursor) ? pages.byCursor.get(cursor) : undefined;
+    if (!page)
+        throw new ProtocolError(ProtocolErrorCode.InvalidParams, "Invalid pagination cursor");
+    return page;
+}
+function installListPagination(server, pagination) {
+    const tools = pagination.get("tools/list");
+    if (tools)
+        server.server.setRequestHandler("tools/list", (request) => paginationPage(tools, request.params?.cursor));
+    const resources = pagination.get("resources/list");
+    if (resources)
+        server.server.setRequestHandler("resources/list", (request) => paginationPage(resources, request.params?.cursor));
+    const templates = pagination.get("resources/templates/list");
+    if (templates)
+        server.server.setRequestHandler("resources/templates/list", (request) => paginationPage(templates, request.params?.cursor));
+    const prompts = pagination.get("prompts/list");
+    if (prompts)
+        server.server.setRequestHandler("prompts/list", (request) => paginationPage(prompts, request.params?.cursor));
+}
 export function createEmseepea(options) {
+    if (options.telemetry !== undefined && typeof options.telemetry !== "boolean") {
+        throw new TypeError("telemetry must be a boolean");
+    }
+    const readiness = options.readiness;
+    const readinessTimeoutMs = callbackTimeout("readiness", readiness, "readinessTimeoutMs", options.readinessTimeoutMs);
+    const stopping = new AbortController();
+    let pendingReadiness;
+    async function ready() {
+        if (stopping.signal.aborted)
+            return false;
+        if (!readiness)
+            return true;
+        if (!pendingReadiness) {
+            const deadline = Date.now() + readinessTimeoutMs;
+            pendingReadiness = runWithDeadline(stopping.signal, deadline, async (signal) => {
+                try {
+                    return await readiness({ signal }) === true && Date.now() < deadline;
+                }
+                finally {
+                    pendingReadiness = undefined;
+                }
+            }).catch(() => false);
+        }
+        const result = await pendingReadiness;
+        return result && !stopping.signal.aborted;
+    }
     assertNonEmpty("name", options.name);
     assertNonEmpty("version", options.version);
+    const serverInfo = checkedProtocolValue("Implementation", {
+        name: options.name,
+        version: options.version,
+        title: options.title,
+        description: options.description,
+        icons: options.icons,
+        websiteUrl: options.websiteUrl,
+    });
     const tools = Object.freeze([...(options.tools ?? [])]);
     const resources = Object.freeze([...(options.resources ?? [])]);
     const prompts = Object.freeze([...(options.prompts ?? [])]);
     assertUniqueToolNames(tools);
     assertUniqueResources(resources);
     assertUniquePromptNames(prompts);
+    const paginationOptions = options.listPagination
+        ? normalizeListPagination(options.listPagination)
+        : undefined;
     const maxRequestBytes = positiveInteger("maxRequestBytes", options.maxRequestBytes ?? 1024 * 1024);
     const maxApplicationResultBytes = positiveInteger("maxApplicationResultBytes", options.maxApplicationResultBytes ?? 1024 * 1024);
     const maxProgressEvents = positiveInteger("maxProgressEvents", options.maxProgressEvents ?? 32);
@@ -328,8 +598,9 @@ export function createEmseepea(options) {
     const deployment = normalizeDeployment(options.deployment ?? { mode: "loopback" });
     const oauth = options.oauth ? normalizeOAuth(options.oauth) : undefined;
     const hasStreaming = tools.some((tool) => tool[TOOL_STREAMING]);
-    if (hasStreaming && deployment.mode !== "loopback") {
-        throw new TypeError("Streaming tools currently require the loopback deployment profile");
+    if (deployment.mode !== "loopback" &&
+        tools.some((tool) => tool[TOOL_STREAMING] && tool[TOOL_ACCESS] !== "public")) {
+        throw new TypeError("Protected streaming tools currently require the loopback deployment profile");
     }
     if (tools.some((tool) => tool[TOOL_ACCESS] !== "public") && !oauth) {
         throw new TypeError("Protected tools require OAuth resource-server configuration");
@@ -349,8 +620,23 @@ export function createEmseepea(options) {
         prompts.some((prompt) => prompt[HAS_COMPLETION]);
     if (hasCompletion)
         enabledMethods.add("completion/complete");
+    const cacheHints = options.cacheHints === undefined
+        ? undefined
+        : normalizeCacheHints(options.cacheHints, enabledMethods);
+    const pagination = paginationOptions
+        ? compileListPagination(paginationOptions, new Map([
+            ["tools/list", tools.map((tool) => tool[TOOL_LISTING])],
+            ["resources/list", resources
+                    .filter((resource) => resource[RESOURCE_LISTING].method === "resources/list")
+                    .map((resource) => resource[RESOURCE_LISTING].value)],
+            ["resources/templates/list", resources
+                    .filter((resource) => resource[RESOURCE_LISTING].method === "resources/templates/list")
+                    .map((resource) => resource[RESOURCE_LISTING].value)],
+            ["prompts/list", prompts.map((prompt) => prompt[PROMPT_LISTING])],
+        ]))
+        : undefined;
     const sdkHandler = createMcpHandler(() => {
-        const server = new McpServer({ name: options.name, version: options.version }, {
+        const server = new McpServer(serverInfo, {
             capabilities: {
                 ...(tools.length ? { tools: { listChanged: false } } : {}),
                 ...(resources.length ? { resources: { subscribe: false, listChanged: false } } : {}),
@@ -358,6 +644,7 @@ export function createEmseepea(options) {
                 ...(hasCompletion ? { completions: {} } : {}),
             },
             instructions: options.instructions,
+            cacheHints,
             supportedProtocolVersions: [PROTOCOL_VERSION],
         });
         for (const tool of tools) {
@@ -367,6 +654,8 @@ export function createEmseepea(options) {
             resource[REGISTER](server, operationTimeoutMs, maxApplicationResultBytes);
         for (const prompt of prompts)
             prompt[REGISTER](server, operationTimeoutMs, maxApplicationResultBytes);
+        if (pagination)
+            installListPagination(server, pagination);
         return server;
     }, {
         legacy: "reject",
@@ -375,11 +664,17 @@ export function createEmseepea(options) {
     });
     const nodeHandler = toNodeHandler(sdkHandler);
     const app = createMcpFastifyApp({ host: deployment.mode === "loopback" ? "127.0.0.1" : "0.0.0.0" });
+    const finishTelemetry = options.telemetry === true ? installRequestTelemetry(app) : undefined;
     const limiter = deployment.mode === "production-behind-proxy"
         ? new FixedWindowRateLimiter(deployment.rateLimit)
         : undefined;
     app.get("/healthz", health("ok\n"));
-    app.get("/readyz", health("ready\n"));
+    app.get("/readyz", async (_request, reply) => {
+        const available = await ready();
+        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(); });
     if (oauth) {
         app.all("/.well-known/*", async (request, reply) => {
             const response = oauthMetadataResponse(new Request(new URL(request.url, oauth.metadata.resourceServerUrl.origin), {
@@ -401,6 +696,8 @@ export function createEmseepea(options) {
         if (deployment.mode === "production-behind-proxy" &&
             !validateProductionRequest(request, reply, deployment, limiter))
             return;
+        if (!await validateMcpRequestHeaders(request, reply))
+            return;
         if (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));
@@ -424,7 +721,7 @@ export function createEmseepea(options) {
         const abort = () => disconnected.abort();
         request.raw.once("aborted", abort);
         reply.raw.once("close", abort);
-        if (request.raw.aborted || request.raw.destroyed || reply.raw.destroyed)
+        if (requestAlreadyClosed(request, reply))
             abort();
         reply.hijack();
         try {
@@ -447,7 +744,7 @@ export function createEmseepea(options) {
         }
     });
     app.addHook("onClose", async () => sdkHandler.close());
-    runtimes.set(app, { deployment, requestTimeoutMs: operationTimeoutMs + 5_000 });
+    runtimes.set(app, { deployment, requestTimeoutMs: operationTimeoutMs + 5_000, stopping, finishTelemetry });
     return app;
 }
 function safeOAuthError(error) {
@@ -467,6 +764,8 @@ async function verifyProtectedCall(request, reply, access, oauth) {
     const abort = () => disconnected.abort();
     request.raw.once("aborted", abort);
     reply.raw.once("close", abort);
+    if (requestAlreadyClosed(request, reply))
+        abort();
     try {
         const authInfo = await runWithDeadline(disconnected.signal, Date.now() + oauth.verificationTimeoutMs, () => verifyBearerToken(singleHeader(request.raw.rawHeaders, "authorization"), {
             verifier: oauth.verifier,
@@ -486,6 +785,9 @@ async function verifyProtectedCall(request, reply, access, oauth) {
         reply.raw.off("close", abort);
     }
 }
+function requestAlreadyClosed(request, reply) {
+    return request.raw.aborted || (request.raw.destroyed && !request.raw.complete) || reply.raw.destroyed;
+}
 async function sendWebResponse(reply, response) {
     for (const [name, value] of response.headers)
         reply.header(name, value);
@@ -518,6 +820,8 @@ export async function serveEmseepea(app, options = {}) {
     }
     const port = nonNegativePort(options.port ?? 3000);
     const shutdownTimeoutMs = positiveInteger("shutdownTimeoutMs", options.shutdownTimeoutMs ?? 5_000);
+    const flushTelemetry = options.flushTelemetry;
+    const telemetryFlushTimeoutMs = callbackTimeout("flushTelemetry", flushTelemetry, "telemetryFlushTimeoutMs", options.telemetryFlushTimeoutMs);
     await app.listen({ host, port });
     app.server.headersTimeout = 10_000;
     app.server.keepAliveTimeout = 5_000;
@@ -533,7 +837,10 @@ export async function serveEmseepea(app, options = {}) {
     let closing;
     return {
         url: new URL(`http://${urlHost}:${address.port}/mcp`),
-        close: () => closing ??= closeApp(app, shutdownTimeoutMs),
+        close: () => {
+            runtime.stopping.abort();
+            return closing ??= closeApp(app, shutdownTimeoutMs, flushTelemetry, telemetryFlushTimeoutMs, runtime.finishTelemetry);
+        },
     };
 }
 function health(body) {
@@ -541,8 +848,12 @@ function health(body) {
         await reply.header("cache-control", "no-store").type("text/plain; charset=utf-8").send(body);
     };
 }
-async function sendRpcError(reply, status, code, message, id = null) {
-    await reply.code(status).send({ jsonrpc: "2.0", id, error: { code, message } });
+async function sendRpcError(reply, status, code, message, id = null, data) {
+    await reply.code(status).send({
+        jsonrpc: "2.0",
+        id,
+        error: { code, message, ...(data ? { data } : {}) },
+    });
 }
 function isFastifyError(error) {
     return error instanceof Error && "code" in error;
@@ -713,9 +1024,203 @@ function singleHeader(rawHeaders, name) {
     }
     return values.length === 0 ? undefined : values.length === 1 ? values[0] : null;
 }
+async function validateMcpRequestHeaders(request, reply) {
+    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")
+        return true;
+    const header = (name) => singleHeader(request.raw.rawHeaders, name);
+    const rejectMismatch = async (name) => {
+        await sendRpcError(reply, 400, -32020, `Missing or mismatched ${name} header`, id);
+        return false;
+    };
+    const protocolVersion = header("mcp-protocol-version");
+    if (!protocolVersion)
+        return rejectMismatch("MCP-Protocol-Version");
+    const params = isRecord(body.params) ? body.params : undefined;
+    const meta = params && isRecord(params._meta) ? params._meta : undefined;
+    const bodyVersion = meta?.["io.modelcontextprotocol/protocolVersion"];
+    if (typeof bodyVersion !== "string" || protocolVersion !== bodyVersion) {
+        return rejectMismatch("MCP-Protocol-Version");
+    }
+    if (protocolVersion !== PROTOCOL_VERSION) {
+        await sendRpcError(reply, 400, ProtocolErrorCode.UnsupportedProtocolVersion, `Unsupported protocol version: ${protocolVersion}`, id, { requested: protocolVersion, supported: [PROTOCOL_VERSION] });
+        return false;
+    }
+    if (header("mcp-method") !== body.method)
+        return rejectMismatch("Mcp-Method");
+    const nameField = body.method === "tools/call" || body.method === "prompts/get"
+        ? "name"
+        : body.method === "resources/read"
+            ? "uri"
+            : undefined;
+    if (!nameField)
+        return true;
+    if (!params || typeof params[nameField] !== "string")
+        return rejectMismatch("Mcp-Name");
+    const name = header("mcp-name");
+    if (!name || decodeMcpHeaderValue(name) !== params[nameField])
+        return rejectMismatch("Mcp-Name");
+    return true;
+}
+function acceptsMcpResponses(value) {
+    const types = (Array.isArray(value) ? value : value ? [value] : [])
+        .flatMap((header) => header.split(","))
+        .filter((part) => !part.split(";").slice(1).some((parameter) => /^\s*q\s*=\s*0(?:\.0*)?\s*$/i.test(parameter)))
+        .map((part) => part.split(";", 1)[0]?.trim().toLowerCase());
+    return types.includes("application/json") && types.includes("text/event-stream");
+}
+function decodeMcpHeaderValue(value) {
+    const normalized = value.replace(/^[\t ]+|[\t ]+$/g, "");
+    const prefix = "=?base64?";
+    if (!normalized.startsWith(prefix) || !normalized.endsWith("?=")) {
+        return /^[\x20-\x7E\t]*$/.test(normalized) ? normalized : undefined;
+    }
+    const encoded = normalized.slice(prefix.length, -2);
+    if (!encoded || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(encoded)) {
+        return undefined;
+    }
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(Buffer.from(encoded, "base64"));
+    }
+    catch {
+        return undefined;
+    }
+}
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function normalizeCacheHint(value, field) {
+    if (!isRecord(value))
+        throw new TypeError(`${field} cacheHint must be an object`);
+    const unknownField = Object.keys(value).find((key) => key !== "ttlMs" && key !== "cacheScope");
+    if (unknownField)
+        throw new TypeError(`${field} cacheHint has an unknown field: ${unknownField}`);
+    const { ttlMs, cacheScope } = value;
+    if (ttlMs !== undefined && (!Number.isSafeInteger(ttlMs) || ttlMs < 0)) {
+        throw new TypeError(`${field} cacheHint.ttlMs must be a non-negative safe integer`);
+    }
+    if (cacheScope !== undefined && cacheScope !== "public" && cacheScope !== "private") {
+        throw new TypeError(`${field} cacheHint.cacheScope must be public or private`);
+    }
+    return Object.freeze({
+        ...(ttlMs === undefined ? {} : { ttlMs: ttlMs }),
+        ...(cacheScope === undefined ? {} : { cacheScope }),
+    });
+}
+function normalizeCacheHints(value, enabledMethods) {
+    if (!isRecord(value))
+        throw new TypeError("cacheHints must be an object");
+    const allowed = new Set(CACHEABLE_METHODS);
+    const normalized = {};
+    for (const [method, hint] of Object.entries(value)) {
+        if (!allowed.has(method))
+            throw new TypeError(`cacheHints has an unknown method: ${method}`);
+        if (hint === undefined)
+            continue;
+        if (!enabledMethods.has(method))
+            throw new TypeError(`cacheHints cannot configure disabled method: ${method}`);
+        normalized[method] = normalizeCacheHint(hint, `cacheHints.${method}`);
+    }
+    return Object.freeze(normalized);
+}
+function checkedInputResponses(responses) {
+    if (!responses)
+        return undefined;
+    const checked = {};
+    for (const [key, value] of Object.entries(responses)) {
+        const elicitation = specTypeSchemas.ElicitResult["~standard"].validate(value);
+        if ("value" in elicitation) {
+            checked[key] = elicitation.value;
+            continue;
+        }
+    }
+    return checked;
+}
+function checkedProtocolValue(type, value) {
+    let copy;
+    try {
+        assertJsonValue(value, new WeakSet(), true);
+        const encoded = JSON.stringify(structuredClone(value));
+        if (encoded === undefined)
+            throw new TypeError("value is not JSON data");
+        copy = JSON.parse(encoded);
+    }
+    catch {
+        throw new TypeError(`${type} metadata must be JSON data`);
+    }
+    const schema = specTypeSchemas[type];
+    const result = schema["~standard"].validate(copy);
+    if (result instanceof Promise || "issues" in result) {
+        throw new TypeError(`${type} metadata does not match the MCP schema`);
+    }
+    return deepFreeze(result.value);
+}
+function assertJsonValue(value, seen, allowUndefinedProperties = false) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new TypeError("number must be finite");
+        return;
+    }
+    if (typeof value !== "object")
+        throw new TypeError("value is not JSON data");
+    if (seen.has(value))
+        throw new TypeError("value is cyclic");
+    seen.add(value);
+    if (Array.isArray(value)) {
+        if (Reflect.ownKeys(value).length !== value.length + 1) {
+            throw new TypeError("JSON arrays must contain only indexed values");
+        }
+        for (let index = 0; index < value.length; index += 1) {
+            if (!(index in value))
+                throw new TypeError("array must not be sparse");
+            assertJsonValue(value[index], seen);
+        }
+        seen.delete(value);
+        return;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+        throw new TypeError("object must be a plain JSON object");
+    }
+    if (Reflect.ownKeys(value).length !== Object.keys(value).length) {
+        throw new TypeError("JSON object keys must be enumerable strings");
+    }
+    for (const child of Object.values(value)) {
+        if (child === undefined && allowUndefinedProperties)
+            continue;
+        assertJsonValue(child, seen);
+    }
+    seen.delete(value);
+}
+function deepFreeze(value) {
+    if (value === null || typeof value !== "object" || Object.isFrozen(value))
+        return value;
+    for (const child of Object.values(value))
+        deepFreeze(child);
+    return Object.freeze(value);
+}
+function jsonMetadataSchema(schema, io) {
+    return { ...z.toJSONSchema(schema, { target: "draft-2020-12", io }) };
+}
+function promptArguments(schema) {
+    const jsonSchema = jsonMetadataSchema(schema, "input");
+    const properties = isRecord(jsonSchema.properties) ? jsonSchema.properties : {};
+    const required = new Set(Array.isArray(jsonSchema.required) ? jsonSchema.required : []);
+    return Object.freeze(Object.entries(properties).map(([name, property]) => Object.freeze({
+        name,
+        ...(isRecord(property) && typeof property.description === "string"
+            ? { description: property.description }
+            : {}),
+        required: required.has(name),
+    })));
+}
 function sdkMetadataSchema(schema) {
     return {
         "~standard": {
@@ -723,12 +1228,63 @@ function sdkMetadataSchema(schema) {
             vendor: "emseepea",
             validate: (value) => ({ value }),
             jsonSchema: {
-                input: () => z.toJSONSchema(schema, { target: "draft-2020-12", io: "input" }),
-                output: () => z.toJSONSchema(schema, { target: "draft-2020-12", io: "output" }),
+                input: () => jsonMetadataSchema(schema, "input"),
+                output: () => jsonMetadataSchema(schema, "output"),
             },
         },
     };
 }
+const MCP_HEADER_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+function assertValidMcpHeaderAnnotations(schema) {
+    const jsonSchema = z.toJSONSchema(schema, { target: "draft-2020-12", io: "input" });
+    const names = new Set();
+    function visit(value, path, reachable) {
+        if (!isRecord(value))
+            return;
+        if ("x-mcp-header" in value) {
+            const name = value["x-mcp-header"];
+            const location = path.join(".") || "the schema root";
+            if (!reachable || path.length === 0) {
+                throw new TypeError(`Tool x-mcp-header at ${location} is not reachable through properties`);
+            }
+            if (typeof name !== "string" || !MCP_HEADER_NAME.test(name)) {
+                throw new TypeError(`Tool x-mcp-header at ${location} must be a non-empty HTTP header token`);
+            }
+            if (value.type !== "string" && value.type !== "integer" && value.type !== "boolean") {
+                throw new TypeError(`Tool x-mcp-header at ${location} must describe a string, integer, or boolean`);
+            }
+            const normalized = name.toLowerCase();
+            if (names.has(normalized)) {
+                throw new TypeError(`Tool x-mcp-header name is duplicated: ${name}`);
+            }
+            names.add(normalized);
+        }
+        if (isRecord(value.properties)) {
+            for (const [property, propertySchema] of Object.entries(value.properties)) {
+                visit(propertySchema, [...path, property], reachable);
+            }
+        }
+        for (const key of ["prefixItems", "oneOf", "anyOf", "allOf"]) {
+            const schemas = value[key];
+            if (Array.isArray(schemas))
+                for (const child of schemas)
+                    visit(child, path, false);
+        }
+        for (const key of [
+            "items", "contains", "additionalProperties", "unevaluatedProperties",
+            "unevaluatedItems", "propertyNames", "not", "if", "then", "else",
+        ]) {
+            visit(value[key], path, false);
+        }
+        for (const key of ["patternProperties", "dependentSchemas", "$defs", "definitions"]) {
+            const schemas = value[key];
+            if (isRecord(schemas))
+                for (const child of Object.values(schemas))
+                    visit(child, path, false);
+        }
+    }
+    visit(jsonSchema, [], true);
+}
 function checkedCompletionHandlers(kind, complete, allowedNames) {
     if (complete === undefined)
         return new Map();
@@ -963,12 +1519,30 @@ function positiveInteger(field, value) {
         throw new TypeError(`${field} must be a positive safe integer`);
     return value;
 }
+function callbackTimeout(callbackName, callback, timeoutName, value) {
+    if (callback !== undefined && typeof callback !== "function")
+        throw new TypeError(`${callbackName} must be a function`);
+    if (value !== undefined && callback === undefined)
+        throw new TypeError(`${timeoutName} requires ${callbackName}`);
+    const timeout = positiveInteger(timeoutName, value === undefined ? 1_000 : value);
+    if (timeout > 60_000)
+        throw new TypeError(`${timeoutName} must not exceed 60000`);
+    return timeout;
+}
 function nonNegativePort(value) {
     if (!Number.isSafeInteger(value) || value < 0 || value > 65_535) {
         throw new TypeError("port must be an integer from 0 to 65535");
     }
     return value;
 }
+function assertStatelessInputRequired(result) {
+    if (!result.inputRequests || result.requestState !== undefined) {
+        throw new Error("Client-input requests must be stateless");
+    }
+    if (Object.values(result.inputRequests).some((request) => request.method !== "elicitation/create")) {
+        throw new Error("Client-input request kind is not supported");
+    }
+}
 function assertResultSize(result, maxApplicationResultBytes, deadlineMs, signal) {
     let serialized;
     try {
@@ -987,14 +1561,52 @@ function assertResultSize(result, maxApplicationResultBytes, deadlineMs, signal)
 function isLoopbackHost(host) {
     return host === "127.0.0.1" || host === "::1" || host === "localhost";
 }
-async function closeApp(app, timeoutMs) {
+async function closeApp(app, timeoutMs, flushTelemetry, flushTimeoutMs, finishTelemetry) {
     let timer;
+    let onClosed;
+    const httpClosed = new Promise((resolve) => { onClosed = resolve; });
+    app.server.once("close", onClosed);
     const timeout = new Promise((resolve) => {
-        timer = setTimeout(() => { app.server.closeAllConnections(); resolve(); }, timeoutMs);
+        timer = setTimeout(() => {
+            app.server.close();
+            app.server.closeAllConnections();
+            resolve();
+        }, timeoutMs);
         timer.unref();
     });
-    await Promise.race([app.close(), timeout]);
-    if (timer)
-        clearTimeout(timer);
+    try {
+        await Promise.race([app.close(), timeout]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        if (flushTelemetry) {
+            const controller = new AbortController();
+            const flushDeadline = Date.now() + flushTimeoutMs;
+            const expired = new Promise((resolve) => {
+                // Keep the process alive long enough to finish flushing after sockets close.
+                timer = setTimeout(() => { controller.abort(); resolve(); }, flushTimeoutMs);
+            });
+            try {
+                await Promise.race([
+                    httpClosed.then(async () => {
+                        await finishTelemetry?.();
+                        if (!controller.signal.aborted && Date.now() < flushDeadline) {
+                            await flushTelemetry({ signal: controller.signal });
+                        }
+                    }).catch(() => { }),
+                    expired,
+                ]);
+            }
+            finally {
+                if (timer)
+                    clearTimeout(timer);
+                app.server.off("close", onClosed);
+            }
+        }
+        else {
+            app.server.off("close", onClosed);
+        }
+    }
 }
 //# sourceMappingURL=index.js.map