MCP сървър

MCP сървър

Използвайте FourA от всеки клиент на Model Context Protocol (Claude Desktop, Claude Code, Cursor, Windsurf, VS Code) като четири вградени инструмента и шест работни prompt шаблона. Без интеграционен код, без персонализиран HTTP клиент.

Отворен код в GitHub; в npm като @fouradata/mcp. Текуща версия: 0.8.3.

Вземете ключ от foura.ai/dashboard#api-keys (с едно щракване, формат pk_live_..., а Reveal показва ключа отново по-късно). Поставете това в конфигурацията на вашия MCP клиент:

{
  "mcpServers": {
    "foura": {
      "command": "npx",
      "args": ["-y", "@fouradata/mcp"],
      "env": { "FOURA_API_KEY": "pk_live_..." }
    }
  }
}

Особеност при Claude Desktop: затворете напълно Claude Desktop (Cmd+Q на macOS) преди да редактирате конфигурационния файл. Ако приложението все още работи, то ще презапише вашите промени с конфигурацията от паметта си при изход.

Командата npx изтегля @fouradata/mcp при първото стартиране и го изпълнява като подпроцес на вашия MCP клиент. Не е необходима глобална инсталация.

Клиент Къде се намира конфигурацията
Claude Desktop (macOS) ~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop (Windows) %APPDATA%\Claude\claude_desktop_config.json
Claude Code claude mcp add foura -- npx -y @fouradata/mcp (първо задайте FOURA_API_KEY в средата)
Cursor ~/.cursor/mcp.json
Windsurf ~/.codeium/windsurf/mcp_config.json
VS Code (MCP разширение) .vscode/mcp.json, под ключ от най-високо ниво servers вместо mcpServers

Рестартирайте клиента. Инструментите (foura_auto, foura_single, foura_proxy, foura_browser) и шест prompt-а се появяват във вашия списък с инструменти.

Бърз старт: хостван (Streamable HTTP)

За клиенти, които поддържат Streamable HTTP транспорт (Cursor, Windsurf, VS Code, Claude Code с --transport http), насочете ги към хоствания endpoint вместо да стартирате локален подпроцес:

{
  "mcpServers": {
    "foura": {
      "url": "https://mcp.foura.ai/mcp",
      "headers": {
        "Authorization": "Bearer pk_live_..."
      }
    }
  }
}

За Claude Desktop използвайте горната конфигурация за stdio или свържете хоствания endpoint чрез mcp-remote:

{
  "mcpServers": {
    "foura": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.foura.ai/mcp", "--header", "Authorization: Bearer pk_live_..."]
    }
  }
}

Референция за хоствания endpoint

Свойство Стойност
URL https://mcp.foura.ai/mcp
Транспорт Streamable HTTP (POST /mcp, SSE отговори)
Автентикация Authorization: Bearer pk_live_... за заявка. Обикновен ключ в Authorization или X-API-Key: pk_live_... също работи
MCP-Protocol-Version Според @modelcontextprotocol/sdk (в момента 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05, 2024-10-07)
401 предизвикателство WWW-Authenticate: Bearer realm="foura-mcp"

Предизвикателството 401 умишлено не съдържа RFC 9728 resource_metadata параметър. Обявяването му кара клиент с поддръжка на OAuth да стартира процес, който този сървър не имплементира. Изпратете вашия pk_live_ ключ като Bearer token и грешката 401 изчезва.

Хостваният сървър е stateless. Всяка заявка носи собствен ключ, който сървърът препраща към FourA API като X-API-Key. Един ключ отключва и четирите инструмента.

За защита срещу DNS-rebinding (CVE-2025-66414) сървърът валидира заглавката Host (трябва да бъде mcp.foura.ai или localhost) и заглавката Origin, когато е налична (в списъка с разрешени: mcp.foura.ai, claude.ai, app.cursor.sh, app.cursor.com). Заявките между сървъри (curl, MCP клиенти в режим stdio bridge) не изпращат Origin и преминават директно.

Инструменти

И четирите инструмента са анотирани с readOnlyHint: true и openWorldHint: true съгласно спецификацията на MCP от 2025-06-18. Клиенти, които автоматично одобряват надеждни инструменти само за четене, ги извикват без модален прозорец за потвърждение на всяка заявка.

foura_auto е интелигентният избор по подразбиране: подайте му URL и той връща съдържанието, като избира метода за извличане вместо вас. Другите три са примитиви от по-ниско ниво, които той оркестрира; използвайте ги, когато искате изричен контрол.

foura_auto

Подайте му URL, когато искате FourA да избере метода на заявката. Той прави ограничен брой опити през наличните HTTP, proxy и browser пътища. Подайте validate при защитени цели, така че отговорът задължително да съдържа съдържание, което идентифицира истинската страница. Ако нито един опит не покрие валидацията, инструментът връща грешка, вместо да представя страница с предизвикателство като успех.

Отговорът включва детайли за изпълнението в meta и по подразбиране многократно използваем session с proxy, cookies и userAgent. За обикновена последваща заявка извикайте foura_single с session.proxy като proxy, сериализирайте бисквитките като Cookie заглавка и изпратете session.userAgent като заглавката User-Agent. За JavaScript рендиране подайте стойностите на сесията към съответстващите foura_browser полета.

Задайте exitClass: "premium", за да позволите на Auto да ескалира до премиум изход, след като стандартният пул не може да достигне страницата. exitClass: "standard" и пропускането на полето запазват Auto в стандартния пул, като само request, който посочва клас, получава обратно exitClass. Работи както при foura_proxy: позволение, а не инструкция, отчита се към премиум трафика в плана ви и се отхвърля с code: "plan_limit_premium" при план без премиум изходи. Полето exitClass в резултата показва кой клас е доставил отговора. Вижте exitClass в Smart Fetch.

foura_single

Един HTTP request, един върнат response. Съответства на POST /api/single/ едно към едно.

Използвайте за статични страници, JSON API, сървърно рендиран HTML.

Избор на браузъра, който представяте

По подразбиране даден request представя най-новия Google Chrome. Когато целта приема един браузър и отхвърля друг, задайте browser (Chrome, Edge, Safari, Firefox или Tor), os (Windows, macOS, Android или iOS), или version, или подайте точен profile id:

{
  "method": "GET",
  "url": "https://example.com",
  "browser": "Firefox",
  "os": "Windows"
}

Най-новата версия има предимство, когато съвпадат няколко профила. Комбинация, която не съществува, връща грешка с наличните опции, така че request никога не се изпраща като browser, който не сте избрали. За селекцията е необходим unblocker, който е включен по подразбиране. Каталогът е публикуван на GET /api/profiles и не изисква API key.

Същите четири полета се намират вътре в обекта request на foura_proxy.

foura_proxy

Пренасочете един HTTP request през ротиращи проксита с автоматичен retry. Използвайте го, когато foura_single е блокиран или целта изисква конкретна изходна държава.

Задайте exitCountries към стриктен allowlist от двубуквени кодове на държави, видими за целта, предоставени от потребителя или изискванията на целта:

{
  "maxTries": 5,
  "exitCountries": ["CZ", "GB"],
  "request": {
    "method": "GET",
    "url": "https://example.com/pricing",
    "browser": "Chrome",
    "os": "Windows"
  }
}

Стойностите се изчистват от интервали, преобразуват се в главни букви и се дедупликират. Изходите от стандартния пул с неизвестна държава се изключват, като стандартният пул никога не преминава към незаявена държава. Премиум изходът също остава в списъка: при exitClass: "premium" стандартният пул пак има предимство, а премиум изходът излиза от някоя от вашите държави и я посочва във exitCountry. Изборът използва най-новите налични метаданни за държавата, видими за целевия ресурс, обикновено обновявани в рамките на десет минути; това не е геолокационно търсене на живо по време на заявката. Не определяйте обслужващата държава по хост адреса на проксито.

Успешно изпълнение с филтър връща exitCountry и ID за повторно използване във proxy. Проверете дали exitCountry принадлежи към заявения списък с разрешени държави. Ако текущият пул няма съвпадение, инструментът връща code: "no_eligible_proxy" с нормализирания обхват във details.exitCountries. Запазете този обхват и опитайте отново по-късно. Променяйте или разширявайте обхвата само когато потребителят изрично промени изискването. Филтрирането по държава е включено от план Startup нагоре. При план без тази функция извикване, което изпраща exitCountries, се отхвърля с 403 и X-FourA-Limit: plan_limit_feature.

Ако избраната страница по-късно изисква JavaScript, предайте върнатото proxy ID към foura_browser.proxy, за да може браузърът да използва същия изход.

Задайте exitClass: "premium" за целеви ресурс, който стандартният пул не може да достигне, независимо от броя изпробвани изходи. Това е разрешение, а не инструкция: стандартният пул все още се опитва пръв да даде отговор и обикновено успява, а заявка, обслужена от него преди опит с премиум изход, не консумира премиум трафик. При опит през премиум изход се отчита пренесеният трафик, дори ако опитът е неуспешен. Отговорът връща обратно exitClass, premium или standard, за да виждате за всяка заявка кой клас ви е обслужил. standard е отговорът и след като включеният във вашия план премиум трафик бъде изчерпан, което представлява нормален резултат, а не грешка. exitClass: "standard" изрично забранява ескалацията. exitClass: "premium" при план без премиум изходи се отхвърля с code: "plan_limit_premium". Вижте exitClass.

Когато ротацията е трябвало да премине към друг браузър, за да получи отговор, успешният отговор съдържа profile: идентификатора на профила от каталога, на който се е установила. Предайте го като profile при следващото извикване, за да представите същия браузър.

Неуспешната ротация връща attemptReport до грешката: едно изречение summary плюс броячи, които разделят изходите, които никога не са отговорили (noResponse), изходите, отхвърлени от проверка за ботове (defense, с доставчиците във vendors), страниците, които са получени и отхвърлени единствено от вашето собствено правило validate.data (contentRejected), statusRejected и other. profilesTried изброява браузърите, изпратени от задачата, подредени по първо използване, като default означава, че заявката е изпратена точно както е зададена. Висока стойност на contentRejected означава, че FourA е доставил реални страници, а вашето собствено правило ги е отхвърлило. Вижте Why a Proxy Request Ran Out of Tries.

foura_browser

Пълна браузърна сесия. JavaScript се изпълнява, DOM се рендерира, бисквитките се връщат. Отразява POST /api/browser/.

Използвайте за single-page приложения, lazy-loaded съдържание или страници с проверка, изискваща истински браузър за преминаване.

За структури на входните данни, стойности по подразбиране и правила за валидация на всеки инструмент вижте справката за REST endpoint. Схемите на инструментите съвпадат с тези на REST API, плюс опцията за включване само в MCP offload_large (вижте по-долу), с две изключения: foura_browser няма поле lean, а foura_proxy все още няма полета за exit location. Стойност, изпратена под тези имена, никога не достига до API. За да зададете такава, извикайте директно POST /api/browser/ или POST /api/proxy/.

Когато целта изпълнява проверка за ботове

foura_single и foura_proxy връщат defense, когато целта е изпълнила проверка за ботове по пътя към body. defense.solved: true означава, че проверката е премината и data е истинската страница; false означава, че тялото може да е challenge страница. Опитайте отново с различен браузър, os или версия, или преминете към foura_proxy или foura_browser, вместо да третирате challenge страницата като съдържание.

Типизирани отговори

Всеки отговор на инструмент включва както content (четим от хора текстов обзор), така и structuredContent (типизиран JSON, валидиран спрямо outputSchema на инструмента). Всеки инструмент има своя собствена уникална структура:

  • foura_auto: единична структура { status, headers, data } плюс meta ({ rung, solved, attempts, credits, attemptsByEngine, browserRequests }, винаги присъстващ, където rung е едно от cache, probe, proxy, browser, warmup, fail) и по подразбиране session ({ proxy, cookies, userAgent }) за повторно изпълнение чрез инструментите от по-ниско ниво; request, посочил клас, включва също exitClass. meta.attemptsByEngine брои заявките, изпратени от извикването към Single, Proxy и Browser, а meta.browserRequests брои тези, които са използвали дневния ви лимит за Browser. Неуспешно изпълнение включва и attemptReport. Без total_time.
  • foura_single: { status, headers, data, total_time, ... } (headers е масив, по един запис за всяка стъпка на пренасочване)
  • foura_proxy: същото като single плюс { proxy, total }; успешен опит с обхват включва също exitCountry, заявка с посочен клас включва exitClass, ротация с променена браузърна фамилия включва profile, а неуспешно изпълнение включва attemptReport
  • foura_browser: отделна структура { status, headers: object, body, cookies, userAgent } (забележка: body може да бъде низ или обект в зависимост от content-type)

Всеки инструмент също така докладва стойността на извикването и как да бъде проследено то, прочетено от response headers на API:

  • credits: кредити, изразходвани за това повикване. Налице е и при неуспешни изпълнения, тъй като работата е била извършена. Таксуват се само успешни повиквания, така че при грешка кредитите се показват тук, но не ви струват нищо.
  • request_id: идентификаторът на повикването във FourA. Цитирайте го при запитване към поддръжката.
  • exitClass: premium, когато повикването е обслужено от premium exit. При foura_single и foura_browser това се случва, когато proxy преизползва premium exit, намерен от foura_proxy или foura_auto.

Всяко от тях липсва, когато API не е върнал данни, така че клиент, разработен за по-ранна версия, продължава да работи без промяна. Същите стойности са документирани в Response Headers.

Клиентите, които поддържат structuredContent, могат да предадат типизирания обект директно към LLM, вместо да изискват от него да парсва JSON от свободен текст.

Многостойностни response headers

Заглавки, които се появяват многократно (Set-Cookie, Link, WWW-Authenticate), се връщат като масиви:

{
  "headers": [
    {
      "result": { "version": "HTTP/2", "code": 200, "reason": "" },
      "content-type": "text/html",
      "set-cookie": ["a=1; Path=/", "b=2; Path=/"]
    }
  ]
}

Това е важно за сайтове, които задават session + tracking + consent cookies в един response (повечето сайтове за електронна търговия).

Големи responses: offload_large (по подразбиране: inline)

По подразбиране (от v0.2.0 насам) пълните response bodies се връщат inline в structuredContent независимо от размера. Това работи директно във всеки MCP клиент.

Ако вашият клиент поддържа MCP resources/read И искате спестяване на токени при големи страници, подайте offload_large: true при всяко tool извикване. Responses >= 50 KB тогава се записват на диска, връщат се като resource_link, а вашият клиент изтегля body само когато реално му е необходимо. На хоствания сървър кешираните payloads изтичат след 1 час. На ваша собствена инстанция нищо не изтрива съхранените payloads: изчиствайте файловете, по-стари от един час, от директорията за payloads сами.

Резултат с offload съдържа offloaded_resource_uri и size_bytes на мястото на body. Резултат с offload също така пропуска defense, както и profile при foura_proxy, така че пропуснете offload_large при извикване, което чете тези полета.

{
  "method": "GET",
  "url": "https://en.wikipedia.org/wiki/Web_scraping",
  "offload_large": true
}
Клиент offload_large: true
Claude Desktop все още не, оставете по подразбиране false
Claude Code, Cursor, Windsurf поддържа се
VS Code MCP extension поддържа се

Изолирано по наематели: всеки API ключ получава собствено именно пространство (sha256(apiKey)[:16]). Само ключът, съхранил даден payload, може да го прочете обратно. Четенията между различни наематели връщат Payload not found без изтичане на информация за съществуване.

Вградени Prompts

Шест шаблона за работни процеси са налични под /prompts във всеки MCP клиент. Всеки от тях приема именувани аргументи и връща шаблонизирано потребителско съобщение, което оркестрира един или повече инструменти.

Prompt Аргументи Какво прави
smart_fetch url, опционален must_contain, extract Автоматично извличане (избира метода, обработва защитата от ботове), след което връща или извлича съдържанието
scrape_product_page url Браузърно извличане, след което извлича заглавие на продукта, цена, изображение, наличност, SKU като JSON
extract_article url Единично извличане с резервен вариант към proxy, след което премахва навигация/реклами и връща изчистен JSON на статията
monitor_pricing url, опционален target_price Proxy извличане, извлича текуща цена, сравнява с целевата
check_endpoint_health url, опционален expected_text Единично извличане със стриктна валидация, връща достъпност и време за отговор
bulk_fetch_urls urls (разделени със запетая) Паралелно единично извличане, автоматичен резервен вариант към proxy за всеки URL, връща само метаданни

Prompts струват нула токени в покой. Само извиканите prompts влизат в LLM контекста.

Пълен текст плюс ръчни резервни prompts: MCP Рецепти.

Обвивка за грешки

Всяка грешка (isError: true) съдържа structuredContent обвивка. Минимални полета за всяка грешка:

{
  "service": "auto | single | proxy | browser",
  "code": "rate_limited",
  "error": "Rate limit exceeded"
}

При грешки от upstream с HTTP статус е налице и status. При rate-limit грешки и превишен капацитет обвивката на upstream добавя retryAfter, current.{concurrency, rpm} и limits.{maxConcurrency, maxRpm}. Вижте API грешки за базовата REST структура.

Стабилни стойности за code:

Код HTTP Значение Безопасно ли е повторно изпращане?
ssrf_blocked n/a Целта е частен или резервиран адрес (RFC 5735, 6598, IPv6 reserved), URL адресът не е http(s), или неговият host name не се резолва Не, проверете URL адреса. Справка, която се е провалила за кратко, може да се опита отново
upstream_non_json варира Upstream върна деформирано тяло Може би, разследвайте
output_validation_failed n/a outputSchema на MCP сървъра отхвърли upstream отговора, или инструментът не успя изобщо да завърши извикването (няма конфигуриран API key, API е недостъпно) Може би: проверете конфигурацията, след което докладвайте
bad_request 400 Форматът на входящите данни е отхвърлен, целевият URL сочи към собственото API на FourA вместо към страница (само /inspect може да бъде извлечен там), или URL адресът съдържа некодиран интервал (кодирайте го като %20) Не, коригирайте аргументите
auth_failed 401 Липсващ, невалиден или деактивиран ключ Не, коригирайте ключа
forbidden 403 Целта отговори с 403 и вашият validate го отхвърли (проверка на сайта, ограничение по държава) Не, или превключете към foura_proxy
not_found 404 Липсва цел или endpoint Не
rate_limited 429 Достигнат RPM лимит Да, изчакайте retryAfter
at_capacity 503 Достигнат лимит за едновременни заявки, или услугата е изключена за поддръжка (error показва Service disabled) Да, изчакайте retryAfter
service_disabled 503 Резервирано. Изключена за поддръжка услуга понастоящем се връща като at_capacity, а инструмент, който планът ви не включва, се връща като plan_limit_feature Свържете се с поддръжката
service_unavailable 503 Общ 503 Да, кратко изчакване (short backoff)
upstream_error 500+ или 0 Целта отговори със сървърна грешка, или при foura_proxy, foura_browser и foura_auto изобщо не отговориха Да, експоненциално изчакване (exponential backoff)
upstream_client_error 4xx Друг 4xx Обикновено не
upstream_unknown друго Заявката се изпълни, но не даде приет отговор: при foura_single целта никога не отговори (таймаут, отказана връзка), а при всеки инструмент вашият validate отхвърли отговор 2xx или 3xx. Прочетете status и error Разследвайте
no_eligible_proxy n/a Няма proxy, което да съответства на строгия exitCountries обхват Опитайте отново по-късно; променете обхвата само изрично
plan_limit_* 403 или 429 Един от лимитите на плана ви отказа извикването: plan_limit_, последван от feature, premium, concurrency, rate, browser_daily, credits или bandwidth. Вижте Грешки на MCP сървъра Изчакайте retryAfter, ако е налично; в противен случай не, докато лимитът не се нулира или планът не се промени

LLM агентите могат да четат директно code за логика за повторни опити, без да парсват текст. Ръководство за автентикация: Authentication.

Лимити

  • Inline тяло по подразбиране. С offload_large: true, отговорите >= 50 KB отиват на диск + resource_link (за отделен клиент, 1 час TTL).
  • Частните цели се отказват (RFC 5735, RFC 6598, IPv6 запазени блокове) на MCP слоя. Препращат се само публични хостове.
  • Ограничение на тялото на заявката от 256 KB за входящи /mcp заявки (реалните MCP полезни товари са < 4 KB).
  • Rate limits се налагат от FourA API за всяка услуга. Вижте Rate Limits.

Самостоятелно хостване

Пълният сорс код на сървъра е публичен в GitHub под @fouradata/mcp. Клонирайте хранилището, npm install, npm run build и изпълнете node dist/http.js, за да вдигнете собствен инстанс. Работи stateless в единичен контейнер зад произволен load balancer.

Конфигурируема среда:

Променлива По подразбиране Предназначение
PORT 3076 HTTP порт за слушане
FOURA_API_BASE https://api.foura.ai/api Базов URL за upstream FourA REST
FOURA_MCP_PAYLOADS_DIR папка foura-mcp-payloads в системната временна директория (включеният Docker Compose файл задава /data/payloads) Къде отговорите >= 50 KB се кешират на диска (с offload_large: true)
FOURA_MCP_ALLOWED_HOSTS mcp.foura.ai,localhost,127.0.0.1,[::1] Списък с разрешени имена на хостове за header Host (защита от DNS-rebinding)
FOURA_MCP_ALLOWED_ORIGINS https://mcp.foura.ai,https://claude.ai,https://app.cursor.sh,https://app.cursor.com Списък с разрешени източници (Origin) за извиквания от браузъра

Официалният контейнер работи като uid 1001 (non-root). Включеният Docker Compose файл съхранява /data/payloads на именуван том; bind mount от хоста в този път трябва да бъде с права за запис от това uid.

Мащабирайте хоризонтално зад произволен load balancer. Клиентите предоставят своя ключ с всяка заявка, така че няма sticky session. С offload_large насочете FOURA_MCP_PAYLOADS_DIR към споделено за всички инстанси хранилище, тъй като записаният полезен товар остава на диска на инстанса, който го е записал. GET /healthz отговаря с ok, name и version, така че load balancer може да проверява състоянието на инстанса.

Обновено: 13 ноември 2026 г.