# customer-replies-mcp-server

خادم MCP لإدارة وتوليد ردود العملاء لمحل صيانة الهواتف النقالة وأجهزة الكمبيوتر. يعمل مع Claude Desktop و Claude Code وأي عميل MCP آخر.

MCP server for managing and composing customer replies for a phone & computer repair shop. Arabic-first with English variants.

## الأدوات | Tools

| Tool | الوظيفة |
|---|---|
| `replies_list_categories` | عرض تصنيفات الردود وعدد القوالب في كل تصنيف |
| `replies_search_templates` | البحث في القوالب بالكلمة، التصنيف، اللغة، أو النبرة |
| `replies_get_template` | جلب قالب كامل مع المتغيرات `{{variable}}` |
| `replies_compose_reply` | تعبئة قالب بقيم حقيقية وإرجاع رد جاهز للإرسال |
| `replies_whatsapp_link` | تحويل رد (من قالب أو نص حر) إلى رابط `wa.me` جاهز للفتح والإرسال يدوياً على واتساب |
| `replies_add_template` | إضافة قالب جديد (المتغيرات تُستخرج تلقائياً من النص) |
| `replies_update_template` | تعديل قالب موجود |
| `replies_delete_template` | حذف قالب نهائياً |

## التصنيفات | Categories

greeting, price_inquiry, diagnosis, repair_status, ready_for_pickup, delay_apology, warranty, complaint, unrepairable, data_disclaimer, part_unavailable, location_hours, payment, follow_up

17 قالباً جاهزاً مضمّناً (عربي + إنجليزي) تغطي: الترحيب، التسعير، نتيجة الفحص، تحديث الحالة، جاهزية الاستلام، الاعتذار عن التأخير، الضمان، الشكاوى، تعذر الإصلاح، إخلاء مسؤولية البيانات، قطع الغيار، الموقع والأوقات، الدفع، والمتابعة بعد التسليم.

## التثبيت | Install

```bash
npm install
npm run build
```

## التشغيل مع Claude Desktop / Claude Code

`claude_desktop_config.json` أو `.mcp.json`:

```json
{
  "mcpServers": {
    "customer-replies": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/customer-replies-mcp-server/dist/index.js"],
      "env": {
        "REPLIES_DATA_PATH": "/ABSOLUTE/PATH/data/templates.json"
      }
    }
  }
}
```

Claude Code:

```bash
claude mcp add customer-replies -- node /ABSOLUTE/PATH/customer-replies-mcp-server/dist/index.js
```

## تخزين البيانات | Data storage

القوالب تُحفظ في ملف JSON. المسار الافتراضي: `~/.customer-replies/templates.json`. يُغيّر عبر متغير البيئة `REPLIES_DATA_PATH`. عند أول تشغيل يُنشأ الملف بالقوالب المضمّنة تلقائياً.

## مثال استخدام | Usage example

Prompt: "اكتب رد لأحمد، جهازه iPhone 13، الحالة بانتظار قطعة الشاشة، التسليم غداً 5 مساءً"

Flow:
1. `replies_search_templates` → `category: repair_status, language: ar`
2. `replies_compose_reply` → `template_id: status-ar-1` + variables

Output:

```
مرحباً أحمد 👋
تحديث بخصوص جهازك iPhone 13:
الحالة الحالية: بانتظار قطعة الشاشة
الموعد المتوقع للتسليم: غداً 5 مساءً
سنبلغك فور جاهزية الجهاز.
```

## الربط بواتساب | WhatsApp link

`replies_whatsapp_link` يبني رابط `https://wa.me/<phone>?text=<message>` من قالب (template_id + variables) أو نص حر (text). العربية مدعومة بالكامل عبر ترميز UTF-8 القياسي في الرابط. فتح الرابط يفتح واتساب مع الرسالة معبّأة مسبقاً، لكن **الإرسال يبقى ضغطة يدوية** — لا إرسال تلقائي.

مثال: `phone: "+966 5x xxx xxxx"`, `template_id: "status-ar-1"`, `variables: {...}` → `{ url, text, missingVariables }`.

## واجهة الويب المحلية | Local web UI

صفحة ويب محلية بالعربية (RTL) لتصفح القوالب وتعبئتها وإرسالها عبر واتساب دون الحاجة لـ Claude أو Inspector — مخصصة لموظف المحل مباشرة.

```bash
npm run build
npm run web
```

ثم افتح `http://localhost:8787` (يمكن تغيير المنفذ عبر `PORT`). التدفق: اختر تصنيفاً من الشريط الجانبي أو ابحث ← اضغط على القالب ← عبّئ المتغيرات وشاهد المعاينة الحيّة ← أدخل رقم العميل ← اضغط **فتح واتساب** لفتح محادثة واتساب مع الرسالة جاهزة (الإرسال يبقى ضغطة يدوية بشرية).

الواجهة متجاوبة مع الجوال (RTL أيضاً على الشاشات الصغيرة).

### تسجيل الدخول

الواجهة محمية بـ HTTP Basic Auth. اسم المستخدم الافتراضي `admin`. إن لم تُحدَّد `WEB_PASSWORD`، تُولَّد كلمة مرور عشوائية وتُطبع في الطرفية عند بدء التشغيل — راقب الناتج. لتحديد بيانات دخول ثابتة:

```bash
WEB_USERNAME=shop WEB_PASSWORD=your-secret npm run web
```

### النسخ الاحتياطي

قبل كل عملية حفظ (إضافة/تعديل/حذف قالب)، يُنسخ الملف الحالي إلى `<REPLIES_DATA_PATH>.bak` قبل الكتابة فوقه. للاستعادة من نسخة احتياطية، أعد تسمية `.bak` إلى الاسم الأصلي يدوياً.

## صيغة المتغيرات | Placeholder syntax

`{{variable_name}}` — أحرف لاتينية وأرقام وشرطة سفلية. `replies_compose_reply` يعيد `missingVariables` لأي متغير لم تُمرَّر قيمته، ويُبقي العنصر النائب في النص كما هو.

## الاختبار | Testing

```bash
npx @modelcontextprotocol/inspector node dist/index.js
```