Update docs and update apify-client-js with fixes for Actor definition

Author: jirispilka

README.md

@@ -154,7 +154,7 @@ Alternatively, you can use simple python [client_see.py](https://github.com/apif
     data: {"result":{"content":[{"type":"text","text":"{\"searchString\":\"restaurants in San Francisco\",\"rank\":1,\"title\":\"Gary Danko\",\"description\":\"Renowned chef Gary Danko's fixed-price menus of American cuisine ... \",\"price\":\"$100+\"...}}]}}
     ```
 
-## MCP Server at a local host
+## ⾕ MCP Server at a local host
 
 ### Prerequisites
 
@@ -248,15 +248,15 @@ ANTHROPIC_API_KEY=your-anthropic-api-token
 ```
 In the `examples` directory, you can find two clients that interact with the server via
 standard input/output (stdio):
-1. [`clientStdio.ts`](https://github.com/apify/actor-mcp-server/tree/main/src/examples/clientStdio.ts):
+1. [`clientStdio.ts`](https://github.com/apify/actor-mcp-server/tree/main/src/examples/clientStdio.ts)
     This client script starts the MCP server with two specified Actors.
     It then calls the `apify/rag-web-browser` tool with a query and prints the result.
     It demonstrates how to connect to the MCP server, list available tools, and call a specific tool using stdio transport.
     ```bash
     node dist/examples/clientStdio.js
     ```
 
-2. [`clientStdioChat.ts`](https://github.com/apify/actor-mcp-server/tree/main/src/examples/clientStdioChat.ts):
+2. [`clientStdioChat.ts`](https://github.com/apify/actor-mcp-server/tree/main/src/examples/clientStdioChat.ts)
     This client script also starts the MCP server but provides an interactive command-line chat interface.
     It prompts the user to interact with the server, allowing for dynamic tool calls and responses.
     This example is useful for testing and debugging interactions with the MCP server in conversational manner.

package-lock.json

@@ -9,27 +9,27 @@
   "main": "dist/index.js",
   "bin": {
     "apify-mcp-server": "dist/index.js"
-   },
-    "repository": {
-        "type": "git",
-        "url": "https://github.com/apify/actor-mcp-server.git"
-    },
-    "bugs": {
-        "url": "https://github.com/apify/actor-mcp-server/issues"
-    },
-    "homepage": "https://apify.com/apify/mcp-server",
-    "keywords": [
-        "apify",
-        "mcp",
-        "server",
-        "actors",
-        "model context protocol"
-    ],
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/apify/actor-mcp-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/apify/actor-mcp-server/issues"
+  },
+  "homepage": "https://apify.com/apify/mcp-server",
+  "keywords": [
+    "apify",
+    "mcp",
+    "server",
+    "actors",
+    "model context protocol"
+  ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.1.0",
     "ajv": "^8.17.1",
     "apify": "^3.2.6",
-    "apify-client": "^2.11.0",
+    "apify-client": "^2.11.1",
     "express": "^4.21.2",
     "minimist": "^1.2.8"
   },

package.json

@@ -1,18 +1,15 @@
 import { Ajv } from 'ajv';
-import type { ActorDefinition } from 'apify-client';
 import { ApifyClient } from 'apify-client';
 
 import { log } from './logger.js';
-
-interface ActorDefinitionWithDesc extends ActorDefinition {
-    description: string;
-}
+import type { ActorDefinitionWithDesc, Tool } from './types';
 
 /**
  * Get actor input schema by actor name.
  * First, fetch the actor details to get the default build tag and buildId.
  * Then, fetch the build details and return actorName, description, and input schema.
- * @param actorFullName
+ * @param {string} actorFullName - The full name of the actor.
+ * @returns {Promise<ActorDefinitionWithDesc | null>} - The actor definition with description or null if not found.
  */
 async function fetchActorDefinition(actorFullName: string): Promise<ActorDefinitionWithDesc | null> {
     if (!process.env.APIFY_API_TOKEN) {
@@ -33,19 +30,16 @@ async function fetchActorDefinition(actorFullName: string): Promise<ActorDefinit
         // Extract default build label
         const tag = actor.defaultRunOptions?.build || '';
         const buildId = actor.taggedBuilds?.[tag]?.buildId || '';
-        const description = actor.description || '';
 
         if (!buildId) {
             log.error(`Failed to fetch input schema for actor: ${actorFullName}. Build ID not found.`);
             return null;
         }
         // Fetch build details and return the input schema
         const buildDetails = await client.build(buildId).get();
-        if (buildDetails && 'actorDefinition' in buildDetails) {
-            // The buildDetails schema contains actorDefinitions but return type is actorDefinition
+        if (buildDetails?.actorDefinition) {
             const actorDefinitions = buildDetails?.actorDefinition as ActorDefinitionWithDesc;
-            actorDefinitions.description = description;
-            // Change the name to the actorFullName (we need to have tools with a full name to call the actor)
+            actorDefinitions.description = actor.description || '';
             actorDefinitions.name = actorFullName;
             return actorDefinitions;
         }
@@ -57,10 +51,15 @@ async function fetchActorDefinition(actorFullName: string): Promise<ActorDefinit
 }
 
 /**
- * Get actor input schemas by actor full names and create MCP tools.
- * @param actors - Array of actor full names
+ * Fetches actor input schemas by actor full names and creates MCP tools.
+ *
+ * This function retrieves the input schemas for the specified actors and compiles them into MCP tools.
+ * It uses the AJV library to validate the input schemas.
+ *
+ * @param {string[]} actors - An array of actor full names.
+ * @returns {Promise<Tool[]>} - A promise that resolves to an array of MCP tools.
  */
-export async function getActorsAsTools(actors: string[]) {
+export async function getActorsAsTools(actors: string[]): Promise<Tool[]> {
     // Fetch input schemas in parallel
     const ajv = new Ajv({ coerceTypes: 'array', strict: false });
     const results = await Promise.all(actors.map(fetchActorDefinition));

src/actorDefinition.ts

@@ -11,7 +11,7 @@ export const defaults = {
         'clockworks/free-tiktok-scraper',
         'compass/crawler-google-places',
         'lukaskrivka/google-maps-with-contact-details',
-        'voyager/booking-scraper'
+        'voyager/booking-scraper',
     ],
 };
 

src/const.ts

@@ -2,8 +2,7 @@
 /**
  * Connect to the MCP server using stdio transport and call a tool.
  * You need provide a path to MCP server and APIFY_API_TOKEN in .env file.
- *
- * Also, you need to choose ACTORS to run in the server, for example: apify/rag-web-browser
+ * You can choose ACTORS to run in the server, for example: apify/rag-web-browser
  */
 
 import { execSync } from 'child_process';

src/examples/clientStdio.ts

@@ -1,3 +1,16 @@
+/**
+ * This script initializes and starts the Apify MCP server using the Stdio transport.
+ *
+ * Usage:
+ *   node <script_name> --actors=<actor1,actor2,...>
+ *
+ * Command-line arguments:
+ *   --actors - A comma-separated list of actor full names to add to the server.
+ *
+ * Example:
+ *   node index.js --actors=apify/google-search-scraper,apify/instagram-scraper
+ */
+
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import minimist from 'minimist';
 

src/index.ts

@@ -1,6 +1,11 @@
 import type { Input } from './types.js';
 
-export async function processInput(originalInput: Partial<Input>) {
+/**
+ * Process input parameters, split actors string into an array
+ * @param originalInput
+ * @returns input
+ */
+export async function processInput(originalInput: Partial<Input>): Promise<Input> {
     const input = originalInput as Input;
 
     // actors can be a string or an array of strings
@@ -10,5 +15,5 @@ export async function processInput(originalInput: Partial<Input>) {
     if (!input.actors || input.actors.length === 0) {
         throw new Error('The `actors` parameter must be a non-empty array.');
     }
-    return { input };
+    return input;
 }

src/input.ts

@@ -28,12 +28,14 @@ const HELP_MESSAGE = `Connect to the server with GET request to ${HOST}/sse?toke
 
 /**
  * Process input parameters and update tools
+ * If URL contains query parameter actors, add tools from actors, otherwise add tools from default actors
+ * @param url
  */
 async function processParamsAndUpdateTools(url: string) {
     const params = parse(url.split('?')[1] || '') as ParsedUrlQuery;
     delete params.token;
     log.debug(`Received input parameters: ${JSON.stringify(params)}`);
-    const { input } = await processInput(params as Input);
+    const input = await processInput(params as Input);
     await (input.actors ? mcpServer.addToolsFromActors(input.actors as string[]) : mcpServer.addToolsFromDefaultActors());
 }
 
@@ -55,6 +57,7 @@ app.head(Routes.ROOT, (_req: Request, res: Response) => {
 app.get(Routes.SSE, async (req: Request, res: Response) => {
     try {
         log.info(`Received GET message at: ${req.url}`);
+        await processParamsAndUpdateTools(req.url);
         transport = new SSEServerTransport(Routes.MESSAGE, res);
         await mcpServer.connect(transport);
     } catch (error) {
@@ -86,7 +89,7 @@ if (STANDBY_MODE) {
     });
 } else {
     log.info('Actor is not designed to run in the NORMAL model (use this mode only for debugging purposes)');
-    const { input } = await processInput((await Actor.getInput<Partial<Input>>()) ?? ({} as Input));
+    const input = await processInput((await Actor.getInput<Partial<Input>>()) ?? ({} as Input));
     log.info(`Loaded input: ${JSON.stringify(input)} `);
 
     if (input && !input.debugActor && !input.debugActorInput) {

src/main.ts

@@ -5,20 +5,20 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
-import type { ValidateFunction } from 'ajv';
 import { Actor } from 'apify';
 import { ApifyClient } from 'apify-client';
 
 import { getActorsAsTools } from './actorDefinition.js';
 import { defaults, SERVER_NAME, SERVER_VERSION } from './const.js';
 import { log } from './logger.js';
+import type { Tool } from './types';
 
 /**
  * Create Apify MCP server
  */
 export class ApifyMcpServer {
     private server: Server;
-    private tools: { name: string; description: string; inputSchema: object, ajvValidate: ValidateFunction}[];
+    private tools: Map<string, Tool>;
 
     constructor() {
         this.server = new Server(
@@ -32,11 +32,22 @@ export class ApifyMcpServer {
                 },
             },
         );
-        this.tools = [];
+        this.tools = new Map();
         this.setupErrorHandling();
         this.setupToolHandlers();
     }
 
+    /**
+     * Calls an Apify actor and retrieves the dataset items.
+     *
+     * It requires the `APIFY_API_TOKEN` environment variable to be set.
+     * If the `APIFY_IS_AT_HOME` the dataset items are pushed to the Apify dataset.
+     *
+     * @param {string} actorName - The name of the actor to call.
+     * @param {unknown} input - The input to pass to the actor.
+     * @returns {Promise<object[]>} - A promise that resolves to an array of dataset items.
+     * @throws {Error} - Throws an error if the `APIFY_API_TOKEN` is not set
+     */
     public async callActorGetDataset(actorName: string, input: unknown): Promise<object[]> {
         if (!process.env.APIFY_API_TOKEN) {
             throw new Error('APIFY_API_TOKEN is required but not set. Please set it as an environment variable');
@@ -71,18 +82,10 @@ export class ApifyMcpServer {
         await this.addToolsFromActors(defaults.actors);
     }
 
-    public addToolIfNotExist(name: string, description: string, inputSchema: object, ajvValidate: ValidateFunction): void {
-        if (!this.tools.find((x) => x.name === name)) {
-            this.tools.push({ name, description, inputSchema, ajvValidate });
-            log.info(`Added tool: ${name}`);
-        } else {
-            log.info(`Tool already exists: ${name}`);
-        }
-    }
-
-    public updateTools(tools: { name: string; description: string; inputSchema: object, ajvValidate: ValidateFunction}[]): void {
+    public updateTools(tools: Tool[]): void {
         for (const tool of tools) {
-            this.addToolIfNotExist(tool.name, tool.description, tool.inputSchema, tool.ajvValidate);
+            this.tools.set(tool.name, tool);
+            log.info(`Added/Updated tool: ${tool.name}`);
         }
     }
 
@@ -98,13 +101,18 @@ export class ApifyMcpServer {
 
     private setupToolHandlers(): void {
         this.server.setRequestHandler(ListToolsRequestSchema, async () => {
-            return { tools: this.tools };
+            return { tools: this.tools.values() };
         });
 
+        /**
+         * Handles the request to call a tool.
+         * @param {object} request - The request object containing tool name and arguments.
+         * @throws {Error} - Throws an error if the tool is unknown or arguments are invalid.
+         */
         this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const { name, arguments: args } = request.params;
 
-            const tool = this.tools.find((t) => t.name === name);
+            const tool = this.tools.get(name);
             if (!tool) {
                 throw new Error(`Unknown tool: ${name}`);
             }