# خادم MCP

> URL: https://foura.ai/ar/docs/mcp/server
> Updated: 2026-11-13
> Index: https://foura.ai/llms.txt

استخدم FourA من أي عميل [Model Context Protocol](https://modelcontextprotocol.io) (مثل Claude Desktop وClaude Code وCursor وWindsurf وVS Code) في صورة أربع أدوات أصلية وستة موجهات سير عمل. دون كود تكامل، ودون عميل HTTP مخصص.

مفتوح المصدر على [GitHub](https://github.com/fouradata/mcp)، ومتاح على [npm](https://www.npmjs.com/package/@fouradata/mcp) باسم `@fouradata/mcp`. الإصدار الحالي: `0.8.3`.

## البدء السريع: stdio محلي (موصى به لـ Claude Desktop)

احصل على مفتاح من [foura.ai/dashboard#api-keys](https://foura.ai/dashboard#api-keys) (بنقرة واحدة، بالتنسيق `pk_live_...`، وخيار **Reveal** يعرض المفتاح مجددا لاحقا). أضف هذا في ملف تهيئة عميل MCP الخاص بك:

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

> **ملاحظة هامة حول Claude Desktop:** أغلِق Claude Desktop تمامًا (`Cmd+Q` على macOS) **قبل** تعديل ملف التكوين. إذا كان التطبيق لا يزال قيد التشغيل، فسيستبدل تعديلاتك بالتكوين المحفوظ في الذاكرة عند الخروج.

يُنزّل الأمر `npx` حزمة `@fouradata/mcp` عند التشغيل لأول مرة ويشغّلها كعملية فرعية (subprocess) لعميل 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`) وستة نماذج توجيه (prompts) في قائمة الأدوات الخاصة بك.

## بدء سريع: مستضاف (Streamable HTTP)

بالنسبة للعملاء الذين يدعمون نقل Streamable HTTP (مثل Cursor وWindsurf وVS Code وClaude Code مع `--transport http`)، وجّههم إلى الـ endpoint المستضاف بدلًا من تشغيل عملية فرعية محلية:

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

بالنسبة إلى Claude Desktop، استخدم إعدادات stdio أعلاه أو قم بربط الـ endpoint المستضاف عبر `mcp-remote`:

```json
{
  "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_...` لكل request. يعمل المفتاح المجرد في `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). يرسل كل request مفتاحه الخاص، والذي يمرره الخادم إلى FourA API كـ `X-API-Key`. يتيح المفتاح الواحد الوصول إلى جميع الأدوات الأربع.

للحماية من هجمات DNS-rebinding (CVE-2025-66414)، يتحقق الخادم من header الخاص بـ `Host` (يجب أن يكون `mcp.foura.ai` أو localhost) وheader الخاص بـ `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](https://modelcontextprotocol.io/specification/2025-06-18/server/tools). العملاء الذين يوافقون تلقائيًا على أدوات القراءة فقط الموثوقة يستدعونها دون نافذة تأكيد لكل request.

الأداة `foura_auto` هي الخيار الافتراضي الذكي: مرر لها URL وستعيد المحتوى، مع اختيار طريقة الجلب المناسبة لك. الأدوات الثلاث الأخرى هي العناصر الأساسية ذات المستوى الأدنى التي تنسقها هذه الأداة؛ استخدمها عندما تحتاج إلى تحكم صريح.

### foura_auto

مرر لها URL عندما تريد أن تختار FourA طريقة الـ request. تجري الأداة محاولات محدودة عبر مسارات HTTP، وproxy، والمتصفح المتاحة. مرر `validate` مع الأهداف المحمية لضمان احتواء الـ response على محتوى يحدد الصفحة الحقيقية. إذا لم تستوفِ أي محاولة شروط التحقق، تُرجع الأداة خطأً بدلًا من عرض صفحة اختبار الأمان كنجاح.

تتضمن الـ response تفاصيل الإكمال في `meta`، وبشكل افتراضي، كائن `session` قابل لإعادة الاستخدام مع `proxy`، و`cookies`، و`userAgent`. للمتابعة العادية، استدعِ `foura_single` مع ضبط `session.proxy` كـ `proxy`، وسلسل ملفات cookies كـ `Cookie` header، وأرسل `session.userAgent` كـ `User-Agent` header. لتصيير JavaScript، مرر قيم الجلسة إلى حقول `foura_browser` المطابقة.

اضبط `exitClass: "premium"` للسماح لـ Auto بالترقية إلى منفذ خروج premium بمجرد تعذر وصول المجموعة القياسية إلى الصفحة. يؤدي `exitClass: "standard"` وتجاهل الحقل إلى إبقاء Auto على المجموعة القياسية، ولن يسترجع `exitClass` إلا الـ request الذي يحدد فئة معينة. تعمل هذه الخاصية كما في `foura_proxy`: تصريح وليس توجيهاً، وتُحسب ضمن استهلاك حركة مرور premium في خطتك، وتُرفض بالرمز `code: "plan_limit_premium"` في الخطط التي لا تتضمن منافذ خروج premium. يوضح `exitClass` في النتيجة الفئة التي قامت بالتسليم. راجع [exitClass on Smart Fetch](https://foura.ai/docs/api/endpoints#exitclass-on-smart-fetch).

### foura_single

طلب HTTP واحد، وتلقي response مباشرة. يطابق [`POST /api/single/`](https://foura.ai/docs/api/endpoints) بدقة بنسبة واحد لواحد.

يُستخدم للصفحات الثابتة، وواجهات برمجة تطبيقات JSON APIs، وHTML المُنشأ على الخادم.

#### اختيار المتصفح الذي تقدمه

يُقدم الـ request أحدث إصدار من Google Chrome افتراضياً. عندما يقبل الهدف متصفحاً معيناً ويرفض متصفحاً آخر، اضبط `browser` (سواء Chrome، أو Edge، أو Safari، أو Firefox، أو Tor)، أو `os` (سواء Windows، أو macOS، أو Android، أو iOS)، أو `version`، أو قم بتمرير معرف `profile` محدد:

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

يكون الفوز للإصدار الأحدث عند تطابق عدة ملفات تعريف (profiles). تُرجع التوليفة غير الموجودة خطأً يسرد ما هو متاح، وبذلك لا يتم إرسال أي request مطلقًا كمتصفح لم تختره. يتطلب التحديد تفعيل `unblocker`، وهو مفعّل افتراضيًا. الكتالوج منشور على [`GET /api/profiles`](https://foura.ai/docs/api/endpoints) ولا يتطلب أي API key.

توجد الحقول الأربعة نفسها داخل كائن `request` الخاص بـ `foura_proxy`.

### foura_proxy

توجيه HTTP request واحد عبر proxies متناوبة مع إعادة المحاولة تلقائيًا. استخدمه عندما يكون `foura_single` محظورًا أو عندما يتطلب الهدف بلد خروج محددًا.

اضبط `exitCountries` على قائمة سماح صارمة لرموز البلدان المكونة من حرفين والمرئية للهدف، والمقدمة بواسطة المستخدم أو متطلبات الهدف:

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

تُجرّد القيم من المسافات الزائدة، وتُحوّل إلى أحرف كبيرة، وتُزال التكرارات منها. تُستبعد مخارج standard pool ذات البلد غير المعروف، ولا تعود standard pool أبدًا إلى بلد غير مطلوب. يظل مخرج premium مقيدًا بالقائمة أيضًا: مع `exitClass: "premium"`، تبدأ standard pool أولاً، وينطلق مخرج premium من أحد بلدانك ويُحدد اسمه في `exitCountry`. يعتمد الاختيار على أحدث بيانات وصفية متاحة للبلد كما تظهر للهدف، وتُحدّث عادةً خلال عشر دقائق؛ وهو ليس بحثًا فوريًا عن الموقع الجغرافي أثناء الطلب. لا تستنتج بلد التقديم من عنوان مضيف proxy.

يُرجع النجاح المحدد بنطاق `exitCountry` ومعرف `proxy` القابل لإعادة الاستخدام. تحقق من أن `exitCountry` ينتمي إلى allowlist المطلوبة. إذا لم يتضمن التجمع الحالي أي تطابق، تُرجع الأداة `code: "no_eligible_proxy"` مع النطاق المعياري في `details.exitCountries`. احتفظ بهذا النطاق وأعد المحاولة لاحقًا. لا تغيّره أو توسعه إلا إذا غيّر المستخدم المتطلبات صراحةً. تحديد نطاق البلد مشمول بدءًا من خطة Startup فما فوق. في أي خطة لا تتضمن ذلك، يُرفض الاستدعاء الذي يرسل `exitCountries` مع `403` و`X-FourA-Limit: plan_limit_feature`.

إذا كانت الصفحة المحددة تتطلب JavaScript لاحقًا، مرّر معرف `proxy` المُرجع إلى `foura_browser.proxy` ليعيد المتصفح استخدام المخرج نفسه.

عيّن `exitClass: "premium"` لهدف تعجز standard pool عن الوصول إليه مهما كان عدد المخارج التي تمت تجربتها. هذا إذن وليس أمرًا إلزاميًا: تظل standard pool تتسابق لجلب الاستجابة وتنجح غالبًا، والطلب الذي تجيب عليه قبل تجربة أي مخرج premium لا يستهلك أي حركة مرور premium. تحسب محاولة premium حركة المرور التي نقلتها حتى عند فشلها. تُبلغ الاستجابة بالقيمة `exitClass`، إما `premium` أو `standard`، لتتمكن من معرفة الفئة التي تولت خدمتك في كل طلب. تُعد `standard` أيضًا هي النتيجة بمجرد استنفاد حركة مرور premium المضمنة في خطتك، وهي نتيجة طبيعية وليست خطأً. تمنع `exitClass: "standard"` الترقية تمامًا. يُرفض استخدام `exitClass: "premium"` في خطة لا تتضمن مخارج premium مع `code: "plan_limit_premium"`. راجع [exitClass](https://foura.ai/docs/api/endpoints#exitclass).

عندما يضطر التدوير إلى الانتقال إلى متصفح آخر للحصول على استجابة، تتضمن الاستجابة الناجحة `profile`: معرف ملف التعريف من الدليل الذي استقر عليه. مرره كـ `profile` في الاستدعاء التالي لتقديم نفس المتصفح.

يتضمن التدوير الفاشل `attemptReport` إلى جانب الخطأ: جملة `summary` واحدة، بالإضافة إلى إحصاءات تفصل المخارج التي لم تستجب أبدًا (`noResponse`)، والمخارج التي رفضها فحص bot (`defense`، مع موفري الخدمة في `vendors`)، والصفحات التي وصلت ورُفضت فقط بواسطة `validate.data` الخاص بك (`contentRejected`)، و`statusRejected`، و`other`. تسرد `profilesTried` المتصفحات التي أرسلتها المهمة، بترتيب الاستخدام الأول، وتَعني `default` أن الطلب أُرسل تمامًا كما هو مكتوب. تعني القيمة المرتفعة لـ `contentRejected` أن FourA جلبت صفحات حقيقية وتخلصت منها قاعدتك الخاصة. راجع [Why a Proxy Request Ran Out of Tries](https://foura.ai/docs/troubleshooting/proxy-attempt-report).

### foura_browser

جلسة متصفح كاملة. يتم تشغيل JavaScript، وعرض DOM، واستعادة ملفات cookie. يطابق [`POST /api/browser/`](https://foura.ai/docs/api/endpoints).

يُستخدم لتطبيقات الصفحة الواحدة، أو المحتوى الذي يتم تحميله تدريجياً، أو الصفحات التي تتطلب فحصاً يحتاج إلى متصفح حقيقي لاكتماله.

للاطلاع على هياكل المدخلات والقيم الافتراضية وقواعد التحقق لكل أداة، ارجع إلى [مرجع نقطة نهاية REST](https://foura.ai/docs/api/endpoints). تطابق مخططات الأدوات واجهة برمجة تطبيقات REST API، بالإضافة إلى خيار `offload_large` المخصص لـ MCP فقط (انظر أدناه)، مع استثناءين: `foura_browser` لا يحتوي على حقل `lean`، و`foura_proxy` لا يحتوي على حقول [موقع الخروج](https://foura.ai/docs/api/endpoints#exit-location) حتى الآن. أي قيمة تُرسل تحت هذه الأسماء لا تصل إلى API أبداً. لتعيين قيمة، قم باستدعاء [`POST /api/browser/`](https://foura.ai/docs/api/endpoints) أو [`POST /api/proxy/`](https://foura.ai/docs/api/endpoints) مباشرة.

### عندما يُجري الهدف فحص روبوت

تُرجع `foura_single` و`foura_proxy` القيمة `defense` عندما يُجري الهدف فحص روبوت في الطريق إلى نص الاستجابة. تعني `defense.solved: true` أنه تم اجتياز الفحص وأن `data` هي الصفحة الحقيقية؛ بينما تعني `false` أن نص الاستجابة قد يكون صفحة تحدٍ. أعد المحاولة باستخدام متصفح أو نظام تشغيل أو إصدار مختلف، أو انتقل إلى `foura_proxy` أو `foura_browser`، بدلاً من التعامل مع صفحة التحدي كمحتوى.

## استجابات مصنفة النوع

تتضمن كل استجابة أداة كلاً من `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 }`) لإعادة التشغيل عبر الأدوات الأقل مستوى؛ ويتضمن الطلب الذي حدد فئة أيضاً `exitClass`. يحسب `meta.attemptsByEngine` الطلبات التي أرسلها الاستدعاء إلى Single وProxy وBrowser، بينما يحسب `meta.browserRequests` الطلبات التي استهلكت من رصيدك اليومي لـ Browser. تتضمن حالة الفشل أيضاً `attemptReport`. لا يوجد `total_time`.
- `foura_single`: `{ status, headers, data, total_time, ... }` (الترويسات عبارة عن مصفوفة، عنصر واحد لكل قفزة إعادة توجيه)
- `foura_proxy`: مطابقة لـ single بالإضافة إلى `{ proxy, total }`؛ يتضمن النجاح محدد النطاق أيضاً `exitCountry`، ويتضمن الطلب الذي حدد فئة `exitClass`، ويتضمن التدوير الذي غيّر عائلة المتصفح `profile`، وتتضمن حالة الفشل `attemptReport`
- `foura_browser`: هيكل متميز `{ status, headers: object, body, cookies, userAgent }` (ملاحظة: قد يكون `body` سلسلة نصية أو كائناً اعتماداً على content-type)

تُبلغ كل أداة أيضاً عن تكلفة الاستدعاء وكيفية تتبعه، مقروءة من ترويسات استجابة API:

- `credits`: الرصيد الذي استهلكه هذا الاستدعاء. يظهر عند حالات الفشل أيضا، لأن العمل قد تم إنجازه في كلتا الحالتين. تتم محاسبتك فقط على الاستدعاء الناجح، لذا يُظهر الفشل رصيده هنا دون أن يكلفك أي شيء.
- `request_id`: المعرّف الخاص بـ FourA للاستدعاء. اذكره في طلب الدعم.
- `exitClass`: يكون `premium` عندما يخدم الاستدعاءَ مخرجٌ متميز (premium exit). في `foura_single` و`foura_browser` يحدث ذلك عندما يعيد `proxy` تشغيل مخرج متميز وجده `foura_proxy` أو `foura_auto`.

يكون كل منها غائبا عندما لا ترجع الـ API أي بيانات، وبالتالي يستمر العميل المكتوب لإصدار سابق في العمل دون تغيير. تم توثيق نفس القيم في [Response Headers](https://foura.ai/docs/api/response-headers).

يمكن للعملاء الذين يدعمون `structuredContent` تمرير الكائن المحدد النوع مباشرة إلى LLM بدلا من مطالبته بتحليل JSON من نص نثري.

### ترويسات الاستجابة متعددة القيم

الـ headers التي تظهر عدة مرات (`Set-Cookie`، `Link`، `WWW-Authenticate`) تعود على شكل مصفوفات:

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

هذا مهم للمواقع التي تضبط ملفات تعريف الارتباط الخاصة بالجلسة + التتبع + الموافقة في استجابة واحدة (معظم مواقع التجارة الإلكترونية).

## الاستجابات الكبيرة: `offload_large` (افتراضي: inline)

بشكل افتراضي (منذ v0.2.0)، تُعاد نصوص الاستجابة الكاملة مضمنة عبر `structuredContent` بغض النظر عن الحجم. يعمل هذا في كل عميل MCP مباشرة.

إذا كان عميلك يدعم MCP `resources/read` وتريد توفير tokens في الصفحات الكبيرة، فمرر `offload_large: true` لكل استدعاء أداة. الاستجابات التي تبلغ >= 50 كيلوبايت تُكتب حينها على القرص، وتُعاد كـ `resource_link`، ويجلب عميلك النص فقط عندما يحتاج إليه فعلياً. على الخادم المستضاف، تنتهي صلاحية الحمولات المخزنة مؤقتاً بعد ساعة واحدة. على مثيلك الخاص، لا يوجد شيء يحذف الحمولات المخزنة: احذف الملفات الأقدم من ساعة من دليل الحمولات بنفسك.

تحمل النتيجة المُفرّغة `offloaded_resource_uri` و `size_bytes` بدلاً من النص. كما تحذف النتيجة المُفرّغة `defense`، و `profile` في `foura_proxy`، لذا تخطَّ `offload_large` في الاستدعاء الذي يقرأ تلك الحقول.

```json
{
  "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 | مدعوم |

معزول حسب المستأجر: يحصل كل مفتاح API على مساحة الاسم الخاصة به (`sha256(apiKey)[:16]`). المفتاح الذي قام بتخزين الحمولة هو الوحيد القادر على قراءتها مجددا. عمليات القراءة عبر المستأجرين ترجع `Payload not found` دون أي تسريب لوجود البيانات.

## Prompts مدمجة

تظهر 6 قوالب لسير العمل تحت `/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 أي tokens أثناء الخمول. تدخل الـ Prompts المستدعاة فقط إلى سياق LLM.

النص الكامل بالإضافة إلى prompts البديلة اليدوية: [وصفات MCP](https://foura.ai/docs/mcp/recipes).

## غلاف الخطأ

يحمل كل خطأ (`isError: true`) غلاف `structuredContent`. الحد الأدنى من الحقول في كل خطأ:

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

عند حدوث أخطاء من المصدر الأساسي (upstream) مع حالة HTTP، يتوفر `status` أيضا. وعند أخطاء حد المعدل (rate-limit) والسعة، يضيف غلاف المصدر الأساسي الحقول `retryAfter` و`current.{concurrency, rpm}` و`limits.{maxConcurrency, maxRpm}`. راجع [أخطاء API](https://foura.ai/docs/api/errors) للاطلاع على بنية REST الأساسية.

قيم `code` الثابتة:

| الرمز | HTTP | المعنى | هل إعادة المحاولة آمنة؟ |
|---|---|---|---|
| `ssrf_blocked` | غير متاح | الهدف عنوان خاص أو محجوز (RFC 5735، 6598، عناوين IPv6 المحجوزة)، أو أن الرابط ليس http(s)، أو تعذر حل اسم المضيف | لا، تحقق من الرابط. يمكن إعادة محاولة البحث الذي فشل لفترة وجيزة |
| `upstream_non_json` | متفاوت | أرجع المصدر الأساسي جسما غير صالح | محتمل، تحقق من الأمر |
| `output_validation_failed` | غير متاح | رفض `outputSchema` الخاص بخادم MCP استجابة المصدر الأساسي، أو تعذر على الأداة إكمال الطلب بالكامل (لم يتم تكوين مفتاح API، أو تعذر الوصول إلى API) | محتمل: تحقق من الإعداد، ثم أبلغ عن المشكلة |
| `bad_request` | 400 | تم رفض بنية المدخلات، أو أن الرابط المستهدف يشير إلى API الخاص بـ FourA بدلا من صفحة (يمكن جلب `/inspect` فقط هناك)، أو يحتوي الرابط على مسافة غير مشفرة بداخله (قم بتشفيرها كـ `%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 عام | نعم، تراجع لفترة قصيرة |
| `upstream_error` | 500+ أو 0 | استجاب الهدف بخطأ في الخادم، أو في حالة `foura_proxy`، لم يستجب `foura_browser` و`foura_auto` إطلاقا | نعم، تراجع أسي |
| `upstream_client_error` | 4xx | أخطاء 4xx أخرى | غالبا لا |
| `upstream_unknown` | أخرى | تم تشغيل الطلب ولكنه لم ينتج استجابة مقبولة: في `foura_single` لم يستجب الهدف إطلاقا (انتهاء المهلة، رفض الاتصال)، وفي أي أداة رفض `validate` الخاص بك استجابة 2xx أو 3xx. اقرأ `status` و`error` | تحقق من الأمر |
| `no_eligible_proxy` | غير متاح | لا يوجد proxy يطابق نطاق `exitCountries` الصارم | أعد المحاولة لاحقا، ولا تغير النطاق إلا بشكل صريح |
| `plan_limit_*` | 403 أو 429 | رفض أحد حدود خطتك هذا الطلب: `plan_limit_` متبوعا بـ `feature`، أو `premium`، أو `concurrency`، أو `rate`، أو `browser_daily`، أو `credits`، أو `bandwidth`. راجع [أخطاء خادم MCP](https://foura.ai/docs/mcp/errors) | انتظر `retryAfter` عند توفره، وإلا فلا تعيد المحاولة حتى تتم إعادة تعيين الحد أو تغيير الخطة |

يمكن لوكلاء LLM قراءة `code` مباشرة لمنطق إعادة المحاولة دون تحليل النصوص النثرية. شرح المصادقة: [المصادقة](https://foura.ai/docs/getting-started/authentication).

## الحدود

- نص مضمن (Inline body) افتراضيا. مع `offload_large: true`، تذهب الاستجابات بحجم >= 50 كيلوبايت إلى القرص + `resource_link` (لكل مستأجر، مع مدة صلاحية TTL لساعة واحدة).
- يتم رفض الأهداف الخاصة (RFC 5735 و RFC 6598 ونطاقات IPv6 المحجوزة) على مستوى طبقة MCP. يتم توجيه المضيفين العامين فقط.
- حد أقصى لحجم نص الطلب يبلغ 256 كيلوبايت لطلبات `/mcp` الواردة (حمولات MCP الفعلية أقل من 4 كيلوبايت).
- تطبق قيود معدل الاستخدام (Rate limits) بواسطة FourA API لكل خدمة. راجع [حدود معدل الاستخدام](https://foura.ai/docs/api/rate-limits).

## الاستضافة الذاتية

شفرة المصدر الكاملة للخادم متاحة للعامة على [GitHub](https://github.com/fouradata/mcp) تحت ترخيص `@fouradata/mcp`. استنسخ المستودع، ثم نفذ `npm install` و `npm run build`، وشغل `node dist/http.js` لتشغيل نسختك الخاصة. يعمل بدون حفظ للحالة (stateless) في حاوية واحدة خلف أي موازن تحميل.

البيئة القابلة للتكوين:

| Variable | Default | Purpose |
|---|---|---|
| `PORT` | `3076` | منفذ استماع HTTP |
| `FOURA_API_BASE` | `https://api.foura.ai/api` | عنوان URL الأساسي لـ FourA REST المصدر |
| `FOURA_MCP_PAYLOADS_DIR` | مجلد `foura-mcp-payloads` في دليل النظام المؤقت (يحدد ملف Docker Compose المرفق `/data/payloads`) | مكان تخزين الاستجابات بحجم >= 50 كيلوبايت مؤقتا على القرص (مع `offload_large: true`) |
| `FOURA_MCP_ALLOWED_HOSTS` | `mcp.foura.ai,localhost,127.0.0.1,[::1]` | القائمة المسموحة لأسماء المضيفين لترويسة `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` (غير جذرية). يحتفظ ملف Docker Compose المرفق بـ `/data/payloads` على وحدة تخزين مسماة (named volume)؛ ويجب أن يكون ربط المضيف (bind mount) في ذلك المسار قابلا للكتابة بواسطة ذلك المعرف uid.

توسع أفقيا خلف أي موازن تحميل. يقدم العملاء مفتاحهم مع كل طلب، لذلك لا توجد جلسات لاصقة (sticky sessions). مع `offload_large`، وجه `FOURA_MCP_PAYLOADS_DIR` إلى وحدة تخزين تتشاركها جميع النسخ، لأن الحمولة المخزنة تستقر على قرص النسخة التي قامت بكتابتها. يستجيب `GET /healthz` بـ `ok` و `name` و `version`، مما يتيح لموازن التحميل فحص النسخة.
