إعداد Claude Desktop

1. احصل على مفتاح API

من لوحة التحكم، انتقل إلى Org Settings → API Keys → Create. امنحه النطاق mcp:* (يغطي الأدوات الخمس أدناه). يُعرض السر مرة واحدة فقط؛ انسخ السلسلة الكاملة snt_live_<prefix>.<secret>.

احفظه في keychain نظام التشغيل أو في ملف .env محلي — لا تقم بـ commit له أبداً. المفتاح مرتبط بـ org الخاصة بك (واختيارياً بمشروع واحد)، والاستدعاءات خارج هذا النطاق تُرجع 404. ألغِه من لوحة التحكم في أي وقت؛ ترجع المفاتيح الملغاة 401 في الاستدعاء التالي.

2. التثبيت (أو تخطّه)

نُشر خادم MCP على npm وHomebrew. مع npx لا تحتاج إلى تثبيت أي شيء — يسحب Claude Desktop آخر إصدار في كل تشغيل. مع brew تحصل على نسخة محلية مثبّتة، مفيدة خلف جدران الحماية الصارمة.

1// لا حاجة للتثبيت — يسحب npx آخر إصدار من @sonenta/mcp عند الطلب2npx -y @sonenta/mcp --version

1// اختياري: ثبّت عالمياً مرة واحدة — يصل مع إطلاق V12brew install sonenta/tap/sonenta-mcp

3. اربط Claude Desktop

افتح ملف إعدادات Claude Desktop، أضف القيد sonenta ضمن mcpServers، ثم أغلق التطبيق وأعد تشغيله.

1// macOS:   ~/Library/Application Support/Claude/claude_desktop_config.json2// Windows: %APPDATA%/Claude/claude_desktop_config.json3{4  "mcpServers": {5    "sonenta": {6      "command": "npx",7      "args": ["-y", "@sonenta/mcp"],8      "env": {9        "SONENTA_API_KEY": "snt_live_<prefix>.<secret>",10        "SONENTA_PROJECTS": "<uuid1>,<uuid2>"11      }12    }13  }14}

ثلاث متغيرات بيئة في المجموع: SONENTA_TOKEN (مطلوب)، وSONENTA_PROJECT (اختياري — يحدّد المشروع مسبقاً حتى لا يحتاج الوكيل إلى استدعاء list_projects أولاً)، وSONENTA_API_BASE (اختياري — افتراضياً https://api.sonenta.com؛ تجاوزه لاستضافة ذاتية أو staging).

SONENTA_PROJECTS يتطلب @sonenta/mcp ≥ 0.11.0. أما على الإصدارات الأقدم، فانظر الرجعية المتوافقة أدناه.

نداءات الأدوات متعددة المشاريع

حين يسرد SONENTA_PROJECTS أكثر من UUID واحد، لا يمكن للوكيل تخمين أي مشروع تقصد — فيجب أن يتضمّن كل نداء أداة قيمة project_uuid. أما بوجود UUID واحد (أو فقط الإعداد القديم SONENTA_PROJECT) فهو اختياري ويُحسَم النداء افتراضيًا إلى ذلك المشروع.

1// list_missing_keys — project_uuid is REQUIRED when SONENTA_PROJECTS lists more than one UUID2{3  "name": "list_missing_keys",4  "arguments": {5    "project_uuid": "<uuid1>",6    "namespace": "checkout",7    "language_code": "ja"8  }9}

صُغ مطالبتك بذكر المشروع («في مشروع Checkout، اسرد المفاتيح المفقودة بـ ja») — وسيحسم الوكيل المشروع إلى UUID الخاص به ويمرّر project_uuid على نداء الأداة. أما عند مطالبة مبهمة بين عدة مشاريع، فسيستدعي الوكيل list_projects أولًا.

Cursor (وعملاء MCP الآخرون)

نفس JSON، ملف مختلف. في Cursor، ضعه في .cursor/mcp.json (نطاق المشروع) أو ~/.cursor/mcp.json (نطاق المستخدم). للعملاء الآخرين، اتبع وثائق إعداد MCP الخاصة بهم — قيد mcpServers.sonenta متطابق.

1// .cursor/mcp.json (project-scoped) or ~/.cursor/mcp.json (user-scoped)2{3  "mcpServers": {4    "sonenta": {5      "command": "npx",6      "args": ["-y", "@sonenta/mcp"],7      "env": { "SONENTA_API_KEY": "snt_live_<prefix>.<secret>" }8    }9  }10}

أدوات V1 الخمس

بعد الإعداد، تتوفر هذه الأدوات للوكيل. لا تستدعيها بالاسم — صف نيتك في الدردشة وسيختار الوكيل. الأسماء أدناه هي المعرّفات القياسية، تنفع عند قراءة سجلات الوكيل أو بناء وكلاء مخصصين فوق نفس الخادم.

الحدود والحصص حسب الخطة

تدفع حين يعدّل وكيل مشروعك، لا حين يراقبه. القراءات والقوائم مجانية؛ والكتابات تستهلك وحدة واحدة؛ أما العمليات الدفعية والمدعومة بالذكاء الاصطناعي فتتدرّج مع حجم العمل الذي تؤديه.

ما الذي يُحسَب نداءً قابلًا للفوترة

الأسقف حسب الخطة

حصة شهرية، وسقف صارم لكل دقيقة، وجلسات MCP متزامنة، وما إذا كانت الكتابات مسموحة. القيم نفسها تغذّي ترويسة X-MCP-Quota-Remaining على كل استجابة.

حين تبلغ سقفًا

تجاوز المعدّل لكل دقيقة ← 429 mcp_rate_limited مع Retry-After (بالثواني). تجاوز الحصة الشهرية ← 429 mcp_quota_exceeded مع Retry-After مضبوطًا على وقت التدوير. كتابات على خطة Free ← 403 mcp_writes_disabled. تُعاد تهيئة الحصص في الأول من كل شهر تقويمي، بتوقيت UTC.

التحقق من العمل

1. 1 أعد تشغيل Claude Desktop بالكامل (أغلق ثم شغّل — يُقرأ الإعداد عند الإقلاع).
2. 2 افتح دردشة جديدة. يجب أن تُظهر أيقونة المطرقة sonenta مع 5 أدوات متاحة.
3. 3 اكتب «List my Sonenta projects.». ينبغي أن يستدعي الوكيل list_projects ويعيد قائمة بمساحات العمل لديك.

علقت؟ راجع سجلات Claude Desktop في ~/Library/Logs/Claude/mcp*.log (macOS). 90٪ من المشاكل أخطاء طباعية في JSON أو توكن منتهٍ.