ربط وكلاء الذكاء الاصطناعي بـ listingsAPI MCP

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

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

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

يتيح الخادم ما يزيد قليلًا على ستين أداة، نحو ثلثيها للقراءة فقط. تتبع الأسماء موارد 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: ينفّذ الخادم الاستدعاءات، وتحدّد المهارة الاستدعاءات المطلوبة وترتيبها. نُشرت 5 مهارات لـ 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: اجعل المنصة تُشعر وكيلك بدلًا من الاستقصاء الدوري.
• راجع المصادقة ورموز الأخطاء لمعرفة الرموز التي سيبلغك بها المساعد.