feat: add help tool (#111)

* add help tool

* Update src/tools/helpers.ts

Co-authored-by: Copilot <[email protected]>

* fix: move tool text into a constant

* fix: helpTool text

* Update src/tools/helpers.ts

Co-authored-by: Jiří Spilka <[email protected]>

---------

Co-authored-by: Copilot <[email protected]>
Co-authored-by: Jiri Spilka <[email protected]>
Co-authored-by: Jiří Spilka <[email protected]>

Author: 3 people

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

@@ -8,6 +8,58 @@ import { getActorsAsTools } from './actor.js';
 import { actorNameToToolName } from './utils.js';
 
 const ajv = new Ajv({ coerceTypes: 'array', strict: false });
+
+const HELP_TOOL_TEXT = `Apify MCP server help:
+
+Note: "MCP" stands for "Model Context Protocol". The user 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 "https://mcp.apify.com".
+
+# Usage
+## Locally over "STDIO"
+1. The user should install the "@apify/actors-mcp-server" NPM package.
+2. The user should configure the MCP client to use the MCP server. Refer to "https://github.com/apify/actors-mcp-server" or the MCP client documentation for more details (the user can specify which MCP client is being used).
+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 an Actor outside the default ones, the user needs to pass it as a CLI argument:
+- "--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, the user needs 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 the MCP client to use the "Actors MCP Server Apify Actor" with:
+   - "SSE" transport URL: "https://actors-mcp-server.apify.actor/sse".
+   - Streamable "HTTP" transport URL: "https://actors-mcp-server.apify.actor/mcp".
+2. The user needs to pass an "APIFY_TOKEN" as a URL query parameter "?token=<APIFY_TOKEN>" or set the following headers: "Authorization: Bearer <APIFY_TOKEN>".
+If the user wants to load an Actor outside the default ones, the user needs to pass it as a URL query parameter:
+- "?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, the user needs to pass the following URL query parameter:
+- "?enable-adding-actors=true".
+
+## Remotely over "SSE" or streamable "HTTP" transport with "https://mcp.apify.com"
+1. The user should configure the MCP client to use "https://mcp.apify.com" with:
+   - "SSE" transport URL: "https://mcp.apify.com/sse".
+   - Streamable "HTTP" transport URL: "https://mcp.apify.com/".
+2. The user needs to pass an "APIFY_TOKEN" as a URL query parameter "?token=<APIFY_TOKEN>" or set the following headers: "Authorization: Bearer <APIFY_TOKEN>".
+If the user wants to load an Actor outside the default ones, the user needs to pass it as a URL query parameter:
+- "?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, the user needs to pass the following URL query parameter:
+- "?enable-adding-actors=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 the user to add or remove Actors from the MCP server.
+Tools related:
+- "add-actor".
+- "remove-actor".
+If the user is using these tools and it seems like the tools have been added but cannot be called, the issue may be that the client does not support dynamic adding of Actors.
+In that case, the user should check the MCP client documentation to see if the client supports this feature.
+`;
+
 export const AddToolArgsSchema = z.object({
     actorName: z.string()
         .describe('Add a tool, Actor or MCP-Server to available tools by Actor ID or tool full name.'
@@ -64,3 +116,20 @@ 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 always returns the same help 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(HelpToolArgsSchema),
+        ajvValidate: ajv.compile(zodToJsonSchema(HelpToolArgsSchema)),
+        call: async () => {
+            return { content: [{ type: 'text', text: HELP_TOOL_TEXT }] };
+        },
+    } 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`);