@apify/actors-mcp-server 0.1.22-beta.9 → 0.1.23

package/README.md

@@ -11,36 +11,34 @@ The server can be used in two ways:
 - **⾕ MCP Server Stdio** – Local server available via standard input/output (stdio), see [guide](#-mcp-server-at-a-local-host)
 
 
-It can also interact with the MCP server using chat-like UI with 💬 [Tester MCP Client](https://apify.com/jiri.spilka/tester-mcp-client)
+You can also interact with the MCP server using a chat-like UI with 💬 [Tester MCP Client](https://apify.com/jiri.spilka/tester-mcp-client)
 
 # 🎯 What does Apify MCP server do?
 
 The MCP Server Actor allows an AI assistant to use any [Apify Actor](https://apify.com/store) as a tool to perform a specific task.
-For example it can:
-- use [Facebook Posts Scraper](https://apify.com/apify/facebook-posts-scraper) to extract data from Facebook posts from multiple pages/profiles
-- use [Google Maps Email Extractor](https://apify.com/lukaskrivka/google-maps-with-contact-details) to extract Google Maps contact details
-- use [Google Search Results Scraper](https://apify.com/apify/google-search-scraper) to scrape Google Search Engine Results Pages (SERPs)
-- use [Instagram Scraper](https://apify.com/apify/instagram-scraper) to scrape Instagram posts, profiles, places, photos, and comments
-- use [RAG Web Browser](https://apify.com/apify/web-scraper) to search the web, scrape the top N URLs, and return their content
+For example, it can:
+- Use [Facebook Posts Scraper](https://apify.com/apify/facebook-posts-scraper) to extract data from Facebook posts from multiple pages/profiles
+- Use [Google Maps Email Extractor](https://apify.com/lukaskrivka/google-maps-with-contact-details) to extract Google Maps contact details
+- Use [Google Search Results Scraper](https://apify.com/apify/google-search-scraper) to scrape Google Search Engine Results Pages (SERPs)
+- Use [Instagram Scraper](https://apify.com/apify/instagram-scraper) to scrape Instagram posts, profiles, places, photos, and comments
+- Use [RAG Web Browser](https://apify.com/apify/web-scraper) to search the web, scrape the top N URLs, and return their content
 
 # MCP Clients
 
 To interact with the Apify MCP server, you can use MCP clients such as:
 - [Claude Desktop](https://claude.ai/download) (only Stdio support)
 - [Visual Studio Code](https://code.visualstudio.com/) (Stdio and SSE support)
-- [LibreChat](https://www.librechat.ai/) (stdio and SSE support (yet without Authorization header))
+- [LibreChat](https://www.librechat.ai/) (Stdio and SSE support, yet without Authorization header)
 - [Apify Tester MCP Client](https://apify.com/jiri.spilka/tester-mcp-client) (SSE support with Authorization headers)
-- other clients at [https://modelcontextprotocol.io/clients](https://modelcontextprotocol.io/clients)
-- more clients at [https://glama.ai/mcp/clients](https://glama.ai/mcp/clients)
-
-Additionally, you can use simple example clients found in the [examples](https://github.com/apify/actor-mcp-server/tree/main/src/examples) directory.
+- Other clients at [https://modelcontextprotocol.io/clients](https://modelcontextprotocol.io/clients)
+- More clients at [https://glama.ai/mcp/clients](https://glama.ai/mcp/clients)
 
 When you have Actors integrated with the MCP server, you can ask:
-- "Search web and summarize recent trends about AI Agents"
-- "Find top 10 best Italian restaurants in San Francisco"
-- "Find and analyze Instagram profile of The Rock"
-- "Provide a step-by-step guide on using the Model Context Protocol with source URLs."
-- "What Apify Actors I can use?"
+- "Search the web and summarize recent trends about AI Agents"
+- "Find the top 10 best Italian restaurants in San Francisco"
+- "Find and analyze the Instagram profile of The Rock"
+- "Provide a step-by-step guide on using the Model Context Protocol with source URLs"
+- "What Apify Actors can I use?"
 
 The following image shows how the Apify MCP server interacts with the Apify platform and AI clients:
 
@@ -54,7 +52,7 @@ We also plan to add more features, see [Roadmap](#-roadmap-march-2025) for more
 The Model Context Protocol (MCP) allows AI applications (and AI agents), such as Claude Desktop, to connect to external tools and data sources.
 MCP is an open protocol that enables secure, controlled interactions between AI applications, AI Agents, and local or remote resources.
 
-For more information, see the [Model Context Protocol](https://modelcontextprotocol.org/) website or blogpost [What is MCP and why does it matter?](https://blog.apify.com/what-is-model-context-protocol/).
+For more information, see the [Model Context Protocol](https://modelcontextprotocol.org/) website or the blog post [What is MCP and why does it matter?](https://blog.apify.com/what-is-model-context-protocol/).
 
 # 🤖 How is MCP Server related to AI Agents?
 
@@ -70,7 +68,7 @@ Interested in building and monetizing your own AI agent on Apify? Check out our
 ### Actors
 
 Any [Apify Actor](https://apify.com/store) can be used as a tool.
-By default, the server is pre-configured with the Actors specified below, but it can be overridden by providing Actor input.
+By default, the server is pre-configured with the Actors specified below, but this can be overridden by providing Actor input.
 
 ```text
 'apify/instagram-scraper'
@@ -90,7 +88,7 @@ For example, for the `apify/rag-web-browser` Actor, the arguments are:
   "maxResults": 3
 }
 ```
-You don't need to specify the input parameters or which Actor to call, everything is managed by an LLM.
+You don't need to specify the input parameters or which Actor to call; everything is managed by an LLM.
 When a tool is called, the arguments are automatically passed to the Actor by the LLM.
 You can refer to the specific Actor's documentation for a list of available arguments.
 
@@ -100,7 +98,7 @@ The server provides a set of helper tools to discover available Actors and retri
 - `get-actor-details`: Retrieves documentation, input schema, and details about a specific Actor.
 - `discover-actors`: Searches for relevant Actors using keywords and returns their details.
 
-There are also tools to manage the available tools list. However, dynamically adding and removing tools requires the MCP client to have the capability to update tools list (handle `ToolListChangedNotificationSchema`), which is typically not supported.
+There are also tools to manage the available tools list. However, dynamically adding and removing tools requires the MCP client to have the capability to update the tools list (handle `ToolListChangedNotificationSchema`), which is typically not supported.
 
 You can try this functionality using the [Apify Tester MCP Client](https://apify.com/jiri.spilka/tester-mcp-client) Actor.
 To enable it, set the `enableActorAutoLoading` parameter.
@@ -115,7 +113,7 @@ We plan to add [Apify's dataset](https://docs.apify.com/platform/storage/dataset
 
 # ⚙️ Usage
 
-The Apify MCP Server can be used in two ways: **as an Apify Actor** running at Apify platform
+The Apify MCP Server can be used in two ways: **as an Apify Actor** running on the Apify platform
 or as a **local server** running on your machine.
 
 ## 🇦 MCP Server Actor
@@ -124,15 +122,14 @@ or as a **local server** running on your machine.
 
 The Actor runs in [**Standby mode**](https://docs.apify.com/platform/actors/running/standby) with an HTTP web server that receives and processes requests.
 
-Start server with default Actors. To use the Apify MCP Server with set of default Actors,
-send an HTTP GET request with your [Apify API token](https://console.apify.com/settings/integrations) to the following URL.
+To start the server with default Actors, send an HTTP GET request with your [Apify API token](https://console.apify.com/settings/integrations) to the following URL:
 ```
 https://actors-mcp-server.apify.actor?token=<APIFY_TOKEN>
 ```
 It is also possible to start the MCP server with a different set of Actors.
 To do this, create a [task](https://docs.apify.com/platform/actors/running/tasks) and specify the list of Actors you want to use.
 
-Then, run task in Standby mode with the selected Actors.
+Then, run the task in Standby mode with the selected Actors:
 ```shell
 https://USERNAME--actors-mcp-server-task.apify.actor?token=<APIFY_TOKEN>
 ```
@@ -144,10 +141,10 @@ You can find a list of all available Actors in the [Apify Store](https://apify.c
 Once the server is running, you can interact with Server-Sent Events (SSE) to send messages to the server and receive responses.
 The easiest way is to use [Tester MCP Client](https://apify.com/jiri.spilka/tester-mcp-client) on Apify.
 
-Most of the MCP clients do not support SSE yet (as of March 2025), but this will likely change.
-[Claude Desktop](https://claude.ai/download) does not support SEE yet, but you can use it with Stdio transport, see [MCP Sever at a local host](#-mcp-server-at-a-local-host) for more details.
+[Claude Desktop](https://claude.ai/download) currently lacks SSE support, but you can use it with Stdio transport; see [MCP Server at a local host](#-mcp-server-at-a-local-host) for more details.
+Note: The free version of Claude Desktop may experience intermittent connection issues with the server.
 
-In the client settings you need to provide server configuration:
+In the client settings, you need to provide server configuration:
 ```json
 {
     "mcpServers": {
@@ -161,7 +158,7 @@ In the client settings you need to provide server configuration:
     }
 }
 ```
-Alternatively, you can use simple python [client_see.py](https://github.com/apify/actor-mcp-server/tree/main/src/examples/client_sse.py) or test the server using `curl` </> commands.
+Alternatively, you can use [clientSse.ts](https://github.com/apify/actor-mcp-server/tree/main/src/examples/clientSse.ts) script or test the server using `curl` </> commands.
 
 1. Initiate Server-Sent-Events (SSE) by sending a GET request to the following URL:
     ```
@@ -202,7 +199,7 @@ Alternatively, you can use simple python [client_see.py](https://github.com/apif
 
 ## ⾕ MCP Server at a local host
 
-You can run the Apify MCP Server on your local machine by configuring it with Claude Desktop or any other [MCP clients](https://modelcontextprotocol.io/clients).
+You can run the Apify MCP Server on your local machine by configuring it with Claude Desktop or any other [MCP client](https://modelcontextprotocol.io/clients).
 You can also use [Smithery](https://smithery.ai/server/@apify/actors-mcp-server) to install the server automatically.
 
 ### Prerequisites
@@ -212,6 +209,13 @@ You can also use [Smithery](https://smithery.ai/server/@apify/actors-mcp-server)
 - [Node.js](https://nodejs.org/en) (v18 or higher)
 - [Apify API Token](https://docs.apify.com/platform/integrations/api#api-token) (`APIFY_TOKEN`)
 
+Make sure you have the `node` and `npx` installed properly:
+```bash
+node -v
+npx -v
+```
+If not, follow this guide to install Node.js: [Downloading and installing Node.js and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm).
+
 #### Claude Desktop
 
 To configure Claude Desktop to work with the MCP server, follow these steps. For a detailed guide, refer to the [Claude Desktop Users Guide](https://modelcontextprotocol.io/quickstart/user).
@@ -220,8 +224,8 @@ To configure Claude Desktop to work with the MCP server, follow these steps. For
    - Available for Windows and macOS.
    - For Linux users, you can build a Debian package using this [unofficial build script](https://github.com/aaddrick/claude-desktop-debian).
 2. Open the Claude Desktop app and enable **Developer Mode** from the top-left menu bar.
-3. Once enabled, open **Settings** (also from the top-left menu bar) and navigate to the **Developer Option**, where you'll find the **Edit Config** button
-4. Open configuration file and edit the following file:
+3. Once enabled, open **Settings** (also from the top-left menu bar) and navigate to the **Developer Option**, where you'll find the **Edit Config** button.
+4. Open the configuration file and edit the following file:
 
     - On macOS: `~/Library/Application\ Support/Claude/claude_desktop_config.json`
     - On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
@@ -240,7 +244,7 @@ To configure Claude Desktop to work with the MCP server, follow these steps. For
      }
     }
     ```
-    Alternatively, you can use `actors` argument to select one or more Apify Actors:
+    Alternatively, you can use the `actors` argument to select one or more Apify Actors:
     ```json
    {
     "mcpServers": {
@@ -261,9 +265,9 @@ To configure Claude Desktop to work with the MCP server, follow these steps. For
 
     - Fully quit Claude Desktop (ensure it's not just minimized or closed).
     - Restart Claude Desktop.
-    - Look for the 🔌 icon to confirm that the Exa server is connected.
+    - Look for the 🔌 icon to confirm that the Actors MCP server is connected.
 
-6. Open the Claude Desktop chat and ask "What Apify Actors I can use?"
+6. Open the Claude Desktop chat and ask "What Apify Actors can I use?"
 
    ![Claude-desktop-with-Actors-MCP-server](https://raw.githubusercontent.com/apify/actors-mcp-server/refs/heads/master/docs/claude-desktop.png)
 
@@ -272,8 +276,8 @@ To configure Claude Desktop to work with the MCP server, follow these steps. For
    You can ask Claude to perform tasks, such as:
     ```text
     Find and analyze recent research papers about LLMs.
-    Find top 10 best Italian restaurants in San Francisco.
-    Find and analyze instagram profile of the Rock.
+    Find the top 10 best Italian restaurants in San Francisco.
+    Find and analyze the Instagram profile of The Rock.
     ```
 
 #### VS Code
@@ -352,16 +356,14 @@ npx -y @smithery/cli install @apify/actors-mcp-server --client claude
 
 #### Stdio clients
 
-Create environment file `.env` with the following content:
+Create an environment file `.env` with the following content:
 ```text
 APIFY_TOKEN=your-apify-token
-# ANTHROPIC_API_KEY is only required when you want to run examples/clientStdioChat.js
-ANTHROPIC_API_KEY=your-anthropic-api-token
 ```
-In the `examples` directory, you can find two clients that interact with the server via
+In the `examples` directory, you can find an example client to 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)
+- [`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.
@@ -369,15 +371,6 @@ standard input/output (stdio):
     node dist/examples/clientStdio.js
     ```
 
-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.
-
-    ```bash
-    node dist/examples/clientStdioChat.js
-    ```
-
 # 👷🏼 Development
 
 ## Prerequisites
@@ -385,17 +378,22 @@ standard input/output (stdio):
 - [Node.js](https://nodejs.org/en) (v18 or higher)
 - Python 3.9 or higher
 
-Create environment file `.env` with the following content:
+Create an environment file `.env` with the following content:
 ```text
 APIFY_TOKEN=your-apify-token
-# ANTHROPIC_API_KEY is only required when you want to run examples/clientStdioChat.js
-ANTHROPIC_API_KEY=your-anthropic-api-key
 ```
+
+Build the actor-mcp-server package:
+
+```bash
+npm run build
+```
+
 ## Local client (SSE)
 
-To test the server with the SSE transport, you can use python script `examples/clientSse.ts`:
-Currently, the node.js client does not support to establish a connection to remote server witch custom headers.
-You need to change URL to your local server URL in the script.
+To test the server with the SSE transport, you can use the script `examples/clientSse.ts`:
+Currently, the Node.js client does not support establishing a connection to a remote server with custom headers.
+You need to change the URL to your local server URL in the script.
 
 ```bash
 node dist/examples/clientSse.js
@@ -406,17 +404,11 @@ node dist/examples/clientSse.js
 Since MCP servers operate over standard input/output (stdio), debugging can be challenging.
 For the best debugging experience, use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector).
 
-Build the actor-mcp-server package:
-
-```bash
-npm run build
-```
-
 You can launch the MCP Inspector via [`npm`](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) with this command:
 
 ```bash
 export APIFY_TOKEN=your-apify-token
-npx @modelcontextprotocol/inspector node ./dist/stdio.js
+npx @modelcontextprotocol/inspector node ./dist/index.js
 ```
 
 Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.
@@ -441,6 +433,12 @@ If you need other features or have any feedback, [submit an issue](https://conso
 - Add Apify's dataset and key-value store as resources.
 - Add tools such as Actor logs and Actor runs for debugging.
 
+# 🐛 Troubleshooting
+
+- Make sure you have the `node` installed by running `node -v`
+- Make sure you have the `APIFY_TOKEN` environment variable set
+- Always use the latest version of the MCP server by setting `@apify/actors-mcp-server@latest`
+
 # 📚 Learn more
 
 - [Model Context Protocol](https://modelcontextprotocol.org/)

package/dist/actors.d.ts

@@ -0,0 +1,74 @@
+import type { ActorDefinitionPruned, ISchemaProperties, Tool } from './types.js';
+export declare function actorNameToToolName(actorName: string): string;
+/**
+ * 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 {string} actorIdOrName - Actor ID or Actor full name.
+ * @param {number} limit - Truncate the README to this limit.
+ * @returns {Promise<ActorDefinitionWithDesc | null>} - The actor definition with description or null if not found.
+ */
+export declare function getActorDefinition(actorIdOrName: string, limit?: number): Promise<ActorDefinitionPruned | null>;
+/**
+ * Helper function to shorten the enum list if it is too long.
+ *
+ * @param {string[]} enumList - The list of enum values to be shortened.
+ * @returns {string[] | undefined} - The shortened enum list or undefined if the list is too long.
+ */
+export declare function shortenEnum(enumList: string[]): string[] | undefined;
+/**
+ * Shortens the description, enum, and items.enum properties of the schema properties.
+ * @param properties
+ */
+export declare function shortenProperties(properties: {
+    [key: string]: ISchemaProperties;
+}): {
+    [key: string]: ISchemaProperties;
+};
+/** Prune Actor README if it is too long
+ * If the README is too long
+ * - We keep the README as it is up to the limit.
+ * - After the limit, we keep heading only
+ * - We add a note that the README was truncated because it was too long.
+ */
+export declare function truncateActorReadme(readme: string, limit?: number): string;
+/**
+ * Helps determine the type of items in an array schema property.
+ * Priority order: explicit type in items > prefill type > default value type > editor type.
+ *
+ * Based on JSON schema, the array needs a type, and most of the time Actor input schema does not have this, so we need to infer that.
+ *
+ */
+export declare function inferArrayItemType(property: ISchemaProperties): string | null;
+/**
+ * Filters schema properties to include only the necessary fields.
+ *
+ * This is done to reduce the size of the input schema and to make it more readable.
+ *
+ * @param properties
+ */
+export declare function filterSchemaProperties(properties: {
+    [key: string]: ISchemaProperties;
+}): {
+    [key: string]: ISchemaProperties;
+};
+/**
+ * Fetches actor input schemas by Actor IDs or 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.
+ *
+ * Tool name can't contain /, so it is replaced with _
+ *
+ * The input schema processing workflow:
+ * 1. Properties are marked as required using markInputPropertiesAsRequired() to add "REQUIRED" prefix to descriptions
+ * 2. Nested properties are built by analyzing editor type (proxy, requestListSources) using buildNestedProperties()
+ * 3. Properties are filtered using filterSchemaProperties()
+ * 4. Properties are shortened using shortenProperties()
+ * 5. Enums are added to descriptions with examples using addEnumsToDescriptionsWithExamples()
+ *
+ * @param {string[]} actors - An array of actor IDs or Actor full names.
+ * @returns {Promise<Tool[]>} - A promise that resolves to an array of MCP tools.
+ */
+export declare function getActorsAsTools(actors: string[]): Promise<Tool[]>;
+//# sourceMappingURL=actors.d.ts.map

package/dist/actors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actors.d.ts","sourceRoot":"","sources":["../src/actors.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,qBAAqB,EAA8C,iBAAiB,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAE7H,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAK7D;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CAAC,aAAa,EAAE,MAAM,EAAE,KAAK,GAAE,MAAgC,GAAG,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAuC9I;AAkBD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,GAAG,SAAS,CAQpE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAAA;CAAC,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAAA;CAAE,CAgBvH;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,SAA0B,GAAG,MAAM,CAS3F;AACD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,GAAG,IAAI,CAgB7E;AA2BD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAAA;CAAE,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAAA;CAAE,CA2B7H;AAmFD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CA6BxE"}