Merge branch feat/decouple and fix all issue and lint

Author: jirispilka

.github/workflows/check.yaml

@@ -9,7 +9,6 @@ on:
     push:
         branches:
             - master
-            - 'feat/decouple'
         tags-ignore:
             - "**" # Ignore all tags to prevent duplicate builds when tags are pushed.
 
@@ -37,3 +36,6 @@ jobs:
 
             -   name: Test
                 run: npm run test
+
+            -   name: Type checks
+                run: npm run type-check

.github/workflows/pre_release.yaml

@@ -6,7 +6,6 @@ on:
     push:
         branches:
             - master
-            - 'feat/decouple'
         tags-ignore:
             - "**" # Ignore all tags to prevent duplicate builds when tags are pushed.
 

.nvmrc

@@ -0,0 +1 @@
+22.13.1

CHANGELOG.md

@@ -8,6 +8,7 @@ All notable changes to this project will be documented in this file.
 ### 🚀 Features
 
 - Local apify api base url (#71) ([581f096](https://github.com/apify/actors-mcp-server/commit/581f096030018aa9f1052151c5b628d9b186193b))
+- Add new specification regarding json response streamable http (#72) ([e918d26](https://github.com/apify/actors-mcp-server/commit/e918d26f224466cca58fa5ed35063c13054f9480))
 
 ### 🐛 Bug Fixes
 

eslint.config.mjs

@@ -1,9 +1,9 @@
-import apify from '@apify/eslint-config';
+import apifyTypeScriptConfig from '@apify/eslint-config/ts.js';
 
 // eslint-disable-next-line import/no-default-export
 export default [
-    { ignores: ['**/dist', '**/.venv'] }, // Ignores need to happen first
-    ...apify,
+    { ignores: ['**/dist'] }, // Ignores need to happen first
+    ...apifyTypeScriptConfig,
     {
         languageOptions: {
             sourceType: 'module',

package-lock.json

@@ -31,7 +31,7 @@
   ],
   "dependencies": {
     "@apify/log": "^2.5.16",
-    "@modelcontextprotocol/sdk": "^1.9.0",
+    "@modelcontextprotocol/sdk": "github:jirispilka/mcp-typescript-sdk#fix/add-src-dir",
     "ajv": "^8.17.1",
     "apify": "^3.4.0",
     "apify-client": "^2.12.1",
@@ -59,13 +59,13 @@
     "start": "npm run start:dev",
     "start:prod": "node dist/main.js",
     "start:dev": "tsx src/main.ts",
-    "lint": "./node_modules/.bin/eslint .",
-    "lint:fix": "./node_modules/.bin/eslint . --fix",
-    "build": "tsc",
-    "build:watch": "tsc -w",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "build": "tsc -b src",
+    "build:watch": "tsc -b src -w",
+    "type-check": "tsc --noEmit",
     "inspector": "npx @modelcontextprotocol/inspector dist/stdio.js",
     "test": "vitest run",
-    "type-check": "tsc --noEmit",
     "clean": "tsc -b src --clean"
   },
   "author": "Apify",

package.json

@@ -5,6 +5,14 @@ export const HEADER_READINESS_PROBE = 'x-apify-container-server-readiness-probe'
 
 export enum Routes {
     ROOT = '/',
+    MCP = '/mcp',
     SSE = '/sse',
     MESSAGE = '/message',
 }
+
+export const getHelpMessage = (host: string) => `To interact with the server you can either:
+- send request to ${host}${Routes.MCP}?token=YOUR-APIFY-TOKEN and receive a response
+or
+- connect for Server-Sent Events (SSE) via GET request to: ${host}${Routes.SSE}?token=YOUR-APIFY-TOKEN
+- send messages via POST request to: ${host}${Routes.MESSAGE}?token=YOUR-APIFY-TOKEN
+  (Include your message content in the request body.)`;

src/actor/const.ts

@@ -2,92 +2,171 @@
  * Express server implementation used for standby Actor mode.
  */
 
+import { randomUUID } from 'node:crypto';
+
 import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import type { Request, Response } from 'express';
 import express from 'express';
 
 import log from '@apify/log';
 
-import { HEADER_READINESS_PROBE, Routes } from './const.js';
 import { type ActorsMcpServer } from '../mcp/server.js';
-import { getActorRunData } from './utils.js';
 import { processParamsGetTools } from '../mcp/utils.js';
+import { getHelpMessage, HEADER_READINESS_PROBE, Routes } from './const.js';
+import { getActorRunData } from './utils.js';
 
 export function createExpressApp(
     host: string,
     mcpServer: ActorsMcpServer,
 ): express.Express {
-    const HELP_MESSAGE = `Connect to the server with GET request to ${host}/sse?token=YOUR-APIFY-TOKEN`
-        + ` and then send POST requests to ${host}/message?token=YOUR-APIFY-TOKEN`;
-
     const app = express();
+    app.use(express.json());
+    let transportSSE: SSEServerTransport;
+    const transports: { [sessionId: string]: StreamableHTTPServerTransport } = {};
 
-    let transport: SSEServerTransport;
+    function respondWithError(res: Response, error: unknown, logMessage: string, statusCode = 500) {
+        log.error(`${logMessage}: ${error}`);
+        if (!res.headersSent) {
+            res.status(statusCode).json({
+                jsonrpc: '2.0',
+                error: {
+                    code: statusCode === 500 ? -32603 : -32000,
+                    message: statusCode === 500 ? 'Internal server error' : 'Bad Request',
+                },
+                id: null,
+            });
+        }
+    }
 
-    app.route(Routes.ROOT)
-        .get(async (req: Request, res: Response) => {
-            if (req.headers && req.get(HEADER_READINESS_PROBE) !== undefined) {
-                log.debug('Received readiness probe');
-                res.status(200).json({ message: 'Server is ready' }).end();
-                return;
+    app.get(Routes.ROOT, async (req: Request, res: Response) => {
+        if (req.headers && req.get(HEADER_READINESS_PROBE) !== undefined) {
+            log.debug('Received readiness probe');
+            res.status(200).json({ message: 'Server is ready' }).end();
+            return;
+        }
+        try {
+            log.info(`Received GET message at: ${Routes.ROOT}`);
+            const tools = await processParamsGetTools(req.url, process.env.APIFY_TOKEN as string);
+            if (tools) {
+                mcpServer.updateTools(tools);
             }
-            try {
-                log.info(`Received GET message at: ${Routes.ROOT}`);
-                const tools = await processParamsGetTools(req.url, process.env.APIFY_TOKEN as string);
-                if (tools) {
-                    mcpServer.updateTools(tools);
-                }
-                res.setHeader('Content-Type', 'text/event-stream');
-                res.setHeader('Cache-Control', 'no-cache');
-                res.setHeader('Connection', 'keep-alive');
-                res.status(200).json({ message: `Actor is using Model Context Protocol. ${HELP_MESSAGE}`, data: getActorRunData() }).end();
-            } catch (error) {
-                log.error(`Error in GET ${Routes.ROOT} ${error}`);
-                res.status(500).json({ message: 'Internal Server Error' }).end();
+            res.setHeader('Content-Type', 'text/event-stream');
+            res.setHeader('Cache-Control', 'no-cache');
+            res.setHeader('Connection', 'keep-alive');
+            res.status(200).json({ message: `Actor is using Model Context Protocol. ${getHelpMessage(host)}`, data: getActorRunData() }).end();
+        } catch (error) {
+            respondWithError(res, error, `Error in GET ${Routes.ROOT}`);
+        }
+    });
+
+    app.head(Routes.ROOT, (_req: Request, res: Response) => {
+        res.status(200).end();
+    });
+
+    app.get(Routes.SSE, async (req: Request, res: Response) => {
+        try {
+            log.info(`Received GET message at: ${Routes.SSE}`);
+            const tools = await processParamsGetTools(req.url, process.env.APIFY_TOKEN as string);
+            if (tools) {
+                mcpServer.updateTools(tools);
             }
-        })
-        .head((_req: Request, res: Response) => {
-            res.status(200).end();
-        });
-
-    app.route(Routes.SSE)
-        .get(async (req: Request, res: Response) => {
-            try {
-                log.info(`Received GET message at: ${Routes.SSE}`);
-                const tools = await processParamsGetTools(req.url, process.env.APIFY_TOKEN as string);
-                if (tools) {
-                    mcpServer.updateTools(tools);
-                }
-                transport = new SSEServerTransport(Routes.MESSAGE, res);
-                await mcpServer.connect(transport);
-            } catch (error) {
-                log.error(`Error in GET ${Routes.SSE}: ${error}`);
-                res.status(500).json({ message: 'Internal Server Error' }).end();
+            transportSSE = new SSEServerTransport(Routes.MESSAGE, res);
+            await mcpServer.connect(transportSSE);
+        } catch (error) {
+            respondWithError(res, error, `Error in GET ${Routes.SSE}`);
+        }
+    });
+
+    app.post(Routes.MESSAGE, async (req: Request, res: Response) => {
+        try {
+            log.info(`Received POST message at: ${Routes.MESSAGE}`);
+            if (transportSSE) {
+                await transportSSE.handlePostMessage(req, res);
+            } else {
+                log.error('Server is not connected to the client.');
+                res.status(400).json({
+                    jsonrpc: '2.0',
+                    error: {
+                        code: -32000,
+                        message: 'Bad Request: Server is not connected to the client. '
+                        + 'Connect to the server with GET request to /sse endpoint',
+                    },
+                    id: null,
+                });
             }
-        });
-
-    app.route(Routes.MESSAGE)
-        .post(async (req: Request, res: Response) => {
-            try {
-                log.info(`Received POST message at: ${Routes.MESSAGE}`);
-                if (transport) {
-                    await transport.handlePostMessage(req, res);
-                } else {
-                    res.status(400).json({
-                        message: 'Server is not connected to the client. '
-                            + 'Connect to the server with GET request to /sse endpoint',
-                    });
+        } catch (error) {
+            respondWithError(res, error, `Error in POST ${Routes.MESSAGE}`);
+        }
+    });
+
+    app.post(Routes.MCP, async (req: Request, res: Response) => {
+        log.info('Received MCP request:', req.body);
+        try {
+            // Check for existing session ID
+            const sessionId = req.headers['mcp-session-id'] as string | undefined;
+            let transport: StreamableHTTPServerTransport;
+
+            if (sessionId && transports[sessionId]) {
+            // Reuse existing transport
+                transport = transports[sessionId];
+            } else if (!sessionId && isInitializeRequest(req.body)) {
+            // New initialization request - use JSON response mode
+                transport = new StreamableHTTPServerTransport({
+                    sessionIdGenerator: () => randomUUID(),
+                    enableJsonResponse: true, // Enable JSON response mode
+                });
+
+                // Connect the transport to the MCP server BEFORE handling the request
+                await mcpServer.connect(transport);
+
+                // After handling the request, if we get a session ID back, store the transport
+                await transport.handleRequest(req, res, req.body);
+
+                // Store the transport by session ID for future requests
+                if (transport.sessionId) {
+                    transports[transport.sessionId] = transport;
                 }
-            } catch (error) {
-                log.error(`Error in POST ${Routes.MESSAGE}: ${error}`);
-                res.status(500).json({ message: 'Internal Server Error' }).end();
+                return; // Already handled
+            } else {
+            // Invalid request - no session ID or not initialization request
+                res.status(400).json({
+                    jsonrpc: '2.0',
+                    error: {
+                        code: -32000,
+                        message: 'Bad Request: No valid session ID provided or not initialization request',
+                    },
+                    id: null,
+                });
+                return;
             }
-        });
+
+            // Handle the request with existing transport - no need to reconnect
+            await transport.handleRequest(req, res, req.body);
+        } catch (error) {
+            respondWithError(res, error, 'Error handling MCP request');
+        }
+    });
+
+    // Handle GET requests for SSE streams according to spec
+    app.get(Routes.MCP, async (_req: Request, res: Response) => {
+        // We don't support GET requests for this server
+        // The spec requires returning 405 Method Not Allowed in this case
+        res.status(405).set('Allow', 'POST').send('Method Not Allowed');
+    });
 
     // Catch-all for undefined routes
     app.use((req: Request, res: Response) => {
-        res.status(404).json({ message: `There is nothing at route ${req.method} ${req.originalUrl}. ${HELP_MESSAGE}` }).end();
+        res.status(404).json({ message: `There is nothing at route ${req.method} ${req.originalUrl}. ${getHelpMessage(host)}` }).end();
     });
 
     return app;
 }
+
+// Helper function to detect initialize requests
+function isInitializeRequest(body: unknown): boolean {
+    if (Array.isArray(body)) {
+        return body.some((msg) => typeof msg === 'object' && msg !== null && 'method' in msg && msg.method === 'initialize');
+    }
+    return typeof body === 'object' && body !== null && 'method' in body && body.method === 'initialize';
+}

src/actor/server.ts

@@ -1,4 +1,3 @@
-
 export interface ActorRunData {
     id?: string;
     actId?: string;