إعداد Claude Desktop

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

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

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

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

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

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

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

3. اربط Claude Desktop

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

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

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

VERBUMIA_PROJECTS requires @verbumia/mcp ≥ 0.11.0. On older releases, see Backwards compatibility below.

Multi-project tool calls

When VERBUMIA_PROJECTS lists more than one UUID, the agent can't infer which project you mean — every tool call must include project_uuid. With a single UUID (or only the legacy VERBUMIA_PROJECT set), it's optional and defaults to that project.

1// list_missing_keys — project_uuid is REQUIRED when VERBUMIA_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}

Phrase your prompt with the project in mind (« in the Checkout project, list missing keys for ja ») — the agent will resolve the project to its UUID and pass project_uuid on the tool call. For ambiguous prompts across multiple projects, the agent will call list_projects first.

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

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

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

أدوات V1 الخمس

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

Plan limits & quotas

You pay when an agent mutates your project, not when it observes it. Reads and listings are free; writes burn one unit; bulk and AI-assisted ops scale with the work they do.

What counts as a billable call

Per-plan ceilings

Monthly quota, hard per-minute rate, concurrent MCP sessions, and whether writes are allowed. The same numbers feed the X-MCP-Quota-Remaining header on every response.

When you hit a ceiling

Over the per-minute rate → 429 mcp_rate_limited with Retry-After (seconds). Over the monthly quota → 429 mcp_quota_exceeded with Retry-After set to the rollover. Free plan writes → 403 mcp_writes_disabled. Quotas reset on the 1st of each calendar month, UTC.

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

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

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