الإعداد

المتطلبات

• مفتاح API لجوكر برايس من صفحة البيانات وواجهة API (Data & API).
• للخادم المستضاف: تطبيق MCP يتصل بالخوادم البعيدة (Streamable HTTP) ويستطيع إرسال ترويسة مع الطلب، دون تثبيت أي شيء.
• للخادم المحلي بديلًا: Node.js 20 أو أحدث، وشيفرة الخادم من مجلد mcp/ في مستودع جوكر برايس مع تشغيل npm install داخله مرة واحدة.

1. أنشئ مفتاح API

سجّل الدخول وافتح البيانات وواجهة API (Data & API) وأنشئ مفتاحًا باسم المساعد، مثل claude. انسخه، فهو يظهر مرة واحدة فقط.

ابدأ التجربة المجانية

2. اتصل بالخادم المستضاف

وجّه تطبيقك إلى نقطة الوصول أدناه وأرسل المفتاح في ترويسة Authorization. يعمل الخادم ببروتوكول النقل Streamable HTTP ويجيب عن كل طلب بصيغة JSON، فلا يعمل شيء على جهازك.

URL: https://jokerprice.com/mcp
Authorization: Bearer ss_your_key_here

في Claude Code، أضفه بأمر واحد:

claude mcp add --transport http jokerprice https://jokerprice.com/mcp --header "Authorization: Bearer ss_your_key_here"

لربط Claude Desktop وCodex وCursor، راجع الخطوة 4. يُحتسب كل استدعاء لأداة طلبًا واحدًا من حدود المفتاح، بينما لا يُحتسب الاتصال ولا عرض قائمة الأدوات.

3. اختبره

يستطيع أي عميل HTTP استدعاء نقطة الوصول باستخدام JSON-RPC 2.0. اعرض الأدوات، ثم استدعِ إحداها:

curl https://jokerprice.com/mcp \
  -H "Authorization: Bearer $JOKERPRICE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

curl https://jokerprice.com/mcp \
  -H "Authorization: Bearer $JOKERPRICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_market","arguments":{"slug":"riyadh"}}}'

تصل نتيجة الأداة نصًّا بصيغة JSON في result.content، وعند الإخفاق تُضبط result.isError مع شرح لما يجب إصلاحه. وتعني الاستجابة 401 أن المفتاح مفقود أو غير صحيح أو ملغى.

4. اربط تطبيقًا

• Claude Desktop وClaude Code
• Codex
• Cursor والتطبيقات الأخرى

Cursor والتطبيقات الأخرى

في Cursor، أضف الخادم المستضاف إلى ~/.cursor/mcp.json (لكل المشاريع) أو .cursor/mcp.json (لمشروع واحد)، ثم فعّله من Cursor Settings → MCP. وتقبل التطبيقات الأخرى التي تتصل بالخوادم البعيدة العنوان والترويسة نفسيهما.

{
  "mcpServers": {
    "jokerprice": {
      "url": "https://jokerprice.com/mcp",
      "headers": {
        "Authorization": "Bearer ss_your_key_here"
      }
    }
  }
}

ولتشغيل الخادم المحلي بدلًا من ذلك، تقبل معظم التطبيقات هذه الصيغة مع المسار المطلق إلى index.mjs:

{
  "mcpServers": {
    "jokerprice": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp/index.mjs"
      ],
      "env": {
        "JOKERPRICE_API_KEY": "ss_your_key_here"
      }
    }
  }
}

أو شغّله محليًا

تعمل الأدوات نفسها أيضًا على جهازك عبر stdio من مجلد mcp/ في مستودع جوكر برايس، إذ يشغّلها التطبيق أمرًا ويمرّر المفتاح متغيرَ بيئة. استخدمه مع التطبيقات التي لا تشغّل إلا خوادم محلية، أو للعمل مع خادم تطوير محلي.

ثبّت الخادم المحلي

cd mcp
npm install
pwd   # note this folder: clients need the absolute path to index.mjs

إعدادات الخادم المحلي

تمرّر التطبيقات هذه القيم متغيراتِ بيئة عند تشغيل الخادم. اضبط JOKERPRICE_BASE_URL=http://localhost:4173 لاستخدام خادم تطوير محلي.

اختبر الخادم المحلي

يشغّل MCP Inspector الخادم ويتيح لك استدعاء كل أداة يدويًا قبل ربط أي مساعد.

JOKERPRICE_API_KEY=ss_your_key_here npx @modelcontextprotocol/inspector node /absolute/path/to/mcp/index.mjs

استدعِ list_markets. إذا ظهرت قائمة بالوجهات فالمفتاح والاتصال يعملان.

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

• 401 عند الاتصال (الخادم المستضاف): لم يرسل التطبيق Authorization: Bearer ss_…، أو أن المفتاح غير صحيح أو ملغى. تحقق من الترويسة في إعدادات التطبيق، أو أنشئ مفتاحًا جديدًا.
• 403 (الخادم المستضاف): جاء الطلب من صفحة ويب على موقع آخر، ولا تستطيع صفحات المتصفح خارج jokerprice.com استدعاء نقطة الوصول؛ اتصل من تطبيق MCP بدلًا من ذلك.
• 405 مع GET (الخادم المستضاف): أمر متوقع، فالخادم يجيب عن طلبات POST بصيغة JSON ولا يفتح بثًّا للأحداث، وتواصل التطبيقات عملها دونه.
• "JOKERPRICE_API_KEY is not set" (الخادم المحلي): لم يمرّر التطبيق متغير البيئة. تحقق من كتلة env.
• "does not look like a JokerPrice key" (الخادم المحلي): يجب أن يتكون المفتاح من ss_ يليها 40 حرفًا ست عشريًا.
• "JokerPrice rejected the API key" (الخادم المحلي): المفتاح غير صحيح أو أُلغي؛ أنشئ مفتاحًا جديدًا.
• بلوغ حد الطلبات: بلغت حد الطلبات في الدقيقة أو في اليوم، ويوضح خطأ الأداة مدة الانتظار.
• لا تظهر الأدوات (الخادم المحلي): استخدم مسارًا مطلقًا إلى index.mjs، وتأكد أن node --version يعرض 20 أو أحدث، ثم أعد تشغيل التطبيق.