fix: smithery

Author: jirispilka

docs/smithery.md

@@ -0,0 +1,19 @@
+# Smithery integration
+
+- The Smithery entrypoint is `src/smithery.ts`.
+- It exports `configSchema` and a default sync function returning the MCP server instance.
+- On startup, if `apifyToken`/`APIFY_TOKEN` is provided, tools load asynchronously and the first `listTools` is gated via a one-time barrier (`blockListToolsUntil`).
+- If no token is provided, tools are loaded with placeholder token `PLACEHOLDER_TOKEN` to allow the server to start without real secrets.
+
+Run with Smithery:
+
+```bash
+npx @smithery/cli build
+# optional, recommended for actors
+export APIFY_TOKEN="your-apify-token"
+npx @smithery/cli dev
+```
+
+Notes:
+- The barrier is used only by Smithery; stdio/SSE/HTTP flows are unaffected.
+- We use a placeholder token (`your-apify-token`) in non-interactive environments (Smithery scans) to allow tool-loading paths to run without real secrets. It does not grant access; when detected, the client runs unauthenticated to let the server start and list tools where possible.

src/apify-client.ts

@@ -2,7 +2,7 @@ import type { ApifyClientOptions } from 'apify';
 import { ApifyClient as _ApifyClient } from 'apify-client';
 import type { AxiosRequestConfig } from 'axios';
 
-import { USER_AGENT_ORIGIN } from './const.js';
+import { PLACEHOLDER_APIFY_TOKEN, USER_AGENT_ORIGIN } from './const.js';
 
 /**
  * Adds a User-Agent header to the request config.
@@ -25,12 +25,14 @@ export function getApifyAPIBaseUrl(): string {
 export class ApifyClient extends _ApifyClient {
     constructor(options: ApifyClientOptions) {
         /**
-         * In order to publish to DockerHub, we need to run their build task to validate our MCP server.
-         * This was failing since we were sending this dummy token to Apify in order to build the Actor tools.
-         * So if we encounter this dummy value, we remove it to use Apify client as unauthenticated, which is sufficient
-         * for server start and listing of tools.
+         * Placeholder token handling (Smithery/Docker Hub).
+         *
+         * We use a placeholder token to allow non-interactive environments (Smithery scans,
+         * Docker Hub builds) to traverse tool-loading paths without real secrets. The placeholder
+         * does not authorize any API calls. If detected here, we drop it and run unauthenticated,
+         * which is enough for server startup and listing tools (where possible).
          */
-        if (options.token?.toLowerCase() === 'your-apify-token') {
+        if (options.token?.toLowerCase() === PLACEHOLDER_APIFY_TOKEN) {
             // eslint-disable-next-line no-param-reassign
             delete options.token;
         }

src/const.ts

@@ -80,3 +80,13 @@ export const ALGOLIA = {
 export const PROGRESS_NOTIFICATION_INTERVAL_MS = 5_000; // 5 seconds
 
 export const APIFY_STORE_URL = 'https://apify.com';
+
+/**
+ * Placeholder token used during non-interactive environments (e.g., Docker Hub builds, Smithery scans)
+ * to allow tool-loading code paths to execute without failing hard when a real APIFY_TOKEN is unavailable.
+ *
+ * IMPORTANT: This token does not authorize any API calls. It is only a sentinel to:
+ * - Unblock Smithery's initial tool scan so tools can be listed after deployment
+ * - Avoid crashes in Docker Hub image builds where secrets are not present
+ */
+export const PLACEHOLDER_APIFY_TOKEN = 'your-apify-token';

src/mcp/server.ts

@@ -51,6 +51,11 @@ export class ActorsMcpServer {
     private options: ActorsMcpServerOptions;
     private toolsChangedHandler: ToolsChangedHandler | undefined;
     private sigintHandler: (() => Promise<void>) | undefined;
+    // Barrier to gate the first listTools until initial load settles.
+    // NOTE: This mechanism is intended to be used ONLY by the Smithery entrypoint
+    // (see src/smithery.ts). Other server entrypoints (stdio/SSE/HTTP) do not
+    // use this and are unaffected.
+    private listToolsBarrier: Promise<void> | null = null;
 
     constructor(options: ActorsMcpServerOptions = {}, setupSigintHandler = true) {
         this.options = {
@@ -89,6 +94,20 @@ export class ActorsMcpServer {
         });
     }
 
+    /**
+     * Block the first listTools request until the provided promise settles or a timeout elapses.
+     * Subsequent listTools calls are not blocked unless this method is invoked again.
+     *
+     * This is used exclusively by the Smithery entrypoint to satisfy its synchronous
+     * factory requirement while ensuring initial tools are available on the first
+     * listTools call. Other entrypoints should not rely on this.
+     */
+    public blockListToolsUntil(promise: Promise<unknown>, timeoutMs = 8_000) {
+        const done = Promise.resolve(promise).then(() => undefined).catch(() => undefined);
+        const timeout = new Promise<void>((resolve) => setTimeout(resolve, timeoutMs));
+        this.listToolsBarrier = Promise.race([done, timeout]).then(() => undefined);
+    }
+
     /**
      * Returns an array of tool names.
      * @returns {string[]} - An array of tool names.
@@ -391,6 +410,10 @@ export class ActorsMcpServer {
          * @returns {object} - The response object containing the tools.
          */
         this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+            if (this.listToolsBarrier) {
+                await this.listToolsBarrier;
+                this.listToolsBarrier = null;
+            }
             const tools = Array.from(this.tools.values()).map((tool) => getToolPublicFieldOnly(tool.tool));
             return { tools };
         });

src/smithery.ts

@@ -11,6 +11,7 @@ import { ActorsMcpServer } from './mcp/server.js';
 import type { Input, ToolCategory } from './types';
 import { serverConfigSchemaSmithery as configSchema } from './types.js';
 import { loadToolsFromInput } from './utils/tools-loader.js';
+import { PLACEHOLDER_APIFY_TOKEN } from './const.js';
 
 // Export the config schema for Smithery. The export must be named configSchema
 export { configSchema };
@@ -21,20 +22,14 @@ export { configSchema };
  */
 export default function ({ config: _config }: { config: z.infer<typeof configSchema> }) {
     try {
-        const apifyToken = _config.apifyToken || process.env.APIFY_TOKEN || '';
+        let apifyToken = _config.apifyToken || process.env.APIFY_TOKEN || '';
         const enableAddingActors = _config.enableAddingActors ?? true;
         const actors = _config.actors || '';
         const actorList = actors ? actors.split(',').map((a: string) => a.trim()) : [];
         const toolCategoryKeys = _config.tools ? _config.tools.split(',').map((t: string) => t.trim()) : [];
 
-        // Validate environment
-        if (!apifyToken) {
-            // eslint-disable-next-line no-console
-            console.warn('APIFY_TOKEN is required but not set in the environment variables or config. Some tools may not work properly.');
-        } else {
-            process.env.APIFY_TOKEN = apifyToken; // Ensure token is set in the environment
-        }
-
+        console.log(`Apify token ${apifyToken}`)
+        process.env.APIFY_TOKEN = apifyToken; // Ensure token is set in the environment
         const server = new ActorsMcpServer({ enableAddingActors, enableDefaultActors: false });
 
         const input: Input = {
@@ -43,21 +38,27 @@ export default function ({ config: _config }: { config: z.infer<typeof configSch
             tools: toolCategoryKeys as ToolCategory[],
         };
 
-        // NOTE: This is a workaround for Smithery's requirement of a synchronous function
-        // We load tools asynchronously and attach the promise to the server
-        // However, this approach is NOT 99% reliable - the external library may still
-        // try to use the server before tools are fully loaded
-        loadToolsFromInput(input, apifyToken, actorList.length === -1)
-            .then((tools) => {
+        // Start async tools loading and gate the first listTools (Smithery-only)
+        // See docs/smithery.md for a brief overview of how this entrypoint works with Smithery
+        const loadPromise = (async () => {
+            try {
+                const tools = await loadToolsFromInput(input, apifyToken, actorList.length === 0);
                 server.upsertTools(tools);
-                return true;
-            })
-            .catch((error) => {
+            } catch (error) {
                 // eslint-disable-next-line no-console
-                console.error('Failed to load tools:', error);
-                return false;
-            });
+                console.error('Failed to load tools with provided token. Retrying with placeholder token, error', error);
+                try {
+                    const tools = await loadToolsFromInput(input, PLACEHOLDER_APIFY_TOKEN, actorList.length === 0);
+                    server.upsertTools(tools);
+                } catch (retryError) {
+                    // eslint-disable-next-line no-console
+                    console.error('Retry failed to load tools with placeholder token, error:', retryError);
+                }
+            }
+        })();
+        server.blockListToolsUntil(loadPromise);
         return server.server;
+
     } catch (e) {
         // eslint-disable-next-line no-console
         console.error(e);

tests/unit/smithery.test.ts

@@ -0,0 +1,30 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import log from '@apify/log';
+
+import * as toolsLoader from '../../src/utils/tools-loader.js';
+import { ActorsMcpServer } from '../../src/mcp/server.js';
+import smithery from '../../src/smithery.js';
+
+// Silence logs in unit tests
+log.setLevel(log.LEVELS.OFF);
+
+describe('smithery entrypoint barrier behavior', () => {
+    beforeEach(() => {
+        vi.restoreAllMocks();
+    });
+
+    it('calls blockListToolsUntil', async () => {
+        // Arrange
+        const blockSpy = vi.spyOn(ActorsMcpServer.prototype as any, 'blockListToolsUntil');
+        const loadSpy = vi.spyOn(toolsLoader, 'loadToolsFromInput').mockResolvedValue([]);
+
+        // Act
+        const server = smithery({ config: { apifyToken: 'TEST_TOKEN', enableAddingActors: true } as any });
+
+        // Assert
+        expect(server).toBeTruthy();
+        expect(blockSpy).toHaveBeenCalledTimes(1);
+        expect(loadSpy).toHaveBeenCalledTimes(1);
+    });
+});