MCP-сервер как Apify Actor — рабочая эталонная реализация

Это исходный код, стоящий за renzomacar/multi-scraper-mcp, — MCP-сервер, который работает как Apify Actor в режиме Standby и предоставляет 16 инструментов для генерации лидов и веб-скрапинга AI-клиентам, таким как Claude, Cursor и Windsurf.

Он опубликован как эталонная реализация, потому что интересная часть — не список инструментов, а три ошибки транспорта, которые не давали реальным клиентам подключиться, при том что каждый запуск сообщал SUCCEEDED.

Три ошибки, которые исправляет этот код

1. Устаревший идентификатор сессии навсегда заклинивал клиента

Сессии живут в Map в памяти, но запуск в режиме Standby — не один долгоживущий процесс: Apify перезапускает его. Клиент, который переподключается во вторник с Mcp-Session-Id от понедельника, попадает в процесс, который о нём никогда не слышал.

Раньше сервер отвечал 400. В спецификации явно сказано, что ответ должен быть 404:

Сервер МОЖЕТ завершить сессию в любой момент, после чего он ОБЯЗАН отвечать на запросы, содержащие этот идентификатор сессии, кодом HTTP 404 Not Found.

Когда клиент получает HTTP 404 [...], он ОБЯЗАН начать новую сессию, отправив новый InitializeRequest без прикреплённого идентификатора сессии.

Путь восстановления клиента привязан к коду состояния. 400 лишает его способности к самовосстановлению. См. sessionGone() в src/main.js.

2. Заголовок Accept отклонял клиентов до того, как выполнялся наш код

Спецификация требует, чтобы клиенты отправляли Accept: application/json, text/event-stream. Некоторые реальные клиенты отправляют только одно из них или вообще ничего, и транспорт отвечает 406 до того, как запрос достигает обработчика, — поэтому в логах ничего нет, а в консоли нет неудачного запуска.

normalizeAccept() всё равно принимает их. Загвоздка: транспорт читает заголовок из req.rawHeaders, поэтому изменение только req.headers ничего не даёт.

3. Медленный инструмент обрывал соединение во время работы

Эти инструменты оборачивают скраперы, которые работают от одной до трёх минут. Без байтов по сети шлюз Standby обрывает соединение. Исправление стримит notifications/message каждые 10 секунд и сбрасывает интервал в finally, чтобы ранний возврат ошибки не мог допустить утечки таймера.

Related MCP server: ZapFetch MCP Server

Честная тарификация

Actor.charge стоит на пути, который реально вернул данные, после того как элементы уже получены, — а не в начале обработчика запроса. Списание по прибытии означает списание за сбои.

Структура

Запуск

npm install
npm start

Затем направьте MCP-клиент на http://localhost:4321/mcp. На платформе Apify URL в режиме Standby — https://USERNAME--ACTOR-NAME.apify.actor/mcp — обратите внимание на префикс USERNAME--; публикация URL без него делает любое копирование-вставку нерабочим.

Проверка, которую стоит провести

Шесть запросов, по одному на каждый баг, который ушёл в продакшн:

1. рукопожатие с корректным заголовком Accept → 200

2. рукопожатие с Accept: application/json → 200 (было 406)

3. рукопожатие без заголовка Accept → 200 (было 406)

4. tools/list с неизвестным идентификатором сессии → 404 (было 400)

5. initialize с всё ещё устаревшим идентификатором → 200 (было 400)

6. tools/list на живой сессии → 200, полный список инструментов

Пункты со 2 по 5 были сломаны в production, при этом Actor сообщал о здоровых запусках.

Лицензия

MIT