@unchainedshop/api 4.8.20 → 4.8.22

package/README.md

@@ -141,14 +141,16 @@ The API exposes a complete GraphQL schema with:
 
 ## MCP Server
 
-Model Context Protocol server for AI agent integrations:
+Model Context Protocol server for AI agent integrations. `connect()` (Express or Fastify) automatically mounts a stateless MCP endpoint at `/mcp` (configurable via `MCP_API_PATH`). The endpoint requires an authenticated user with the `admin` role and serves 9 management tools plus the shop localization resources.
 
-```typescript
-import { createMCPServer } from '@unchainedshop/api/mcp';
+MCP support is an optional peer dependency:
 
-const mcpServer = createMCPServer(unchainedCore);
+```bash
+npm install @modelcontextprotocol/server
 ```
 
+Without it, the engine boots normally and `/mcp` responds with `503`. The chat handlers (`connect(..., { chat })`) additionally require the optional peers `ai` and `@ai-sdk/mcp` — and `@modelcontextprotocol/server` too, since chat derives its tool set through the engine's own `/mcp` endpoint.
+
 ## Security
 
 The API layer implements comprehensive security controls.

package/lib/chat/utils.d.ts

@@ -1,4 +1,6 @@
 import type * as aiTypes from 'ai';
+import type { ServerResponse } from 'node:http';
+export declare const logOptionalPeerLoadError: (packageName: string, error: unknown) => void;
 export type StreamTextParams = Parameters<typeof aiTypes.streamText>[0];
 export type ChatConfiguration = Omit<StreamTextParams, 'messages'> & {
     unchainedMCPUrl?: string;
@@ -8,4 +10,10 @@ export type ChatConfiguration = Omit<StreamTextParams, 'messages'> & {
     };
 };
 export declare const errorHandler: (error: any) => string;
+export declare const chatErrorStatus: (error: unknown) => number;
+export declare const createChatRequestLifecycle: (response: ServerResponse, configuredSignal?: AbortSignal) => {
+    signal: AbortSignal;
+    setClientClose(closeClient: () => Promise<void>): void;
+    close: () => Promise<void>;
+};
 export declare const categorizeTools: (toolName: string) => string;

package/lib/chat/utils.js

@@ -1,3 +1,14 @@
+import { createLogger } from '@unchainedshop/logger';
+import { isPeerNotInstalledError } from "../utils/optionalPeerError.js";
+const logger = createLogger('unchained:api:chat');
+export const logOptionalPeerLoadError = (packageName, error) => {
+    if (isPeerNotInstalledError(packageName, error)) {
+        logger.warn(`optional peer npm package '${packageName}' not installed, chat will not work`);
+    }
+    else {
+        logger.error(`failed to load '${packageName}'`, error);
+    }
+};
 let NoSuchToolError;
 let InvalidArgumentError;
 try {
@@ -8,9 +19,9 @@ try {
 catch {
 }
 export const errorHandler = (error) => {
-    if (NoSuchToolError.isInstance(error))
+    if (NoSuchToolError?.isInstance(error))
         return 'NoSuchToolError';
-    if (InvalidArgumentError.isInstance(error))
+    if (InvalidArgumentError?.isInstance(error))
         return 'InvalidToolArgumentsError';
     if (error?.message?.toLowerCase()?.includes('forbidden'))
         return 'NetworkError';
@@ -18,6 +29,47 @@ export const errorHandler = (error) => {
         return 'LimitExceeded';
     return `Failed to stream response: ${error?.message || 'Unknown error'}`;
 };
+export const chatErrorStatus = (error) => error?.statusCode === 503 ? 503 : 500;
+export const createChatRequestLifecycle = (response, configuredSignal) => {
+    const disconnectController = new AbortController();
+    const signal = configuredSignal
+        ? AbortSignal.any([configuredSignal, disconnectController.signal])
+        : disconnectController.signal;
+    let clientClose;
+    let closing;
+    const detach = () => {
+        response.off('close', abortOnDisconnect);
+        signal.removeEventListener('abort', closeAfterAbort);
+    };
+    const close = async () => {
+        detach();
+        if (!clientClose)
+            return;
+        closing ??= clientClose();
+        await closing;
+    };
+    const closeAfterAbort = () => {
+        void close().catch((error) => logger.error('Failed to close MCP chat client', error));
+    };
+    const abortOnDisconnect = () => {
+        if (!response.writableFinished && !disconnectController.signal.aborted) {
+            disconnectController.abort(new Error('Chat HTTP client disconnected'));
+        }
+    };
+    response.once('close', abortOnDisconnect);
+    signal.addEventListener('abort', closeAfterAbort, { once: true });
+    if (signal.aborted)
+        queueMicrotask(closeAfterAbort);
+    return {
+        signal,
+        setClientClose(closeClient) {
+            clientClose = closeClient;
+            if (signal.aborted)
+                closeAfterAbort();
+        },
+        close,
+    };
+};
 export const categorizeTools = (toolName) => {
     const name = toolName.toLowerCase();
     if (name.includes('product'))

package/lib/express/chatHandler.js

@@ -1,36 +1,36 @@
 import express from 'express';
-import { errorHandler } from "../chat/utils.js";
+import { chatErrorStatus, createChatRequestLifecycle, errorHandler, logOptionalPeerLoadError, } from "../chat/utils.js";
 import generateImageHandler from "../chat/generateImageHandler.js";
 import defaultSystemPrompt from "../chat/defaultSystemPrompt.js";
 import normalizeToolsIndex from "../chat/normalizeToolsIndex.js";
+import { buildChatResourceContext } from "../mcp/resources/localization.js";
 import { createLogger } from '@unchainedshop/logger';
 const logger = createLogger('unchained:api:chat');
 let convertToModelMessages;
 let stepCountIs;
 let streamText;
 let createMCPClient;
-let StreamableHTTPClientTransport;
-let Client;
 try {
     const aiTools = await import('ai');
-    const mcpTools = await import('@ai-sdk/mcp');
-    const mcpSDKClientLibrary = await import('@modelcontextprotocol/sdk/client/streamableHttp.js');
-    const mcpSDKClient = await import('@modelcontextprotocol/sdk/client/index.js');
-    StreamableHTTPClientTransport = mcpSDKClientLibrary.StreamableHTTPClientTransport;
-    Client = mcpSDKClient.Client;
     convertToModelMessages = aiTools.convertToModelMessages;
     stepCountIs = aiTools.stepCountIs;
     streamText = aiTools.streamText;
+}
+catch (error) {
+    logOptionalPeerLoadError('ai', error);
+}
+try {
+    const mcpTools = await import('@ai-sdk/mcp');
     createMCPClient = mcpTools.createMCPClient;
 }
-catch {
-    logger.warn(`optional peer npm packages 'ai', '@ai-sdk/mcp' and '@modelcontextprotocol/sdk' not installed, chat will not work`);
+catch (error) {
+    logOptionalPeerLoadError('@ai-sdk/mcp', error);
 }
 const setupMCPChatHandler = (chatConfiguration) => {
     if (!chatConfiguration || !chatConfiguration.model) {
         throw new Error('Model is required');
     }
-    const { tools: additionalTools = {}, unchainedMCPUrl = `${process.env.ROOT_URL}/mcp`, model, imageGenerationTool, ...restChatConfig } = chatConfiguration;
+    const { tools: additionalTools = {}, unchainedMCPUrl = `${process.env.ROOT_URL}/mcp`, model, imageGenerationTool, abortSignal: configuredAbortSignal, onAbort: configuredOnAbort, onEnd: configuredOnEnd, onFinish: configuredOnFinish, ...restChatConfig } = chatConfiguration;
     const system = chatConfiguration.system ?? defaultSystemPrompt;
     const mcpChatHandler = async (req, res) => {
         if (req.method === 'OPTIONS') {
@@ -43,50 +43,22 @@ const setupMCPChatHandler = (chatConfiguration) => {
             res.status(405).json({ error: 'Method Not Allowed. Use POST.' });
             return;
         }
-        const resourceTransport = new StreamableHTTPClientTransport(new URL(unchainedMCPUrl), {
-            requestInit: {
-                headers: {
-                    Cookie: req.headers.cookie || '',
-                },
-            },
-        });
-        const sdkClient = new Client({ name: 'unchained-chat-client', version: '1.0.0' });
-        await sdkClient.connect(resourceTransport);
-        const transport = new StreamableHTTPClientTransport(new URL(unchainedMCPUrl), {
-            requestInit: {
-                headers: {
-                    Cookie: req.headers.cookie || '',
-                },
-            },
-        });
-        const client = await createMCPClient({
-            transport,
-        });
+        let client;
+        const lifecycle = createChatRequestLifecycle(res, configuredAbortSignal);
         try {
+            client = await createMCPClient({
+                transport: {
+                    type: 'http',
+                    url: unchainedMCPUrl,
+                    headers: {
+                        Cookie: req.headers.cookie || '',
+                    },
+                },
+                initializationOptions: { signal: lifecycle.signal },
+            });
+            lifecycle.setClientClose(() => client.close());
             const defaultUnchainedTools = await client.tools();
-            let resourceContext = '';
-            try {
-                const resources = await sdkClient.listResources();
-                if (resources?.resources) {
-                    const resourceTexts = await Promise.all(resources.resources.map(async (resource) => {
-                        try {
-                            const content = await sdkClient.readResource({ uri: resource.uri });
-                            if (content?.contents?.[0]?.text) {
-                                return `${resource.name}:\n${content.contents[0].text}`;
-                            }
-                        }
-                        catch (e) {
-                            logger.error(`Failed to read resource ${resource.uri}: ${e.message}`);
-                        }
-                        return null;
-                    }));
-                    resourceContext =
-                        '\n\nAVAILABLE SHOP CONFIGURATION:\n' + resourceTexts.filter(Boolean).join('\n\n');
-                }
-            }
-            catch (e) {
-                logger.error(`Failed to fetch MCP resources: ${e.message}`);
-            }
+            const resourceContext = await buildChatResourceContext(req.unchainedContext);
             const tools = {
                 ...defaultUnchainedTools,
                 ...additionalTools,
@@ -95,6 +67,7 @@ const setupMCPChatHandler = (chatConfiguration) => {
                 tools.generateImage = generateImageHandler(req)(imageGenerationTool);
             }
             if (req.method === 'GET') {
+                await lifecycle.close();
                 res.status(200).json({
                     tools: normalizeToolsIndex(tools),
                     cached: false,
@@ -130,15 +103,28 @@ const setupMCPChatHandler = (chatConfiguration) => {
             }
             const messagesToInclude = normalizedMessages.slice(startIndex);
             const result = streamText({
-                stopWhen: stepCountIs(10),
-                temperature: 0.2,
+                stopWhen: stepCountIs(500),
                 maxRetries: 3,
                 ...restChatConfig,
+                abortSignal: lifecycle.signal,
                 system: system + resourceContext,
                 model,
                 tools: cacheControlledTools,
-                onFinish: async () => {
-                    await client?.close();
+                onEnd: async (event) => {
+                    try {
+                        await (configuredOnEnd ?? configuredOnFinish)?.(event);
+                    }
+                    finally {
+                        await lifecycle.close();
+                    }
+                },
+                onAbort: async (event) => {
+                    try {
+                        await configuredOnAbort?.(event);
+                    }
+                    finally {
+                        await lifecycle.close();
+                    }
                 },
                 messages: messagesToInclude,
                 providerOptions: {
@@ -149,20 +135,25 @@ const setupMCPChatHandler = (chatConfiguration) => {
                     },
                 },
             });
+            void result.finishReason.then(undefined, async () => {
+                await lifecycle.close();
+            });
             result.pipeUIMessageStreamToResponse(res, {
                 onError: errorHandler,
             });
         }
         catch (err) {
-            await client?.close();
-            await sdkClient?.close();
-            res.status(500).json({ error: errorHandler(err) });
+            logger.error(err);
+            await lifecycle.close();
+            if (lifecycle.signal.aborted || res.destroyed || res.writableEnded)
+                return;
+            res.status(chatErrorStatus(err)).json({ error: errorHandler(err) });
         }
     };
     return mcpChatHandler;
 };
 export const connectChat = (app, chatConfiguration) => {
-    if (!createMCPClient) {
+    if (!createMCPClient || !streamText) {
         logger.warn('Optional dependencies for AI SDK Chat Handler are not installed. Please install @ai-sdk/mcp and ai packages to use this feature.');
         return;
     }

package/lib/express/createMCPMiddleware.js

@@ -1,106 +1,25 @@
 import { createLogger } from '@unchainedshop/logger';
+import handleMcpHttpRequest from "../mcp/handleMcpHttpRequest.js";
+import { toWebRequest, sendWebResponse } from "../mcp/nodeHttpBridge.js";
 const logger = createLogger('unchained:api:mcp');
-let StreamableHTTPServerTransport;
-let isInitializeRequest;
-let McpServer;
-try {
-    const mcpSDKServerLibrary = await import('@modelcontextprotocol/sdk/server/streamableHttp.js');
-    const mcpSDKClient = await import('@modelcontextprotocol/sdk/types.js');
-    const mcpSDKServer = await import('@modelcontextprotocol/sdk/server/mcp.js');
-    McpServer = mcpSDKServer.McpServer;
-    StreamableHTTPServerTransport = mcpSDKServerLibrary.StreamableHTTPServerTransport;
-    isInitializeRequest = mcpSDKClient.isInitializeRequest;
-}
-catch {
-    logger.warn(`optional peer npm package '@modelcontextprotocol/sdk' not installed, mcp will not work`);
-}
-const transports = {};
-const handlePostRequest = async (req, res) => {
-    const sessionId = req.headers['mcp-session-id'];
-    const currentUserId = req.unchainedContext.user._id;
-    let transport;
-    if (sessionId && transports[sessionId]) {
-        if (transports[sessionId].userId !== currentUserId) {
-            res.status(404).json({
-                jsonrpc: '2.0',
-                error: {
-                    code: -32000,
-                    message: 'Bad Request: No valid session ID provided',
-                },
-                id: null,
-            });
+const createMCPMiddleware = async (req, res) => {
+    try {
+        if (req.method !== 'POST' && req.method !== 'GET' && req.method !== 'DELETE') {
+            res.status(405).send('Method Not Allowed');
             return;
         }
-        Object.assign(transports[sessionId].context, req.unchainedContext);
-        transport = transports[sessionId].transport;
-    }
-    else if (!sessionId && isInitializeRequest(req.body)) {
-        const contextHolder = req.unchainedContext;
-        transport = new StreamableHTTPServerTransport({
-            sessionIdGenerator: () => crypto.randomUUID(),
-            onsessioninitialized: (sessionId) => {
-                transports[sessionId] = { transport, userId: currentUserId, context: contextHolder };
-            },
-        });
-        transport.onclose = () => {
-            if (transport.sessionId) {
-                delete transports[transport.sessionId];
-            }
-        };
-        const roles = contextHolder.user?.roles || [];
-        const { default: initMCPServer } = await import("../mcp/index.js");
-        const server = initMCPServer(new McpServer({
-            name: 'Unchained MCP Server',
-            version: '1.0.0',
-        }), contextHolder, roles);
-        await server.connect(transport);
-    }
-    else {
-        res.status(400).json({
-            jsonrpc: '2.0',
-            error: {
-                code: -32000,
-                message: 'Bad Request: No valid session ID provided',
-            },
-            id: null,
-        });
-        return;
-    }
-    await transport.handleRequest(req, res, req.body);
-};
-const handleSessionRequest = async (req, res) => {
-    const sessionId = req.headers['mcp-session-id'];
-    if (!sessionId ||
-        !transports[sessionId] ||
-        transports[sessionId].userId !== req.unchainedContext.user._id) {
-        res.status(400).send('Invalid or missing session ID');
-        return;
-    }
-    Object.assign(transports[sessionId].context, req.unchainedContext);
-    const transport = transports[sessionId].transport;
-    await transport.handleRequest(req, res);
-};
-const createMCPMiddleware = (req, res, next) => {
-    const user = req.unchainedContext.user;
-    if (!user) {
-        res.status(401);
-        res.header('WWW-Authenticate', `Bearer realm="Unchained MCP", error="invalid_token", resource="${process.env.ROOT_URL || 'http://localhost:4010'}",`);
-        res.json({
-            error: 'invalid_token',
-            resource_metadata: `${process.env.ROOT_URL || 'http://localhost:4010'}/.well-known/oauth-protected-resource`,
-        });
-        return;
-    }
-    if (!(user.roles || []).includes('admin')) {
-        res.status(403).json({ error: 'forbidden', message: 'MCP requires admin privileges' });
-        return;
-    }
-    if (req.method === 'POST') {
-        return handlePostRequest(req, res, next);
-    }
-    else if (req.method === 'GET' || req.method === 'DELETE') {
-        return handleSessionRequest(req, res, next);
+        const bodyText = req.method === 'POST' && req.body !== undefined ? JSON.stringify(req.body) : undefined;
+        const response = await handleMcpHttpRequest(req.unchainedContext, toWebRequest(req, res, bodyText), req.method === 'POST' ? req.body : undefined);
+        await sendWebResponse(res, response);
+    }
+    catch (error) {
+        logger.error(error);
+        if (!res.headersSent) {
+            res.status(500).json({ error: 'Internal Server Error' });
+        }
+        else {
+            res.destroy();
+        }
     }
-    res.status(405).send('Method Not Allowed');
 };
 export default createMCPMiddleware;

package/lib/fastify/chatHandler.js

@@ -1,55 +1,47 @@
 import generateImageHandler from "../chat/generateImageHandler.js";
 import defaultSystemPrompt from "../chat/defaultSystemPrompt.js";
 import normalizeToolsIndex from "../chat/normalizeToolsIndex.js";
-import { errorHandler } from "../chat/utils.js";
+import { chatErrorStatus, createChatRequestLifecycle, errorHandler, logOptionalPeerLoadError, } from "../chat/utils.js";
+import { buildChatResourceContext } from "../mcp/resources/localization.js";
 import { createLogger } from '@unchainedshop/logger';
 const logger = createLogger('unchained:api:chat');
 let convertToModelMessages;
 let stepCountIs;
 let streamText;
 let createMCPClient;
-let StreamableHTTPClientTransport;
-let Client;
 try {
     const aiTools = await import('ai');
-    const mcpTools = await import('@ai-sdk/mcp');
-    const mcpSDKClientLibrary = await import('@modelcontextprotocol/sdk/client/streamableHttp.js');
-    const mcpSDKClient = await import('@modelcontextprotocol/sdk/client/index.js');
-    StreamableHTTPClientTransport = mcpSDKClientLibrary.StreamableHTTPClientTransport;
-    Client = mcpSDKClient.Client;
     convertToModelMessages = aiTools.convertToModelMessages;
     stepCountIs = aiTools.stepCountIs;
     streamText = aiTools.streamText;
+}
+catch (error) {
+    logOptionalPeerLoadError('ai', error);
+}
+try {
+    const mcpTools = await import('@ai-sdk/mcp');
     createMCPClient = mcpTools.createMCPClient;
 }
-catch {
-    logger.warn(`optional peer npm packages 'ai' and '@ai-sdk/mcp' not installed, chat will not work`);
+catch (error) {
+    logOptionalPeerLoadError('@ai-sdk/mcp', error);
 }
 const setupMCPChatHandler = (chatConfiguration) => {
     if (!chatConfiguration?.model) {
         throw new Error('Model is required');
     }
-    const { tools: additionalTools = {}, unchainedMCPUrl = `${process.env.ROOT_URL}/mcp`, imageGenerationTool, ...restChatConfig } = chatConfiguration;
+    const { tools: additionalTools = {}, unchainedMCPUrl = `${process.env.ROOT_URL}/mcp`, model, imageGenerationTool, abortSignal: configuredAbortSignal, onAbort: configuredOnAbort, onEnd: configuredOnEnd, onFinish: configuredOnFinish, ...restChatConfig } = chatConfiguration;
     const system = chatConfiguration.system ?? defaultSystemPrompt;
     const mcpChatHandler = async (req, res) => {
+        if (req.method === 'OPTIONS') {
+            res.headers({
+                'access-control-allow-credentials': 'true',
+                'access-control-allow-private-network': 'true',
+            });
+            return res.status(200).send();
+        }
         let client;
+        const lifecycle = createChatRequestLifecycle(res.raw, configuredAbortSignal);
         try {
-            if (req.method === 'OPTIONS') {
-                res.headers({
-                    'access-control-allow-credentials': 'true',
-                    'access-control-allow-private-network': 'true',
-                });
-                return res.status(200).send();
-            }
-            const resourceTransport = new StreamableHTTPClientTransport(new URL(unchainedMCPUrl), {
-                requestInit: {
-                    headers: {
-                        Cookie: req.headers.cookie || '',
-                    },
-                },
-            });
-            const sdkClient = new Client({ name: 'unchained-chat-client', version: '1.0.0' });
-            await sdkClient.connect(resourceTransport);
             client = await createMCPClient({
                 transport: {
                     type: 'http',
@@ -58,31 +50,11 @@ const setupMCPChatHandler = (chatConfiguration) => {
                         Cookie: req.headers.cookie || '',
                     },
                 },
+                initializationOptions: { signal: lifecycle.signal },
             });
+            lifecycle.setClientClose(() => client.close());
             const defaultUnchainedTools = await client.tools();
-            let resourceContext = '';
-            try {
-                const resources = await sdkClient.listResources();
-                if (resources?.resources) {
-                    const resourceTexts = await Promise.all(resources.resources.map(async (resource) => {
-                        try {
-                            const content = await sdkClient.readResource({ uri: resource.uri });
-                            if (content?.contents?.[0]?.text) {
-                                return `${resource.name}:\n${content.contents[0].text}`;
-                            }
-                        }
-                        catch (e) {
-                            logger.error(`Failed to read resource ${resource.uri}: ${e.message}`);
-                        }
-                        return null;
-                    }));
-                    resourceContext =
-                        '\n\nAVAILABLE SHOP CONFIGURATION:\n' + resourceTexts.filter(Boolean).join('\n\n');
-                }
-            }
-            catch (e) {
-                logger.error(`Failed to fetch MCP resources: ${e.message}`);
-            }
+            const resourceContext = await buildChatResourceContext(req.unchainedContext);
             const tools = {
                 ...defaultUnchainedTools,
                 ...additionalTools,
@@ -91,6 +63,7 @@ const setupMCPChatHandler = (chatConfiguration) => {
                 tools.generateImage = generateImageHandler(req)(imageGenerationTool);
             }
             if (req.method === 'GET') {
+                await lifecycle.close();
                 return res.status(200).send({
                     tools: normalizeToolsIndex(tools),
                     cached: false,
@@ -128,11 +101,26 @@ const setupMCPChatHandler = (chatConfiguration) => {
                 stopWhen: stepCountIs(500),
                 maxRetries: 3,
                 ...restChatConfig,
+                abortSignal: lifecycle.signal,
                 messages: messagesToInclude,
                 system: system + resourceContext,
+                model,
                 tools: cacheControlledTools,
-                onFinish: async () => {
-                    await client?.close();
+                onEnd: async (event) => {
+                    try {
+                        await (configuredOnEnd ?? configuredOnFinish)?.(event);
+                    }
+                    finally {
+                        await lifecycle.close();
+                    }
+                },
+                onAbort: async (event) => {
+                    try {
+                        await configuredOnAbort?.(event);
+                    }
+                    finally {
+                        await lifecycle.close();
+                    }
                 },
                 providerOptions: {
                     anthropic: {
@@ -142,21 +130,26 @@ const setupMCPChatHandler = (chatConfiguration) => {
                     },
                 },
             });
+            void result.finishReason.then(undefined, async () => {
+                await lifecycle.close();
+            });
             return res.send(result.toUIMessageStreamResponse({
                 onError: errorHandler,
             }));
         }
         catch (err) {
             logger.error(err);
-            await client?.close();
-            res.status(500);
+            await lifecycle.close();
+            if (lifecycle.signal.aborted || res.raw.destroyed)
+                return res;
+            res.status(chatErrorStatus(err));
             return res.send({ error: errorHandler(err) });
         }
     };
     return mcpChatHandler;
 };
 export const connectChat = (app, chatConfiguration) => {
-    if (!createMCPClient) {
+    if (!createMCPClient || !streamText) {
         logger.warn('Optional dependencies for AI SDK Chat Handler are not installed. Please install @ai-sdk/mcp and ai packages to use this feature.');
         return;
     }