@apify/actors-mcp-server 0.1.0

package/src/examples/clientStdioChat.ts

@@ -0,0 +1,227 @@
+/* eslint-disable no-console */
+/**
+ * Create a simple chat client that connects to the Model Context Protocol server using the stdio transport.
+ * Based on the user input, the client sends a query to the MCP server, retrieves results and processes them.
+ *
+ * You can expect the following output:
+ *
+ * MCP Client Started!
+ * Type your queries or 'quit|q|exit' to exit.
+ * You: Find to articles about AI agent and return URLs
+ * [internal] Received response from Claude: [{"type":"text","text":"I'll search for information about AI agents
+ *   and provide you with a summary."},{"type":"tool_use","id":"tool_01He9TkzQfh2979bbeuxWVqM","name":"search",
+ *   "input":{"query":"what are AI agents definition capabilities applications","maxResults":2}}]
+ * [internal] Calling tool: {"name":"search","arguments":{"query":"what are AI agents definition ...
+ * I can help analyze the provided content about AI agents.
+ * This appears to be crawled content from AWS and IBM websites explaining what AI agents are.
+ * Let me summarize the key points:
+ */
+
+import { execSync } from 'child_process';
+import path from 'path';
+import * as readline from 'readline';
+import { fileURLToPath } from 'url';
+
+import { Anthropic } from '@anthropic-ai/sdk';
+import type { Message, ToolUseBlock, MessageParam } from '@anthropic-ai/sdk/resources/messages';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { CallToolResultSchema } from '@modelcontextprotocol/sdk/types.js';
+import dotenv from 'dotenv';
+
+const filename = fileURLToPath(import.meta.url);
+const dirname = path.dirname(filename);
+
+dotenv.config({ path: path.resolve(dirname, '../../.env') });
+
+const REQUEST_TIMEOUT = 120_000; // 2 minutes
+const MAX_TOKENS = 2048; // Maximum tokens for Claude response
+
+// const CLAUDE_MODEL = 'claude-3-5-sonnet-20241022'; // the most intelligent model
+// const CLAUDE_MODEL = 'claude-3-5-haiku-20241022'; // a fastest model
+const CLAUDE_MODEL = 'claude-3-haiku-20240307'; // a fastest and most compact model for near-instant responsiveness
+const DEBUG = true;
+const DEBUG_SERVER_PATH = path.resolve(dirname, '../../dist/index.js');
+
+const NODE_PATH = execSync('which node').toString().trim();
+
+dotenv.config(); // Load environment variables from .env
+
+export type Tool = {
+    name: string;
+    description: string | undefined;
+    input_schema: unknown;
+}
+
+class MCPClient {
+    private anthropic: Anthropic;
+    private client = new Client(
+        {
+            name: 'example-client',
+            version: '0.1.0',
+        },
+        {
+            capabilities: {}, // Optional capabilities
+        },
+    );
+
+    private tools: Tool[] = [];
+
+    constructor() {
+        this.anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
+    }
+
+    /**
+     * Start the server using node and provided server script path.
+     * Connect to the server using stdio transport and list available tools.
+     */
+    async connectToServer(serverArgs: string[]) {
+        const transport = new StdioClientTransport({
+            command: NODE_PATH,
+            args: serverArgs,
+            env: { APIFY_TOKEN: process.env.APIFY_TOKEN || '' },
+        });
+
+        await this.client.connect(transport);
+        const response = await this.client.listTools();
+
+        this.tools = response.tools.map((x) => ({
+            name: x.name,
+            description: x.description,
+            input_schema: x.inputSchema,
+        }));
+        console.log('Connected to server with tools:', this.tools.map((x) => x.name));
+    }
+
+    /**
+     * Process LLM response and check whether it contains any tool calls.
+     * If a tool call is found, call the tool and return the response and save the results to messages with type: user.
+     * If the tools response is too large, truncate it to the limit.
+     */
+    async processMsg(response: Message, messages: MessageParam[]): Promise<MessageParam[]> {
+        for (const content of response.content) {
+            if (content.type === 'text') {
+                messages.push({ role: 'assistant', content: content.text });
+            } else if (content.type === 'tool_use') {
+                await this.handleToolCall(content, messages);
+            }
+        }
+        return messages;
+    }
+
+    /**
+     * Call the tool and return the response.
+     */
+    private async handleToolCall(content: ToolUseBlock, messages: MessageParam[], toolCallCount = 0): Promise<MessageParam[]> {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const params = { name: content.name, arguments: content.input as any };
+        console.log(`[internal] Calling tool (count: ${toolCallCount}): ${JSON.stringify(params)}`);
+        let results;
+        try {
+            results = await this.client.callTool(params, CallToolResultSchema, { timeout: REQUEST_TIMEOUT });
+            if (results.content instanceof Array && results.content.length !== 0) {
+                const text = results.content.map((x) => x.text);
+                messages.push({ role: 'user', content: `Tool result: ${text.join('\n\n')}` });
+            } else {
+                messages.push({ role: 'user', content: `No results retrieved from ${params.name}` });
+            }
+        } catch (error) {
+            messages.push({ role: 'user', content: `Error calling tool: ${params.name}, error: ${error}` });
+        }
+        // Get next response from Claude
+        const nextResponse: Message = await this.anthropic.messages.create({
+            model: CLAUDE_MODEL,
+            max_tokens: MAX_TOKENS,
+            messages,
+            tools: this.tools as any[], // eslint-disable-line @typescript-eslint/no-explicit-any
+        });
+
+        for (const c of nextResponse.content) {
+            if (c.type === 'text') {
+                messages.push({ role: 'assistant', content: c.text });
+            } else if (c.type === 'tool_use' && toolCallCount < 3) {
+                return await this.handleToolCall(c, messages, toolCallCount + 1);
+            }
+        }
+
+        return messages;
+    }
+
+    /**
+     * Process user query by sending it to the server and returning the response.
+     * Also, process any tool calls.
+     */
+    async processQuery(query: string, messages: MessageParam[]): Promise<MessageParam[]> {
+        messages.push({ role: 'user', content: query });
+        const response: Message = await this.anthropic.messages.create({
+            model: CLAUDE_MODEL,
+            max_tokens: MAX_TOKENS,
+            messages,
+            tools: this.tools as any[], // eslint-disable-line @typescript-eslint/no-explicit-any
+        });
+        console.log('[internal] Received response from Claude:', JSON.stringify(response.content));
+        return await this.processMsg(response, messages);
+    }
+
+    /**
+     * Create a chat loop that reads user input from the console and sends it to the server for processing.
+     */
+    async chatLoop() {
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+            prompt: 'You: ',
+        });
+
+        console.log("MCP Client Started!\nType your queries or 'quit|q|exit' to exit.");
+        rl.prompt();
+
+        let lastPrintMessage = 0;
+        const messages: MessageParam[] = [];
+        rl.on('line', async (input) => {
+            const v = input.trim().toLowerCase();
+            if (v === 'quit' || v === 'q' || v === 'exit') {
+                rl.close();
+                return;
+            }
+            try {
+                await this.processQuery(input, messages);
+                for (let i = lastPrintMessage + 1; i < messages.length; i++) {
+                    if (messages[i].role === 'assistant') {
+                        console.log('CLAUDE:', messages[i].content);
+                    } else if (messages[i].role === 'user') {
+                        console.log('USER:', messages[i].content.slice(0, 500), '...');
+                    } else {
+                        console.log('CLAUDE[thinking]:', messages[i].content);
+                    }
+                }
+                lastPrintMessage += messages.length;
+            } catch (error) {
+                console.error('Error processing query:', error);
+            }
+            rl.prompt();
+        });
+    }
+}
+
+async function main() {
+    const client = new MCPClient();
+
+    if (process.argv.length < 3) {
+        if (DEBUG) {
+            process.argv.push(DEBUG_SERVER_PATH);
+        } else {
+            console.error('Usage: node <path_to_server_script>');
+            process.exit(1);
+        }
+    }
+
+    try {
+        await client.connectToServer(process.argv.slice(2));
+        await client.chatLoop();
+    } catch (error) {
+        console.error('Error:', error);
+    }
+}
+
+main().catch(console.error);

package/src/examples/client_sse.py

@@ -0,0 +1,48 @@
+"""
+Test Apify MCP Server using SSE client
+
+It is using python client as the typescript one does not support custom headers when connecting to the SSE server.
+
+Install python dependencies (assumes you have python installed):
+> pip install requests python-dotenv mcp
+"""
+
+import asyncio
+import os
+from pathlib import Path
+
+import requests
+from dotenv import load_dotenv
+from mcp.client.session import ClientSession
+from mcp.client.sse import sse_client
+
+load_dotenv(Path(__file__).resolve().parent.parent.parent / ".env")
+
+MCP_SERVER_URL = "https://actors-mcp-server.apify.actor"
+
+HEADERS = {"Authorization": f"Bearer {os.getenv('APIFY_TOKEN')}"}
+
+async def run() -> None:
+
+    print("Start MCP Server with Actors")
+    r = requests.get(MCP_SERVER_URL, headers=HEADERS)
+    print("MCP Server Response:", r.json(), end="\n\n")
+
+    async with sse_client(url=f"{MCP_SERVER_URL}/sse", timeout=60, headers=HEADERS) as (read, write):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+
+            tools = await session.list_tools()
+            print("Available Tools:", tools, end="\n\n")
+
+            if hasattr(tools, "tools") and not tools.tools:
+                print("No tools available!")
+                return
+
+            result = await session.call_tool("apify/rag-web-browser", { "query": "example.com", "maxResults": 3 })
+            print("Tools Call Result:")
+
+            for content in result.content:
+                print(content)
+
+asyncio.run(run())

package/src/index.ts

@@ -0,0 +1,34 @@
+/**
+ * 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';
+
+import { ApifyMcpServer } from './server.js';
+
+const argv = minimist(process.argv.slice(2));
+const argActors = argv.actors?.split(',').map((actor: string) => actor.trim()) || [];
+
+async function main() {
+    const server = new ApifyMcpServer();
+    await (argActors.length !== 0
+        ? server.addToolsFromActors(argActors)
+        : server.addToolsFromDefaultActors());
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+
+main().catch((error) => {
+    console.error('Server error:', error); // eslint-disable-line no-console
+    process.exit(1);
+});

package/src/input.ts

@@ -0,0 +1,16 @@
+import type { Input } from './types.js';
+
+/**
+ * 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
+    if (input.actors && typeof input.actors === 'string') {
+        input.actors = input.actors.split(',').map((format: string) => format.trim()) as string[];
+    }
+    return input;
+}

package/src/logger.ts

@@ -0,0 +1,5 @@
+import { log } from 'apify';
+
+log.setLevel(log.LEVELS.DEBUG);
+
+export { log };

package/src/main.ts

@@ -0,0 +1,106 @@
+import type { ParsedUrlQuery } from 'querystring';
+import { parse } from 'querystring';
+
+import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
+import { Actor } from 'apify';
+import type { Request, Response } from 'express';
+import express from 'express';
+
+import { Routes } from './const.js';
+import { processInput } from './input.js';
+import { log } from './logger.js';
+import { ApifyMcpServer } from './server.js';
+import type { Input } from './types.js';
+
+await Actor.init();
+
+const STANDBY_MODE = Actor.getEnv().metaOrigin === 'STANDBY';
+const HOST = Actor.isAtHome() ? process.env.ACTOR_STANDBY_URL : 'http://localhost';
+const PORT = Actor.isAtHome() ? process.env.ACTOR_STANDBY_PORT : 3001;
+
+const app = express();
+
+const mcpServer = new ApifyMcpServer();
+let transport: SSEServerTransport;
+
+const HELP_MESSAGE = `Connect to the server with GET request to ${HOST}/sse?token=YOUR-APIFY-TOKEN`
+    + ` and then send POST requests to ${HOST}/message?token=YOUR-APIFY-TOKEN.`;
+
+/**
+ * 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);
+    if (input.actors) {
+        await mcpServer.addToolsFromActors(input.actors as string[]);
+    } else {
+        log.debug(`Server is running in STANDBY mode with the following Actors (tools): ${mcpServer.getToolNames()}.
+        To use different Actors, provide them in query parameter "actors" or include them in the Actor Task input.`);
+    }
+}
+
+app.get(Routes.ROOT, async (req: Request, res: Response) => {
+    try {
+        log.info(`Received GET message at: ${req.url}`);
+        await processParamsAndUpdateTools(req.url);
+        res.status(200).json({ message: `Actor is using Model Context Protocol. ${HELP_MESSAGE}` }).end();
+    } catch (error) {
+        log.error(`Error in GET ${Routes.ROOT} ${error}`);
+        res.status(500).json({ message: 'Internal Server Error' }).end();
+    }
+});
+
+app.head(Routes.ROOT, (_req: Request, res: Response) => {
+    res.status(200).end();
+});
+
+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) {
+        log.error(`Error in GET ${Routes.SSE}: ${error}`);
+        res.status(500).json({ message: 'Internal Server Error' }).end();
+    }
+});
+
+app.post(Routes.MESSAGE, async (req: Request, res: Response) => {
+    try {
+        log.info(`Received POST message at: ${req.url}`);
+        await transport.handlePostMessage(req, res);
+    } catch (error) {
+        log.error(`Error in POST ${Routes.MESSAGE}: ${error}`);
+        res.status(500).json({ message: 'Internal Server Error' }).end();
+    }
+});
+
+// Catch-all for undefined routes
+app.use((req: Request, res: Response) => {
+    res.status(404).json({ message: `There is nothing at route ${req.method} ${req.originalUrl}. ${HELP_MESSAGE}` }).end();
+});
+
+const input = await processInput((await Actor.getInput<Partial<Input>>()) ?? ({} as Input));
+log.info(`Loaded input: ${JSON.stringify(input)} `);
+
+if (STANDBY_MODE) {
+    log.info('Actor is running in the STANDBY mode.');
+    await mcpServer.addToolsFromDefaultActors();
+    app.listen(PORT, () => {
+        log.info(`The Actor web server is listening for user requests at ${HOST}.`);
+    });
+} else {
+    log.info('Actor is not designed to run in the NORMAL model (use this mode only for debugging purposes)');
+
+    if (input && !input.debugActor && !input.debugActorInput) {
+        await Actor.fail('If you need to debug a specific actor, please provide the debugActor and debugActorInput fields in the input.');
+    }
+    await mcpServer.callActorGetDataset(input.debugActor!, input.debugActorInput!);
+    await Actor.exit();
+}

package/src/server.ts

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+/**
+ * Model Context Protocol (MCP) server for Apify Actors
+ */
+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 { Actor } from 'apify';
+import { ApifyClient } from 'apify-client';
+
+import { getActorsAsTools } from './actorDefinition.js';
+import {
+    ACTOR_OUTPUT_MAX_CHARS_PER_ITEM,
+    ACTOR_OUTPUT_TRUNCATED_MESSAGE,
+    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: Map<string, Tool>;
+
+    constructor() {
+        this.server = new Server(
+            {
+                name: SERVER_NAME,
+                version: SERVER_VERSION,
+            },
+            {
+                capabilities: {
+                    tools: {},
+                },
+            },
+        );
+        this.tools = new Map();
+        this.setupErrorHandling();
+        this.setupToolHandlers();
+    }
+
+    /**
+     * Calls an Apify actor and retrieves the dataset items.
+     *
+     * It requires the `APIFY_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_TOKEN` is not set
+     */
+    public async callActorGetDataset(actorName: string, input: unknown): Promise<object[]> {
+        if (!process.env.APIFY_TOKEN) {
+            throw new Error('APIFY_TOKEN is required but not set. Please set it as an environment variable');
+        }
+        try {
+            log.info(`Calling actor ${actorName} with input: ${JSON.stringify(input)}`);
+            const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
+            const actorClient = client.actor(actorName);
+
+            const results = await actorClient.call(input);
+            const dataset = await client.dataset(results.defaultDatasetId).listItems();
+            log.info(`Actor ${actorName} finished with ${dataset.items.length} items`);
+
+            if (process.env.APIFY_IS_AT_HOME) {
+                await Actor.pushData(dataset.items);
+                log.info(`Pushed ${dataset.items.length} items to the dataset`);
+            }
+            return dataset.items;
+        } catch (error) {
+            log.error(`Error calling actor: ${error}. Actor: ${actorName}, input: ${JSON.stringify(input)}`);
+            throw new Error(`Error calling actor: ${error}`);
+        }
+    }
+
+    public async addToolsFromActors(actors: string[]) {
+        const tools = await getActorsAsTools(actors);
+        this.updateTools(tools);
+    }
+
+    public async addToolsFromDefaultActors() {
+        await this.addToolsFromActors(defaults.actors);
+    }
+
+    public updateTools(tools: Tool[]): void {
+        for (const tool of tools) {
+            this.tools.set(tool.name, tool);
+            log.info(`Added/Updated tool: ${tool.name}`);
+        }
+    }
+
+    public getToolNames(): string[] {
+        return Array.from(this.tools.keys());
+    }
+
+    private setupErrorHandling(): void {
+        this.server.onerror = (error) => {
+            console.error('[MCP Error]', error); // eslint-disable-line no-console
+        };
+        process.on('SIGINT', async () => {
+            await this.server.close();
+            process.exit(0);
+        });
+    }
+
+    private setupToolHandlers(): void {
+        this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+            return { tools: Array.from(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;
+
+            // Anthropic can't handle '/' in tool names. The replace is only necessary when calling the tool from stdio clients.
+            const tool = this.tools.get(name) || this.tools.get(name.replace('/', '_'));
+            if (!tool) {
+                throw new Error(`Unknown tool: ${name}`);
+            }
+            log.info(`Validate arguments for tool: ${tool.name} with arguments: ${JSON.stringify(args)}`);
+            if (!tool.ajvValidate(args)) {
+                throw new Error(`Invalid arguments for tool ${tool.name}: args: ${JSON.stringify(args)} error: ${JSON.stringify(tool?.ajvValidate.errors)}`);
+            }
+
+            try {
+                const items = await this.callActorGetDataset(tool.actorName, args);
+                const content = items.map((item) => {
+                    const text = JSON.stringify(item).slice(0, ACTOR_OUTPUT_MAX_CHARS_PER_ITEM);
+                    return text.length === ACTOR_OUTPUT_MAX_CHARS_PER_ITEM
+                        ? { type: 'text', text: `${text} ... ${ACTOR_OUTPUT_TRUNCATED_MESSAGE}` }
+                        : { type: 'text', text };
+                });
+                return { content };
+            } catch (error) {
+                log.error(`Error calling tool: ${error}`);
+                throw new Error(`Error calling tool: ${error}`);
+            }
+        });
+    }
+
+    async connect(transport: Transport): Promise<void> {
+        await this.server.connect(transport);
+    }
+}

package/src/types.ts

@@ -0,0 +1,20 @@
+import type { ValidateFunction } from 'ajv';
+import type { ActorDefinition } from 'apify-client';
+
+export type Input = {
+    actors: string[] | string;
+    debugActor?: string;
+    debugActorInput?: unknown;
+};
+
+export interface ActorDefinitionWithDesc extends ActorDefinition {
+    description: string;
+}
+
+export interface Tool {
+    name: string;
+    actorName: string;
+    description: string;
+    inputSchema: object;
+    ajvValidate: ValidateFunction;
+}

package/tsconfig.eslint.json

@@ -0,0 +1,4 @@
+{
+  "extends": "./tsconfig.json",
+  "include": ["./src/**/*"]
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "@apify/tsconfig",
+  "compilerOptions": {
+    "module": "ESNext",
+    "target": "ESNext",
+    "outDir": "dist",
+    "moduleResolution": "node",
+    "noUnusedLocals": false,
+    "lib": ["ES2022"],
+    "skipLibCheck": true,
+    "typeRoots": ["./types", "./node_modules/@types"],
+    "strict": true
+  },
+  "include": ["./src/**/*"],
+  "exclude": ["node_modules"]
+}