Karzoun Docs

يمنح MCP الوكلاء أيديًا على بيانات كرزون. تساعد هذه الأنماط في الحصول على نتائج موثوقة دون تكرار نفسك في كل محادثة.

قريبًا: لقطة شاشة لوكيل يسرد العملاء ويطبّق وسومًا عبر أدوات كرزون MCP.

للاتصالات المستضافة (Claude.ai، Manus، Cursor عن بُعد)، راجع موصّلات تطبيقات الذكاء الاصطناعي — نفس الأدوات، إعداد عميل مختلف.

أرْسِ الوكيل أولًا

أضف تعليمات نظام أو مشروع قصيرة حتى يعرف النموذج أن أدوات كرزون موجودة:

You have Karzoun MCP tools for CRM and workspace data.
- Prefer read tools (customers, tags, customerDetail) before mutations.
- Use page: 1, perPage: 10 for list queries unless I ask for more.
- Confirm destructive actions (customersRemove, tagsRemove) before calling.

وجّه الوكيل إلى موقع الوثائق هذا لأسماء العمليات: كتالوج الأدوات.

النمط: ابحث قبل التنفيذ

الخطوة	الأداة	لماذا
1	`customers` مع `searchValue`	إيجاد السجل الصحيح
2	`customerDetail` مع `_id`	سياق كامل (الوسوم، المالك، الحقول المخصصة)
3	`customersEdit` أو `tagsTag`	تعديل بثقة

مثال أمر: “Find customer with email alice@example.com, show their tags, then add tag VIP if missing.”

النمط: استكشاف آمن

ابدأ بالقراءة فقط ببادئة أدوات:

"KARZOUN_MCP_TOOL_PREFIX": "customer"

أو وجّه: “Only use query tools for the next five messages.” استخدم currentUser للتحقق من عمل الرمز ومعرفة هوية مساحة العمل التي يعمل بها التطبيق.

النمط: قوائم مرقّمة

غالبًا ما تجلب الوكلاء قوائم بلا حدود وتصطدم بـ حد الاستجابة 512 كيلوبايت. أمر جيد: “List the first 5 customers created this month using page 1 and perPage 5.” مثال حجج الأداة:

{ "page": 1, "perPage": 5 }

راجع الترقيم لـ pagination.totalCount وhasNextPage.

النمط: نظافة CRM

الهدف	الأدوات
فحص التكرار	`customers` + `searchValue`، ثم `customerDetail` على المرشحين
الدمج	`customersMerge` (أكّد مع المستخدم أولًا)
حملات الوسوم	`tags` → `tagsTag` على معرّفات العملاء
البحث عن منتج	`products` → `productDetail`

النمط: فحص خطافات الويب

لتصحيح أخطاء التكامل (وليس خطافات المزوّد):

webhooks — سرد الاشتراكات
webhookDetail — فحص الإعداد
webhookDeliveryLogs — رؤية الإخفاقات ورموز حالة HTTP

اربط مع دليل خطافات الويب لأحداث المستأجر الصادرة.

النمط: وكيل خلفية مستضاف

لعمال جهة الخادم الذين يستدعون /mcp:

خزّن KARZOUN_APP_TOKEN في مدير الأسرار
initialize → التقط mcp-session-id
tools/call في حلقة بأسماء أدوات صريحة
سجّل أخطاء GraphQL من استجابات الأدوات

لا تعرض الجلسة أو الرمز للمستخدمين النهائيين. التفاصيل: MCP المستضاف.

أنماط مضادة

تجنّب	افعل بدلًا من ذلك
”Do everything with Karzoun” (غامض)	سمِّ الأدوات أو النتائج: “list open tags”
`perPage` ضخم في أول استدعاء	ابدأ بـ 5–20 صفًا
تعديلات دون تأكيد	اطلب من الوكيل الاقتراح ثم التنفيذ
تضمين الرموز في قواعد Cursor	أبقِ الرموز في `env` لـ MCP أو أسرار الخادم
استخدام MCP في JavaScript الواجهة	GraphQL من الخلفية، أو MCP المستضاف من جهة الخادم فقط

قواعد مخصصة في Cursor

اختياري .cursor/rules/karzoun-mcp.mdc:

# Karzoun MCP

- Use Karzoun tools for live CRM data; do not invent customer ids.
- After mutations, summarize what changed and link to relevant record ids.
- On permission errors, tell the user to check Developer → Apps scopes.

نظرة عامة

الإعداد

أدلة

الأدوات

أنماط الوكلاء

أرْسِ الوكيل أولًا

النمط: ابحث قبل التنفيذ

النمط: استكشاف آمن

النمط: قوائم مرقّمة

النمط: نظافة CRM

النمط: فحص خطافات الويب

النمط: وكيل خلفية مستضاف

أنماط مضادة

قواعد مخصصة في Cursor

​أرْسِ الوكيل أولًا

​النمط: ابحث قبل التنفيذ

​النمط: استكشاف آمن

​النمط: قوائم مرقّمة

​النمط: نظافة CRM

​النمط: فحص خطافات الويب

​النمط: وكيل خلفية مستضاف

​أنماط مضادة

​قواعد مخصصة في Cursor

أرْسِ الوكيل أولًا

النمط: ابحث قبل التنفيذ

النمط: استكشاف آمن

النمط: قوائم مرقّمة

النمط: نظافة CRM

النمط: فحص خطافات الويب

النمط: وكيل خلفية مستضاف

أنماط مضادة

قواعد مخصصة في Cursor