MCP

مرجع API

Verbumia ships a native MCP server so any MCP-aware client — Claude Desktop, Cursor, your own agent — can search keys, propose translations, review PRs, and inspect the missing-key queue. Two lines of config, your token, done.

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

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

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

2. Install (or skip)

The MCP server is published to npm and Homebrew. With npx you don't need to install anything — Claude Desktop pulls the latest version on every launch. With brew you get a pinned local binary, useful behind strict firewalls.

npx (موصى به)

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

Homebrew (بديل) Tap يُنشر مع V1

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

3. اربط Claude Desktop

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

claude_desktop_config.json

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"],8      "env": {9        "VERBUMIA_TOKEN":   "vrb_live_<prefix>.<secret>",10        "VERBUMIA_PROJECT": "<project_uuid>"11      }12    }13  }14}

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

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

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

.cursor/mcp.json

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"],7      "env": { "VERBUMIA_TOKEN": "vrb_live_<prefix>.<secret>" }8    }9  }10}

أدوات V1 الخمس

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

list_projects يعدد المشاريع التي يمكن لمفتاح API الحالي الوصول إليها. مفيد لاختيار workspace في بداية الدردشة.

الوسائط

limit number حدّ اختياري لعدد المشاريع المُعادة

مثال prompt

«List my Verbumia projects.»

get_project_info يجلب بيانات المشروع التعريفية: لغة المصدر، اللغات الهدف، namespaces، إجمالي عدد المفاتيح.

الوسائط

project_uuid string required

مثال prompt

«ما اللغات والـ namespaces التي يقدّمها مشروع Checkout؟»

list_missing_keys يُدرج أحداث المفاتيح الناقصة المعلّقة التي يلتقطها SDK في الـ runtime (مع cursor للتصفح). يمكن التصفية حسب namespace أو اللغة.

الوسائط

project_uuid string required
namespace string يضيق إلى namespace واحد (مثل "checkout")
language_code string يضيق إلى لغة واحدة (مثل "ja")
cursor string cursor التصفح المُعاد من استدعاء سابق
limit number حجم الصفحة (افتراضياً 20)

مثال prompt

«ما مفاتيح الترجمة الناقصة لـ ja في namespace checkout؟»

propose_translation يُرسل قيمة ترجمة لمفتاح ضمن لغة هدف. تُكتب دائماً كـ draft؛ يقوم مراجع بشري بترقيتها لاحقاً — Verbumia هو المدير، وليس المحرّك.

الوسائط

project_uuid string required
key string required
namespace string required
language_code string required
value string required

مثال prompt

«Propose \"Confirmer la commande\" for checkout.review.confirm in fr-CA.»

validate_translations يفحص (lint) حمولة JSON i18next قبل الـ push: اتساق placeholders ICU، المفاتيح الناقصة/الزائدة، انجراف الأنواع عبر اللغات.

الوسائط

project_uuid string required
language_code string required
payload object required خريطة ترجمات بهيئة JSON i18next

مثال prompt

«تحقق من ملف الترجمة هذا مقابل المصدر الإنجليزي للمشروع.»

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

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