initial working draft of proxy actorized mcp servers

MQ37 · MQ37 · commit 9a0846b7e14e · 2025-04-14T15:13:49.000+02:00
diff --git a/src/actor/server.ts b/src/actor/server.ts
@@ -9,8 +9,9 @@ import express from 'express';
 import log from '@apify/log';
 
 import { HEADER_READINESS_PROBE, Routes } from './const.js';
-import { type ActorsMcpServer } from '../mcp-server.js';
-import { getActorRunData, processParamsGetTools } from './utils.js';
+import { type ActorsMcpServer } from '../mcp/mcp-server.js';
+import { getActorRunData } from './utils.js';
+import { processParamsGetTools } from '../mcp/utils.js';
 
 export function createExpressApp(
     host: string,
@@ -32,7 +33,7 @@ export function createExpressApp(
             }
             try {
                 log.info(`Received GET message at: ${Routes.ROOT}`);
-                const tools = await processParamsGetTools(req.url);
+                const tools = await processParamsGetTools(req.url, process.env.APIFY_TOKEN as string);
                 if (tools) {
                     mcpServer.updateTools(tools);
                 }
@@ -53,7 +54,7 @@ export function createExpressApp(
         .get(async (req: Request, res: Response) => {
             try {
                 log.info(`Received GET message at: ${Routes.SSE}`);
-                const tools = await processParamsGetTools(req.url);
+                const tools = await processParamsGetTools(req.url, process.env.APIFY_TOKEN as string);
                 if (tools) {
                     mcpServer.updateTools(tools);
                 }
diff --git a/src/actor/types.ts b/src/actor/types.ts
@@ -1,10 +1,3 @@
-export type Input = {
-    actors: string[] | string;
-    enableActorAutoLoading?: boolean;
-    maxActorMemoryBytes?: number;
-    debugActor?: string;
-    debugActorInput?: unknown;
-};
 
 export interface ActorRunData {
     id?: string;
diff --git a/src/actor/utils.ts b/src/actor/utils.ts
@@ -1,34 +1,7 @@
-import { parse } from 'node:querystring';
 
 import { Actor } from 'apify';
+import type { ActorRunData } from './types.js';
 
-import { processInput } from './input.js';
-import type { ActorRunData, Input } from './types.js';
-import { addTool, getActorsAsTools, removeTool } from '../tools/index.js';
-import type { ToolWrap } from '../types.js';
-
-export function parseInputParamsFromUrl(url: string): Input {
-    const query = url.split('?')[1] || '';
-    const params = parse(query) as unknown as Input;
-    return processInput(params);
-}
-
-/**
- * Process input parameters and get tools
- * If URL contains query parameter `actors`, return tools from Actors otherwise return null.
- * @param url
- */
-export async function processParamsGetTools(url: string) {
-    const input = parseInputParamsFromUrl(url);
-    let tools: ToolWrap[] = [];
-    if (input.actors) {
-        tools = await getActorsAsTools(input.actors as string[]);
-    }
-    if (input.enableActorAutoLoading) {
-        tools.push(addTool, removeTool);
-    }
-    return tools;
-}
 
 export function getActorRunData(): ActorRunData | null {
     return Actor.isAtHome() ? {
diff --git a/src/index.ts b/src/index.ts
@@ -3,5 +3,5 @@
  The ActorsMcpServer should be the only class exported from the package
 */
 
-import { ActorsMcpServer } from './mcp-server.js';
+import { ActorsMcpServer } from './mcp/mcp-server.js';
 export default ActorsMcpServer;
diff --git a/src/input.ts b/src/input.ts
diff --git a/src/main.ts b/src/main.ts
@@ -8,10 +8,10 @@ import type { ActorCallOptions } from 'apify-client';
 
 import log from '@apify/log';
 
-import { processInput } from './actor/input.js';
+import { processInput } from './input.js';
 import { createExpressApp } from './actor/server.js';
-import type { Input } from './actor/types';
-import { ActorsMcpServer } from './mcp-server.js';
+import type { Input } from './types.js';
+import { ActorsMcpServer } from './mcp/mcp-server.js';
 import { actorDefinitionTool, addTool, removeTool, searchTool, callActorGetDataset } from './tools/index.js';
 
 const STANDBY_MODE = Actor.getEnv().metaOrigin === 'STANDBY';
diff --git a/src/mcp/actors.ts b/src/mcp/actors.ts
@@ -0,0 +1,13 @@
+
+export async function isActorMCPServer(actorID: string): Promise<boolean> {
+    // TODO: implement the logic
+    return actorID === 'apify/actors-mcp-server';
+}
+
+export async function getActorsMCPServerURL(actorID: string): Promise<string> {
+    // TODO: implement the logic
+    if (actorID === 'apify/actors-mcp-server') {
+        return 'https://actors-mcp-server.apify.actor/sse';
+    }
+    throw new Error(`Actor ${actorID} is not an MCP server`);
+}
diff --git a/src/mcp/client.ts b/src/mcp/client.ts
@@ -0,0 +1,41 @@
+
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { getMCPServerID } from "./utils";
+
+/**
+ * Creates and connects a ModelContextProtocol client.
+ */
+export async function createMCPClient(
+    url: string, token: string
+): Promise<Client> {
+    const transport = new SSEClientTransport(
+        new URL(url),
+        {
+            requestInit: {
+                headers: {
+                    authorization: `Bearer ${token}`,
+                },
+            },
+            eventSourceInit: {
+                // The EventSource package augments EventSourceInit with a "fetch" parameter.
+                // You can use this to set additional headers on the outgoing request.
+                // Based on this example: https://github.com/modelcontextprotocol/typescript-sdk/issues/118
+                async fetch(input: Request | URL | string, init?: RequestInit) {
+                    const headers = new Headers(init?.headers || {});
+                    headers.set('authorization', `Bearer ${token}`);
+                    return fetch(input, { ...init, headers });
+                },
+            // We have to cast to "any" to use it, since it's non-standard
+            } as any, // eslint-disable-line @typescript-eslint/no-explicit-any
+        });
+
+    const client = new Client({
+        name: getMCPServerID(url),
+        version: "1.0.0",
+    });
+
+    await client.connect(transport);
+
+    return client;
+}
diff --git a/src/mcp/const.ts b/src/mcp/const.ts
@@ -0,0 +1,3 @@
+
+export const MAX_TOOL_NAME_LENGTH = 64;
+export const SERVER_ID_LENGTH = 16
diff --git a/src/mcp/mcp-server.ts b/src/mcp/mcp-server.ts
@@ -1,3 +1,4 @@
+
 /**
  * Model Context Protocol (MCP) server for Apify Actors
  */
@@ -14,12 +15,14 @@ import {
     ACTOR_OUTPUT_TRUNCATED_MESSAGE,
     SERVER_NAME,
     SERVER_VERSION,
-} from './const.js';
-import { actorDefinitionTool, callActorGetDataset, getActorsAsTools, searchTool } from './tools/index.js';
-import type { ActorTool, HelperTool, ToolWrap } from './types.js';
-import { defaults } from './const.js';
-import { actorNameToToolName } from './tools/utils.js';
-import { processParamsGetTools } from './actor/utils.js';
+} from '../const.js';
+import { actorDefinitionTool, callActorGetDataset, getActorsAsTools, searchTool } from '../tools/index.js';
+import type { ActorMCPTool, ActorTool, HelperTool, ToolWrap } from '../types.js';
+import { defaults } from '../const.js';
+import { actorNameToToolName } from '../tools/utils.js';
+import { processParamsGetTools } from './utils.js';
+import { createMCPClient } from './client.js';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 
 /**
  * Create Apify MCP server
@@ -51,9 +54,9 @@ export class ActorsMcpServer {
     /**
      * Loads missing default tools.
      */
-    public async loadDefaultTools() {
+    public async loadDefaultTools(apifyToken: string) {
         const missingDefaultTools = defaults.actors.filter(name => !this.tools.has(actorNameToToolName(name)));
-        const tools = await getActorsAsTools(missingDefaultTools);
+        const tools = await getActorsAsTools(missingDefaultTools, apifyToken);
         if (tools.length > 0) this.updateTools(tools);
     }
 
@@ -62,8 +65,8 @@ export class ActorsMcpServer {
      *
      * Used primarily for SSE.
      */
-    public async loadToolsFromUrl(url: string) {
-        const tools = await processParamsGetTools(url);
+    public async loadToolsFromUrl(url: string, apifyToken: string) {
+        const tools = await processParamsGetTools(url, apifyToken);
         if (tools.length > 0) this.updateTools(tools);
     }
 
@@ -117,7 +120,10 @@ export class ActorsMcpServer {
          */
         this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const { name, arguments: args } = request.params;
-            const apifyToken = request.params.apifyToken || process.env.APIFY_TOKEN;
+            const apifyToken = (request.params.apifyToken || process.env.APIFY_TOKEN) as string;
+
+            // Remove apifyToken from request.params just in case
+            delete request.params.apifyToken;
 
             // Validate token
             if (!apifyToken) {
@@ -147,11 +153,29 @@ export class ActorsMcpServer {
                         args,
                         apifyMcpServer: this,
                         mcpServer: this.server,
+                        apifyToken,
                     }) as object;
 
                     return { ...res };
                 }
 
+                if (tool.type === 'actor-mcp') {
+                    const serverTool = tool.tool as ActorMCPTool;
+                    let client: Client | undefined;
+                    try {
+                        client = await createMCPClient(serverTool.serverUrl, apifyToken);
+                        const res = await client.callTool({
+                            name: name,
+                            arguments: args,
+                        });
+
+                        return { ...res };
+                    } finally {
+                        if (client) await client.close();
+                    }
+
+                }
+
                 // Handle actor tool
                 if (tool.type === 'actor') {
                     const actorTool = tool.tool as ActorTool;
diff --git a/src/mcp/proxy.ts b/src/mcp/proxy.ts
@@ -0,0 +1,39 @@
+import Ajv from "ajv";
+import { ActorMCPTool, ToolWrap } from "../types";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { getMCPServerID } from "./utils";
+
+export async function getMCPServerTools(
+    actorID: string,
+    client: Client,
+    // Name of the MCP server
+    serverUrl: string
+): Promise<ToolWrap[]> {
+    const res = await client.listTools();
+    const tools = res.tools;
+
+
+    const ajv = new Ajv({ coerceTypes: 'array', strict: false });
+
+    const compiledTools: ToolWrap[] = [];
+    for (const tool of tools) {
+        const mcpTool: ActorMCPTool = {
+            actorID,
+            serverId: getMCPServerID(serverUrl),
+            serverUrl,
+            name: tool.name,
+            description: tool.description || "",
+            inputSchema: tool.inputSchema,
+            ajvValidate: ajv.compile(tool.inputSchema)
+        }
+
+        const wrap: ToolWrap = {
+            type: 'actor-mcp',
+            tool: mcpTool,
+        }
+
+        compiledTools.push(wrap);
+    }
+
+    return compiledTools;
+}
diff --git a/src/mcp/utils.ts b/src/mcp/utils.ts
@@ -0,0 +1,65 @@
+
+import { createHash } from "node:crypto";
+import { MAX_TOOL_NAME_LENGTH, SERVER_ID_LENGTH } from "./const";
+
+import { parse } from 'node:querystring';
+import { processInput } from '../input.js';
+import type { ToolWrap } from '../types.js';
+
+import { addTool, getActorsAsTools, removeTool } from '../tools/index.js';
+import { Input } from "../types.js";
+import { getActorsMCPServerURL, isActorMCPServer } from "./actors";
+import { getMCPServerTools } from "./proxy";
+import { createMCPClient } from "./client";
+
+/**
+ * Generates a unique server ID based on the provided URL.
+ *
+ * URL is used instead of Actor ID becase one Actor may expose multiple servers - legacy SSE / streamable HTTP.
+ *
+ * @param url The URL to generate the server ID from.
+ * @returns A unique server ID.
+ */
+export function getMCPServerID(url: string): string {
+    const serverHashDigest = createHash('sha256').update(url).digest('hex');
+
+    return serverHashDigest.slice(0, SERVER_ID_LENGTH);
+}
+
+/**
+ * Generates a unique tool name based on the provided URL and tool name.
+ * @param url The URL to generate the tool name from.
+ * @param toolName The tool name to generate the tool name from.
+ * @returns A unique tool name.
+ */
+export function getServerToolName(url: string, toolName: string): string {
+    const prefix = getMCPServerID(url);
+
+    const fullName = `${prefix}-${toolName}`;
+    return fullName.slice(0, MAX_TOOL_NAME_LENGTH);
+}
+
+/**
+ * Process input parameters and get tools
+ * If URL contains query parameter `actors`, return tools from Actors otherwise return null.
+ * @param url
+ */
+export async function processParamsGetTools(url: string, apifyToken: string) {
+    const input = parseInputParamsFromUrl(url);
+    let tools: ToolWrap[] = [];
+    if (input.actors) {
+        const actors = input.actors as string[];
+        // Normal Actors as a tool
+        tools = await getActorsAsTools(actors, apifyToken);
+    }
+    if (input.enableActorAutoLoading) {
+        tools.push(addTool, removeTool);
+    }
+    return tools;
+}
+
+export function parseInputParamsFromUrl(url: string): Input {
+    const query = url.split('?')[1] || '';
+    const params = parse(query) as unknown as Input;
+    return processInput(params);
+}
diff --git a/src/stdio.ts b/src/stdio.ts
@@ -18,7 +18,7 @@ import minimist from 'minimist';
 import log from '@apify/log';
 
 import { defaults } from './const.js';
-import { ActorsMcpServer } from './mcp-server.js';
+import { ActorsMcpServer } from './mcp/mcp-server.js';
 import { addTool, removeTool, getActorsAsTools } from './tools/index.js';
 
 // Configure logging, set to ERROR
@@ -37,7 +37,7 @@ if (!process.env.APIFY_TOKEN) {
 async function main() {
     const mcpServer = new ActorsMcpServer();
     // Initialize tools
-    const tools = await getActorsAsTools(actorList.length ? actorList : defaults.actors);
+    const tools = await getActorsAsTools(actorList.length ? actorList : defaults.actors, process.env.APIFY_TOKEN as string);
     if (enableActorAutoLoading) {
         tools.push(addTool, removeTool);
     }
diff --git a/src/tools/actor.ts b/src/tools/actor.ts
diff --git a/src/tools/helpers.ts b/src/tools/helpers.ts
diff --git a/src/types.ts b/src/types.ts

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+`
	`2`	`+export const MAX_TOOL_NAME_LENGTH = 64;`
	`3`	`+export const SERVER_ID_LENGTH = 16`