خادم MCP

العمليات الموثقة وحدود التغطية الفعلية

نسخة المصدر هذه تضيف 80 عملية موثقة عبر SDK وCLI وMCP. تحقق بشكل منفصل من إصدار npm المثبت وتفعيل الخدمة المستضافة.

التغطية: جهات الاتصال والمهام والتذاكر؛ إسناد وحالة وتصنيفات وملاحظات المحادثات وإرسال نص بإجراء مستقل؛ مسودات وإعداد ومعرفة نصية وقنوات واختبارات وتفعيل موظفي الذكاء الاصطناعي؛ الطلبات اليدوية وحالتها ودفعها وتنفيذها؛ المنتجات والتصنيفات؛ وحالة جهات الاتصال ومراحلها وإسنادها وتاجاتها وحقولها؛ وقراءة الأتمتة ومسوداتها ومحاكاتها وإيقافها وتفعيل نسختها المعتمدة؛ ومعاينة الحملات ومسوداتها وإيقافها وإلغائها وإرسالها واستئنافها وجدولتها بموافقة دقيقة. دليل 553 مسارًا هو بيانات اكتشاف وليس تغطية تنفيذية كاملة للوحة التحكم.

SDK: استخدم describeOperations() ثم prepareOperation(id, input, idempotencyKey) وexecuteOperation(id, input, { idempotencyKey, confirmation }). CLI: أوامر operations list/inspect/preview/run مع --input و--idempotency-key و--confirm. MCP: أدوات operations_list وoperation_inspect وoperation_preview وoperation_execute؛ الرسائل تستخدم message_send والتفعيل يستخدم lifecycle_activate؛ والحملات تستخدم campaign_send أو campaign_schedule. في CLI استخدم messages send بعد معاينة inbox.message.send.

اعرض المعاينة الدقيقة واحصل على موافقة المستخدم الصريحة قبل التعديل. بصمة التأكيد تربط الإدخال والمفتاح لكنها ليست إثباتًا للموافقة البشرية. احتفظ بنفس مفتاح منع التكرار عند استعادة الطلب. لا توجد إعادة محاولة تلقائية. تستمر قيود الشركة والدور والصلاحية والباقة. صلاحيات OAuth للكتابة تحتاج موافقة صريحة جديدة وتبدأ غير محددة؛ المنح القديمة لا تكتسب صلاحيات.

اختبارات ومعالجة معرفة الذكاء الاصطناعي قد تستهلك الرصيد. التفعيل وإسناد القنوات قد يؤثران على الردود الحية. الإرسال يحتاج موافقة على contactId وchannelId ونوع القناة والنص الكامل؛ والخادم يعيد التحقق من الوجهة. لا إرسال وسائط أو قوالب عبر المحادثات ولا حذف كيانات أو HTTP حر أو فوترة أو إدارة منصة. إرسال قوالب الحملات وجدولتها يتطلبان إجراء مستقل وموافقة على لقطة ثابتة للجمهور والمحتوى والمرسل والتوقيت. تعديل الطلبات والتاجات قد يشغّل الأتمتة؛ والحقول المخصصة تستبدل الخريطة كاملة؛ تحديث الدفع لا يخصم من مزود الدفع. استرداد وإلغاء الطلبات والتغطية الكاملة للحملات والأتمتة ما زالت مستثناة.

@inboxychat/mcp خادم Model Context Protocol يعمل على جهازك عبر STDIO. يشغّله تطبيق الذكاء الاصطناعي عبر npx، ويقرأ Inboxy من خلال الواجهة العامة v1 بمفتاحك.

يحتاج Node.js ‏>= 20.3. لا حاجة لتثبيت عام؛ التطبيق يشغّل الحزمة عبر npx. للتأكد من أنه يعمل:

INBOXY_API_KEY="inboxy_YOUR_KEY" npx -y @inboxychat/mcp

1. سجّل الدخول إلى Inboxy بحساب مدير الشركة وافتح المطورون ← API keys في لوحة التحكم ‏(/developer-center/keys).
2. اختر "أنشئ مفتاح API" وسمِّ المفتاح باسم تعرفه لاحقاً (مثل "Claude على جهازي").
3. اختر الصلاحيات التي تحتاجها فقط. لا توجد صلاحيات افتراضية، ولا يمكن إنشاء مفتاح بلا صلاحيات. أدوات القراءة تحتاج صلاحيات ":read" ‏(contacts:read وorders:read ...).
4. اختر مدة الصلاحية: 30 أو 90 (الافتراضي) أو 180 أو 365 يوماً أو بلا انتهاء. الافتراضي 90 يوماً.
5. انسخ المفتاح عند ظهوره، وهو يبدأ بـ"inboxy_". احفظه في مدير أسرار أو في سلسلة مفاتيح النظام، ولا تضعه أبداً في مستودع كود.

أين يبحث الخادم عن المفتاح

1. المتغير INBOXY_API_KEY في قسم "env" بإعداد التطبيق (وINBOXY_API_URL اختياري).
2. مدخل سلسلة مفاتيح النظام الذي يكتبه inboxy auth login ‏(CLI). ويختار INBOXY_PROFILE ملف التعريف.
3. فقط على الأجهزة التي لا تملك سلسلة مفاتيح: ملف الإعداد بأذونات 0600 الذي يكتبه inboxy auth login --store file.

npm i -g @inboxychat/cli
inboxy auth login        # opens the browser (or paste a key when piped)

ChatGPT (MCP المستضاف)

ChatGPT لا يشغّل عملية محلية. استخدم الخادم المستضاف. يلزم أن تكون مسؤول شركة؛ تفتح الموافقة في Inboxy ولا تشارك مفتاح API خام مع OpenAI.

1. في ChatGPT: الإعدادات ← Apps & Connectors (أو Custom MCP) ← أضف موصلاً جديداً.
2. رابط الخادم: https://api.inboxy.chat/mcp (يُكتشف OAuth من بيانات well-known على نفس المضيف).
3. وافق على شاشة الموافقة في Inboxy كمسؤول شركة، ثم اسأل: "بأي شركة في Inboxy أنا متصل؟"
4. يمكنك الإلغاء في أي وقت من المطورون ← MCP ← تطبيقات الذكاء الاصطناعي المتصلة.

https://api.inboxy.chat/mcp

claude.ai (MCP المستضاف)

نفس رابط ChatGPT المستضاف. موصلات claude.ai تستخدم OAuth؛ تعرض صفحة موافقة Inboxy صلاحيات القراءة المطلوبة قبل أي منح.

1. في Claude.ai: الإعدادات ← Connectors ← أضف موصلاً مخصصاً / خادم MCP.
2. الصق https://api.inboxy.chat/mcp، أكمل OAuth، ووافق كمسؤول شركة.
3. جرّب: "اعرض أقدم خمسة طلبات معلّقة." يجب أن يستدعي Claude أداة orders_list.

https://api.inboxy.chat/mcp

Claude Code

الخادم المستضاف: أضف الرابط، ثم اكتب /mcp داخل Claude Code واختر inboxy وسجّل الدخول، ووافق على شاشة الموافقة في Inboxy كمسؤول شركة. الخادم المحلي: احفظ المفتاح عبر inboxy auth login ثم أضف أمر npx.

claude mcp add --transport http inboxy https://api.inboxy.chat/mcp

claude mcp add inboxy -- npx -y @inboxychat/mcp

claude mcp add inboxy -e INBOXY_API_KEY="$INBOXY_API_KEY" -- npx -y @inboxychat/mcp

{
  "mcpServers": {
    "inboxy": {
      "command": "npx",
      "args": ["-y", "@inboxychat/mcp"],
      "env": { "INBOXY_API_KEY": "${INBOXY_API_KEY}" }
    }
  }
}

Claude Desktop

الإعدادات ← Developer ← Edit Config، أضف الخادم إلى claude_desktop_config.json ثم أعد تشغيل Claude Desktop. لا يستبدل Claude Desktop صيغة ${VAR}: احفظ المفتاح عبر inboxy auth login واحذف "env"، أو ضع المفتاح في "env" وأبقِ الملف خاصاً.

{
  "mcpServers": {
    "inboxy": {
      "command": "npx",
      "args": ["-y", "@inboxychat/mcp"]
    }
  }
}

Codex (OpenAI Codex CLI)

يتصل Codex بالخادم المستضاف عبر HTTPS ويسجّل الدخول بـOAuth في المتصفح؛ وافق على شاشة الموافقة في Inboxy كمسؤول شركة. يحتاج إصداراً حديثاً من Codex CLI: حدّثه إذا لم يتعرّف على --url أو codex mcp login.

codex mcp add inboxy --url https://api.inboxy.chat/mcp
codex mcp login inboxy

[mcp_servers.inboxy]
url = "https://api.inboxy.chat/mcp"

codex mcp add inboxy --env INBOXY_API_KEY="$INBOXY_API_KEY" -- npx -y @inboxychat/mcp

Gemini CLI

يتصل Gemini CLI بالخادم المستضاف عبر HTTPS. بعد إضافته شغّل gemini ونفّذ /mcp auth inboxy لتسجيل الدخول بـOAuth، ثم وافق على شاشة الموافقة في Inboxy كمسؤول شركة.

gemini mcp add --transport http inboxy https://api.inboxy.chat/mcp

{
  "mcpServers": {
    "inboxy": {
      "httpUrl": "https://api.inboxy.chat/mcp"
    }
  }
}

{
  "mcpServers": {
    "inboxy": {
      "command": "npx",
      "args": ["-y", "@inboxychat/mcp"],
      "env": { "INBOXY_API_KEY": "$INBOXY_API_KEY" }
    }
  }
}

Cursor

{
  "mcpServers": {
    "inboxy": {
      "command": "npx",
      "args": ["-y", "@inboxychat/mcp"]
    }
  }
}

VS Code

{
  "inputs": [
    { "type": "promptString", "id": "inboxy-key", "description": "Inboxy API key", "password": true }
  ],
  "servers": {
    "inboxy": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@inboxychat/mcp"],
      "env": { "INBOXY_API_KEY": "${input:inboxy-key}" }
    }
  }
}

1. أنشئ مفتاحاً بصلاحيات القراءة التي تريدها.
2. احفظه: inboxy auth login.
3. أضف الخادم إلى تطبيقك (أعلاه).
4. اسأل: "بأي شركة في Inboxy أنا متصل؟" فيستدعي التطبيق company_get.

أسئلة للتجربة

• "كم طلباً ما زال معلقاً؟ اعرض أقدم خمسة." ‏(orders_list)
• "ابحث عن العميل صاحب الرقم 9665... واعرض طلباته." ‏(contacts_search وorders_list)
• "لخّص محادثات واتساب غير المقروءة اليوم." ‏(conversations_list وconversation_messages)
• "كم بقي لي من حدود باقتي؟" ‏(usage_get)
• "هل المنتج ذو الرمز ABC-1 متوفر؟" ‏(products_search)

عدة شركات (للوكالات)

احفظ ملف تعريف لكل شركة عبر inboxy auth login --profile client-a، ثم أضف خادماً لكل شركة مع ضبط INBOXY_PROFILE.

claude mcp add inboxy-client-a -e INBOXY_PROFILE=client-a -- npx -y @inboxychat/mcp
claude mcp add inboxy-client-b -e INBOXY_PROFILE=client-b -- npx -y @inboxychat/mcp

الأدوات

القوائم تستخدم المؤشرات: limit من 1 إلى 50 (الافتراضي 20)؛ وأعد meta.nextCursor في cursor. أداة operation_execute موسومة بأنها قد تعدّل البيانات؛ الاكتشاف والمعاينة للقراءة فقط.

متغيرات البيئة

• التعديلات محدودة بدليل العمليات الموثقة مع التأكيد الصريح.
• قراءة واحدة من الواجهة لكل استدعاء أداة، ولا شيء غيرها.
• تنطبق على المفتاح حدود الطلبات نفسها الخاصة بواجهة REST.
• HTTPS فقط (وhttp لـlocalhost)؛ تُرفض إعادة التوجيه؛ ولا يظهر المفتاح في النتائج أو الأخطاء أو السجلات.
• إلغاء الطلب في التطبيق يوقف طلب HTTP.

نفّذ inboxy doctor لفحص المفتاح والرابط نفسيهما اللذين يستخدمهما الخادم.