Merge remote-tracking branch 'origin/master' into feature/default-enable-dynamic-actor-loading

Author: MichalKalita

CHANGELOG.md

@@ -9,6 +9,7 @@ All notable changes to this project will be documented in this file.
 
 - Explicitly clear resources ([#136](https://github.com/apify/actors-mcp-server/pull/136)) ([779d2ba](https://github.com/apify/actors-mcp-server/commit/779d2ba2407bcd5fbdd89d3201463a784e67c931)) by [@jirispilka](https://github.com/jirispilka)
 - Readme Actors list ([#141](https://github.com/apify/actors-mcp-server/pull/141)) ([dc0a332](https://github.com/apify/actors-mcp-server/commit/dc0a332c8dbe450290d4acb5a19759545edf3c32)) by [@MQ37](https://github.com/MQ37)
+- Notifications ([#145](https://github.com/apify/actors-mcp-server/pull/145)) ([d96c427](https://github.com/apify/actors-mcp-server/commit/d96c42775db86f563c1012285c4a42f12fc23a19)) by [@MQ37](https://github.com/MQ37)
 
 
 <!-- git-cliff-unreleased-end -->

src/actor/server.ts

@@ -130,7 +130,7 @@ export function createExpressApp(
             // New initialization request - use JSON response mode
                 transport = new StreamableHTTPServerTransport({
                     sessionIdGenerator: () => randomUUID(),
-                    enableJsonResponse: true, // Enable JSON response mode
+                    enableJsonResponse: false, // Use SSE response mode
                 });
                 // Load MCP server tools
                 await loadToolsAndActors(mcpServer, req.url, process.env.APIFY_TOKEN as string);

src/mcp/server.ts

@@ -344,9 +344,10 @@ export class ActorsMcpServer {
         /**
          * Handles the request to call a tool.
          * @param {object} request - The request object containing tool name and arguments.
+         * @param {object} extra - Extra data given to the request handler, such as sendNotification function.
          * @throws {McpError} - based on the McpServer class code from the typescript MCP SDK
          */
-        this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        this.server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
             // eslint-disable-next-line prefer-const
             let { name, arguments: args } = request.params;
             const apifyToken = (request.params.apifyToken || process.env.APIFY_TOKEN) as string;
@@ -414,6 +415,7 @@ export class ActorsMcpServer {
                     const internalTool = tool.tool as HelperTool;
                     const res = await internalTool.call({
                         args,
+                        extra,
                         apifyMcpServer: this,
                         mcpServer: this.server,
                         apifyToken,

src/tools/helpers.ts

@@ -78,7 +78,7 @@ export const addTool: ToolEntry = {
         ajvValidate: ajv.compile(zodToJsonSchema(addToolArgsSchema)),
         // TODO: I don't like that we are passing apifyMcpServer and mcpServer to the tool
         call: async (toolArgs) => {
-            const { apifyMcpServer, mcpServer, apifyToken, args } = toolArgs;
+            const { apifyMcpServer, apifyToken, args, extra: { sendNotification } } = toolArgs;
             const parsed = addToolArgsSchema.parse(args);
             if (apifyMcpServer.listAllToolNames().includes(parsed.actorName)) {
                 return {
@@ -90,7 +90,7 @@ export const addTool: ToolEntry = {
             }
             const tools = await getActorsAsTools([parsed.actorName], apifyToken);
             const toolsAdded = apifyMcpServer.upsertTools(tools, true);
-            await mcpServer.notification({ method: 'notifications/tools/list_changed' });
+            await sendNotification({ method: 'notifications/tools/list_changed' });
 
             return {
                 content: [{
@@ -121,13 +121,13 @@ export const removeTool: ToolEntry = {
         ajvValidate: ajv.compile(zodToJsonSchema(removeToolArgsSchema)),
         // TODO: I don't like that we are passing apifyMcpServer and mcpServer to the tool
         call: async (toolArgs) => {
-            const { apifyMcpServer, mcpServer, args } = toolArgs;
+            const { apifyMcpServer, args, extra: { sendNotification } } = toolArgs;
             const parsed = removeToolArgsSchema.parse(args);
             // Check if tool exists before attempting removal
             if (!apifyMcpServer.tools.has(parsed.toolName)) {
                 // Send notification so client can update its tool list
                 // just in case the client tool list is out of sync
-                await mcpServer.notification({ method: 'notifications/tools/list_changed' });
+                await sendNotification({ method: 'notifications/tools/list_changed' });
                 return {
                     content: [{
                         type: 'text',
@@ -136,7 +136,7 @@ export const removeTool: ToolEntry = {
                 };
             }
             const removedTools = apifyMcpServer.removeToolsByName([parsed.toolName], true);
-            await mcpServer.notification({ method: 'notifications/tools/list_changed' });
+            await sendNotification({ method: 'notifications/tools/list_changed' });
             return { content: [{ type: 'text', text: `Tools removed: ${removedTools.join(', ')}` }] };
         },
     } as InternalTool,

src/types.ts

@@ -1,4 +1,6 @@
 import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';
+import type { Notification, Request } from '@modelcontextprotocol/sdk/types.js';
 import type { ValidateFunction } from 'ajv';
 import type { ActorDefaultRunOptions, ActorDefinition } from 'apify-client';
 
@@ -80,6 +82,13 @@ export interface ActorTool extends ToolBase {
 export type InternalToolArgs = {
     /** Arguments passed to the tool */
     args: Record<string, unknown>;
+    /** Extra data given to request handlers.
+     *
+     * Can be used to send notifications from the server to the client.
+     *
+     * For more details see: https://github.com/modelcontextprotocol/typescript-sdk/blob/f822c1255edcf98c4e73b9bf17a9dd1b03f86716/src/shared/protocol.ts#L102
+     */
+    extra: RequestHandlerExtra<Request, Notification>;
     /** Reference to the Apify MCP server instance */
     apifyMcpServer: ActorsMcpServer;
     /** Reference to the MCP server instance */

tests/integration/suite.ts

@@ -1,4 +1,5 @@
 import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { ToolListChangedNotificationSchema } from '@modelcontextprotocol/sdk/types.js';
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from 'vitest';
 
 import { defaults, HelperTools } from '../../src/const.js';
@@ -330,5 +331,24 @@ export function createIntegrationTestsSuite(
             expect(notificationCount).toBe(1);
             await client.close();
         });
+
+        it('should notify client about tool list changed', async () => {
+            const client = await createClientFn({ enableAddingActors: true });
+
+            // This flag is set to true when a 'notifications/tools/list_changed' notification is received,
+            // indicating that the tool list has been updated dynamically.
+            let hasReceivedNotification = false;
+            client.setNotificationHandler(ToolListChangedNotificationSchema, async (notification) => {
+                if (notification.method === 'notifications/tools/list_changed') {
+                    hasReceivedNotification = true;
+                }
+            });
+            // Add Actor dynamically
+            await client.callTool({ name: HelperTools.ACTOR_ADD, arguments: { actorName: ACTOR_PYTHON_EXAMPLE } });
+
+            expect(hasReceivedNotification).toBe(true);
+
+            await client.close();
+        });
     });
 }