feat: MCP server implementation

.actor/input_schema.json

@@ -3,6 +3,17 @@
     "type": "object",
     "schemaVersion": 1,
     "properties": {
+        "actors": {
+            "title": "Actors names to be exposed for an AI application (AI agent)",
+            "type": "array",
+            "description": "List the names of Actors to be exposed to an AI application (AI agent) for communication via the MCP protocol. \n\n Ensure the Actor definitions fit within the LLM context by limiting the number of used Actors.",
+            "editor": "stringList",
+            "prefill": [
+                "apify/instagram-scraper",
+                "apify/rag-web-browser",
+                "lukaskrivka/google-maps-with-contact-details"
+            ]
+        },
         "debugActor": {
             "title": "Debug actor",
             "type": "string",

.env.example

@@ -1,3 +1,3 @@
-APIFY_API_TOKEN=
+APIFY_TOKEN=
 # ANTHROPIC_API_KEY is only required when you want to run examples/clientStdioChat.js
 ANTHROPIC_API_KEY=

README.md

@@ -11,23 +11,26 @@ The server can be used in two ways:
 
 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:
-- [Facebook Posts Scraper](https://apify.com/apify/facebook-posts-scraper) extracts data from Facebook posts from multiple pages/profiles
-- [Google Maps Email Extractor](https://apify.com/lukaskrivka/google-maps-with-contact-details) extracts Google Maps contact details
-- [Google Search Results Scraper](https://apify.com/apify/google-search-scraper) scrapes Google Search Engine Results Pages (SERPs)
-- [Instagram Scraper](https://apify.com/apify/instagram-scraper) scrapes Instagram posts, profiles, places, hashtags, photos, and comments
-- [RAG Web Browser](https://apify.com/apify/web-scraper) performs web search, scrape the top N URLs from the results, and return content
+- 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, hashtags, photos, and comments
+- use [RAG Web Browser](https://apify.com/apify/web-scraper) to perform a web search, scrape the top N URLs from the results, and return content
 
 To interact with the Apify MCP server, you can use MCP clients such as [Claude Desktop](https://claude.ai/download), [Superinference.ai](https://superinterface.ai/), or [LibreChat](https://www.librechat.ai/).
 Additionally, you can use simple example clients found in the [examples](https://github.com/apify/actor-mcp-server/tree/main/src/examples) directory.
 
 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 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?"
 
-# 🔄 What is model context protocol?
+In the future, we plan to load Actors dynamically and provide Apify's dataset and key-value store as resources.
+See the [Roadmap](#-roadmap-january-2025) for more details.
+
+# 🔄 What is the Model Context Protocol?
 
 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.
@@ -37,18 +40,12 @@ MCP is an open protocol that enables secure, controlled interactions between AI
 ## Tools
 
 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 a list of Actor names in the `actors` query parameter.
+By default, the server is pre-configured with the Actors specified below, but it can be overridden by providing Actor input.
 
 ```text
-   'apidojo/tweet-scraper',
-   'apify/facebook-posts-scraper',
-   'apify/google-search-scraper',
    'apify/instagram-scraper',
    'apify/rag-web-browser',
-   'clockworks/free-tiktok-scraper',
-   'compass/crawler-google-places',
    'lukaskrivka/google-maps-with-contact-details',
-   'voyager/booking-scraper'
 ```
 The MCP server loads the Actor input schema and creates MCP tools corresponding to the Actors.
 See this example of input schema for the [RAG Web Browser](https://apify.com/apify/rag-web-browser/input-schema).
@@ -86,14 +83,17 @@ The Actor runs in [**Standby mode**](https://docs.apify.com/platform/actors/runn
 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.
 ```
-https://mcp-server.apify.actor?token=<APIFY_API_TOKEN>
-```
-It is also possible to start MCP server with a different set of tools by providing a list of Actor names in the `actors` query parameter.
-Provide a comma-separated list of Actors in the `actors` query parameter:
+https://actors-mcp-server.apify.actor?token=<APIFY_TOKEN>
 ```
-https://mcp-server.apify.actor?token=<APIFY_API_TOKEN>&actors=junglee/free-amazon-product-scraper,lukaskrivka/google-maps-with-contact-details
+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 using your Apify API token.
+```shell
+https://actors-mcp-server-task.apify.actor?token=<APIFY_TOKEN>
 ```
-Find list of all available Actors in the [Apify Store](https://apify.com/store).
+
+You can find a list of all available Actors in the [Apify Store](https://apify.com/store).
 
 #### 💬 Interact with the MCP Server
 
@@ -107,9 +107,9 @@ In the client settings you need to provide server configuration:
     "mcpServers": {
         "apify": {
             "type": "sse",
-            "url": "https://mcp-server.apify.actor/sse",
+            "url": "https://actors-mcp-server.apify.actor/sse",
             "env": {
-                "APIFY-API-TOKEN": "your-apify-api-token"
+                "APIFY_TOKEN": "your-apify-token"
             }
         }
     }
@@ -119,7 +119,7 @@ Alternatively, you can use simple python [client_see.py](https://github.com/apif
 
 1. Initiate Server-Sent-Events (SSE) by sending a GET request to the following URL:
     ```
-    curl https://mcp-server.apify.actor/sse?token=<APIFY_API_TOKEN>
+    curl https://actors-mcp-server.apify.actor/sse?token=<APIFY_TOKEN>
     ```
     The server will respond with a `sessionId`, which you can use to send messages to the server:
     ```shell
@@ -129,7 +129,7 @@ Alternatively, you can use simple python [client_see.py](https://github.com/apif
 
 2. Send a message to the server by making a POST request with the `sessionId`:
     ```shell
-    curl -X POST "https://mcp-server.apify.actor?token=<APIFY_API_TOKEN>&session_id=a1b" -H "Content-Type: application/json" -d '{
+    curl -X POST "https://actors-mcp-server.apify.actor?token=<APIFY_TOKEN>&session_id=a1b" -H "Content-Type: application/json" -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
@@ -161,7 +161,7 @@ Alternatively, you can use simple python [client_see.py](https://github.com/apif
 - MacOS or Windows
 - The latest version of Claude Desktop must be installed (or another MCP client)
 - [Node.js](https://nodejs.org/en) (v18 or higher)
-- [Apify API Token](https://docs.apify.com/platform/integrations/api#api-token) (`APIFY_API_TOKEN`)
+- [Apify API Token](https://docs.apify.com/platform/integrations/api#api-token) (`APIFY_TOKEN`)
 
 ### Install
 
@@ -201,7 +201,7 @@ Configure Claude Desktop to recognize the MCP server.
           "/path/to/actor-mcp-server/dist/index.js"
         ]
         "env": {
-           "APIFY-API-TOKEN": "your-apify-api-token"
+           "APIFY_TOKEN": "your-apify-token"
         }
       }
     }
@@ -217,7 +217,7 @@ Configure Claude Desktop to recognize the MCP server.
           "lukaskrivka/google-maps-with-contact-details,apify/instagram-scraper"
         ]
         "env": {
-           "APIFY-API-TOKEN": "your-apify-api-token"
+           "APIFY_TOKEN": "your-apify-token"
         }
       }
     }
@@ -242,7 +242,7 @@ Configure Claude Desktop to recognize the MCP server.
 
 Create environment file `.env` with the following content:
 ```text
-APIFY_API_TOKEN=your-apify-api-token
+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
 ```
@@ -274,7 +274,7 @@ standard input/output (stdio):
 
 Create environment file `.env` with the following content:
 ```text
-APIFY_API_TOKEN=your-apify-api-token
+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
 ```
@@ -302,7 +302,15 @@ 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
-npx @modelcontextprotocol/inspector node /path/to/actor-mcp-server/dist/index.js --env APIFY_API_TOKEN=your-apify-api-token
+npx @modelcontextprotocol/inspector node /path/to/actor-mcp-server/dist/index.js --env APIFY_TOKEN=your-apify-token
 ```
 
 Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.
+
+# 🚀 Roadmap (January 2025)
+
+- Document examples for [Superinference.ai](https://superinterface.ai/) and [LibreChat](https://www.librechat.ai/).
+- Provide tools to search for Actors and load them as needed.
+- Add Apify's dataset and key-value store as resources.
+- Add tools such as Actor logs and Actor runs for debugging.
+- Prune Actors input schema to reduce context size.

package.json

@@ -26,7 +26,7 @@
     "model context protocol"
   ],
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.1.0",
+    "@modelcontextprotocol/sdk": "^1.1.1",
     "ajv": "^8.17.1",
     "apify": "^3.2.6",
     "apify-client": "^2.11.1",
@@ -38,7 +38,7 @@
     "@anthropic-ai/tokenizer": "^0.0.4",
     "@apify/eslint-config": "^0.5.0-beta.2",
     "@apify/tsconfig": "^0.1.0",
-    "@types/express": "^5.0.0",
+    "@types/express": "^4.0.0",
     "@types/minimist": "^1.2.5",
     "dotenv": "^16.4.7",
     "eslint": "^9.17.0",

src/actorDefinition.ts

@@ -12,11 +12,11 @@ import type { ActorDefinitionWithDesc, Tool } from './types';
  * @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) {
-        log.error('APIFY_API_TOKEN is required but not set. Please set it as an environment variable');
+    if (!process.env.APIFY_TOKEN) {
+        log.error('APIFY_TOKEN is required but not set. Please set it as an environment variable');
         return null;
     }
-    const client = new ApifyClient({ token: process.env.APIFY_API_TOKEN });
+    const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
     const actorClient = client.actor(actorFullName);
 
     try {
@@ -27,7 +27,9 @@ async function fetchActorDefinition(actorFullName: string): Promise<ActorDefinit
             return null;
         }
 
-        // Extract default build label
+        // fnesveda: The default build is not necessarily tagged, you can specify any build number as default build.
+        // There will be a new API endpoint to fetch a default build.
+        // For now, we'll use the tagged build, it will work for 90% of Actors. Later, we can update this.
         const tag = actor.defaultRunOptions?.build || '';
         const buildId = actor.taggedBuilds?.[tag]?.buildId || '';
 
@@ -56,6 +58,8 @@ async function fetchActorDefinition(actorFullName: string): Promise<ActorDefinit
  * 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 _
+ *
  * @param {string[]} actors - An array of actor full names.
  * @returns {Promise<Tool[]>} - A promise that resolves to an array of MCP tools.
  */
@@ -69,6 +73,7 @@ export async function getActorsAsTools(actors: string[]): Promise<Tool[]> {
             try {
                 tools.push({
                     name: result.name.replace('/', '_'),
+                    actorName: result.name,
                     description: result.description,
                     inputSchema: result.input || {},
                     ajvValidate: ajv.compile(result.input || {}),

src/const.ts

@@ -3,18 +3,16 @@ export const SERVER_VERSION = '0.1.0';
 
 export const defaults = {
     actors: [
-        'apidojo/tweet-scraper',
-        'apify/facebook-posts-scraper',
-        'apify/google-search-scraper',
         'apify/instagram-scraper',
         'apify/rag-web-browser',
-        'clockworks/free-tiktok-scraper',
-        'compass/crawler-google-places',
         'lukaskrivka/google-maps-with-contact-details',
-        'voyager/booking-scraper',
     ],
 };
 
+export const ACTOR_OUTPUT_MAX_CHARS_PER_ITEM = 2_000;
+export const ACTOR_OUTPUT_TRUNCATED_MESSAGE = `Output was truncated because it will not fit into context.`
+    + ` There is no reason to call this tool again!`;
+
 export enum Routes {
     ROOT = '/',
     SSE = '/sse',