1. نبذة عامة

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

يتيح لك ZenHR Connector ربط بياناتك المباشرة من ZenHR مع Claude، لتتمكن من طرح الأسئلة بلغة طبيعية والحصول على إجابات تستند إلى بياناتك الفعلية داخل نظام الموارد البشرية. ويوفر ZenHR Connector مجموعة مختارة من الأدوات للقراءة فقط، تشمل دليل الموظفين، والفروع، وملخصات المعاملات المالية، وتحليلات السعودة ونطاقات، ومؤشرات الموارد البشرية الخاصة بقيادات الموارد البشرية (CHRO)، وتوزيع نتائج تقييمات الأداء، بالإضافة إلى تخطيط الإجازات وإدارة الإجازات على مستوى الفرق.

يُعد ZenHR منصة متكاملة لإدارة الموارد البشرية والرواتب، مصممة لتلبية احتياجات الشركات في مختلف أنحاء منطقة الشرق الأوسط وشمال أفريقيا.

تم تطوير وتشغيل ZenHR Connector بواسطة ZenHR، ويعتمد على نظام تسجيل الدخول وإدارة الصلاحيات الخاص بالمنصة، مما يضمن أن Claude لا يمكنه الوصول إلا إلى البيانات التي تمتلك صلاحية الاطلاع عليها داخل ZenHR. كما أنه لا يستطيع تعديل أي بيانات أو إضافتها أو حذفها. وتبقى كل عملية اتصال معزولة وآمنة ضمن بيانات شركتك فقط.

2. ما الذي يمكنك أن تسأله؟

فيما يلي بعض الأمثلة على الأسئلة التي يمكنك طرحها على Claude، والأداة التي يستخدمها للإجابة عليها:

3. المتطلبات الأساسية

• امتلاك حساب فعّال على ZenHR.

• تخضع صلاحيات الوصول إلى البيانات لدورك وصلاحياتك داخل ZenHR. ولا يعرض ZenHR Connector إلا البيانات التي يحق لك الاطلاع عليها بالفعل داخل المنصة. فإذا لم يكن لديك صلاحية للوصول إلى قسم معيّن (مثل المعاملات المالية)، فلن يتمكن Claude من الوصول إليه أيضاً.

• أدوات نطاقات مخصصة للمملكة العربية السعودية فقط.

4. التثبيت والاتصال

يمكنك إضافة (ZenHR Connector) في Claude كربط مخصص (Custom Connector) يشير إلى نقطة الاتصال الخاصة بـ ZenHR.

1. في Claude، انتقل إلى

 Settings → Connectors → Add Custom Connector

2. أدخل عنوان الخادم |Server URL
   https://app.zenhr.com/zen_mcp

3. سيكتشف Claude تلقائياً طريقة تسجيل الدخول المناسبة.

4. سيقوم Claude بفتح صفحة تسجيل الدخول والموافقة الخاصة بـ ZenHR. سجّل الدخول باستخدام حسابك في ZenHR، ثم وافق على صلاحيات القراءة فقط الموضحة في القسم 5. لا تحتاج إلى نسخ أي كلمة مرور أو مفتاح سري، إذ يتم الاتصال عبر بروتوكول OAuth الآمن.

5. بعد منح الموافقة، سيتصل Claude بـ ZenHR، وستصبح أدوات ZenHR Connector متاحة للاستخدام، ويمكنك البدء بطرح أسئلتك مباشرة.

يمكنك إنهاء الجلسة في أي وقت من خلال فصل الربط (Disconnect) من داخل Claude.

5. المصادقة والصلاحيات

• طريقة تسجيل الدخول: يستخدم ZenHR Connector بروتوكول OAuth 2.1 مع PKCE، وهو نفس أسلوب تسجيل الدخول الآمن المعتمد في ZenHR. ولا يتطلب ذلك إدارة مفتاح API أو Client Secret، كما يتم تجديد الجلسات تلقائياً.

• مكان تسجيل الدخول: تتم عملية تسجيل الدخول عبر خادم المصادقة الخاص بـ ZenHR. ويكتشف Claude إعدادات المصادقة تلقائياً من خلال بيانات OAuth القياسية، ثم يُسجّل نفسه تلقائياُ قبل أول عملية تسجيل دخول.

• عزل البيانات بين الشركات: يرتبط الاتصال بحسابك في ZenHR ضمن شركتك فقط، ولا يمكن للبيانات الانتقال أو مشاركتها بين الشركات.

6. الأدوات

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

جميع الأدوات تعمل بصلاحية القراءة فقط، أي أنها لا تستطيع إنشاء البيانات أو تعديلها أو حذفها. وتتيح لك بعض الأدوات تحديد عدد النتائج المعروضة أو استبعاد الحقول غير الضرورية لتقديم استجابات أكثر اختصاراً. ويتم جلب جميع البيانات مباشرةً من حسابك في ZenHR وفقاً لصلاحياتك الحالية، لذلك لا يمكن لـ Claude الوصول إلا إلى البيانات المصرح لك بالاطلاع عليها. 

تعتمد جميع الأدوات على بياناتك المباشرة في ZenHR من خلال واجهات ZenHR API، مع الالتزام بصلاحيات الوصول الممنوحة لدورك في النظام في كل سؤال. 

6.1 get_my_profile - ملفي الشخصي

• قراءة فقط. يعرض بيانات ملفك الشخصي، ومعلومات المصادقة، وحالة الجلسة، وموعد انتهاء صلاحية رمز الوصول (Token).

• المعاملات/Parameters: لا يوجد.

• يُستخدم للإجابة على أسئلة مثل:

  • من الحساب الذي سجلت الدخول به؟

  • هل لا تزال جلستي فعالة؟

{ "method": "tools/call", "params": { "name": "get_my_profile", "arguments": {} } }

{ "structuredContent": {

    "user_id": 90210, "employee_id": 33412, "name": "Sample User",

    "company_id": 771, "branch_id": 4821,

    "token_expires_at": "2026-06-23T18:40:00Z" } }

6.2 list_branches - عرض الفروع

• قراءة فقط. يعرض قائمة بالفروع التي تمتلك صلاحية الوصول إليها.

• يُستخدم أيضاً للحصول على معرّفات الفروع (Branch IDs) اللازمة لاستخدامها مع الأدوات الأخرى.

{ "method": "tools/call", "params": { "name": "list_branches",

  "arguments": { "country_id": 134, "limit": 5 } } }

{ "structuredContent": {

    "branches": [

      { "id": 4821, "name": "Riyadh HQ", "country": { "country_code": "SA" } },

      { "id": 4822, "name": "Jeddah Office", "country": { "country_code": "SA" } } ],

    "pagination": { "page": 1, "total_pages": 1, "total": 2 },

    "search_term": null } }

6.3 list_employees — عرض الموظفين

• قراءة فقط. يعرض قائمة الموظفين في فرع معين (ويستخدم الفرع الحالي افتراضياً).

• ملاحظة: قد تتضمن سجلات الموظفين بيانات شخصية مثل رقم جواز السفر، والهوية الوطنية، والديانة، وبيانات التواصل. وإذا كنت تحتاج فقط إلى البيانات الأساسية، يمكنك استخدام exclude_fields لاستبعاد الحقول غير المطلوبة.

{ "method": "tools/call", "params": { "name": "list_employees",

  "arguments": { "branch_id": 4821, "limit": 2,

    "exclude_fields": ["passport_number", "national_id", "religion"] } } }

{ "structuredContent": {

    "employees": [

      { "id": 33412, "name": "Sample Employee A", "employment_number": "E-1001",

        "nationality": ["Saudi Arabia"] },

      { "id": 33413, "name": "Sample Employee B", "employment_number": "E-1002",

        "nationality": ["Jordan"] } ],

    "pagination": { "page": 1, "total_pages": 18, "total": 36 },

    "branch_id": 4821, "search_term": null } }

6.4 summarize_financial_transactions — تلخيص المعاملات المالية

• قراءة فقط. يقوم بتجميع المعاملات المالية لفرع معين حسب العملة، ثم الربع السنوي، ثم نوع المعاملة، مع عرض عدد المعاملات، وإجمالي المبالغ، والنسب المئوية.

• يتولى الربط عملية التنقل بين الصفحات تلقائياً، لذلك لا تحتاج إلى تمرير page أو limit.

• ملاحظة: يقرأ حتى 1,500 معاملة في كل طلب (30 صفحة × 50 معاملة). وإذا تجاوز عدد المعاملات هذا الحد، فستكون قيمة truncated مساوية لـ true، مما يعني أن النتائج جزئية، ويُنصح عندها بتضييق نطاق التاريخ أو استخدام عوامل تصفية إضافية.

{ "method": "tools/call", "params": { "name": "summarize_financial_transactions",

  "arguments": { "branch_id": 4821, "direction": "deduction",

    "effective_date_from": "2026-01-01", "effective_date_to": "2026-06-30" } } }

{ "structuredContent": {

    "summary": { "total_transactions": 84, "dropped_transactions": 0,

      "pages_fetched": 2, "total_pages": 2, "branch_id": 4821, "truncated": false,

      "window": { "from": "2026-01-01", "to": "2026-06-30" },

      "filters": { "direction": "deduction" } },

    "currencies": [

      { "currency": "SAR", "count": 84, "amount_fils": 12500000,

        "quarters": [

          { "quarter": "Q1 2026", "count": 40, "amount_fils": 6000000,

            "percentage_of_currency_total": 48.0,

            "types": [ { "name": "GOSI Deduction", "count": 40, "amount_fils": 6000000,

              "percentage_of_quarter": 100.0, "percentage_of_currency_total": 48.0 } ] } ] } ] } }

6.5 get_nitaqat_workforce — بيانات القوى العاملة (السعودية)

• قراءة فقط. يعرض عدد الموظفين النشطين، بالإضافة إلى توزيع السعوديين وغير السعوديين في كل فرع داخل المملكة العربية السعودية، لدعم تحليلات السعودة وبرنامج نطاقات.

• يعتبر الموظف سعودياً إذا كانت جنسيته تتضمن السعودية.

• لا تقوم الأداة بحساب نطاق المنشأة تلقائياً، وإنما تُستخدم مع أداة get_nitaqat_guideline التي توفر المعادلات الرسمية اللازمة لذلك.

• ملاحظة: يعد تحديد economic_activity (النشاط الاقتصادي) إلزامياً. وإذا لم تكن تعرف النشاط الصحيح، يمكنك استخدام get_nitaqat_guideline للحصول على قائمة الأنشطة المعتمدة في الملحق رقم (1).

{ "method": "tools/call", "params": { "name": "get_nitaqat_workforce",

  "arguments": { "economic_activity": "Manufacturing" } } }

{ "structuredContent": {

    "economic_activity": "Manufacturing", "country_code": "SA",

    "nitaqat_official_source_url": "https://www.hrsd.gov.sa/.../E20210523.pdf",

    "nitaqat_resource_uri": "zenhr://compliance/nitaqat",

    "summary": { "ksa_branch_count": 2, "total_active_employees": 120,

      "total_saudi_employees": 78, "total_non_saudi_employees": 42,

      "saudization_rate_percent": 65.0 },

    "branch_breakdown": [

      { "id": 4821, "name": "Riyadh HQ", "country_code": "SA",

        "total_active_employees": 80, "total_saudi_employees": 56,

        "total_non_saudi_employees": 24, "saudization_rate_percent": 70.0 } ] } }

6.6 get_nitaqat_guideline — دليل برنامج نطاقات

• قراءة فقط. يعرض دليل برنامج نطاقات المطور (الإصدار 2.0)، والذي يتضمن:

  • الأنشطة الاقتصادية الواردة في الملحق رقم (1).

  • معاملات m وc.

  • معادلات احتساب النطاق (y = m · ln(x) + c).

  • الخدمات التي تقدمها الوزارة لكل لون من ألوان النطاق.

• يعتمد على الدليل الرسمي الصادر عن وزارة الموارد البشرية والتنمية الاجتماعية.

• يُستخدم لفهم آلية عمل برنامج نطاقات، ولحساب نطاق المنشأة بالاشتراك مع get_nitaqat_workforce.

{ "method": "tools/call", "params": { "name": "get_nitaqat_guideline", "arguments": {} } }

6.7 get_hr_updates — مؤشرات الموارد البشرية

• قراءة فقط. يحسب مؤشرات الموارد البشرية على مستوى ربع سنوي، أو نصف سنوي، أو سنوي، لاستخدامها في تقارير الإدارة التنفيذية ومراجعات القوى العاملة.

• تشمل المؤشرات:

  1. عدد الموظفين في بداية ونهاية الفترة.

  2. صافي التغيير في عدد الموظفين.

  3. التعيينات الجديدة.

  4. حالات انتهاء الخدمة.

  5. معدلات دوران الموظفين (الإجمالي، الطوعي، غير الطوعي، وخلال السنة الأولى).

  6. معدل الاحتفاظ بالموظفين.

  7. معدل الإجراءات التأديبية.

  8. توزيع الموظفين حسب الجنس.

• تعمل الأداة على مرحلتين:

  1. استدعاؤها مع تحديد الفترة الزمنية فقط، لتحديد نطاق التقرير.

  2. إعادة استدعائها بعد اختيار نطاق التقرير (جميع الفروع أو فرع محدد، مع خيارات التجميع المختلفة).

• ملاحظة: إذا لم تكن لديك صلاحية الوصول إلى بعض المؤشرات، فسيتم إدراجها ضمن unavailable بدلاً من عرض بياناتها.

{ "method": "tools/call", "params": { "name": "get_hr_updates",

  "arguments": { "period": "Q2-2026" } } }

First reply (asks you to choose scope):

{ "structuredContent": { "status": "needs_selection",

    "missing": ["branch_scope"], "errors": [] } }

Final reply (abbreviated):

{ "structuredContent": {

    "period": { "label": "Q2 2026" },

    "grouping": { "branch": "all", "time": "combined", "org": "combined" },

    "metrics_included": ["headcount_end_of_period", "new_hires", "overall_turnover_rate"],

    "segments": [ { "segment": "Company", "dimension": "company",

      "buckets": [ { "label": "Q2 2026",

        "metrics": { "new_hires": { "label": "New hires", "value": 12, "unit": "employees" } } } ] } ],

    "unavailable": {} } }

6.8 get_pe_bell_curve_data — تحليل تقييم الأداء ومنحنى التوزيع

• قراءة فقط. توفر تحليلات تقييم الأداء من خلال وضعين:

  • وضع الاستكشاف: يعرض دورات تقييم الأداء المتاحة (مع إمكانية التصفية حسب السنة).

  • تحليل منحنى التوزيع (Bell Curve): يعرض توزيع نتائج التقييم، والإحصاءات الخاصة بدورة تقييم محددة.

• يشمل التقرير:

  • توزيع الموظفين حسب مستويات التقييم.

  • المتوسط الحسابي.

  • الوسيط.

  • الانحراف المعياري.

  • أعلى وأدنى درجة.

{ "method": "tools/call", "params": { "name": "get_pe_bell_curve_data",

  "arguments": { "evaluation_cycle_id": 512, "score_type": "final" } } }

{ "structuredContent": {

    "meta": { "evaluation_cycle_id": 512, "evaluation_cycle_name": "2025 Annual",

      "year": 2025, "score_type": "final", "total_with_scores": 96, "total_in_cohort": 100,

      "branches_included": [ { "id": 4821, "name": "Riyadh HQ" } ] },

    "distribution_by_scale": [

      { "level": 1, "name": "Below Expectations", "count": 6, "percentage": 6.25 },

      { "level": 2, "name": "Meets Expectations", "count": 70, "percentage": 72.92 },

      { "level": 3, "name": "Exceeds Expectations", "count": 20, "percentage": 20.83 } ],

    "statistics": { "mean": 78.4, "median": 79.0, "std_dev": 8.1, "min": 55.0, "max": 96.0 } } }

6.9 get_team_timeoff — إجازات الفريق والتخطيط للإجازات

• قراءة فقط. يعرض جميع الإجازات التي تتقاطع مع فترة زمنية محددة، مما يساعد على تخطيط الإجازات ومعرفة توفر أعضاء الفريق.

• يُستخدم للإجابة على أسئلة مثل:

  • من لديه إجازة الأسبوع القادم؟

  • كم عدد أيام الإجازة التي حصل عليها موظف معين هذا الشهر؟

  • هل الفريق متاح قبل جدولة إجازة جديدة؟

• لا يمكن استخدامه لتقديم طلبات الإجازة أو الموافقة عليها أو رفضها.

Parameters:

o   from_date (required, ISO 8601 e.g. 2026-07-01) - start of the date window.

o   to_date (optional, ISO 8601) - end of the window. Defaults to 6 days after
 from_date (one week).

o   branch_id (optional) - branch to query; defaults to your current branch. Ignored when
 company_wide: true.

o   employee_id (optional) - filter to a single employee (use for "how many leaves did X
 take?").

o   status (optional) - approved (default; confirmed leaves, including HR-entered),
 pending (awaiting approval), or all.

o   company_wide (optional, default false) - when true, queries all accessible
 branches (matches the dashboard "who is off" view); when false, queries the current
 branch only.

المعاملات الرئيسية:

• from_date (إلزامي): تاريخ بداية الفترة.

• to_date (اختياري): تاريخ نهاية الفترة (افتراضياً بعد 6 أيام).

• branch_id (اختياري): الفرع المطلوب.

• employee_id (اختياري): لتصفية النتائج لموظف معين.

• status (اختياري): معتمد، أو قيد الموافقة، أو جميع الحالات.

• company_wide (اختياري): عند تفعيله يتم البحث في جميع الفروع التي تملك صلاحية الوصول إليها.

ملاحظة: يقتصر الحد الأقصى للنتائج على 200 سجل عبر 50 فرع. وإذا تم تجاوز هذا الحد، فستكون قيمة truncated مساوية لـ true، ويُنصح بتضييق نطاق البحث أو تصفيته للحصول على نتائج كاملة.

{ "method": "tools/call", "params": { "name": "get_team_timeoff",

  "arguments": { "from_date": "2026-07-06", "to_date": "2026-07-12",

    "company_wide": true, "status": "approved" } } }

{ "structuredContent": {

    "timeoff_entries": [

      { "id": 55101, "employee_id": 33412, "employee_name": "Sample Employee A",

        "timeoff_type": "Annual Leave", "from_date": "2026-07-06", "to_date": "2026-07-10",

        "amount_days": 5, "status": 2 },

      { "id": 55102, "employee_id": 33413, "employee_name": "Sample Employee B",

        "timeoff_type": "Sick Leave", "from_date": "2026-07-08", "to_date": "2026-07-09",

        "amount_days": 2, "status": 2 } ],

    "date_range": { "from": "2026-07-06", "to": "2026-07-12" },

    "total_entries": 2, "truncated": false,

    "filters": { "status": "approved", "company_wide": true } } }

7. الأمان

• بياناتك تبقى ملكاُ لك: يرتبط كل طلب بحسابك الموثّق في ZenHR وبشركتك، ولا يمكن للبيانات الانتقال أو مشاركتها بين الشركات.

• صلاحية قراءة فقط: يعمل ZenHR Connector بصلاحيات القراءة فقط، ولا يمكنه تعديل البيانات أو إنشاؤها أو حذفها. وحتى إذا كانت لديك صلاحيات تعديل داخل ZenHR، فلن يتمكن هذا ZenHR Connector من استخدامها، إذ يقتصر وصوله على قراءة البيانات المصرح بها فقط.

• صلاحياتك هي المرجع: في كل طلب، يتحقق ZenHR Connector من صلاحيات الوصول الممنوحة لك داخل ZenHR، لذلك لن يتمكن Claude من الوصول إلى أي بيانات لا يمكنك الاطلاع عليها داخل النظام.

• حدود الاستخدام: لحماية الخدمة، يتم تطبيق حدود على عدد الطلبات لكل شركة، بواقع 100 طلب في الساعة و500 طلب يومي بشكل افتراضي.

• اتصال وتسجيل دخول آمنان: تتم جميع عمليات الاتصال عبر HTTPS باستخدام بروتوكول OAuth 2.1 مع PKCE، دون الحاجة إلى إدارة مفاتيح أو بيانات اعتماد طويلة الأمد.

• التفعيل على مستوى الشركة: يتم تفعيل ZenHR Connector لكل شركة بشكل مستقل، ولا يمكن الوصول إليه ما لم يكن مفعّلاً لحساب الشركة.

8. القيود وملاحظات مهمة

1. صلاحية قراءة فقط: لا يمكن لهذا الربط (ZenHR Connector) إنشاء البيانات أو تعديلها أو حذفها داخل ZenHR.

2. بيانات الموظفين: تعرض أداة list_employees بعض البيانات الشخصية افتراضياً. ويمكنك استخدام exclude_fields لاستبعاد الحقول التي لا تحتاج إليها.

3. ملخصات المعاملات المالية: عند الاستعلام عن نطاقات زمنية كبيرة، قد تكون النتائج جزئية. إذ تقرأ أداة summarize_financial_transactions ما يصل إلى حوالي 1,500 معاملة في الطلب الواحد، وعند تجاوز هذا الحد ستكون قيمة truncated مساوية لـ true. للحصول على نتائج كاملة، يُنصح بتقليص الفترة الزمنية أو استخدام عوامل تصفية إضافية.

4. تقارير الموارد البشرية: تعمل أداة get_hr_updates على مرحلتين، كما يقتصر عرض التفاصيل حسب الفروع على 30 فرع كحد أقصى.

5. تحليلات نطاقات: تتطلب أداة get_nitaqat_workforce تحديد النشاط الاقتصادي (economic_activity) وفقاً للأنشطة الواردة في الملحق رقم (1).

6. إجازات الفريق: تعرض أداة get_team_timeoff جميع الإجازات التي تتداخل مع الفترة الزمنية المحددة. ويقتصر عدد النتائج على 200 سجل عبر 50 فرع كحد أقصى، وعند تجاوز هذا الحد ستكون قيمة truncated مساوية لـ true. وتبحث الأداة في الفرع الحالي افتراضياً، أو في جميع الفروع عند استخدام company_wide: true.

7. الصلاحيات: تتم الموافقة على مجموعة صلاحيات القراءة فقط بالكامل عند ربط (ZenHR Connector) لأول مرة، بينما يحدد دورك وصلاحياتك داخل ZenHR البيانات التي يمكنك الاطلاع عليها فعلياً.

8. توفر الخدمة: يتم تفعيل الربط (ZenHR Connector) لكل شركة بشكل مستقل، وهو حالياً في مرحلة الإطلاق التدريجي، لذلك قد لا يكون متاح لجميع الشركات بعد.

9. استكشاف الأخطاء الشائعة

• لا يستطيع Claude الاتصال بـ ZenHR Connector، أو تظهر رسالة "Not Found" في جميع الطلبات:
  لم يتم تفعيل ZenHR Connector لشركتك بعد. تواصل مع مسؤول ZenHR في شركتك لتفعيله.

• يُطلب منك تسجيل الدخول باستمرار، أو تظهر رسالة "Unauthorized":
  أعد تسجيل الدخول ومنح الموافقات المطلوبة لصلاحيات القراءة فقط، فقد تكون جلستك قد انتهت صلاحيتها.

• تظهر رسالة "You are not authorized to do that":
  قد لا يمتلك دورك في ZenHR صلاحية الوصول إلى هذه البيانات، أو ربما تجاوزت الحد المسموح لعدد الطلبات (100 طلب في الساعة أو 500 طلب يومياً لكل شركة).

• تظهر رسالة "No branch available":
  تأكد من أن حسابك مرتبط بفرع، أو حدّد branch_id عند تنفيذ الطلب. ويمكنك استخدام أداة list_branches لمعرفة معرّفات الفروع.

• تطلب أداة get_nitaqat_workforce تحديد النشاط الاقتصادي باستمرار:
  يعد النشاط الاقتصادي (economic_activity) حقل إلزامي. ويمكنك استخدام أداة get_nitaqat_guideline لمعرفة الأنشطة المعتمدة الواردة في الملحق رقم (1).

• تعرض أداة get_hr_updates رسالة needs_selection أو needs_narrowing:
  تعمل هذه الأداة على مرحلتين. حدّد الخيارات المطلوبة ثم أعد تنفيذ الطلب. وإذا كان لديك صلاحية الوصول إلى أكثر من 30 فرعاً، فاختر فرع واحد للحصول على النتائج.

• تظهر بعض مؤشرات الموارد البشرية على أنها "Unavailable":
  يعني ذلك أن دورك في ZenHR لا يملك صلاحية الاطلاع على هذه المؤشرات.