MCP сървър
MCP сървър
Използвайте FourA от всеки клиент на Model Context Protocol (Claude Desktop, Claude Code, Cursor, Windsurf, VS Code) като четири вградени инструмента и шест работни prompt шаблона. Без интеграционен код, без персонализиран HTTP клиент.
Отворен код в GitHub; в npm като @fouradata/mcp. Текуща версия: 0.8.3.
Бърз старт: локално stdio (препоръчително за Claude Desktop)
Вземете ключ от 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, а неуспешно изпълнение включваattemptReportfoura_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 може да проверява състоянието на инстанса.