🌟 CharityPro MCP Server

CharityPro MCP Server - خادم MCP للاستعلام عن مشاريع المؤسسات الخيرية من لوحة إدارة المشاريع

يتيح هذا المشروع للمؤسسات الخيرية الاستعلام عن بيانات مشاريعها وتحليلها باستخدام Claude Desktop عبر بروتوكول Model Context Protocol (MCP).

---

👨‍💻 المطور / Developer

أبو حمدي (Shadi1985)

---

✨ المميزات

• 🔍 استعلام ذكي: استعلام عن المشاريع والإحصائيات بلغة طبيعية
• 🏢 دعم متعدد المؤسسات: كل مؤسسة ترى بياناتها فقط
• 🔒 آمن ومحمي: Row Level Security على مستوى قاعدة البيانات
• 🐳 Docker Ready: جاهز للتشغيل مع Claude Desktop
• 🌍 دعم كامل للعربية: واجهة ورسائل بالعربية
• 📊 تحليلات متقدمة: إحصائيات وتقارير أداء الفرق

---

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

هذا السيرفر مخصص للاستعلام والتحليل فقط (Read-Only) من لوحة إدارة المشاريع:

• ✅ الاستعلام عن قوائم المشاريع
• ✅ تفاصيل مشروع معين
• ✅ إحصائيات المؤسسة
• ✅ تحليل أداء الفرق
• ✅ المشاريع المتأخرة
• ✅ معلومات المؤسسة

ملاحظة: لإضافة أو تعديل المشاريع، استخدم لوحة الإدارة الرئيسية للمؤسسة.

---

🛠️ الأدوات المتاحة (7 أدوات)

1. authenticate_user - تسجيل الدخول

التعرف على المستخدم والمؤسسة التابع لها

2. get_my_organization - معلومات المؤسسة

الحصول على معلومات المؤسسة الحالية

3. list_projects - قائمة المشاريع

استعراض المشاريع مع إمكانية الفلترة حسب الحالة

4. get_project - تفاصيل مشروع

الحصول على تفاصيل كاملة لمشروع محدد

5. get_organization_stats - إحصائيات المؤسسة

إحصائيات شاملة عن المشاريع والميزانيات

6. analyze_team_performance - تحليل أداء الفريق

تحليل أداء فريق معين في المؤسسة

7. get_overdue_projects - المشاريع المتأخرة

الحصول على قائمة المشاريع المتأخرة عن موعدها

---

📥 التثبيت والإعداد

المتطلبات

• Docker Desktop
• Claude Desktop
• لوحة إدارة مشاريع CharityPro

الخطوة 1: استنساخ المشروع

git clone https://github.com/Shadi1985/charitypro-mcp-server.git
cd charitypro-mcp-server

الخطوة 2: إعداد البيئة

# انسخ ملف المثال
cp .env.example .env

# حرر الملف وأضف بياناتك من Supabase
# SUPABASE_URL=https://your-project.supabase.co
# SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

الخطوة 3: بناء Docker Image

docker build -t charitypro-mcp:latest .

الخطوة 4: إعداد Claude Desktop

افتح ملف الإعداد:

• Windows: C:\Users\YOUR_USERNAME\AppData\Roaming\Claude\claude_desktop_config.json
• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

أضف هذا الإعداد (استبدل البيانات ببياناتك):

{
  "mcpServers": {
    "charitypro": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "SUPABASE_URL=YOUR_SUPABASE_URL",
        "-e",
        "SUPABASE_SERVICE_ROLE_KEY=YOUR_SERVICE_ROLE_KEY",
        "charitypro-mcp:latest"
      ]
    }
  }
}

الخطوة 5: إعادة تشغيل Claude Desktop

أغلق Claude Desktop تماماً وأعد فتحه.

---

💬 أمثلة الاستخدام

التسجيل والاستعلام:

سجل دخولي: ahmad@charity1.org
أعطني قائمة المشاريع النشطة
ما هي تفاصيل المشروع رقم 123؟

التحليل والإحصائيات:

أعطني إحصائيات مؤسستي
حلل أداء فريق التوزيع
ما هي المشاريع المتأخرة؟

---

🏗️ البنية المعمارية

Claude Desktop
    ↓ (stdio)
Docker Container (charitypro-mcp:latest)
    ↓ (HTTPS)
Supabase PostgreSQL
    ↓
CharityPro Database (لوحة الإدارة)

---

🐳 التطوير

البناء من المصدر

# تثبيت المكتبات
npm install

# بناء TypeScript
npm run build

# بناء Docker image
docker build -t charitypro-mcp:latest .

الاختبار المحلي

docker run -i --rm \
  -e SUPABASE_URL="YOUR_URL" \
  -e SUPABASE_SERVICE_ROLE_KEY="YOUR_KEY" \
  charitypro-mcp:latest

---

🔒 الأمان

• ✅ البيانات الحساسة في متغيرات البيئة فقط
• ✅ Row Level Security في Supabase
• ✅ لا توجد منافذ مكشوفة
• ✅ صلاحيات قراءة فقط (Read-Only)

---

🔧 حل المشاكل

Claude Desktop لا يرى السيرفر

1. تأكد من تشغيل Docker: docker ps
2. تأكد من وجود الصورة: docker images | grep charitypro
3. أعد تشغيل Claude Desktop تماماً

أخطاء الاتصال بقاعدة البيانات

• تحقق من صحة SUPABASE_URL
• تحقق من صحة SUPABASE_SERVICE_ROLE_KEY
• تأكد من أن مشروع Supabase نشط
• تأكد من إعداد قاعدة البيانات بشكل صحيح

---

🤝 المساهمة

نرحب بجميع المساهمات! اقرأ CONTRIBUTING.md للمزيد من التفاصيل.

---

📜 الترخيص

MIT License - اقرأ LICENSE للتفاصيل.

---

🔗 روابط مفيدة

• Model Context Protocol
• Claude Desktop MCP
• Supabase Documentation

---

📞 الدعم

• افتح Issue للإبلاغ عن مشاكل
• راجع SECURITY.md للإبلاغ عن ثغرات أمنية

---

صُنع بـ ❤️ لخدمة المؤسسات الخيرية

المطور: أبو حمدي (Shadi1985)