feat: add MCP server card (SEP-1649) (#453)

Add getServerCard() function that returns structured server metadata
for client discovery via /.well-known/mcp/server-card.json.

- Reuse existing constants (SERVER_NAME, SERVER_VERSION, APIFY_MCP_URL)
- Load description dynamically from server.json via readJsonFile helper
- Export ServerCard type and getServerCard via index-internals
- Add readJsonFile utility, fix createRequire anti-pattern in version.ts
- Export APIFY_FAVICON_URL and SERVER_TITLE for internal repo reuse

Author: MQ37

src/const.ts

@@ -18,6 +18,7 @@ export const TOOL_MAX_OUTPUT_CHARS = 50000;
 
 // MCP Server
 export const SERVER_NAME = 'apify-mcp-server';
+export const SERVER_TITLE = 'Apify MCP Server';
 export const SERVER_VERSION = '1.0.0';
 
 // User agent headers
@@ -171,7 +172,9 @@ export const ALLOWED_DOC_DOMAINS = [
 export const PROGRESS_NOTIFICATION_INTERVAL_MS = 5_000; // 5 seconds
 
 export const APIFY_STORE_URL = 'https://apify.com';
+export const APIFY_FAVICON_URL = `${APIFY_STORE_URL}/favicon.ico`;
 export const APIFY_MCP_URL = 'https://mcp.apify.com';
+export const APIFY_DOCS_MCP_URL = 'https://docs.apify.com/platform/integrations/mcp';
 
 // Telemetry
 export const TELEMETRY_ENV = {

src/index-internals.ts

@@ -3,38 +3,45 @@
 */
 
 import { ApifyClient } from './apify-client.js';
-import { defaults, HelperTools } from './const.js';
+import { APIFY_FAVICON_URL, defaults, HelperTools, SERVER_NAME, SERVER_TITLE } from './const.js';
 import { processParamsGetTools } from './mcp/utils.js';
+import { getServerCard } from './server_card.js';
 import { addTool } from './tools/helpers.js';
 import { defaultTools, getActorsAsTools, getUnauthEnabledToolCategories, toolCategories,
     toolCategoriesEnabledByDefault, unauthEnabledTools } from './tools/index.js';
 import { actorNameToToolName } from './tools/utils.js';
-import type { ActorStore, ToolCategory, UiMode } from './types.js';
-import { parseCommaSeparatedList, parseQueryParamList } from './utils/generic.js';
+import type { ActorStore, ServerCard, ToolCategory, UiMode } from './types.js';
+import { parseCommaSeparatedList, parseQueryParamList, readJsonFile } from './utils/generic.js';
 import { redactSkyfirePayId } from './utils/logging.js';
 import { getExpectedToolNamesByCategories } from './utils/tool-categories-helpers.js';
 import { getToolPublicFieldOnly } from './utils/tools.js';
 import { TTLLRUCache } from './utils/ttl-lru.js';
 
 export {
+    APIFY_FAVICON_URL,
     ApifyClient,
     getExpectedToolNamesByCategories,
+    getServerCard,
     TTLLRUCache,
     actorNameToToolName,
     HelperTools,
+    SERVER_NAME,
+    SERVER_TITLE,
     defaults,
     defaultTools,
     addTool,
     toolCategories,
     toolCategoriesEnabledByDefault,
     type ActorStore,
+    type ServerCard,
     type ToolCategory,
     type UiMode,
     processParamsGetTools,
     getActorsAsTools,
     getToolPublicFieldOnly,
     getUnauthEnabledToolCategories,
     unauthEnabledTools,
+    readJsonFile,
     parseCommaSeparatedList,
     parseQueryParamList,
     redactSkyfirePayId,

src/server_card.ts

@@ -0,0 +1,36 @@
+import { LATEST_PROTOCOL_VERSION } from '@modelcontextprotocol/sdk/types.js';
+
+import { APIFY_DOCS_MCP_URL, APIFY_FAVICON_URL, SERVER_NAME, SERVER_TITLE, SERVER_VERSION } from './const.js';
+import type { ServerCard } from './types.js';
+import { readJsonFile } from './utils/generic.js';
+
+const serverJson = readJsonFile<{ description: string }>(import.meta.url, '../server.json');
+
+/** Returns the MCP server card object per SEP-1649. */
+export function getServerCard(): ServerCard {
+    return {
+        $schema: 'https://static.modelcontextprotocol.io/schemas/mcp-server-card/v1.json',
+        version: '1.0',
+        protocolVersion: LATEST_PROTOCOL_VERSION,
+        serverInfo: {
+            name: SERVER_NAME,
+            title: SERVER_TITLE,
+            version: SERVER_VERSION,
+        },
+        description: serverJson.description,
+        iconUrl: APIFY_FAVICON_URL,
+        documentationUrl: APIFY_DOCS_MCP_URL,
+        transport: {
+            type: 'streamable-http',
+            endpoint: '/',
+        },
+        capabilities: {
+            tools: { listChanged: true },
+        },
+        authentication: {
+            required: true,
+            schemes: ['bearer', 'oauth2'],
+        },
+        tools: 'dynamic',
+    };
+}

src/types.ts

@@ -512,3 +512,30 @@ export type ApifyRequestParams = {
     /** Allow any other request parameters */
     [key: string]: unknown;
 };
+
+/** MCP Server Card per SEP-1649. */
+export type ServerCard = {
+    $schema: string;
+    version: string;
+    protocolVersion: string;
+    serverInfo: {
+        name: string;
+        title: string;
+        version: string;
+    };
+    description: string;
+    iconUrl: string;
+    documentationUrl: string;
+    transport: {
+        type: string;
+        endpoint: string;
+    };
+    capabilities: {
+        tools: { listChanged: boolean };
+    };
+    authentication: {
+        required: boolean;
+        schemes: string[];
+    };
+    tools: string;
+};

src/utils/generic.ts

@@ -1,3 +1,22 @@
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Reads and parses a JSON file relative to the caller's module URL.
+ * Resolves the path from the directory of the calling module (via `import.meta.url`).
+ *
+ * @param importMetaUrl - The `import.meta.url` of the calling module.
+ * @param relativePath - The relative path to the JSON file from the calling module.
+ * @returns The parsed JSON content.
+ * @example
+ * const serverJson = readJsonFile(import.meta.url, '../../server.json');
+ */
+export function readJsonFile<T = unknown>(importMetaUrl: string, relativePath: string): T {
+    const jsonPath = resolve(dirname(fileURLToPath(importMetaUrl)), relativePath);
+    return JSON.parse(readFileSync(jsonPath, 'utf-8')) as T;
+}
+
 /**
  * Parses a comma-separated string into an array of trimmed strings.
  * Empty strings are filtered out after trimming.

src/utils/version.ts

@@ -1,7 +1,6 @@
-import { createRequire } from 'node:module';
+import { readJsonFile } from './generic.js';
 
-const require = createRequire(import.meta.url);
-const packageJson = require('../../package.json');
+const packageJson = readJsonFile<{ version?: string }>(import.meta.url, '../../package.json');
 
 /**
  * Gets the package version from package.json

tests/unit/server-card.test.ts

@@ -0,0 +1,64 @@
+import { LATEST_PROTOCOL_VERSION } from '@modelcontextprotocol/sdk/types.js';
+import { describe, expect, it } from 'vitest';
+
+import { SERVER_NAME, SERVER_TITLE, SERVER_VERSION } from '../../src/const.js';
+import { getServerCard } from '../../src/server_card.js';
+import { readJsonFile } from '../../src/utils/generic.js';
+
+const serverJson = readJsonFile<{ description: string }>(import.meta.url, '../../server.json');
+
+describe('getServerCard', () => {
+    it('should return a valid MCP server card object', () => {
+        const card = getServerCard();
+
+        expect(card.$schema).toBe('https://static.modelcontextprotocol.io/schemas/mcp-server-card/v1.json');
+        expect(card.version).toBe('1.0');
+        expect(card.protocolVersion).toBe(LATEST_PROTOCOL_VERSION);
+    });
+
+    it('should contain required serverInfo fields using constants from const.ts', () => {
+        const card = getServerCard();
+
+        expect(card.serverInfo.name).toBe(SERVER_NAME);
+        expect(card.serverInfo.title).toBe(SERVER_TITLE);
+        expect(card.serverInfo.version).toBe(SERVER_VERSION);
+    });
+
+    it('should declare streamable-http transport at root endpoint', () => {
+        const card = getServerCard();
+
+        expect(card.transport.type).toBe('streamable-http');
+        expect(card.transport.endpoint).toBe('/');
+    });
+
+    it('should declare tools capability with listChanged', () => {
+        const card = getServerCard();
+
+        expect(card.capabilities.tools.listChanged).toBe(true);
+    });
+
+    it('should require authentication with bearer and oauth2 schemes', () => {
+        const card = getServerCard();
+
+        expect(card.authentication.required).toBe(true);
+        expect(card.authentication.schemes).toEqual(['bearer', 'oauth2']);
+    });
+
+    it('should declare tools as dynamic', () => {
+        const card = getServerCard();
+
+        expect(card.tools).toBe('dynamic');
+    });
+
+    it('should load description from server.json', () => {
+        const card = getServerCard();
+
+        expect(card.description).toBe(serverJson.description);
+    });
+
+    it('should include documentation URL', () => {
+        const card = getServerCard();
+
+        expect(card.documentationUrl).toBe('https://docs.apify.com/platform/integrations/mcp');
+    });
+});