> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agencyhandy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# اربط Claude وCursor لتشغيل AgencyHandy عبر MCP

> أعد حزمة AgencyHandy MCP لتطلب من Claude Desktop أو Cursor موجزًا صباحيًا أو تعيين تذاكر أو إرسال فواتير والمزيد — بلغة طبيعية.

يتيح لك اتصال MCP في AgencyHandy التحدث إلى **Claude** أو **Cursor** بلغة طبيعية وتشغيل العمل اليومي في مساحة عمل AgencyHandy — دون فتح كل شاشة بنفسك.

تبقى السيطرة لديك. يعمل Claude وCursor فقط بمفتاح API لمساحة العمل الذي تنشئه، ويطلبان التأكيد عندما يطابق الاسم أكثر من شخص.

<Note>
  تحتاج إلى دور يمكنه فتح **Workspace Config** وإدارة **API keys** (عادةً **SuperAdmin** أو **Admin**). تحتاج أيضًا إلى **Node.js 20+** على الجهاز الذي يشغّل Claude Desktop أو Cursor.
</Note>

## المتطلبات

| المتطلب                          | التفاصيل                                      |
| -------------------------------- | --------------------------------------------- |
| **Node.js**                      | الإصدار **20** أو أحدث (تحقق بـ `node -v`)    |
| **Claude Desktop** أو **Cursor** | أحد هذين التطبيقين مثبت على جهازك             |
| **مساحة عمل AgencyHandy**        | الوصول إلى **Workspace Config** → **API Key** |

حزمة MCP على npm هي `agencyhandy-mcp`. يشغّلها Claude وCursor عبر `npx -y agencyhandy-mcp@1`.

## إعداد Claude أو Cursor MCP

<Steps>
  <Step title="افتح Workspace Config">
    في AgencyHandy، افتح **Workspace Config** (إعدادات الشركة)، ثم انتقل إلى تبويب **API Key**.
  </Step>

  <Step title="أنشئ مفتاح API لمساحة العمل">
    أنشئ مفتاح API جديدًا لمساحة العمل (أو استخدم مفتاحًا محفوظًا). انسخ المفتاح عند ظهوره — لن يتمكن AgencyHandy من إظهار المفتاح الكامل لاحقًا.
  </Step>

  <Step title="انسخ إعداد MCP">
    في تبويب **API Key** نفسه، استخدم لوحة إعداد Claude / Cursor MCP. انقر **Copy MCP config** ليضم JSON مفتاحك ورابط الواجهة الخلفية.
  </Step>

  <Step title="الصق في Cursor أو Claude Desktop">
    الصق الإعداد في:

    * **Cursor**: مشروع أو مستخدم `.mcp.json`
    * **Claude Desktop**: `claude_desktop_config.json`

    أبقِ الأمر `npx -y agencyhandy-mcp@1` ومفتاح API كما تم إنشاؤهما.
  </Step>

  <Step title="أعد التشغيل وجرّب مطالبة">
    أغلق **Cursor** أو **Claude Desktop** بالكامل ثم أعد فتحه. بعد ذلك اطلب شيئًا بسيطًا مثل موجز صباحي لمساحة العمل.
  </Step>
</Steps>

<Tip>
  إذا لم يعثر Claude أو Cursor على خادم MCP، تأكد من تثبيت **Node.js 20+** وإعادة تشغيل التطبيق بعد حفظ الإعداد.
</Tip>

## أمثلة على المطالبات

استخدم لغة طبيعية. فضّل الاسم الكامل أو البريد عند تعيين العمل لاختيار الشخص الصحيح.

| الهدف                           | مثال مطالبة                                                                                                         |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| **موجز صباحي**                  | «أعطني موجزًا صباحيًا: التذاكر المفتوحة والفواتير غير المدفوعة والعروض بانتظار العملاء.»                            |
| **تعيين تذكرة**                 | «عيّن تذكرة إعادة تصميم الصفحة الرئيسية لـ Acme إلى Jordan Lee ([jordan@agency.com](mailto:jordan@agency.com)).»    |
| **إرسال فاتورة**                | «أرسل الفاتورة INV-1042 إلى العميل بالبريد.»                                                                        |
| **إنشاء عميل محتمل**            | «أنشئ عميلًا محتملًا لـ Nora Patel في Bright Studio، البريد [nora@brightstudio.com](mailto:nora@brightstudio.com).» |
| **وضع علامة مدفوعة على فاتورة** | «ضع علامة paid على الفاتورة INV-1042.»                                                                              |

## عندما يشترك شخصان في الاسم نفسه

إذا كان في الفريق شخصان باسم Sara، فسيسأل Claude أيهما تقصد. إنه **لا يخترع** المعرّفات ولا يخمن بصمت.

ضمّن دائمًا **اسمًا كاملًا** أو **بريدًا** في المطالبة عندما قد تتعارض الأسماء.

## ما يعمل الآن مقابل ما لم يتوفر بعد

| يعمل الآن                                                 | غير متاح عبر MCP بعد            |
| --------------------------------------------------------- | ------------------------------- |
| موجزات وعمليات بحث في العروض والمشاريع والتذاكر والفواتير | الرد في **client chat** عبر MCP |
| تعيين التذاكر وأعمال الفريق الأخرى                        | —                               |
| إنشاء عملاء محتملين                                       | —                               |
| إرسال الفواتير ووضع علامة مدفوعة                          | —                               |

يدعم MCP قراءة مساحة العمل والإجراءات (إنشاء، تعيين، إرسال، تحديث) بمفتاح API الخاص بك. ردود دردشة العميل غير معروضة عبر MCP بعد — استخدم AgencyHandy لتلك المحادثات.

## ذات صلة

* أنشئ المفاتيح وانسخ الإعداد داخل التطبيق من **Workspace Config** → **API Key**

<Note>
  Latest package on the `1` tag is **1.7.2+**. Claude can read **`ah://api-context`** (also inside **`ah://full-context`**) for API path gotchas: leads, projects/orders, tasks, comments, labels, clients, invoices, vouchers, and forms.
</Note>

* الحزمة: [`agencyhandy-mcp`](https://www.npmjs.com/package/agencyhandy-mcp) على npm (`npx -y agencyhandy-mcp@1`)