@convertcom/mcp-server 0.0.1-beta.15 → 0.0.1-beta.16

package/build/runtime.d.ts

@@ -1,16 +1,18 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { type CallToolRequest, type CallToolResult, type Implementation, type ReadResourceResult, type Resource, type Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';
+import { type CallToolRequest, type CallToolResult, type GetPromptRequest, type ReadResourceRequest, type ClientRequest, type Implementation, type ListResourcesResult, type ReadResourceResult, type Resource, type ServerNotification, type Tool } from '@modelcontextprotocol/sdk/types.js';
 import type { ToolExecutionContext } from './auth-context.js';
 import { type CatalogChangeRequest } from './catalog-change.js';
 import { type KbChunk, type KbDocument, type SearchResult } from './kb-search.js';
 export declare const SERVER_NAME = "convert-api";
-export declare const SERVER_VERSION_FALLBACK = "0.0.1-beta.15";
+export declare const SERVER_VERSION_FALLBACK = "0.0.1-beta.16";
+export declare const MAX_SEARCH_QUERY_CHARACTERS = 500;
 export type ExecutionContextResolver = (extra: any, request: CallToolRequest) => ToolExecutionContext | undefined | Promise<ToolExecutionContext | undefined>;
 export type ToolCatalogContextResolver = (extra: any) => ToolExecutionContext | undefined | Promise<ToolExecutionContext | undefined>;
 export type DocsSearchProvider = {
-    search(query: string, limit?: number): SearchResult[] | Promise<SearchResult[]>;
-    getById(id: string): KbChunk | null | Promise<KbChunk | null>;
-    getDocumentById?(id: string): KbDocument | null | Promise<KbDocument | null>;
+    search(query: string, limit?: number, signal?: AbortSignal): SearchResult[] | Promise<SearchResult[]>;
+    getById(id: string, signal?: AbortSignal): KbChunk | null | Promise<KbChunk | null>;
+    getDocumentById?(id: string, signal?: AbortSignal): KbDocument | null | Promise<KbDocument | null>;
 };
 export type RuntimeLogger = {
     log(event: string, payload?: unknown): void;
@@ -34,6 +36,8 @@ export type RuntimeResourceProvider = {
 };
 export type ConvertMcpRuntimeOptions = {
     docs: DocsSearchProvider;
+    /** Disable only where the serving transport cannot scope list-change delivery safely. */
+    advertiseListChanged?: boolean;
     executionContextResolver?: ExecutionContextResolver;
     toolCatalogContextResolver?: ToolCatalogContextResolver;
     logger?: RuntimeLogger;
@@ -47,12 +51,224 @@ export type ConvertMcpRuntimeOptions = {
     toolExtensions?: RuntimeToolExtension[];
     resourceProvider?: RuntimeResourceProvider;
     toolDecorator?: (tool: Tool) => Tool;
+    /** Bounded authorization-shape cache supplied only by transports with stable configuration. */
+    toolCatalogCache?: Map<string, RuntimeToolCatalogSnapshot>;
+    /** Shares deterministic tool-catalog digests across stateless modern requests. */
+    toolCatalogRevisionCache?: Map<string, Promise<string>>;
+    /** Must cover every dynamic input used by toolDecorator; never include bearer or principal data. */
+    toolCatalogDecoratorCacheKey?: () => string;
     serverInstructions?: string | ((toolSet: string) => string);
     catalogChangeNotifier?: (request: CatalogChangeRequest) => Promise<void>;
 };
+export type RuntimeToolCatalogSnapshot = {
+    tools: Tool[];
+    toolsByName: ReadonlyMap<string, Tool>;
+};
+export type RuntimeRequestExtra = Pick<RequestHandlerExtra<ClientRequest, ServerNotification>, 'sendNotification' | 'signal' | 'requestId'> & {
+    clientInfo?: Implementation;
+};
+export type RuntimeToolResolutionObserver = (tool: Tool | undefined) => void;
 export declare const SERVER_INSTRUCTIONS: string;
 export declare function serverInstructionsForToolSet(toolSet: string, renderToolNames?: readonly string[]): string;
 export declare const canonicalSearchTool: Tool;
 export declare const canonicalFetchTool: Tool;
 export declare function getToolsForClient(toolSet?: string, feedbackEnabled?: boolean, executionContext?: ToolExecutionContext): Tool[];
+export type ConvertMcpServerIdentityOptions = Pick<ConvertMcpRuntimeOptions, 'serverVersion' | 'serverTitle' | 'iconBaseUrl' | 'websiteUrl' | 'toolsForClient' | 'serverInstructions'>;
+export declare function convertMcpServerDefinition(options: ConvertMcpServerIdentityOptions): {
+    implementation: {
+        name: string;
+        version: string;
+        title: string;
+        description: string;
+        websiteUrl: string;
+        icons: {
+            src: string;
+            mimeType?: string | undefined;
+            sizes?: string[] | undefined;
+            theme?: "light" | "dark" | undefined;
+        }[];
+    };
+    options: {
+        capabilities: {
+            tools: {
+                listChanged: boolean;
+            };
+            prompts: {
+                listChanged: boolean;
+            };
+            resources: {
+                listChanged: boolean;
+            };
+        };
+        instructions: string;
+    };
+};
 export declare function createConvertMcpServer(options: ConvertMcpRuntimeOptions): Server;
+export declare function createConvertMcpHandlers(options: ConvertMcpRuntimeOptions, clientInfoFor: (extra: RuntimeRequestExtra) => Implementation | undefined): {
+    listTools: (extra: RuntimeRequestExtra) => Promise<{
+        tools: {
+            inputSchema: {
+                [x: string]: unknown;
+                type: "object";
+                properties?: {
+                    [x: string]: object;
+                } | undefined;
+                required?: string[] | undefined;
+            };
+            name: string;
+            description?: string | undefined;
+            outputSchema?: {
+                [x: string]: unknown;
+                type: "object";
+                properties?: {
+                    [x: string]: object;
+                } | undefined;
+                required?: string[] | undefined;
+            } | undefined;
+            annotations?: {
+                title?: string | undefined;
+                readOnlyHint?: boolean | undefined;
+                destructiveHint?: boolean | undefined;
+                idempotentHint?: boolean | undefined;
+                openWorldHint?: boolean | undefined;
+            } | undefined;
+            execution?: {
+                taskSupport?: "required" | "optional" | "forbidden" | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+            icons?: {
+                src: string;
+                mimeType?: string | undefined;
+                sizes?: string[] | undefined;
+                theme?: "light" | "dark" | undefined;
+            }[] | undefined;
+            title?: string | undefined;
+        }[];
+    }>;
+    listResources: (extra: RuntimeRequestExtra) => Promise<ListResourcesResult>;
+    listResourceTemplates: (extra: RuntimeRequestExtra) => Promise<{
+        resourceTemplates: never[];
+    }>;
+    readResource: (request: ReadResourceRequest, extra: RuntimeRequestExtra) => Promise<ReadResourceResult>;
+    listPrompts: (extra: RuntimeRequestExtra) => Promise<{
+        prompts: {
+            name: string;
+            description?: string | undefined;
+            arguments?: {
+                name: string;
+                description?: string | undefined;
+                required?: boolean | undefined;
+            }[] | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+            icons?: {
+                src: string;
+                mimeType?: string | undefined;
+                sizes?: string[] | undefined;
+                theme?: "light" | "dark" | undefined;
+            }[] | undefined;
+            title?: string | undefined;
+        }[];
+    }>;
+    getPrompt: (request: GetPromptRequest, extra: RuntimeRequestExtra) => Promise<{
+        [x: string]: unknown;
+        messages: {
+            role: "user" | "assistant";
+            content: {
+                type: "text";
+                text: string;
+                annotations?: {
+                    audience?: ("user" | "assistant")[] | undefined;
+                    priority?: number | undefined;
+                    lastModified?: string | undefined;
+                } | undefined;
+                _meta?: {
+                    [x: string]: unknown;
+                } | undefined;
+            } | {
+                type: "image";
+                data: string;
+                mimeType: string;
+                annotations?: {
+                    audience?: ("user" | "assistant")[] | undefined;
+                    priority?: number | undefined;
+                    lastModified?: string | undefined;
+                } | undefined;
+                _meta?: {
+                    [x: string]: unknown;
+                } | undefined;
+            } | {
+                type: "audio";
+                data: string;
+                mimeType: string;
+                annotations?: {
+                    audience?: ("user" | "assistant")[] | undefined;
+                    priority?: number | undefined;
+                    lastModified?: string | undefined;
+                } | undefined;
+                _meta?: {
+                    [x: string]: unknown;
+                } | undefined;
+            } | {
+                uri: string;
+                name: string;
+                type: "resource_link";
+                description?: string | undefined;
+                mimeType?: string | undefined;
+                size?: number | undefined;
+                annotations?: {
+                    audience?: ("user" | "assistant")[] | undefined;
+                    priority?: number | undefined;
+                    lastModified?: string | undefined;
+                } | undefined;
+                _meta?: {
+                    [x: string]: unknown;
+                } | undefined;
+                icons?: {
+                    src: string;
+                    mimeType?: string | undefined;
+                    sizes?: string[] | undefined;
+                    theme?: "light" | "dark" | undefined;
+                }[] | undefined;
+                title?: string | undefined;
+            } | {
+                type: "resource";
+                resource: {
+                    uri: string;
+                    text: string;
+                    mimeType?: string | undefined;
+                    _meta?: {
+                        [x: string]: unknown;
+                    } | undefined;
+                } | {
+                    uri: string;
+                    blob: string;
+                    mimeType?: string | undefined;
+                    _meta?: {
+                        [x: string]: unknown;
+                    } | undefined;
+                };
+                annotations?: {
+                    audience?: ("user" | "assistant")[] | undefined;
+                    priority?: number | undefined;
+                    lastModified?: string | undefined;
+                } | undefined;
+                _meta?: {
+                    [x: string]: unknown;
+                } | undefined;
+            };
+        }[];
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+        description?: string | undefined;
+    }>;
+    callTool: (request: CallToolRequest, extra: RuntimeRequestExtra, onToolResolved?: RuntimeToolResolutionObserver) => Promise<CallToolResult>;
+};

package/build/runtime.js

@@ -9,8 +9,11 @@ import { getPrompt, listPrompts } from './prompts.js';
 import { composeResourceProviders, investigationPlaybookResourceProvider, } from './investigation-playbook.js';
 import { JSON_SCHEMA_DRAFT_2020_12, tryParseJsonLike } from './shared.js';
 import { displayKbTitle } from './kb-search.js';
+import { applyFalsyRequestIdCancellationCompat } from './mcp-server-compat.js';
 export const SERVER_NAME = 'convert-api';
-export const SERVER_VERSION_FALLBACK = '0.0.1-beta.15';
+export const SERVER_VERSION_FALLBACK = '0.0.1-beta.16';
+export const MAX_SEARCH_QUERY_CHARACTERS = 500;
+const MAX_RUNTIME_TOOL_CATALOG_VARIANTS = 16;
 const noopLogger = { log: () => { } };
 function failOpenLogger(logger) {
     return {
@@ -175,6 +178,7 @@ export const canonicalSearchTool = {
         properties: {
             query: {
                 type: 'string',
+                maxLength: MAX_SEARCH_QUERY_CHARACTERS,
                 description: 'Search query for Convert.com documentation.',
             },
         },
@@ -250,15 +254,47 @@ export const canonicalFetchTool = {
 export function getToolsForClient(toolSet = 'reporting', feedbackEnabled = true, executionContext) {
     return [canonicalSearchTool, canonicalFetchTool, ...getNamespacedTools(toolSet, executionContext), ...getOperatorTools(toolSet, feedbackEnabled)];
 }
-function getRuntimeTools(options, toolSet, executionContext) {
+function getRuntimeToolCatalog(options, toolSet, executionContext) {
+    const feedbackEnabled = resolveBooleanOption(options.feedbackEnabled);
+    const notificationsEnabled = resolveBooleanOption(options.notificationsEnabled);
+    const decoratorKey = options.toolCatalogDecoratorCacheKey?.();
+    const cacheKey = options.toolCatalogCache && (!options.toolDecorator || decoratorKey !== undefined)
+        ? [
+            toolSet,
+            `feedback=${feedbackEnabled}`,
+            `notifications=${notificationsEnabled}`,
+            `account-wide=${executionContext?.authorizedAccounts?.some((account) => account.projects === null) === true}`,
+            `decorator=${decoratorKey ?? 'none'}`,
+        ].join(':')
+        : undefined;
+    const cached = cacheKey ? options.toolCatalogCache?.get(cacheKey) : undefined;
+    if (cached)
+        return cached;
     const tools = [
-        ...getToolsForClient(toolSet, resolveBooleanOption(options.feedbackEnabled), {
+        ...getToolsForClient(toolSet, feedbackEnabled, {
             ...executionContext,
-            notificationsEnabled: resolveBooleanOption(options.notificationsEnabled),
+            notificationsEnabled,
         }),
         ...(options.toolExtensions ?? []).flatMap((extension) => extension.tools(toolSet)),
     ];
-    return options.toolDecorator ? tools.map(options.toolDecorator) : tools;
+    const decorated = options.toolDecorator ? tools.map(options.toolDecorator) : tools;
+    const snapshot = {
+        tools: decorated,
+        toolsByName: new Map(decorated.map((tool) => [tool.name, tool])),
+    };
+    if (cacheKey && options.toolCatalogCache) {
+        while (options.toolCatalogCache.size >= MAX_RUNTIME_TOOL_CATALOG_VARIANTS) {
+            const oldest = options.toolCatalogCache.keys().next().value;
+            if (typeof oldest !== 'string')
+                break;
+            options.toolCatalogCache.delete(oldest);
+        }
+        options.toolCatalogCache.set(cacheKey, snapshot);
+    }
+    return snapshot;
+}
+function getRuntimeTools(options, toolSet, executionContext) {
+    return getRuntimeToolCatalog(options, toolSet, executionContext).tools;
 }
 function canonicalKbId(id) {
     return id.startsWith('convert-kb:') ? id : `convert-kb:${id}`;
@@ -300,39 +336,59 @@ function resolveServerTitle(serverTitle) {
     const value = typeof serverTitle === 'function' ? serverTitle() : serverTitle;
     return value?.trim() || 'Convert MCP';
 }
-export function createConvertMcpServer(options) {
-    const logger = failOpenLogger(options.logger ?? noopLogger);
-    const resourceProvider = composeResourceProviders(investigationPlaybookResourceProvider, options.resourceProvider);
-    const hasResources = true;
+export function convertMcpServerDefinition(options) {
     const initialToolSet = resolveToolSet(options.toolsForClient);
     const instructions = typeof options.serverInstructions === 'function'
         ? options.serverInstructions(initialToolSet)
         : options.serverInstructions ?? serverInstructionsForToolSet(initialToolSet);
-    const server = new Server({
-        name: SERVER_NAME,
-        version: options.serverVersion ?? SERVER_VERSION_FALLBACK,
-        title: resolveServerTitle(options.serverTitle),
-        description: "Convert.com MCP tools for experimentation workflows, account data, and product documentation.",
-        websiteUrl: resolveWebsiteUrl(options.websiteUrl),
-        icons: convertBrandIcons(resolveIconBaseUrl(options.iconBaseUrl)),
-    }, {
-        capabilities: {
-            tools: { listChanged: true },
-            prompts: { listChanged: true },
-            ...(hasResources ? { resources: { listChanged: true } } : {}),
+    return {
+        implementation: {
+            name: SERVER_NAME,
+            version: options.serverVersion ?? SERVER_VERSION_FALLBACK,
+            title: resolveServerTitle(options.serverTitle),
+            description: "Convert.com MCP tools for experimentation workflows, account data, and product documentation.",
+            websiteUrl: resolveWebsiteUrl(options.websiteUrl),
+            icons: convertBrandIcons(resolveIconBaseUrl(options.iconBaseUrl)),
+        },
+        options: {
+            capabilities: {
+                tools: { listChanged: true },
+                prompts: { listChanged: true },
+                resources: { listChanged: true },
+            },
+            instructions,
         },
-        instructions,
-    });
+    };
+}
+export function createConvertMcpServer(options) {
+    const definition = convertMcpServerDefinition(options);
+    const server = new Server(definition.implementation, definition.options);
+    applyFalsyRequestIdCancellationCompat(server);
+    const handlers = createConvertMcpHandlers(options, () => server.getClientVersion());
+    server.setRequestHandler(ListToolsRequestSchema, (_request, extra) => handlers.listTools(extra));
+    server.setRequestHandler(ListResourcesRequestSchema, (_request, extra) => handlers.listResources(extra));
+    server.setRequestHandler(ListResourceTemplatesRequestSchema, (_request, extra) => handlers.listResourceTemplates(extra));
+    server.setRequestHandler(ReadResourceRequestSchema, (request, extra) => handlers.readResource(request, extra));
+    server.setRequestHandler(ListPromptsRequestSchema, (_request, extra) => handlers.listPrompts(extra));
+    server.setRequestHandler(GetPromptRequestSchema, (request, extra) => handlers.getPrompt(request, extra));
+    server.setRequestHandler(CallToolRequestSchema, (request, extra) => handlers.callTool(request, extra));
+    return server;
+}
+// Both protocol adapters register these same handlers. No transport may bypass
+// the namespace dispatcher, grant checks, or target-bound confirmations.
+export function createConvertMcpHandlers(options, clientInfoFor) {
+    const logger = failOpenLogger(options.logger ?? noopLogger);
+    const resourceProvider = composeResourceProviders(investigationPlaybookResourceProvider, options.resourceProvider);
     let staticCatalogRevisionsPromise;
-    const toolCatalogRevisionPromises = new Map();
-    const staticCatalogRevisions = () => {
+    const toolCatalogRevisionPromises = options.toolCatalogRevisionCache ?? new Map();
+    const staticCatalogRevisions = (extra) => {
         staticCatalogRevisionsPromise ??= Promise.all([
             catalogRevision(listPrompts()),
-            Promise.resolve(resourceProvider.listResources(server.getClientVersion())).then(catalogRevision),
+            Promise.resolve(resourceProvider.listResources(clientInfoFor(extra))).then(catalogRevision),
         ]).then(([prompts, resources]) => ({ prompts, resources }));
         return staticCatalogRevisionsPromise;
     };
-    const catalogRevisions = async (tools, cacheKey) => {
+    const catalogRevisions = async (tools, cacheKey, extra) => {
         let toolRevisionPromise = toolCatalogRevisionPromises.get(cacheKey);
         if (!toolRevisionPromise) {
             toolRevisionPromise = catalogRevision(tools);
@@ -340,7 +396,7 @@ export function createConvertMcpServer(options) {
         }
         const [toolRevision, staticRevisions] = await Promise.all([
             toolRevisionPromise,
-            staticCatalogRevisions(),
+            staticCatalogRevisions(extra),
         ]);
         return { tools: toolRevision, ...staticRevisions };
     };
@@ -366,6 +422,7 @@ export function createConvertMcpServer(options) {
         `feedback=${resolveBooleanOption(options.feedbackEnabled)}`,
         `notifications=${resolveBooleanOption(options.notificationsEnabled)}`,
         `account-wide=${context?.authorizedAccounts?.some((account) => account.projects === null) === true}`,
+        `decorator=${options.toolCatalogDecoratorCacheKey?.() ?? 'none'}`,
     ].join(':');
     const notifyCatalogChanges = async (requestedCatalog, extra, tools, cacheKey) => {
         if (!options.catalogChangeNotifier || !cacheKey)
@@ -373,7 +430,7 @@ export function createConvertMcpServer(options) {
         try {
             await options.catalogChangeNotifier({
                 requestedCatalog,
-                revisions: await catalogRevisions(tools, cacheKey),
+                revisions: await catalogRevisions(tools, cacheKey, extra),
                 sendNotification: extra.sendNotification,
             });
         }
@@ -390,7 +447,7 @@ export function createConvertMcpServer(options) {
             }
         }
     };
-    server.setRequestHandler(ListToolsRequestSchema, async (_request, extra) => {
+    const listToolsHandler = async (extra) => {
         const toolSet = resolveToolSet(options.toolsForClient);
         const resolvedCatalog = await resolveCatalogContextSafely(extra);
         const catalogContext = resolvedCatalog.context;
@@ -401,54 +458,62 @@ export function createConvertMcpServer(options) {
         // request can emit list_changed when the full catalog recovers.
         catalogCacheKey(toolSet, catalogContext));
         return { tools };
-    });
-    if (hasResources) {
-        server.setRequestHandler(ListResourcesRequestSchema, async (_request, extra) => {
-            const toolSet = resolveToolSet(options.toolsForClient);
+    };
+    const listResourcesHandler = async (extra) => {
+        const toolSet = resolveToolSet(options.toolsForClient);
+        if (options.catalogChangeNotifier) {
             const resolvedCatalog = await resolveCatalogContextSafely(extra);
             const catalogContext = resolvedCatalog.context;
             const tools = getRuntimeTools(options, toolSet, catalogContext);
             await notifyCatalogChanges('resources', extra, tools, resolvedCatalog.authoritative ? catalogCacheKey(toolSet, catalogContext) : undefined);
-            return { resources: await resourceProvider.listResources(server.getClientVersion()) };
-        });
-        server.setRequestHandler(ListResourceTemplatesRequestSchema, async (_request, extra) => {
+        }
+        return { resources: await resourceProvider.listResources(clientInfoFor(extra)) };
+    };
+    const listResourceTemplatesHandler = async (extra) => {
+        if (options.catalogChangeNotifier) {
             const toolSet = resolveToolSet(options.toolsForClient);
             const resolvedCatalog = await resolveCatalogContextSafely(extra);
             const catalogContext = resolvedCatalog.context;
             const tools = getRuntimeTools(options, toolSet, catalogContext);
             await notifyCatalogChanges(undefined, extra, tools, resolvedCatalog.authoritative ? catalogCacheKey(toolSet, catalogContext) : undefined);
-            return { resourceTemplates: [] };
-        });
-        server.setRequestHandler(ReadResourceRequestSchema, async (request, extra) => {
+        }
+        return { resourceTemplates: [] };
+    };
+    const readResourceHandler = async (request, extra) => {
+        if (options.catalogChangeNotifier) {
             const toolSet = resolveToolSet(options.toolsForClient);
             const resolvedCatalog = await resolveCatalogContextSafely(extra);
             const catalogContext = resolvedCatalog.context;
             const tools = getRuntimeTools(options, toolSet, catalogContext);
             await notifyCatalogChanges(undefined, extra, tools, resolvedCatalog.authoritative ? catalogCacheKey(toolSet, catalogContext) : undefined);
-            const result = await resourceProvider.readResource(request.params.uri, server.getClientVersion());
-            if (!result) {
-                throw new McpError(ErrorCode.InvalidParams, `Unknown resource URI: ${request.params.uri}`);
-            }
-            return result;
-        });
-    }
-    server.setRequestHandler(ListPromptsRequestSchema, async (_request, extra) => {
-        const toolSet = resolveToolSet(options.toolsForClient);
-        const resolvedCatalog = await resolveCatalogContextSafely(extra);
-        const catalogContext = resolvedCatalog.context;
-        const tools = getRuntimeTools(options, toolSet, catalogContext);
-        await notifyCatalogChanges('prompts', extra, tools, resolvedCatalog.authoritative ? catalogCacheKey(toolSet, catalogContext) : undefined);
+        }
+        const result = await resourceProvider.readResource(request.params.uri, clientInfoFor(extra));
+        if (!result) {
+            throw new McpError(ErrorCode.InvalidParams, `Unknown resource URI: ${request.params.uri}`);
+        }
+        return result;
+    };
+    const listPromptsHandler = async (extra) => {
+        if (options.catalogChangeNotifier) {
+            const toolSet = resolveToolSet(options.toolsForClient);
+            const resolvedCatalog = await resolveCatalogContextSafely(extra);
+            const catalogContext = resolvedCatalog.context;
+            const tools = getRuntimeTools(options, toolSet, catalogContext);
+            await notifyCatalogChanges('prompts', extra, tools, resolvedCatalog.authoritative ? catalogCacheKey(toolSet, catalogContext) : undefined);
+        }
         return { prompts: listPrompts() };
-    });
-    server.setRequestHandler(GetPromptRequestSchema, async (request, extra) => {
+    };
+    const getPromptHandler = async (request, extra) => {
         const toolSet = resolveToolSet(options.toolsForClient);
-        const resolvedCatalog = await resolveCatalogContextSafely(extra);
-        const catalogContext = resolvedCatalog.context;
-        const tools = getRuntimeTools(options, toolSet, catalogContext);
-        await notifyCatalogChanges(undefined, extra, tools, resolvedCatalog.authoritative ? catalogCacheKey(toolSet, catalogContext) : undefined);
+        if (options.catalogChangeNotifier) {
+            const resolvedCatalog = await resolveCatalogContextSafely(extra);
+            const catalogContext = resolvedCatalog.context;
+            const tools = getRuntimeTools(options, toolSet, catalogContext);
+            await notifyCatalogChanges(undefined, extra, tools, resolvedCatalog.authoritative ? catalogCacheKey(toolSet, catalogContext) : undefined);
+        }
         return getPrompt(request.params.name, request.params.arguments ?? {}, toolSet);
-    });
-    server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+    };
+    const callToolHandler = async (request, extra, onToolResolved) => {
         const { name: toolName, arguments: toolArgs } = request.params;
         const toolSet = resolveToolSet(options.toolsForClient);
         const executionContext = await options.executionContextResolver?.(extra, request);
@@ -456,7 +521,27 @@ export function createConvertMcpServer(options) {
             ? { context: executionContext, authoritative: true }
             : await resolveCatalogContextSafely(extra);
         const catalogContext = resolvedCatalog.context;
-        await notifyCatalogChanges(undefined, extra, getRuntimeTools(options, toolSet, catalogContext), resolvedCatalog.authoritative ? catalogCacheKey(toolSet, catalogContext) : undefined);
+        const lightweightBuiltin = toolName === 'search'
+            ? canonicalSearchTool
+            : toolName === 'fetch'
+                ? canonicalFetchTool
+                : undefined;
+        // Hosted modern HTTP creates one protocol Server per request. Avoid
+        // materializing and decorating the entire hosted catalog immediately
+        // before KB search/fetch solely to recover one static output schema. The
+        // legacy notifier path still reconciles the complete catalog, and a tool
+        // decorator is applied to the selected built-in so projection remains
+        // identical to its advertised definition.
+        const runtimeCatalog = options.catalogChangeNotifier || (onToolResolved && !lightweightBuiltin)
+            ? getRuntimeToolCatalog(options, toolSet, catalogContext)
+            : undefined;
+        const resolvedTool = lightweightBuiltin
+            ? (options.toolDecorator ? options.toolDecorator(lightweightBuiltin) : lightweightBuiltin)
+            : runtimeCatalog?.toolsByName.get(toolName);
+        onToolResolved?.(resolvedTool);
+        if (runtimeCatalog) {
+            await notifyCatalogChanges(undefined, extra, runtimeCatalog.tools, resolvedCatalog.authoritative ? catalogCacheKey(toolSet, catalogContext) : undefined);
+        }
         logger.log('callToolRequest', {
             toolName,
             hasAuthContext: Boolean(executionContext?.authContext || executionContext?.credentialsByAccount),
@@ -503,7 +588,16 @@ export function createConvertMcpServer(options) {
                         structuredContent: { error: "The 'query' argument is required for search." },
                     });
                 }
-                const results = await options.docs.search(query, 8);
+                if (query.length > MAX_SEARCH_QUERY_CHARACTERS) {
+                    logger.log('search.invalidArguments');
+                    const message = `The 'query' argument must be ${MAX_SEARCH_QUERY_CHARACTERS} characters or fewer.`;
+                    return omitStructuredContentOnError('search', {
+                        isError: true,
+                        content: [{ type: 'text', text: JSON.stringify({ error: message }) }],
+                        structuredContent: { error: message },
+                    });
+                }
+                const results = await options.docs.search(query, 8, extra.signal);
                 const payload = toSearchPayload(results);
                 logger.log('search.success', { matchCount: payload.results.length });
                 return {
@@ -534,9 +628,9 @@ export function createConvertMcpServer(options) {
                 }
                 const rawId = rawKbId(id);
                 const document = options.docs.getDocumentById
-                    ? await options.docs.getDocumentById(rawId)
+                    ? await options.docs.getDocumentById(rawId, extra.signal)
                     : null;
-                const chunk = document?.requested ?? await options.docs.getById(rawId);
+                const chunk = document?.requested ?? await options.docs.getById(rawId, extra.signal);
                 if (!chunk) {
                     const message = `Knowledge base document not found for id "${id}". Run search again and fetch one of the returned IDs.`;
                     logger.log('fetch.notFound');
@@ -656,8 +750,16 @@ export function createConvertMcpServer(options) {
             content: [{ type: 'text', text: `Error: Unknown tool requested: ${toolName}` }],
             structuredContent: { error: `Unknown tool: ${toolName}` },
         };
-    });
-    return server;
+    };
+    return {
+        listTools: listToolsHandler,
+        listResources: listResourcesHandler,
+        listResourceTemplates: listResourceTemplatesHandler,
+        readResource: readResourceHandler,
+        listPrompts: listPromptsHandler,
+        getPrompt: getPromptHandler,
+        callTool: callToolHandler,
+    };
 }
 const MAX_FETCH_TEXT_BYTES = 384 * 1024;
 function assembleKbDocument(document, sourceComplete) {