add help tool

Author: MQ37

src/const.ts

@@ -26,6 +26,7 @@ export enum HelperTools {
     ADD_ACTOR = 'add-actor',
     REMOVE_ACTOR = 'remove-actor',
     GET_ACTOR_DETAILS = 'get-actor-details',
+    HELP_TOOL = 'help-tool',
 }
 
 export const defaults = {
@@ -35,6 +36,7 @@ export const defaults = {
     helperTools: [
         HelperTools.SEARCH_ACTORS,
         HelperTools.GET_ACTOR_DETAILS,
+        HelperTools.HELP_TOOL,
     ],
     actorAddingTools: [
         HelperTools.ADD_ACTOR,

src/mcp/server.ts

@@ -17,6 +17,7 @@ import {
     SERVER_NAME,
     SERVER_VERSION,
 } from '../const.js';
+import { helpTool } from '../tools/helpers.js';
 import {
     actorDefinitionTool,
     addTool,
@@ -66,7 +67,7 @@ export class ActorsMcpServer {
         this.setupToolHandlers();
 
         // Add default tools
-        this.updateTools([searchTool, actorDefinitionTool]);
+        this.updateTools([searchTool, actorDefinitionTool, helpTool]);
 
         // Add tools to dynamically load Actors
         if (this.options.enableAddingActors) {

src/tools/helpers.ts

@@ -64,3 +64,73 @@ export const removeTool: ToolWrap = {
         },
     } as InternalTool,
 };
+
+// Tool takes no arguments
+export const HelpToolArgsSchema = z.object({});
+export const helpTool: ToolWrap = {
+    type: 'internal',
+    tool: {
+        name: HelperTools.HELP_TOOL,
+        description: 'Helper tool to get information on how to use and troubleshoot the Apify MCP server. '
+            + 'This tool returns a message with information about the server and how to use it. '
+            + 'Call this tool in case of any problems or uncertainties with the server. ',
+        inputSchema: zodToJsonSchema(RemoveToolArgsSchema),
+        ajvValidate: ajv.compile(zodToJsonSchema(RemoveToolArgsSchema)),
+        call: async () => {
+            return { content: [{
+                type: 'text',
+                text: `Apify MCP server help:
+
+Note: MCP stands for Model Context Protocol. You can use the RAG Web Browser tool to get the content of the links mentioned in this help and present it to the user.
+
+This MCP server can be used in the following ways:
+- Locally over STDIO
+- Remotely over SSE or streamable HTTP transport with the Actors MCP Server Apify Actor
+- Remotely over SSE or streamable HTTP transport with mcp.apify.com
+
+# Usage
+## Locally over STDIO
+1. The user should install the @apify/actors-mcp-server NPM package.
+2. The user should configure their MCP client to use the MCP server. Refer to https://github.com/apify/actors-mcp-server or the MCP client documentation for more details (you can ask the user which MCP client they are using).
+The user needs to set the following environment variables:
+- APIFY_TOKEN: Apify token to authenticate with the MCP server.
+If the user wants to load some Actors outside of the default ones, they need to pass them as CLI arguments:
+- --actors <actor1,actor2,...> // comma-separated list of Actor names, for example, apify/rag-web-browser,apify/instagram-scraper.
+If the user wants to enable the dynamic addition of Actors to the MCP server, they need to pass the following CLI argument:
+- --enable-adding-actors
+
+## Remotely over SSE or streamable HTTP transport with Actors MCP Server Apify Actor
+1. The user should configure their MCP client to use the Actors MCP Server Apify Actor.
+SSE transport URL: https://actors-mcp-server.apify.actor/sse
+Streamable HTTP transport URL: https://actors-mcp-server.apify.actor/mcp
+The user needs to set the following headers or pass ?token=<APIFY_TOKEN> as a URL query parameter:
+- Authorization: Bearer <APIFY_TOKEN>
+If the user wants to load some Actors outside of the default ones, they need to pass them as URL query parameters:
+- ?actors=<actor1,actor2,...> // comma-separated list of Actor names, for example, apify/rag-web-browser,apify/instagram-scraper
+If the user wants to enable the addition of Actors to the MCP server dynamically, they need to pass the following URL query parameter:
+- ?enableAddingActors=true
+
+## Remotely over SSE or streamable HTTP transport with mcp.apify.com
+1. The user should configure their MCP client to use mcp.apify.com.
+SSE transport URL: https://mcp.apify.com/sse
+Streamable HTTP transport URL: https://mcp.apify.com/
+The user needs to set the following headers or pass ?token=<APIFY_TOKEN> as a URL query parameter:
+- Authorization: Bearer <APIFY_TOKEN>
+If the user wants to load some Actors outside of the default ones, they need to pass them as URL query parameters:
+- ?actors=<actor1,actor2,...> // comma-separated list of Actor names, for example, apify/rag-web-browser,apify/instagram-scraper
+If the user wants to enable the addition of Actors to the MCP server dynamically, they need to pass the following URL query parameter:
+- ?enableAddingActors=true
+
+# Features
+## Dynamic Adding of Actors
+THIS FEATURE MAY NOT BE SUPPORTED BY ALL MCP CLIENTS. THE USER MUST ENSURE THAT THE CLIENT SUPPORTS IT!
+To enable this feature, see the usage section. Once dynamic adding is enabled, tools will be added that allow you to add or remove Actors from the MCP server.
+Tools related:
+- add-actor
+- remove-actor
+In case you are using these tools and it seems like the tools have been added but you cannot call them, the issue may be that the client does not support dynamic adding of Actors. In that case, please inform the user that the MCP client documentation should be checked to see if the client supports this feature.
+`,
+            }] };
+        },
+    } as InternalTool,
+};

tests/integration/actor.server.test.ts

@@ -52,37 +52,6 @@ describe('Actors MCP Server SSE', {
         });
     });
 
-    it('should load actors from query parameters', async () => {
-        // Test with multiple actors including different username cases
-        const testActors = ['apify/rag-web-browser', 'apify/instagram-scraper'];
-        const numberOfHelperTools = 2;
-
-        // Make request to trigger server initialization
-        const response = await fetch(`${testHost}/?actors=${testActors.join(',')}`);
-        expect(response.status).toBe(200);
-
-        // Verify loaded tools
-        const toolNames = server.getToolNames();
-        expect(toolNames).toEqual(expect.arrayContaining([
-            'apify-slash-rag-web-browser',
-            'apify-slash-instagram-scraper',
-        ]));
-        expect(toolNames.length).toBe(testActors.length + numberOfHelperTools);
-    });
-
-    it('should enable auto-loading tools when flag is set', async () => {
-        const response = await fetch(`${testHost}/?enableActorAutoLoading=true`);
-        expect(response.status).toBe(200);
-
-        const toolNames = server.getToolNames();
-        expect(toolNames).toEqual([
-            HelperTools.SEARCH_ACTORS,
-            HelperTools.GET_ACTOR_DETAILS,
-            HelperTools.ADD_ACTOR,
-            HelperTools.REMOVE_ACTOR,
-        ]);
-    });
-
     it('default tools list', async () => {
         const client = await createMCPSSEClient(`${testHost}/sse`);