@emseepea/server 0.8.1 → 0.10.0

package/dist/index.js

@@ -4,15 +4,17 @@ import { toNodeHandler } from "@modelcontextprotocol/node";
 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 { readFileSync } from "node:fs";
 import { readdir, realpath } from "node:fs/promises";
 import { isIP } from "node:net";
-import { join } from "node:path";
+import { isAbsolute, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 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(spec), {
+    roots: sdkInputRequired.listRoots,
     elicit: sdkInputRequired.elicit,
     elicitUrl: sdkInputRequired.elicitUrl,
 });
@@ -23,6 +25,20 @@ export function inputResponse(responses, key) {
     const response = sdkInputResponse(checkedInputResponses(responses), key);
     return response.kind === "elicit" ? response : { kind: "missing" };
 }
+const checkedRootsResponses = new WeakSet();
+/** Reads roots validated by the framework; missing keys return undefined. */
+export function rootsResponse(responses, key) {
+    if (responses === undefined)
+        return undefined;
+    if (!checkedRootsResponses.has(responses))
+        throw new TypeError("Roots responses have not been checked");
+    if (!Object.hasOwn(responses, key))
+        return undefined;
+    const value = responses[key];
+    if (!isRecord(value) || !Array.isArray(value.roots))
+        throw new TypeError("Response is not roots");
+    return value.roots;
+}
 const PROTOCOL_VERSION = "2026-07-28";
 const LEGACY_PROTOCOL_VERSIONS = Object.freeze([
     "2025-11-25",
@@ -98,6 +114,51 @@ function createRequestStateRuntime(options) {
         },
     });
 }
+export function loadDeploymentProfile(environment = process.env) {
+    const mode = environment.EMSEEPEA_DEPLOYMENT_MODE;
+    const configPath = environment.EMSEEPEA_DEPLOYMENT_CONFIG_FILE;
+    if (mode === undefined) {
+        if (configPath !== undefined)
+            throw new TypeError("Deployment config requires an explicit deployment mode");
+        return { mode: "loopback" };
+    }
+    if (mode !== "production-behind-proxy")
+        throw new TypeError(`Unsupported deployment mode: ${mode}`);
+    if (!configPath || !isAbsolute(configPath)) {
+        throw new TypeError("Production deployment config must be an absolute file path");
+    }
+    const bytes = readFileSync(configPath);
+    if (bytes.byteLength > 16 * 1024)
+        throw new TypeError("Production deployment config exceeds 16 KiB");
+    const source = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    const parsed = z.strictObject({
+        allowedAuthorities: z.array(z.string()).min(1),
+        allowedOrigins: z.array(z.string()).min(1),
+        trustedProxyAddresses: z.array(z.string()).min(1),
+        rateLimit: z.strictObject({
+            maxRequests: z.number().int().positive(),
+            windowMs: z.number().int().positive(),
+            maxClients: z.number().int().positive(),
+        }),
+    }).parse(JSON.parse(source));
+    const profile = { mode, ...parsed };
+    const normalized = normalizeDeployment(profile);
+    if (normalized.mode !== "production-behind-proxy")
+        throw new TypeError("Production deployment config is invalid");
+    for (const [label, values, normalizedValues] of [
+        ["allowed authority", parsed.allowedAuthorities, normalized.allowedAuthorities],
+        ["allowed origin", parsed.allowedOrigins, normalized.allowedOrigins],
+        ["trusted proxy address", parsed.trustedProxyAddresses, normalized.trustedProxyAddresses],
+    ]) {
+        if (normalizedValues.size !== values.length)
+            throw new TypeError(`Duplicate ${label}`);
+    }
+    for (const address of parsed.trustedProxyAddresses) {
+        if (normalizeIp(address) !== address)
+            throw new TypeError(`Trusted proxy address is not normalized: ${address}`);
+    }
+    return profile;
+}
 export function defineTool(definition) {
     const handler = definition.handler;
     return createCheckedTool(definition, handler, false, true);
@@ -173,13 +234,13 @@ export function defineResource(definition) {
             value: listing,
         }),
         [HAS_COMPLETION]: false,
-        [REGISTER](server, timeoutMs, maxApplicationResultBytes, requestState) {
+        [REGISTER](server, timeoutMs, maxApplicationResultBytes, requestState, clientLogging) {
             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(directHandlerContext(access, context, signal, deadlineMs, requestState));
+                        const result = await withClientLogReporter(context, signal, clientLogging, (reportLog) => handler(directHandlerContext(access, context, signal, deadlineMs, requestState, reportLog)));
                         signal.throwIfAborted();
                         if (isInputRequiredResult(result)) {
                             await assertInputRequired(result, requestState, context);
@@ -245,7 +306,7 @@ export function defineResourceTemplate(definition) {
             value: listing,
         }),
         [HAS_COMPLETION]: completions.size > 0,
-        [REGISTER](server, timeoutMs, maxApplicationResultBytes, requestState) {
+        [REGISTER](server, timeoutMs, maxApplicationResultBytes, requestState, clientLogging) {
             const registeredTemplate = completions.size === 0
                 ? template
                 : new ResourceTemplate(uriTemplate, {
@@ -260,7 +321,7 @@ 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 }, directHandlerContext(access, context, signal, deadlineMs, requestState));
+                        const result = await withClientLogReporter(context, signal, clientLogging, (reportLog) => handler({ uri: requestedUri.href, variables }, directHandlerContext(access, context, signal, deadlineMs, requestState, reportLog)));
                         signal.throwIfAborted();
                         if (isInputRequiredResult(result)) {
                             await assertInputRequired(result, requestState, context);
@@ -311,7 +372,7 @@ export function definePrompt(definition) {
         [PROMPT_ACCESS]: access,
         [HAS_COMPLETION]: completions.size > 0,
         [PROMPT_LISTING]: listing,
-        [REGISTER](server, timeoutMs, maxApplicationResultBytes, requestState) {
+        [REGISTER](server, timeoutMs, maxApplicationResultBytes, requestState, clientLogging) {
             server.registerPrompt(name, {
                 ...metadata,
                 argsSchema: sdkPromptMetadataSchema(argsSchema, completions, argumentNames, timeoutMs, maxApplicationResultBytes),
@@ -323,7 +384,7 @@ export function definePrompt(definition) {
                         if (!parsedArgs.success)
                             throw new Error("Prompt received invalid arguments");
                         signal.throwIfAborted();
-                        const result = await handler(parsedArgs.data, directHandlerContext(access, context, signal, deadlineMs, requestState));
+                        const result = await withClientLogReporter(context, signal, clientLogging, (reportLog) => handler(parsedArgs.data, directHandlerContext(access, context, signal, deadlineMs, requestState, reportLog)));
                         signal.throwIfAborted();
                         if (isInputRequiredResult(result)) {
                             await assertInputRequired(result, requestState, context);
@@ -496,7 +557,10 @@ function createCheckedTool(definition, execute, streaming, allowsInputRequired)
         [TOOL_ACCESS]: access,
         [TOOL_STREAMING]: streaming,
         [TOOL_LISTING]: listing,
-        [REGISTER](server, timeoutMs, maxApplicationResultBytes, maxProgressEvents, maxProgressEventBytes, requestState) {
+        [REGISTER](server, timeoutMs, maxApplicationResultBytes, maxProgressEvents, maxProgressEventBytes, requestState, clientLogging) {
+            const runLoggedTool = clientLogging
+                ? createLoggedToolRunner(clientLogging, execute, allowsInputRequired, access, requestState)
+                : undefined;
             server.registerTool(name, metadata, async (input, context) => {
                 try {
                     const deadlineMs = requestOperations.getStore()?.deadlineMs ?? Date.now() + timeoutMs;
@@ -510,9 +574,12 @@ function createCheckedTool(definition, execute, streaming, allowsInputRequired)
                             ? progressReporter(context, signal, maxProgressEvents, maxProgressEventBytes)
                             : undefined;
                         let result;
-                        try {
-                            result = await execute(parsedInput.data, {
-                                ...(allowsInputRequired
+                        if (runLoggedTool) {
+                            result = await runLoggedTool(parsedInput.data, context, signal, deadlineMs, reporter);
+                        }
+                        else {
+                            try {
+                                const handlerContext = allowsInputRequired
                                     ? directHandlerContext(access, context, signal, deadlineMs, requestState)
                                     : {
                                         signal,
@@ -520,14 +587,16 @@ function createCheckedTool(definition, execute, streaming, allowsInputRequired)
                                         principal: access === "public"
                                             ? undefined
                                             : principalFrom(context.http?.authInfo),
-                                    }),
-                                ...(reporter ? { reportProgress: reporter.report } : {}),
-                            });
-                        }
-                        finally {
-                            await reporter?.finish();
+                                    };
+                                if (reporter)
+                                    Object.assign(handlerContext, { reportProgress: reporter.report });
+                                result = await execute(parsedInput.data, handlerContext);
+                            }
+                            finally {
+                                await reporter?.finish();
+                            }
+                            reporter?.throwIfFailed();
                         }
-                        reporter?.throwIfFailed();
                         if (allowsInputRequired && isInputRequiredResult(result)) {
                             signal.throwIfAborted();
                             await assertInputRequired(result, requestState, context);
@@ -561,6 +630,33 @@ function createCheckedTool(definition, execute, streaming, allowsInputRequired)
     };
     return Object.freeze(registration);
 }
+function createLoggedToolRunner(clientLogging, execute, allowsInputRequired, access, requestState) {
+    return async (input, context, signal, deadlineMs, reporter) => {
+        const logReporter = clientLogReporter(context, signal, clientLogging.maxEvents, clientLogging.maxEventBytes);
+        let result;
+        try {
+            result = await execute(input, {
+                ...(allowsInputRequired
+                    ? directHandlerContext(access, context, signal, deadlineMs, requestState, logReporter.report)
+                    : {
+                        signal,
+                        deadlineMs,
+                        principal: access === "public"
+                            ? undefined
+                            : principalFrom(context.http?.authInfo),
+                        reportLog: logReporter.report,
+                    }),
+                ...(reporter ? { reportProgress: reporter.report } : {}),
+            });
+        }
+        finally {
+            await Promise.all([reporter?.finish(), logReporter.finish()]);
+        }
+        reporter?.throwIfFailed();
+        logReporter.throwIfFailed();
+        return result;
+    };
+}
 function progressReporter(context, signal, maxEvents, maxEventBytes) {
     const token = context.mcpReq._meta?.progressToken;
     let closed = false;
@@ -616,6 +712,74 @@ function progressReporter(context, signal, maxEvents, maxEventBytes) {
             throw failure; },
     };
 }
+function clientLogReporter(context, signal, maxEvents, maxEventBytes) {
+    let closed = false;
+    let failure;
+    let attempts = 0;
+    const pending = new Set();
+    return {
+        report(message) {
+            if (closed)
+                return Promise.reject(new Error("Client logging is no longer available"));
+            if (failure)
+                return Promise.reject(failure);
+            const operation = (async () => {
+                try {
+                    signal.throwIfAborted();
+                    attempts += 1;
+                    if (attempts > maxEvents)
+                        throw new Error("Client log event limit exceeded");
+                    const notification = {
+                        method: "notifications/message",
+                        params: {
+                            level: message.level,
+                            data: message.data,
+                            ...(message.logger === undefined ? {} : { logger: message.logger }),
+                        },
+                    };
+                    assertJsonValue(notification, new WeakSet());
+                    const encoded = JSON.stringify(notification);
+                    if (Buffer.byteLength(encoded, "utf8") > maxEventBytes) {
+                        throw new Error("Client log event exceeds configured size limit");
+                    }
+                    const parsed = specTypeSchemas.LoggingMessageNotification["~standard"].validate(JSON.parse(encoded));
+                    if (parsed instanceof Promise || "issues" in parsed) {
+                        throw new Error("Client log event is invalid");
+                    }
+                    const params = parsed.value.params;
+                    await context.mcpReq.log(params.level, params.data, params.logger);
+                }
+                catch (error) {
+                    failure = error instanceof Error ? error : new Error("Client log emission failed");
+                    throw failure;
+                }
+            })();
+            pending.add(operation);
+            void operation.then(() => pending.delete(operation), () => pending.delete(operation));
+            return operation;
+        },
+        async finish() {
+            closed = true;
+            await Promise.allSettled(pending);
+        },
+        throwIfFailed() { if (failure)
+            throw failure; },
+    };
+}
+async function withClientLogReporter(context, signal, options, run) {
+    const reporter = options
+        ? clientLogReporter(context, signal, options.maxEvents, options.maxEventBytes)
+        : undefined;
+    let result;
+    try {
+        result = await run(reporter?.report);
+    }
+    finally {
+        await reporter?.finish();
+    }
+    reporter?.throwIfFailed();
+    return result;
+}
 function catalogueListings(tools, resources, prompts, supportedTools = tools, supportedResources = resources, supportedPrompts = prompts) {
     const catalogues = new Map();
     if (supportedTools.length)
@@ -778,10 +942,25 @@ export function createEmseepea(options) {
         ? normalizeListPagination(options.listPagination)
         : undefined;
     const maxRequestBytes = positiveInteger("maxRequestBytes", options.maxRequestBytes ?? 1024 * 1024);
+    if (options.clientRoots !== undefined && !isRecord(options.clientRoots)) {
+        throw new TypeError("clientRoots must be an object");
+    }
+    const maxClientRoots = options.clientRoots === undefined ? undefined
+        : positiveInteger("clientRoots.maxRoots", options.clientRoots.maxRoots === undefined ? 100 : options.clientRoots.maxRoots);
     const requestState = options.requestState
         ? createRequestStateRuntime(options.requestState)
         : undefined;
     const maxApplicationResultBytes = positiveInteger("maxApplicationResultBytes", options.maxApplicationResultBytes ?? 1024 * 1024);
+    const clientLoggingOptions = options.clientLogging;
+    if (clientLoggingOptions !== undefined && !isRecord(clientLoggingOptions)) {
+        throw new TypeError("clientLogging must be an object");
+    }
+    const clientLogging = clientLoggingOptions === undefined
+        ? undefined
+        : Object.freeze({
+            maxEvents: positiveInteger("clientLogging.maxEvents", clientLoggingOptions.maxEvents ?? 32),
+            maxEventBytes: positiveInteger("clientLogging.maxEventBytes", clientLoggingOptions.maxEventBytes ?? 8 * 1024),
+        });
     const maxProgressEvents = positiveInteger("maxProgressEvents", options.maxProgressEvents ?? 32);
     const maxProgressEventBytes = positiveInteger("maxProgressEventBytes", options.maxProgressEventBytes ?? 8 * 1024);
     const operationTimeoutMs = positiveInteger("operationTimeoutMs", options.operationTimeoutMs ?? 30_000);
@@ -861,6 +1040,7 @@ export function createEmseepea(options) {
             : discoverablePrompts;
         const activeHasCompletion = activeResources.some((resource) => resource[HAS_COMPLETION]) ||
             activePrompts.some((prompt) => prompt[HAS_COMPLETION]);
+        const activeClientLogging = request?.legacy ? undefined : clientLogging;
         const server = new McpServer(serverInfo, {
             capabilities: {
                 ...(activeTools.length ? { tools: { listChanged: false } } : {}),
@@ -872,6 +1052,7 @@ export function createEmseepea(options) {
                 } : {}),
                 ...(activePrompts.length ? { prompts: { listChanged: false } } : {}),
                 ...(activeHasCompletion ? { completions: {} } : {}),
+                ...(activeClientLogging ? { logging: {} } : {}),
             },
             instructions: options.instructions,
             cacheHints: request?.filterCatalogues || request?.legacy ? undefined : cacheHints,
@@ -879,13 +1060,13 @@ export function createEmseepea(options) {
             ...(requestState && !request?.legacy ? { requestState: { verify: requestState.verify } } : {}),
         });
         for (const tool of activeTools) {
-            tool[REGISTER](server, operationTimeoutMs, maxApplicationResultBytes, maxProgressEvents, maxProgressEventBytes, requestState);
+            tool[REGISTER](server, operationTimeoutMs, maxApplicationResultBytes, maxProgressEvents, maxProgressEventBytes, requestState, activeClientLogging);
         }
         for (const resource of activeResources) {
-            resource[REGISTER](server, operationTimeoutMs, maxApplicationResultBytes, requestState);
+            resource[REGISTER](server, operationTimeoutMs, maxApplicationResultBytes, requestState, activeClientLogging);
         }
         for (const prompt of activePrompts) {
-            prompt[REGISTER](server, operationTimeoutMs, maxApplicationResultBytes, requestState);
+            prompt[REGISTER](server, operationTimeoutMs, maxApplicationResultBytes, requestState, activeClientLogging);
         }
         const filteredCatalogues = request?.filterCatalogues
             ? catalogueListings(activeDiscoverableTools, activeDiscoverableResources, activeDiscoverablePrompts, activeTools, activeResources, activePrompts)
@@ -903,7 +1084,7 @@ export function createEmseepea(options) {
             installListPagination(server, pagination);
         return server;
     }, {
-        responseMode: hasStreaming || resourceSubscriptions ? "auto" : "json",
+        responseMode: hasStreaming || resourceSubscriptions || clientLogging ? "auto" : "json",
         keepAliveMs: 0,
     });
     const nodeHandler = toNodeHandler(sdkHandler);
@@ -1111,6 +1292,7 @@ export function createEmseepea(options) {
                 filterCatalogues: protectsCatalogue,
                 capability,
                 legacy,
+                maxClientRoots,
             }, () => nodeHandler(request.raw, reply.raw, request.body));
         }
         finally {
@@ -1313,7 +1495,7 @@ export async function serveEmseepea(app, options = {}) {
     const runtime = runtimes.get(app);
     if (!runtime)
         throw new TypeError("serveEmseepea requires an app created by createEmseepea");
-    const host = options.host ?? "127.0.0.1";
+    const host = options.host ?? (runtime.deployment.mode === "loopback" ? "127.0.0.1" : "0.0.0.0");
     if (runtime.deployment.mode === "loopback" && !isLoopbackHost(host)) {
         throw new TypeError("The loopback deployment profile cannot bind publicly");
     }
@@ -2083,31 +2265,88 @@ function nonNegativePort(value) {
     }
     return value;
 }
-function directHandlerContext(access, context, signal, deadlineMs, requestState) {
+function directHandlerContext(access, context, signal, deadlineMs, requestState, reportLog) {
     return {
         signal,
         deadlineMs,
         principal: access === "public" ? undefined : principalFrom(context.http?.authInfo),
-        inputResponses: checkedInputResponses(context.mcpReq.inputResponses),
+        inputResponses: checkedDirectInputResponses(context, signal, deadlineMs),
         ...(requestState ? {
             requestState: context.mcpReq.requestState(),
             mintRequestState: (payload) => requestState.mint(payload, context),
         } : {}),
+        ...(reportLog ? { reportLog } : {}),
     };
 }
 async function assertInputRequired(result, requestState, context) {
     if (!result.inputRequests && result.requestState === undefined) {
         throw new Error("Client-input result must include requests or state");
     }
-    if (result.inputRequests && Object.values(result.inputRequests).some((request) => request.method !== "elicitation/create")) {
+    if (result.inputRequests && Object.values(result.inputRequests).some((request) => request.method !== "elicitation/create" && request.method !== "roots/list")) {
         throw new Error("Client-input request kind is not supported");
     }
+    if (result.inputRequests && Object.values(result.inputRequests).some((request) => request.method === "roots/list")) {
+        const operation = requestOperations.getStore();
+        if (operation?.legacy || operation?.maxClientRoots === undefined) {
+            throw new Error("Client roots are unavailable for this request");
+        }
+        // The SDK checks outgoing requests against this round's client capabilities.
+    }
     if (result.requestState !== undefined) {
         if (!requestState)
             throw new Error("Client-input request state is not configured");
         await requestState.verify(result.requestState, context);
     }
 }
+function assertClientRootsEnabled(context) {
+    const operation = requestOperations.getStore();
+    const envelope = context.mcpReq.envelope;
+    const capabilities = isRecord(envelope) ? envelope["io.modelcontextprotocol/clientCapabilities"] : undefined;
+    if (operation?.legacy || operation?.maxClientRoots === undefined ||
+        !isRecord(capabilities) || !isRecord(capabilities.roots)) {
+        throw new Error("Client roots are unavailable for this request");
+    }
+    return operation.maxClientRoots;
+}
+function checkedDirectInputResponses(context, signal, deadlineMs) {
+    const operation = requestOperations.getStore();
+    if (operation?.maxClientRoots === undefined || operation.legacy) {
+        return checkedInputResponses(context.mcpReq.inputResponses);
+    }
+    if (context.mcpReq.droppedInputResponseKeys?.length)
+        throw new Error("Malformed client input response");
+    const responses = context.mcpReq.inputResponses;
+    if (responses === undefined)
+        return undefined;
+    const checked = Object.create(null);
+    for (const [key, value] of Object.entries(responses)) {
+        if (isRecord(value) && Object.hasOwn(value, "roots")) {
+            const maxRoots = assertClientRootsEnabled(context);
+            if (!Array.isArray(value.roots) || value.roots.length > maxRoots || Object.hasOwn(value, "action")) {
+                throw new Error("Invalid roots response");
+            }
+            const result = specTypeSchemas.ListRootsResult["~standard"].validate(value);
+            if (result instanceof Promise || "issues" in result)
+                throw new Error("Invalid roots response");
+            for (const root of result.value.roots) {
+                if (new URL(root.uri).protocol !== "file:")
+                    throw new Error("Invalid root URI");
+            }
+            checked[key] = deepFreeze(structuredClone(result.value));
+        }
+        else {
+            const result = specTypeSchemas.ElicitResult["~standard"].validate(value);
+            if (result instanceof Promise || "issues" in result)
+                throw new Error("Invalid client input response");
+            checked[key] = deepFreeze(structuredClone(result.value));
+        }
+    }
+    signal.throwIfAborted();
+    if (Date.now() >= deadlineMs)
+        throw new Error("Client input validation exceeded its deadline");
+    checkedRootsResponses.add(checked);
+    return Object.freeze(checked);
+}
 function assertResultSize(result, maxApplicationResultBytes, deadlineMs, signal) {
     let serialized;
     try {