ربط وكيل ذكاء اصطناعي باستخدام MCP

صِل Claude أو ChatGPT أو Cursor أو Gemini بخادم MCP المستضاف ليقرأ مواقعك وإدراجاتك وتقييماتك ويعمل عليها بالأدوات نفسها التي تستدعيها أنت.

تستضيف Listings API خادمًا لبروتوكول سياق النموذج (MCP) على https://listingsapi.com/mcp. لا حاجة إلى تثبيت أي شيء أو تشغيله. يتصل مساعد ذكاء اصطناعي يدعم MCP بعنوان URL هذا، ويكتشف أداة واحدة لكل نقطة نهاية REST، إلى جانب بضع أدوات للتوثيق، ويستدعيها على حسابك. يشرح هذا الدليل خطوات ربط كل عميل رئيسي، ثم التحقق من الاتصال.

1. تعرّف على ما يتاح للوكيل

يتيح الخادم ما يزيد قليلًا على 60 أداة، نحو ثلثيها للقراءة فقط. تتبع الأسماء موارد REST، لذا تؤدي locations_search وlistings_premium وreviews_respond وposts_create_social وظائف نقاط النهاية المقابلة لها، بالمعاملات نفسها وبنية الاستجابة نفسها. تتيح أدوات التوثيق الثلاث، search_docs وget_doc وget_endpoint، للمساعد البحث عن صفحة أو مواصفات نقطة نهاية بدلًا من تخمين بنية حمولة البيانات.

لا تُتاح العمليات المدمِّرة، مثل حذف منشور أو أرشفة موقع، كأدوات. استخدم واجهة REST API أو إحدى حزم SDK لتنفيذها، حتى لا يتمكن المساعد من إزالة البيانات من تلقاء نفسه.

2. اختر طريقة تسجيل دخول العميل

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

يستخدم OAuth تدفق رمز التفويض مع PKCE والتسجيل الديناميكي للعملاء، لذلك لا يحتاج العميل إلى بيانات اعتماد صادرة مسبقًا. تتوفر البيانات الوصفية على https://listingsapi.com/.well-known/oauth-authorization-server. النطاقان هما read وwrite؛ ويحصل العميل الذي لا يطلب أي نطاق على read. تنشئ كل موافقة مفتاحًا مخصصًا لذلك الاتصال، ويمكنك إلغاءه من /dashboard/keys مثل أي مفتاح آخر.

3. ربط Claude

Claude.ai وClaude Desktop. الخادم مدرج في دليل الموصلات، لذا فإن أسرع طريقة هي فتح https://claude.ai/directory/listings-api والنقر على Connect (اتصال). ينفّذ Claude تدفق OAuth، وتوافق أنت على النطاقات، ثم تتوفر الأدوات في أي محادثة تفعّل فيها الموصل باستخدام الزر +، ثم Connectors (الموصلات).

إذا كنت تفضّل إضافته عبر عنوان URL، فانتقل إلى Customize (تخصيص)، ثم Connectors (الموصلات)، وانقر على + ثم Add custom connector (إضافة موصل مخصص)، والصق https://listingsapi.com/mcp وانقر على Add (إضافة). اترك Advanced settings (الإعدادات المتقدمة) فارغة؛ إذ يسجّل الخادم Claude كعميل تلقائيًا. في خطتي Team وEnterprise، يضيف أحد المالكين الموصل ضمن Organization settings (إعدادات المؤسسة)، ثم Connectors (الموصلات)، وبعد ذلك ينقر الأعضاء على Connect (اتصال) الخاص به. يتصل Claude من خوادم Anthropic، وليس من جهازك، ولهذا تبرز أهمية عنوان URL المستضاف.

Claude Code. يضيف أمر واحد الخادم باستخدام مفتاحك:

claude mcp add --transport http listingsapi https://listingsapi.com/mcp \--header "Authorization: API $LISTINGSAPI_KEY"

احذف العلامة --header وشغّل /mcp داخل Claude Code لتسجيل الدخول عبر المتصفح بدلًا من ذلك. استخدم --scope project لحفظ إعدادات الخادم في .mcp.json يشترك فيه الفريق بأكمله ضمن نظام التحكم في الإصدارات؛ ولا تحفظ مفتاحًا معها.

4. ربط ChatGPT

يتصل ChatGPT بخوادم MCP البعيدة عبر موصّل مخصص بمجرد تفعيل Developer mode (وضع المطوّر). تتوفر هذه الميزة في خطط Plus وPro وBusiness وEnterprise وEdu، ولا تتوفر في الخطة المجانية.

1. افتح Settings (الإعدادات) من قائمة ملفك الشخصي وفعّل Developer mode (وضع المطوّر). بحسب إصدار التطبيق، ستجده ضمن Apps & Connectors (التطبيقات والموصّلات) أو Security and login (الأمان وتسجيل الدخول).
2. في صفحة الموصّلات (المسمّاة Plugins (الإضافات) في الإصدارات الحالية)، انقر على + أو Create (إنشاء).
3. أدخل اسمًا، والصق https://listingsapi.com/mcp بوصفه عنوان URL للخادم، واختر OAuth للمصادقة. احفظ.
4. يفتح ChatGPT صفحة تسجيل الدخول. وافق على read أو read write.
5. في محادثة جديدة، افتح قائمة الأدوات، واختر الموصّل، وتأكد من ظهوره مع أدواته. تطلب أدوات الكتابة تأكيدًا منك قبل تنفيذها.

Codex CLI. يقرأ وكيل OpenAI الذي يعمل في الطرفية خوادم MCP من ~/.codex/config.toml. يبدأ Codex عملية OAuth تلقائيًا لخوادم HTTP ويلتزم بنطاقات الصلاحيات المعلنة، لذا فإن سطر الترويسة اختياري:

[mcp_servers.listingsapi]url = "https://listingsapi.com/mcp"http_headers = { "Authorization" = "API <your key>" }

5. ربط Cursor

تحتوي صفحة لوحة التحكم الموجودة في /dashboard/mcp على زر Add to Cursor (إضافة إلى Cursor). يفتح الزر رابط تثبيت في Cursor مع تعبئة عنوان URL للخادم ومفتاحك مسبقًا، لذا تكفي نقرة واحدة لإكمال الإعداد.

لإعداده يدويًا، أضف الخادم إلى ~/.cursor/mcp.json لجميع المشاريع، أو إلى .cursor/mcp.json داخل مستودع واحد:

{"mcpServers": {  "listingsapi": {    "url": "https://listingsapi.com/mcp",    "headers": {      "Authorization": "API <your key>"    }  }}}

أزل كتلة headers لتسجيل الدخول باستخدام OAuth بدلًا من ذلك: يعرض Cursor زر Connect (اتصال) في بند الخادم ضمن Settings (الإعدادات)، ثم MCP، ويفتح مسار تسجيل الدخول في المتصفح. لا تُضمّن مطلقًا مفتاحًا في ملف .cursor/mcp.json على مستوى المشروع عند تسجيل التغييرات في المستودع؛ استخدم الملف العام أو OAuth للمستودعات المشتركة.

6. ربط Gemini

Gemini CLI. يقبل وكيل Google الذي يعمل في الطرفية إعدادات الخوادم البعيدة في ~/.gemini/settings.json (أو .gemini/settings.json في أحد المشاريع). استخدم httpUrl، وليس url، ليختار وسيلة النقل Streamable HTTP:

{"mcpServers": {  "listingsapi": {    "httpUrl": "https://listingsapi.com/mcp",    "headers": {      "Authorization": "API <your key>"    },    "timeout": 30000  }}}

لاستخدام OAuth، استبدل كتلة headers بـ "oauth": { "enabled": true }، وابدأ CLI وشغّل /mcp auth listingsapi. شغّل /mcp في أي وقت لعرض الخادم وحالة اتصاله والأدوات التي اكتشفها.

تطبيق Gemini. لا يحتوي تطبيق Gemini الموجّه للمستهلكين على إعداد لموصّل مخصص. تتوفر خوادم MCP المخصصة لمسؤولي الفرق في إصدار Gemini Enterprise Business: سجّل الدخول على business.gemini.google، وافتح Settings & help (الإعدادات والمساعدة)، ثم Manage team (إدارة الفريق) وConnected apps (التطبيقات المتصلة)، وانقر على Add MCP Server (إضافة خادم MCP). الصق https://listingsapi.com/mcp بوصفه عنوان URL. يطلب النموذج تفاصيل OAuth: عنوان URL للتفويض هو https://listingsapi.com/oauth/authorize، وعنوان URL للرمز هو https://listingsapi.com/oauth/token، ونطاقات الصلاحيات هي read write. ويطلب أيضًا معرّف عميل وسرّ عميل. يُصدر هذا الخادم عملاء PKCE عامّين بلا سرّ، لذا سجّل عميلًا باستخدام عنوان URL لإعادة التوجيه الذي يعرضه النموذج، واترك حقل السرّ فارغًا إذا سمح النموذج بذلك:

curl -s https://listingsapi.com/oauth/register \-H "Content-Type: application/json" \-d '{  "client_name": "Gemini Business",  "redirect_uris": ["<redirect URL shown in the Gemini form>"],  "grant_types": ["authorization_code", "refresh_token"],  "token_endpoint_auth_method": "none"}'

تتضمن الاستجابة client_id. إذا كان نموذج Gemini لديك يشترط وجود سرّ، فاستخدم طريقة Gemini CLI الموضّحة أعلاه أو طوّر باستخدام Gemini API بدلًا من ذلك.

التطوير باستخدام Gemini API. تقبل حزمة SDK الخاصة بـ Gemini API جلسة عميل MCP بوصفها أداة، لذا يمكن لبرنامج نصي إتاحة الأدوات نفسها لنموذج Gemini:

import asyncio, osfrom google import genaifrom mcp import ClientSessionfrom mcp.client.streamable_http import streamablehttp_client HEADERS = {"Authorization": "API " + os.environ["LISTINGSAPI_KEY"]} async def main():  gemini = genai.Client()  async with streamablehttp_client("https://listingsapi.com/mcp", headers=HEADERS) as (r, w, _):      async with ClientSession(r, w) as session:          await session.initialize()          reply = await gemini.aio.models.generate_content(              model="gemini-2.5-pro",              contents="Which of my locations have a Google listing that is not live yet?",              config=genai.types.GenerateContentConfig(tools=[session]),          )          print(reply.text) asyncio.run(main())

7. التحقق من الاتصال

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

curl -s https://listingsapi.com/mcp \-H "Content-Type: application/json" \-H "Accept: application/json, text/event-stream" \-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | head -c 400

بعد ذلك، اطلب من المساعد شيئًا يتطلب الوصول إلى حسابك:

استخدم أدوات listingsapi لإخباري بالحساب الذي أتصل من خلاله، وعدد المواقع التي يحتوي عليها، واستخدامي لواجهة API هذا الشهر.

عندما يكون الاتصال صحيحًا، تأتي الإجابة من whoami وlocations_all وget_usage وتتضمن معرّف حسابك الفعلي والأعداد الفعلية. يؤدي المفتاح الخاطئ أو المنتهي الصلاحية إلى إرجاع خطأ Unauthenticated عند أول استدعاء لأداة، وليس أثناء الاكتشاف.

تعليمات للوكيل مناسبة للبدء بعد نجاح الاتصال:

• "اعرض قائمة بمواقعي التي تتضمن أخطاء في إدراجات الأنشطة التجارية، ولخّص كل خطأ."
• "اعرض التقييمات الواردة خلال آخر 7 أيام التي لا يوجد رد عليها، وصُغ مسودة رد لكل منها. لا ترسل الردود بعد."
• "قارن تحليلات الملف التجاري على Google للموقع 1800289 على مدى الشهرين الماضيين."
• "اقرأ مواصفات نقطة النهاية create-location، ثم أضف هذا الموقع: ..."

أضف مهارات الوكيل الخاصة بـ listingsAPI

المهارات هي تعليمات يحمّلها الوكيل عندما تتطابق معها مهمة، ليتّبع سير عمل مجرّبًا بدلًا من ابتكار سير عمل بنفسه. وتعمل إلى جانب خادم MCP: ينفّذ الخادم الاستدعاءات، وتحدّد المهارة الاستدعاءات التي ينبغي تنفيذها وترتيبها. نُشرت خمس مهارات لـ listingsAPI على skills.sh من مستودع listingsapi-mcp العام:

ثبّت المهارات الخمس كلها في مشروعك باستخدام Skills CLI:

npx skills add listings-api/listingsapi-mcp

أو ثبّت مهارة واحدة باسمها، واختر الوكيل باستخدام -a:

npx skills add listings-api/listingsapi-mcp --skill listingsapi-integration -a claude-code

استخدم -a cursor أو -a codex لهذين الوكيلين، وأضف -g للتثبيت لجميع المشاريع بدلًا من المشروع الحالي.

اعثر على listingsAPI في أدلة أدوات الذكاء الاصطناعي

الخادم نفسه مُدرج في هذه الأدلة، إلى جانب مهارة الوكيل الخاصة بـ listingsAPI. ثبّته من الدليل الذي يستخدمه عميلك بالفعل. يشير كل مدخل لخادم MCP إلى https://listingsapi.com/mcp.

استكشاف الأخطاء وإصلاحها

الخطوات التالية

• اختر طريقة التكامل: متى يكون MCP مناسبًا ومتى يكون REST أو SDK الخيار الأفضل.
• أجرِ أول استدعاء لواجهة API: احصل على مفتاح وتعرّف على بنية الاستجابة التي تُرجعها الأدوات.
• الاستجابة للأحداث باستخدام webhooks: اجعل المنصة تُخطِر وكيلك بدلًا من الاستقصاء الدوري.
• راجع المصادقة ورموز الأخطاء لمعرفة الرموز التي سيُبلغك بها المساعد.