caldav-mcp: توصيل تقويمات CalDAV بمساعد الذكاء الاصطناعي

لمن هذا مناسب

• لمن يملك بالفعل حسابًا على خادم CalDAV (مستضاف ذاتيًا أو من مقدّم خدمة) ويريد أن يعاين مساعد الذكاء الاصطناعي التقويمات ويديرها مباشرة. التموضع الرسمي هو كشف عمليات التقويم بوصفها أدوات لمساعدي الذكاء الاصطناعي.
• العمليات المشمولة: الاتصال بخادم CalDAV، وسرد التقويمات، وسرد أحداث التقويم ضمن فترة زمنية، وإنشاء الأحداث، وتحديثها، وحذفها وفق المعرّف UID.
• شروط الاستخدام واضحة: يجب توفير عنوان خادم CalDAV واسم المستخدم وكلمة المرور عبر متغيرات البيئة الثلاثة CALDAV_BASE_URL وCALDAV_USERNAME وCALDAV_PASSWORD، وثلاثتها لا غنى عنها.
• غير مناسب لـ: من لا يملك خادم CalDAV، أو لا يرغب في تسليم بيانات حسابه إلى عملية محلية. الوثائق الرسمية لا تذكر أي تطبيقات خوادم CalDAV محددة يدعمها، ولا ما إن كان هناك وضع قراءة فقط؛ وكلا النقطتين غير مؤكَّد.

أول محاولة في 3 دقائق

المسار الرئيسي الموصى به: التشغيل عبر npx ضمن إعداد mcpServers في عميل MCP؛ حيث ينزّل npx حزمة caldav-mcp ويشغّلها تلقائيًا. أضف المقتطف التالي إلى الإعداد:

"command": "npx",
      "args": [
        "caldav-mcp"
      ],

وقدّم بيانات الاعتماد في الإعداد نفسه عبر متغيرات البيئة:

"CALDAV_BASE_URL": "<CalDAV server URL>",
        "CALDAV_USERNAME": "<CalDAV username>",
        "CALDAV_PASSWORD": "<CalDAV password>"

بعد الحفظ وإعادة تشغيل العميل، ابدأ بنداء قراءة: اطلب من مساعد الذكاء الاصطناعي «اسرد تقويماتي»، وهو ما يقابل List calendars في قائمة القدرات الرسمية. إشارة النجاح هي أن يعيد المساعد قائمة تقويمات ذلك الحساب. هذه الخطوة تقرأ بنية التقويم فقط ولا تنشئ أحداثًا أو تعدّلها، لكنها تتصل بخادم CalDAV ببيانات اعتمادك.

تنبيه ضروري: عمليات الإنشاء والتحديث والحذف في هذه الخدمة كلها كتابة عن بُعد تغيّر التقويم الفعلي مباشرة. قبل أي إجراء كتابة، اطلب من المساعد أن يعيد ذكر العملية المراد تنفيذها والحدث الهدف والحقول، ولا تنفّذ إلا بعد تأكيدك.

يوفر المشروع كذلك طريقة تشغيل موجّهة للتطوير: تشغيل شيفرة TypeScript مباشرة بوضع watch مع تحميل متغيرات البيئة تلقائيًا من .env؛ وهي مناسبة لتصحيح الشيفرة، بينما يبقى الاستخدام اليومي على المسار الرئيسي عبر npx أعلاه.

حالات الاستخدام

الحالة الأولى: التحقق من الاتصال والصلاحيات (List calendars). السيناريو: أعددت بيانات الاعتماد للتو ولست متأكدًا من صحة العنوان أو كلمة المرور. الطريقة: اطلب من المساعد «اسرد تقويماتي»، فهو أرخص إجراء قراءة للتحقق من بيانات الاعتماد. النتيجة المتوقعة: قائمة تقويمات حساب CalDAV ذاك؛ وإن فشل الطلب، فتحقق من قيم متغيرات البيئة الثلاثة ثم أعد المحاولة.

الحالة الثانية: تعديل الحقول المطلوبة فقط عبر update-event. السيناريو: تغيّر موعد اجتماع بينما يبقى العنوان والمكان وسائر البيانات كما هي. الطريقة: اجعل المساعد يحدد الحدث الهدف ثم ينادي update-event مع تمرير الحقول المطلوب تعديلها فقط؛ والوصف الرسمي هو: «يحدّث حدث تقويم موجود، ولا تتغير إلا الحقول الممرَّرة». النتيجة المتوقعة: لا تُحدَّث إلا الحقول التي مرّرتها ويبقى الباقي كما هو. نقطة التأكيد: هذا إجراء كتابة عن بُعد يسري مباشرة على خادم CalDAV، فتحقق حتمًا من الحدث الهدف والحقول المراد تغييرها قبل التنفيذ.

حدود الاستخدام

• طبيعة القراءة والكتابة: القدرات تجمع بين القراءة (سرد التقويمات وسرد الأحداث ضمن فترة) والكتابة (إنشاء وتحديث وحذف وفق UID)، والأدوات تعمل مباشرة على التقويم الفعلي. الحذف يتم وفق UID، والوثائق الرسمية لا تذكر ما إن كان المحذوف قابلًا للاستعادة ولا تتيح أي مسار للتراجع، فكن صارمًا بشكل خاص عند خطوة التأكيد.
• متطلبات بيانات الاعتماد: يجب تمرير عنوان الخادم واسم المستخدم وكلمة المرور عبر متغيرات البيئة؛ ولا تذكر الوثائق الرسمية ما إن كانت تدعم مصادقات بديلة مثل OAuth أو كلمات مرور التطبيقات؛ غير مؤكَّد.
• الأثار الجانبية ونقاط التأكيد: عمليات الكتابة تعدّل تقويم الخادم فعليًا؛ وupdate-event يغيّر الحقول الممرَّرة فقط، أما الحقول غير المذكورة فلا تتأثر.
• أمور أخرى غير مؤكَّدة: قائمة برمجيات خوادم CalDAV المدعومة، وحدود المعدل أو التزامن، كلها بلا ذكر رسمي. «لا ذكر» يعكس نطاق الوثائق فقط ولا يشكل أي استنتاج أمني.