# 🌟 CharityPro MCP Server

![License](https://img.shields.io/badge/license-MIT-blue.svg)
![Docker](https://img.shields.io/badge/docker-ready-brightgreen.svg)
![MCP](https://img.shields.io/badge/MCP-compatible-orange.svg)

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

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

---

## 👨‍💻 المطور / Developer

**أبو حمدي** ([Shadi1985](https://github.com/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: استنساخ المشروع

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

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

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

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

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

```bash
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`

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

```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 (لوحة الإدارة)
```

---

## 🐳 التطوير

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

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

# بناء TypeScript
npm run build

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

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

```bash
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](CONTRIBUTING.md) للمزيد من التفاصيل.

---

## 📜 الترخيص

MIT License - اقرأ [LICENSE](LICENSE) للتفاصيل.

---

## 🔗 روابط مفيدة

- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Claude Desktop MCP](https://docs.anthropic.com/claude/docs/model-context-protocol)
- [Supabase Documentation](https://supabase.com/docs)

---

## 📞 الدعم

- افتح [Issue](https://github.com/Shadi1985/charitypro-mcp-server/issues) للإبلاغ عن مشاكل
- راجع [SECURITY.md](SECURITY.md) للإبلاغ عن ثغرات أمنية

---

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

**المطور**: أبو حمدي ([Shadi1985](https://github.com/Shadi1985))