# وصفات MCP

> URL: https://foura.ai/ar/docs/mcp/recipes
> Updated: 2026-10-28
> Index: https://foura.ai/llms.txt

تسع مطالبات جاهزة للنسخ يمكنك تشغيلها داخل أي عميل متوافق مع MCP مثل (Claude Desktop وClaude Code وCursor وWindsurf وVS Code) بعد تثبيت [FourA MCP server](https://foura.ai/docs/mcp/server).

تستخدم كل وصفة `foura_auto` (الخيار الافتراضي الذكي) أو واحدة أو أكثر من الأدوات الأقل مستوى `foura_single` و`foura_proxy` و`foura_browser` لمهمة scraping شائعة. توجد طريقتان لاستخدامها:

1. **استدعاء المطالبة المدمجة**، حيث يعرض كل عميل MCP المطالبات التي يوفرها الخادم كأمر بشرطة مائلة أو لوحة `/prompts`. اختر المطالبة، ثم املأ الوسائط، ثم نفذ. يعيد خادم MCP سير العمل المجهز بالقالب، وينفذه LLM باستخدام الأدوات المناسبة.
2. **نسخ النص** أدناه إلى محادثتك الخاصة. يعطي النتيجة نفسها ولكنه أقل قابلية للاكتشاف.

يقدم خادم MCP هذه المطالبات كمطالبات أصلية: `smart_fetch` و`scrape_product_page` و`extract_article` و`monitor_pricing` و`check_endpoint_health` و`bulk_fetch_urls`.

> **ملاحظة بشأن الصفحات الكبيرة (v0.2.0+):** بشكل افتراضي، يتم إرجاع نصوص الاستجابة مضمنة في `structuredContent` بغض النظر عن الحجم، ويعمل هذا في كل عميل MCP بما في ذلك Claude Desktop. إذا كنت تستخدم عميلا يدعم MCP `resources/read` وتريد توفير tokens في الصفحات الكبيرة، فمرر `offload_large: true` في استدعاء الأداة. تأتي الاستجابات التي يبلغ حجمها 50 كيلوبايت أو أكثر كـ `resource_link` يجلبه عميلك عند الطلب. تفترض المطالبات المدمجة أدناه الإعداد الافتراضي (المضمن).


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

## الجلب الذكي (تلقائي): ابدأ من هنا

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

مدمج: `smart_fetch(url, must_contain?, extract?)`

مطالبة يدوية:

```
Fetch <URL> using foura_auto.

Pass validate.data.accept:["<a string the real page must contain>"] so only the real page counts as success. Auto makes bounded attempts and returns an error if none satisfies the validation.

For a plain follow-up, call foura_single with session.proxy as proxy, session.cookies serialized as a Cookie header, and session.userAgent as a User-Agent header. For JavaScript, pass the session values to the matching foura_browser fields.

Return the content, or extract the requested fields as JSON.
```

الحالات المناسبة لاستخدام هذه الوصفة: المحاولة الأولى عندما ينبغي لـ FourA اختيار الطريقة، وخاصة عندما يمكن للتحقق من المحتوى التمييز بين صفحة حقيقية وصفحة رفض.

## 1. استخراج بيانات صفحة منتج

لصفحات تفاصيل المنتجات في التجارة الإلكترونية، بما في ذلك مواقع تطبيقات الصفحة الواحدة (single-page-app) والصفحات التي تتضمن فحص الموقع.

مدمج: `scrape_product_page(url)`

الموجه اليدوي:

```
Fetch the product page at <URL> using foura_browser - most product pages are single-page apps and need JavaScript to render.

From the response body extract:
- product title
- price (with currency)
- primary product image URL (absolute, not relative)
- availability / stock status
- product SKU or ID if visible

Return as JSON: {"title": "...", "price": 0, "currency": "USD", "image_url": "...", "in_stock": true, "sku": "..."}
```

الحالات التي تناسبها هذه الوصفة: وكيل مقارنة أسعار، أداة تنبيه بتوفر المخزون، جدول بيانات للتحليل التنافسي.

## 2. استخراج مقال

للمقالات الإخبارية، تدوينات المدونات، الوثائق التقنية، أو أي محتوى ترغب في قراءة نصه بوضوح دون تشتيت من عناصر التنقل، الإعلانات، والتذييل.

مدمج: `extract_article(url)`

المطالبة اليدوية:

```
Fetch <URL> using foura_single with unblocker:true. Use plain HTTP first when the article is present in the server-rendered response.

If foura_single returns a 403, a verification page, or empty content, retry the same URL with foura_proxy (maxTries:3) - it routes through a rotating proxy pool.

From the response, extract:
- headline (the main H1, not the page title bar)
- author byline (may be inside .author, [rel=author], itemprop)
- publication date (look for <time>, .published, or JSON-LD)
- main article body (strip navigation, ads, related-content, footer, comments)
- canonical URL (rel=canonical or og:url)

Return as JSON: {"title": "...", "author": "...", "date_published": "ISO8601", "body": "...", "canonical_url": "..."}
```

حالات الاستخدام المناسبة لهذا النمط: تلخيص الأبحاث، أو إنشاء خلاصة RSS لموقع واحد، أو إعداد موجز إخباري يومي.

## 3. تتبع الأسعار

لصفحات الأسعار وعروض المنتجات، مع خيار المقارنة بسعر مستهدف.

مدمج: `monitor_pricing(url, target_price?)`

الموجه اليدوي:

```
Use foura_proxy with maxTries:5 to fetch <URL>. Pricing pages often have aggressive bot detection, so go through the proxy pool from the start.

Extract the current price (look for visible $/€/£ amounts, JSON-LD Offer schema, [itemprop=price]).

If a target price is provided, compare: report whether current is below/at/above target and the absolute difference.

Return as JSON: {"url": "...", "current_price": 0.00, "currency": "USD", "target_price": 0, "difference": 0, "status": "below|at|above"}
```

حالات الاستخدام المناسبة لهذا النمط: وكيل لتنبيهات التوفير، أو متتبع لأسعار تذاكر السفر، أو متتبع لأسعار المنافسين في قطاع B2B.

## 4. التحقق من سلامة endpoint

لفحوصات وقت التشغيل uptime والتحقق من صحة API endpoint.

مدمج: `check_endpoint_health(url, expected_text?)`

الموجه اليدوي:

```
Use foura_single with GET on <URL>, timeout_ms:5000, and validate.status.accept:[200]. If an expected substring is provided, also set validate.data.accept:["<EXPECTED>"] so the request only counts as success when the body contains it.

Report:
- reachable (true if any response came back, false on connection error/timeout)
- status_code (HTTP code from target)
- total_time_ms (the total_time field is in seconds: multiply by 1000)
- validation_passed (true if status + body validation conditions were met)

Return as JSON: {"url": "...", "reachable": true, "status_code": 200, "total_time_ms": 0, "validation_passed": true}
```

حالات الاستخدام المناسبة: مراقبة وقت تشغيل خارجي، أو اختبار أولي للنشر (smoke test)، أو مراقبة API لجهة خارجية.

## 5. جلب قائمة من عناوين URL بالتوازي

للمهام الدفعية (batch jobs) عند الحاجة إلى بيانات وصفية لعدة عناوين URL دون تضمين محتوياتها.

مدمج: `bulk_fetch_urls(urls)`

المطالبة اليدوية:

```
Parse the following comma-separated URLs and fetch each one concurrently using foura_single (unblocker:true).

URLs: <COMMA_SEPARATED>

For any URL that returns 403, a verification page, or empty body - retry that single URL with foura_proxy (maxTries:3).

Return a JSON array, one entry per URL in input order:
[{"url": "...", "status": 200, "success": true, "body_size_bytes": 0, "via": "single|proxy", "error": null}, ...]

Do NOT inline full response bodies in the output - only metadata. If you need body content, call foura_single individually after this report.
```

متى تكون هذه هي الوصفة المناسبة: فحص شامل لإمكانية الوصول إلى خريطة الموقع (sitemap)، أو تدقيق لروابط معطلة (link-rot)، أو فحص لتحديد "أي من عناوين URL الخمسين لهذه المنتجات لا يزال موجوداً".

## 6. اختيار وإعادة استخدام نقطة خروج محددة ببلد معين

استخدم هذا الخيار عندما يتعين على الهدف رؤية الـ request قادماً من إحدى دول محددة، بما في ذلك صفحات JavaScript التي يجب أن يتم فيها اختيار الـ proxy قبل تصيير المتصفح (browser rendering).

المطالبة اليدوية:

```
First call foura_proxy for the actual target:
{
  "maxTries": 5,
  "exitCountries": ["FR", "GB"],
  "request": { "method": "GET", "url": "<TARGET_URL>" }
}

Treat exitCountries as a strict allowlist. On success, verify that exitCountry is FR or GB and capture the returned proxy ID.

If the page then needs JavaScript, call foura_browser with the returned proxy ID in foura_browser.proxy. Do not start a new proxy selection, because that may choose a different exit.

If foura_proxy returns no_eligible_proxy, preserve the requested country scope and retry later. Change or widen the list only after the user explicitly changes the requirement. Never retry silently without exitCountries.
```

متى يكون هذا هو الحل المناسب: المحتوى الإقليمي، أو الأسواق المرخصة، أو التسعير المخصص جغرافيا، أو أي سير عمل يتطلب دولة مستهدفة وظاهرة تم التحقق منها ثم إعادة استخدام نقطة الخروج المحددة. تحديد نطاق الدولة مشمول بدءا من خطة Startup فما فوق؛ في الخطط الأخرى، يرجع `foura_proxy` الخطأ `plan_limit_feature`، والذي لن تزيله أي إعادة محاولة.

## 7. صفحة محمية: استخدم proxy أولا، ثم المتصفح عند الحاجة إلى JavaScript

استخدم محاولة proxy محددة النطاق مع التحقق من صحة المحتوى عندما يرجع الطلب المباشر صفحة رفض. إذا نجحت الاستجابة التي تم التحقق من صحتها ولكن المحتوى المطلوب لا يزال بحاجة إلى JavaScript، فأعد استخدام معرّف proxy نفسه بالضبط في المتصفح. وجود مزود حماية مرئي لا يضمن نجاح أي طريقة.

الموجه اليدوي:

```
Step 1 - call foura_proxy for <TARGET_URL>. Put a string unique to the real page in request.validate.data.accept. If the user supplied an allowed country list, pass it as exitCountries; do not guess country codes.

Step 2 - if the response passes validation and JavaScript is still required, call foura_browser with the returned proxy ID in the proxy field.

Do not call foura_proxy again after a successful selection, because the new call may choose a different exit. If the bounded attempt fails, report the failure honestly instead of claiming support for the target's protection vendor.
```

متى تكون هذه الوصفة هي الخيار الصحيح: هدف محمي حيث يمكن لـ HTTP تحديد مخرج فعال، لكن المحتوى النهائي يتطلب تصيير JavaScript.

## 8. محظور في صفحة ثابتة: قم بتغيير المتصفح الذي تظهره

استخدم هذا عندما يُرجع هدف ثابت صفحة حظر أو صفحة تحدٍ، ولا يكون JavaScript هو المشكلة. يقدم الـ request أحدث إصدار من Google Chrome افتراضيا؛ وتقبل بعض الأهداف متصفحا أو منصة مختلفة.

المطالبة اليدوية:

```
Step 1 - call foura_single for <TARGET_URL> with request validation: put a string unique to the real page in validate.data.accept.

Step 2 - if the response is a refusal page, or defense comes back with solved false, call foura_single again with a different presented browser, for example {"browser": "Firefox"} or {"browser": "Chrome", "os": "Android"}. Keep the same validation.

If the tool answers that the combination does not exist, pick one from the list it returns. Do not retry the same impossible combination, and do not assume another browser was used instead: the request was refused, not substituted.

Step 3 - if changing the presented browser does not help, escalate to foura_proxy for a different exit, and to foura_browser only when the content genuinely needs JavaScript.
```

متى يكون هذا الحل مناسبا: هدف يُعرض من جانب الخادم (server-rendered) ويقوم بالتصفية بناء على العميل الذي يراه بدلا من عنوان الخروج. تغيير المتصفح المعروض لا يكلف شيئا إضافيا ويستحق التجربة قبل تدوير الـ proxy.

## نصائح تنطبق على جميع الأدوات

- **لست متأكدا من الأداة المناسبة؟ استخدم foura_auto.** تختار هذه الأداة الطريقة وتتولى عملية التصعيد نيابة عنك. لا تلجأ إلى أداة محددة إلا عندما تريد تحكما صريحا.
- **ابدأ بـ `foura_single` عندما يكون HTTP العادي كافيا.** صعد إلى `foura_proxy` عندما يتم حظر الـ request المباشر، وإلى `foura_browser` عندما يتطلب المحتوى المطلوب وجود JavaScript.
- **ترويسات الـ request الشبيهة بالمتصفح مفعلة افتراضيا (`unblocker`).** حافظ على تفعيل التحقق من المحتوى حتى لا تُحسب صفحة الرفض نجاحا، وقم بتغيير المتصفح المعروض باستخدام `browser` أو `os` أو `version` عندما يرفض الهدف الإعداد الافتراضي.
- **قواعد التحقق توفر محاولات إعادة الإرسال.** اضبط `validate.data.fail:["captcha", "blocked"]` حتى يُحسب الـ response المحظور بوضوح كفشل ويؤدي إلى تشغيل إعادة المحاولة أو تصعيد الـ proxy، بدلا من تحليله كنتيجة ناجحة.
- **نطاق الدولة صارم.** نتيجة `no_eligible_proxy` لا تعني الإذن بإعادة المحاولة بدون `exitCountries`؛ احتفظ بالشرط المحدد أو استشر المستخدم قبل تغييره.
- **أجسام الـ response الكبيرة تكون مضمنة (inline) افتراضيا (v0.2.0+).** مرر `offload_large: true` للتبديل إلى `resource_link` + `resources/read` على العملاء الذين يدعمون هذه الإمكانيات.

## هل تريد حلا غير موجود هنا؟

أرسل بريدا إلكترونيا إلى `support@foura.ai` موضحا حالة الاستخدام. يوفر خادم MCP قوالب توجيه (prompts) جديدة بالتزامن مع إصدارات REST API.
