diff --git a/.actor/ACTOR.md b/.actor/ACTOR.md index 87710d38..0d361253 100644 --- a/.actor/ACTOR.md +++ b/.actor/ACTOR.md @@ -1,5 +1,8 @@ # Apify Model Context Protocol (MCP) Server +> **⚠️ Legacy solution notice** +> This Actor is legacy implementation of the Apify MCP Server. For the current and actively maintained solution, please visit **[mcp.apify.com](https://mcp.apify.com)** where you'll find the latest server, comprehensive documentation, and setup guides. + [![Actors MCP Server](https://apify.com/actor-badge?actor=apify/actors-mcp-server)](https://apify.com/apify/actors-mcp-server) Implementation of an MCP server for all [Apify Actors](https://apify.com/store). @@ -91,18 +94,13 @@ When a tool is called, the arguments are automatically passed to the Actor by th You can refer to the specific Actor's documentation for a list of available arguments. ### Helper tools +One of the powerful features of MCP with Apify is dynamic actor tooling – the ability for an AI agent to find new tools (Actors) as needed and incorporate them. Here are some special MCP operations and how Apify MCP Server supports them: -The server provides a set of helper tools to discover available Actors and retrieve their details: -- `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 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. - -- `add-actor-as-tool`: Adds an Actor by name to the available tools list without executing it, requiring user consent to run later. -- `remove-actor-from-tool`: Removes an Actor by name from the available tools list when it's no longer needed. +- Actor discovery and management: Search for Actors (`search-actors`), view details (`get-actor-details`), and dynamically add or remove tools (`add-actor`, `remove-actor`). +- Actor execution and monitoring: Start Actor runs, fetch run results (`get-actor-run`), logs (`get-actor-log`), and abort runs (`abort-actor-run`). +- Dataset access: List datasets, retrieve dataset info and items (`get-dataset`, `get-dataset-list`, `get-dataset-items`). +- Key-value store access: List key-value stores, view keys, and retrieve records (`get-key-value-store-list`, `get-key-value-store`, `get-key-value-store-keys`, `get-key-value-store-record`). +- Built-in help tool: A static helper (`apify-actor-help-tool`) that returns usage info for the Apify MCP Server. ## Prompt & Resources @@ -156,44 +154,6 @@ In the client settings, you need to provide server configuration: } } ``` -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: - ``` - curl https://actors-mcp-server.apify.actor/sse?token= - ``` - The server will respond with a `sessionId`, which you can use to send messages to the server: - ```shell - event: endpoint - data: /message?sessionId=a1b - ``` - -2. Send a message to the server by making a POST request with the `sessionId`: - ```shell - curl -X POST "https://actors-mcp-server.apify.actor/message?token=&session_id=a1b" -H "Content-Type: application/json" -d '{ - "jsonrpc": "2.0", - "id": 1, - "method": "tools/call", - "params": { - "arguments": { "searchStringsArray": ["restaurants in San Francisco"], "maxCrawledPlacesPerSearch": 3 }, - "name": "lukaskrivka/google-maps-with-contact-details" - } - }' - ``` - The MCP server will start the Actor `lukaskrivka/google-maps-with-contact-details` with the provided arguments as input parameters. - For this POST request, the server will respond with: - - ```text - Accepted - ``` - -3. Receive the response. The server will invoke the specified Actor as a tool using the provided query parameters and stream the response back to the client via SSE. - The response will be returned as JSON text. - - ```text - event: message - 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 @@ -216,7 +176,7 @@ If not, follow this guide to install Node.js: [Downloading and installing Node.j #### 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). +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) or watch the [video tutorial](https://youtu.be/gf5WXeqydUU?t=440). 1. Download Claude for desktop - Available for Windows and macOS. @@ -401,31 +361,6 @@ export APIFY_TOKEN=your-apify-token npx @modelcontextprotocol/inspector npx -y @apify/actors-mcp-server ``` -### Installing via Smithery - -To install Apify Actors MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@apify/actors-mcp-server): - -```bash -npx -y @smithery/cli install @apify/actors-mcp-server --client claude -``` - -#### Stdio clients - -Create an environment file `.env` with the following content: -```text -APIFY_TOKEN=your-apify-token -``` -In the `examples` directory, you can find an example client to interact with the server via -standard input/output (stdio): - -- [`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 - ``` - # 👷🏼 Development ## Prerequisites @@ -499,6 +434,7 @@ If you need other features or have any feedback, [submit an issue](https://conso - [Model Context Protocol](https://modelcontextprotocol.org/) - [What are AI Agents?](https://blog.apify.com/what-are-ai-agents/) - [What is MCP and why does it matter?](https://blog.apify.com/what-is-model-context-protocol/) +- [How to use MCP with Apify Actors](https://blog.apify.com/how-to-use-mcp/) - [Tester MCP Client](https://apify.com/jiri.spilka/tester-mcp-client) - [AI agent workflow: building an agent to query Apify datasets](https://blog.apify.com/ai-agent-workflow/) - [MCP Client development guide](https://github.com/cyanheads/model-context-protocol-resources/blob/main/guides/mcp-client-development-guide.md) diff --git a/README.md b/README.md index 0d361253..7abf61a7 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,5 @@ # Apify Model Context Protocol (MCP) Server -> **⚠️ Legacy solution notice** -> This Actor is legacy implementation of the Apify MCP Server. For the current and actively maintained solution, please visit **[mcp.apify.com](https://mcp.apify.com)** where you'll find the latest server, comprehensive documentation, and setup guides. - [![Actors MCP Server](https://apify.com/actor-badge?actor=apify/actors-mcp-server)](https://apify.com/apify/actors-mcp-server) Implementation of an MCP server for all [Apify Actors](https://apify.com/store). diff --git a/docs/actors-mcp-server.png b/docs/actors-mcp-server.png index 098fa14f..d0cd9942 100644 Binary files a/docs/actors-mcp-server.png and b/docs/actors-mcp-server.png differ