خادم MCP

تقدّم OrcaRail خادم Model Context Protocol (MCP) رسميًا باسم @orcarail/mcp. يعمل محليًا عبر stdio ويغلّف حزمة @orcarail/node، ليتمكن وكلاء البرمجة بالذكاء الاصطناعي مثل Claude Code وCursor وCodex من إنشاء payment intents وإدارة الاشتراكات وصيانة كتالوج المنتجات والبحث عن أسعار الصرف نيابةً عنك؛ بنموذج التوزيع نفسه لـ @stripe/mcp من Stripe.

الكود المصدري: github.com/OrcaRail/mcp

ما الذي يمكنك فعله به

بعد الاتصال، يمكنك أن تطلب من وكيلك أشياء مثل:

• «أنشئ payment intent بقيمة 25 دولارًا بـ USDC على Polygon مع رابط العودة https://myapp.com/success وأعطني رابط الدفع.»
• «اسرد اشتراكاتي النشطة وألغِ اشتراك [email protected] في نهاية الفترة.»
• «أنشئ منتجًا باسم Pro Plan بسعر متكرر 29 دولارًا شهريًا.»
• «كم تساوي 500 يورو بـ USDC الآن؟»
• «ما حالة الـ payment intent ‏550e8400-…؟»

يستدعي الوكيل أدوات MCP المقابلة. لا تحتاج الأدوات العامة (rates.* وpay.*) إلى بيانات اعتماد؛ وتصادق الأدوات الخاصة بمفتاح API وسرّه مقابل REST API الخاصة بـ OrcaRail.

المتطلبات

• Node.js 18 أو أحدث
• للأدوات الخاصة: مفتاح API وسرّه من OrcaRail (ak_… / sk_…) من لوحة التحكم
• تعمل أدوات الأسعار والدفع العامة دون بيانات اعتماد

البدء السريع

الأدوات العامة فقط (دون بيانات اعتماد):

npx -y @orcarail/mcp --tools=all

مع بيانات اعتماد للأدوات الخاصة (فضّل متغيرات البيئة):

export ORCARAIL_API_KEY=ak_live_xxx
export ORCARAIL_API_SECRET=sk_live_xxx
npx -y @orcarail/mcp --tools=all

أو مرّر الخيارات:

npx -y @orcarail/mcp --tools=all --api-key=ak_live_xxx --api-secret=sk_live_xxx

يتحدث الخادم بروتوكول MCP عبر stdin/stdout؛ وهو مصمم ليشغّله عميل MCP (راجع أقسام العملاء أدناه)، لا للاستخدام التفاعلي.

الإعداد

كل خيار متاح كخيار سطر أوامر أو متغير بيئة. للخيارات الأولوية. فضّل متغيرات البيئة للأسرار.

الخيار	متغير البيئة	مطلوب	الوصف
--api-key	ORCARAIL_API_KEY	للأدوات الخاصة	مفتاح API (ak_…)
--api-secret	ORCARAIL_API_SECRET	للأدوات الخاصة	سر API (sk_…)
--api-base	ORCARAIL_API_BASE	لا	الرابط الأساسي لـ API. الافتراضي https://api.orcarail.com/api/v1
--organization-id	ORCARAIL_ORGANIZATION_ID	لا	المؤسسة الافتراضية لأدوات الكتالوج (products.* وprices.*)
--tools	—	لا	all (افتراضي) أو قائمة بأسماء الأدوات مفصولة بفواصل

تقييد الأدوات

افتراضيًا تُتاح كل الأدوات. استخدم --tools لتقييد ما يستطيع الوكيل فعله؛ مثل القراءة والإنشاء فقط دون إلغاء أو حذف:

npx -y @orcarail/mcp \
  --tools=payment_intents.create,payment_intents.retrieve,subscriptions.list,rates.get_fiat_quote \
  --api-key=ak_live_xxx --api-secret=sk_live_xxx

تُتجاهل الأسماء غير المعروفة بصمت؛ ولا يسجّل الخادم إلا الأدوات المطابقة.

API مستضافة ذاتيًا أو محلية

وجّه --api-base إلى نشرك الخاص:

npx -y @orcarail/mcp --tools=all \
  --api-base=http://127.0.0.1:3000/api/v1 \
  --api-key=ak_test_xxx --api-secret=sk_test_xxx

إعداد العميل

Claude Code

claude mcp add orcarail -- npx -y @orcarail/mcp --tools=all --api-key=ak_live_xxx --api-secret=sk_live_xxx

أو أبقِ الأسرار خارج سطر الأوامر باستخدام متغيرات البيئة:

claude mcp add orcarail \
  -e ORCARAIL_API_KEY=ak_live_xxx \
  -e ORCARAIL_API_SECRET=sk_live_xxx \
  -- npx -y @orcarail/mcp --tools=all

تحقق عبر claude mcp list، ثم اطلب من Claude Code مثلًا «اسرد اشتراكاتي في OrcaRail».

Cursor

أضف إلى .cursor/mcp.json في مشروعك (أو ~/.cursor/mcp.json لكل المشاريع):

{
  "mcpServers": {
    "orcarail": {
      "command": "npx",
      "args": ["-y", "@orcarail/mcp", "--tools=all"],
      "env": {
        "ORCARAIL_API_KEY": "ak_live_xxx",
        "ORCARAIL_API_SECRET": "sk_live_xxx"
      }
    }
  }
}

يلتقط Cursor الخادم تلقائيًا؛ تحقق من Settings ← MCP أنه يعمل.

Codex

أضف إلى ~/.codex/config.toml:

[mcp_servers.orcarail]
command = "npx"
args = ["-y", "@orcarail/mcp", "--tools=all"]

[mcp_servers.orcarail.env]
ORCARAIL_API_KEY = "ak_live_xxx"
ORCARAIL_API_SECRET = "sk_live_xxx"

عملاء MCP آخرون

يعمل أي عميل يدعم خوادم MCP عبر stdio بالشكل نفسه: الأمر npx والوسائط ["-y", "@orcarail/mcp", "--tools=all"]. بيانات الاعتماد (ORCARAIL_API_KEY / ORCARAIL_API_SECRET) اختيارية للأدوات العامة ومطلوبة للأدوات الخاصة. في Claude Desktop أضف كتلة JSON نفسها الخاصة بـ Cursor إلى claude_desktop_config.json.

الإنتاج مقابل الـ sandbox

يكتشف الخادم وضعه من مفتاح API ويخبر وكيلك عبر تعليمات MCP وأداة account.get_mode:

• ak_test_… (مؤسسة sandbox): شبكات تجريبية فقط، دون أموال حقيقية. تتوفر payment_intents.simulate.
• ak_live_…: أموال حقيقية. يُطلب من الوكيل التأكيد معك قبل أي عملية كتابة.
• دون مفتاح: الأدوات العامة فقط.

استخدم مفتاح sandbox أثناء البناء مع وكيل.

مرجع الأدوات

تتبع أسماء الأدوات الصيغة resource.action. كل الاستجابات هي كائنات API الخام من OrcaRail مُسلسَلة كـ JSON.

Payment intents

الأداة	الوسائط	الوصف
payment_intents.create	return_url (مطلوب)؛ إما price_id أو amount + currency + tokenId + networkId؛ واختياريًا cancel_url وdescription وmetadata وexpires_at وpayment_method_types وwithdrawal_addresses	تنشئ payment intent. تعيد الـ intent مع client_secret ورابط الدفع
payment_intents.retrieve	id	تجلب الحالة الحالية
payment_intents.update	id + أي حقل قابل للتحديث	تحدّث قبل التأكيد
payment_intents.confirm	id وclient_secret وreturn_url	تؤكد وتحصل على رابط التوجيه إلى صفحة الدفع المستضافة
payment_intents.complete	id	تعلّم بأنه قيد المعالجة بعد عودة العميل إلى رابط النجاح
payment_intents.cancel	id	تلغي الـ intent

tokenId وnetworkId معرّفات UUID؛ راجع الشبكات والرموز للقيم الحية.

الاشتراكات

الأداة	الوسائط	الوصف
subscriptions.create	description (مطلوب)؛ إما price_id أو interval + amount + currency + token_id + network_id؛ واختياريًا collection_method وtotal_cycles وtrial_period_days وtrial_end وpayer_email وpayer_user_id وbilling_cycle_anchor وcancel_at وcancel_at_period_end وdays_until_due وinterval_count وmetadata وwithdrawal_addresses وreturn_url وcancel_url	تنشئ اشتراكًا متكررًا
subscriptions.retrieve	id	تجلب اشتراكًا
subscriptions.update	id + أي حقل قابل للتحديث، بما فيه pause_collection	تحدّث اشتراكًا
subscriptions.cancel	id، وcancellation_details اختياري (comment وfeedback)	الإلغاء
subscriptions.resume	id	تستأنف اشتراكًا متوقفًا
subscriptions.list	اختياريًا status وcollection_method ومرشحات النطاق created/current_period_start/current_period_end وlimit وstarting_after وending_before	السرد مع ترقيم بالمؤشر
subscriptions.list_payment_links	id، واختياريًا limit وstarting_after وending_before	فواتير الدورات (روابط الدفع) لاشتراك

الكتالوج: المنتجات

تعمل أدوات الكتالوج على مؤسسة. مرّر organization_id في كل استدعاء، أو اضبط قيمة افتراضية مرة واحدة عبر --organization-id / ORCARAIL_ORGANIZATION_ID.

الأداة	الوسائط	الوصف
products.list	organization_id اختياري	تسرد المنتجات
products.create	name (مطلوب)؛ واختياريًا description وactive وmetadata وdefault_price وmarketing_features وغيرها	تنشئ منتجًا
products.update	product_id + أي حقل قابل للتحديث	تحدّث منتجًا
products.delete	product_id	تحذف منتجًا

الكتالوج: الأسعار

الأداة	الوسائط	الوصف
prices.list	اختياريًا organization_id وactive وrecurring وlimit	تسرد الأسعار
prices.create	unit_amount_decimal وcurrency وtoken_id وnetwork_id (مطلوبة)؛ وproduct أو product_data مضمّن؛ واختياريًا recurring (interval وinterval_count وtrial_period_days) وnickname وlookup_key وactive وmetadata	تنشئ سعرًا لمرة واحدة أو متكررًا
prices.update	price_id + أي حقل قابل للتحديث	تحدّث سعرًا
prices.deactivate	price_id	تعطّل سعرًا

الأسعار (عامة، دون بيانات اعتماد)

الأداة	الوسائط	الوصف
rates.get_fiat_quote	amount وcurrency	تحوّل مبلغًا بالعملة الورقية إلى USD/USDC
rates.list_currencies	active اختياري	تسرد العملات الورقية المدعومة

الدفع (صفحات الدفع المستضافة، عامة، دون بيانات اعتماد)

الأداة	الوسائط	الوصف
pay.get_by_slug	slug	تحصل على تفاصيل الدفع عبر slug صفحة الدفع المستضافة
pay.cancel_by_slug	slug	تلغي payment intent عبر slug الدفع الخاص به

أمثلة على سير العمل

إنشاء دفعة والحصول على رابط الدفع

اطلب من وكيلك:

أنشئ في OrcaRail ‏payment intent بقيمة 50 دولارًا باستخدام USDC على Polygon، مع رابط العودة https://myshop.com/thanks، ثم أكّده وأعطني رابط الدفع المخصص للعميل.

سيستدعي الوكيل payment_intents.create، ثم payment_intents.confirm مع client_secret المُعاد، ويخبرك برابط صفحة الدفع المستضافة.

إعداد منتج اشتراك

أنشئ في OrcaRail منتجًا باسم «Pro Plan» بسعر متكرر 29 دولارًا شهريًا بـ USDC، ثم أنشئ اشتراكًا لـ [email protected] بذلك السعر.

يربط الوكيل products.create ← prices.create (مع recurring.interval: "month") ← subscriptions.create (مع price_id الجديد وpayer_email).

التحقيق في دفعة

ابحث عن الـ payment intent ‏550e8400-e29b-41d4-a716-446655440000 وأخبرني بحالته ومبلغه وآخر معاملة.

معالجة الأخطاء

تُعاد أعطال API إلى الوكيل كأخطاء أدوات مع حالة HTTP ونوع الخطأ ورسالة API كما هي (مثل API error (401): [authentication_error]: …). يقرأ الوكلاء هذه الأخطاء عادةً ويصححون استدعاءهم التالي؛ ولا يُعاد أي شيء تلقائيًا.

يعيد استدعاء أداة خاصة دون بيانات اعتماد خطأ أداة واضحًا: اضبط ORCARAIL_API_KEY وORCARAIL_API_SECRET (أو خيارات سطر الأوامر المقابلة).

الأمان

• تمنح المفاتيح وصولًا كاملًا إلى المؤسسة المرتبطة بمفتاح API. تعامل مع ملفات إعداد MCP بالحرص نفسه الذي تتعامل به مع ملفات .env.
• فضّل متغيرات البيئة على الوسائط المضمّنة --api-key=… حتى لا تنتهي الأسرار في سجل الطرفية أو إعدادات مُضافة إلى المستودع.
• لا تضف المفاتيح الحية أبدًا إلى المستودع. إذا استخدمت .cursor/mcp.json على مستوى المشروع، فأبقِ المفتاح خارج git (استخدم مراجع متغيرات البيئة أو ملفًا محليًا فقط).
• حدّد النطاق عبر --tools. أتح فقط العمليات التي يحتاجها وكيلك؛ مثل استبعاد products.delete وsubscriptions.cancel في سير العمل القائم على القراءة غالبًا.
• استخدم مفاتيح الاختبار أثناء التطوير، ودوّر أي مفتاح قد يكون تسرّب من لوحة التحكم.

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

العَرَض	الحل
Missing credentials for this tool	اضبط ORCARAIL_API_KEY/ORCARAIL_API_SECRET (أو --api-key/--api-secret) للأدوات الخاصة
Authentication error في كل استدعاء	تحقق من زوج المفتاح/السر في لوحة التحكم؛ وتأكد من عدم الخلط بين بيانات الاختبار والإنتاج
organization_id is required	مرّر organization_id في استدعاء الأداة أو شغّل الخادم مع --organization-id
أداة مفقودة في العميل	تحقق من مرشح --tools؛ يجب أن تتطابق الأسماء تمامًا (مثل payment_intents.create)
العميل لا يستطيع تشغيل الخادم	تأكد من وجود Node.js 18+ في PATH الذي يستخدمه العميل؛ وجرّب npx -y @orcarail/mcp --help في الطرفية

ذو صلة

• البناء بالذكاء الاصطناعي
• Node.js SDK
• مفاتيح API
• الشبكات والرموز
• llms.txt