التعليمات: دمج Spy.House عبر MCP

يُركس هذا الدليل على إعداد واستخدام تكامل خدمة تحليلات الإعلانات الابتكارية Spy.House مع عملاء الذكاء الاصطناعي وبيئات التطوير عبر بروتوكول Model Context Protocol (MCP).

يتناول المستند بالتفصيل المتطلبات المسبقة للاتصال (وجود اشتراك مدفوع وتفويض OAuth بدون استخدام مفاتيح API)، الخوارزمية الأساسية من ثلاث خطوات لتشغيل الربط، بالإضافة إلى إرشادات خطوة بخطوة لتطبيقات محددة: Claude (Desktop, Web, Code), Codex, Cursor, VS Code و ChatGPT.

معلومات مهمة قبل الاتصال

• رابط الموصل (Connector URL): [https://spy.house/mcp]. يجب إدخال هذا الرابط في عميل MCP الخاص بك.

• المتطلبات: يتطلب اشتراكًا مدفوعًا نشطًا. لا يمكن ربط النسخة التجريبية (trial).

• التفويض: يتم عبر OAuth — يفتح عميلك المتصفح وتسجل الدخول باستخدام حساب Spy.House الخاص بك. لا يلزم وجود مفتاح API.

3 خطوات للاتصال

1. أضف السيرفر (Add the server): وجّه عميل MCP الخاص بك إلى رابط الموصل — هذا سطر تكوين واحد أو أمر (انظر أدناه).

2. سجّل الدخول باستخدام Spy.House (Sign in with Spy.House): سيفتح عميلك المتصفح لتفويض OAuth.

3. اسأل وكيلك (Ask your agent): اكتب طلبًا، على سبيل المثال: «Find up to 12 Black Friday FB creatives for the USA». سيتصل الوكيل بالأداة المطلوبة ويرد عليك.

الإعداد لعملاء محددين

ملاحظة لعملاء CLI (مثل Claude Code و Codex): بعد إضافة السيرفر، يجب إعادة تشغيل العميل لأن الجلسة الحالية لن تقوم بتحميله. ثم قم بتسجيل الدخول: بالنسبة لـ Claude Code باستخدام الأمر /mcp، ولـ Codex بالأمر codex mcp login spy-house (من الكتلة أدناه).

1. Claude

تستخدم نسختا سطح المكتب والويب Client ID الموضح أدناه. بينما يستخدم Claude Code أمر CLI مع Client ID خاص به.

Desktop / Web:

1. انتقل إلى Settings (الإعدادات) ← Connectors (الموصلات) ← Add custom connector (إضافة موصل مخصص).

2. أدخل endpoint URL: [https://spy.house/mcp].

3. اضغط على Connect & authorize (توصيل وتفويض).

Claude Code (CLI): نفّذ الأمر التالي:

claude mcp add --transport http --client-id spy-mcp-claude-code \
--callback-port 8787 spy-house https://spy.house/mcp

• Client ID لـ Desktop/Web: spy-mcp-claude-desktop

2. Codex

أضف سيرفرًا بعيدًا باستخدام أمر واحد، ثم قم بتسجيل الدخول:

codex mcp add spy-house --url https://spy.house/mcp \
--oauth-client-id spy-mcp-codex

codex mcp login spy-house

• Client ID: spy-mcp-codex

3. Cursor

نفّذ الأمر أدناه أو أضف السيرفر إلى الملف ~/.cursor/mcp.json أو .cursor/mcp.json:

cursor --add-mcp '{"name":"spy-house","url":"https://spy.house/mcp","auth":{"CLIENT_ID":"spy-mcp-cursor","scopes":["mcp:search"]}}'

• Client ID: spy-mcp-cursor

4. VS Code

نفّذ الأمر أدناه أو أضف السيرفر إلى ملف mcp.json للمستخدم أو بيئة العمل (workspace):

code --add-mcp '{"name":"spy-house","type":"http","url":"https://spy.house/mcp","oauth":{"clientId":"spy-mcp-vscode"}}'

• Client ID: spy-mcp-vscode

5. Claude Web

1. افتح Claude ← Customize ← Connectors ← Add custom connector.

2. حدّد: Name — Spy.House ، URL — [https://spy.house/mcp].

3. في إعدادات Advanced OAuth settings أدخل Client ID: spy-mcp-claude-desktop واترك Client Secret فارغًا.

4. اضغط على Add / Connect.

6. ChatGPT

1. في ChatGPT web، فعّل Settings ← Security and login ← Developer mode.

2. أضف تطبيق MCP بعيد (remote MCP app) في Plugins:

   • URL: [https://spy.house/mcp]

   • Client ID: spy-mcp-chatgpt

   • Type: Streamable HTTP

   • Client Secret: اتركه فارغًا (no Client Secret)

3. اضغط على Connect / Authenticate، وسجّل الدخول إلى Spy.House وأكّد الوصول. لا يلزم وجود مفتاح API أو Client Secret.

4. نفّذ هذا الطلب:

   Find up to 12 Black Friday FB creatives for the US.

التحقق حسب الطلب (Verification by request)

بعد الاتصال، نفّذ هذه الطلبات في عميلك. النتائج المتوقعة هي قائمة تحقق وليست بحثًا حيًا.

• search_creatives

  • طلب التحقق: Find up to 12 Black Friday Facebook ad creatives for the US.

  • النتيجة المتوقعة: ما يصل إلى 12 إعلانًا ابتكاريًا، بما في ذلك البيانات والحصة المتبقية للبحث. شبكة واحدة لكل استدعاء: push, inpage, facebook, tiktok أو native. كل عملية بحث غير فارغة تستهلك وحدة واحدة من الحصة.

• get_filter_options

  • طلب التحقق: List the available Facebook search filters.

  • النتيجة المتوقعة: كتالوج فلترات Facebook الخالي من المحتوى المخصص للبالغين (non-adult) والقيم الدقيقة لـ search_creatives. الفلترات الخاصة بالبالغين مخفية.

• get_creative_media

  • طلب التحقق: Show me the images of the creatives you just found.

  • النتيجة المتوقعة: وسائط لما يصل إلى ثلاثة من creative_ref من هذا البحث. لا يتم خصم شيء من حصة البحث. لا يتم إرجاع الفيديو الكامل، وقد لا يعرض الدردشة المعاينة المدمجة.

• render_creatives_gallery

  • طلب التحقق: Show these creatives as a gallery.

  • النتيجة المتوقعة: معرض مدمج من 1 إلى 12 creative_ref من نفس البحث في العملاء التي تدعم MCP Apps. تتجاهل بقية العملاء هذه الأداة وتستخدم النص أو get_creative_media.

الأسئلة الشائعة (FAQ)

• كيف يمكن إزالة ربط Spy.House من عميل الذكاء الاصطناعي؟

  احذف أو عطّل سيرفر Spy.House في عميل الذكاء الاصطناعي الخاص بك. يتوقف الوصول أيضًا بمجرد انتهاء اشتراكك المدفوع. الحسابات التجريبية (Trial) لا يمكنها الاتصال.

• كيفية التواصل مع الدعم الفني؟

  • البريد الإلكتروني: [email protected]

  • تلغرام: https://telegram.me/Spy_House

  • ساعات العمل: من الإثنين إلى الجمعة، 10:00–18:00 (UTC+3)

  • في حالة حدوث خطأ، يرجى إرسال: اسم عميل الذكاء الاصطناعي، الوقت، نص الخطأ، ولقطة شاشة (Screenshot).

تحول عملية تكامل Spy.House عبر بروتوكول MCP مساعدي الذكاء الاصطناعي وبيئات التطوير الشهيرة إلى أدوات فعالة للاستخبارات التنافسية. بفضل تفويض OAuth السلس والموصل الموحد، يحصل المستخدمون على القدرة على البحث عن الإعلانات الابتكارية، وتحليل الفلترات المتاحة، واستعراض ملفات الوسائط مباشرة من واجهة عميلهم المعتاد، مما يختصر عملية البحث إلى طلبات بسيطة بلغة طبيعية.