<div align="center">

# 📝 Joplin MCP Server

**Connect Joplin notes to AI — Claude Desktop, opencode, Cursor, VS Code Copilot**

اربط ملاحظات Joplin بالذكاء الاصطناعي عبر Model Context Protocol

![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white)
![License](https://img.shields.io/badge/License-MIT-blue.svg)
![MCP](https://img.shields.io/badge/MCP-Server-000000?logo=modelcontextprotocol)
![Joplin](https://img.shields.io/badge/Joplin-REST%20API-107C10)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)

</div>

---

## 🚀 ما هو هذا المشروع / What is this project

**Joplin MCP Server** هو خادم [Model Context Protocol (MCP)](https://modelcontextprotocol.io) يربط أدوات الذكاء الاصطناعي بملاحظاتك في **Joplin** عبر **REST API المحلي** (المنفذ 41184).

An **MCP server** that gives AI assistants direct, read/write access to your **Joplin notes** through Joplin's local REST API — no cloud, no sync, everything stays on your machine.

> ✅ **20 أداة جاهزة** | **يعمل محلياً 100%** | **يدعم العربية و UTF-8** | **سطر واحد للتشغيل**

### ✨ المزايا / Features

- 🔌 **تكامل مع كل عملاء MCP**: Claude Desktop, opencode, Cursor, VS Code Copilot
- 📂 **إدارة كاملة**: قراءة، إنشاء، تعديل، حذف، نقل الملاحظات والمجلدات
- 🔍 **بحث نصي كامل** عبر `/search`
- ✅ **دعم المهام (Todos)** مع فلترة حسب الحالة
- 🏷️ **دعم الوسوم (Tags)**
- ⚡ **عمليات جماعية (Bulk)**: نقل/حذف/وسم دفعة واحدة
- 🛡️ **أمان**: التوكن من متغير بيئة فقط، لا يُكتب في الكود
- 🌍 **UTF-8 كامل** — يعمل بسلاسة مع العربية وكل اللغات

---

## 📦 المتطلبات المسبقة / Prerequisites

| المطلوب | الوصف / Description |
|---|---|
| **Joplin** | تطبيق سطح المكتب مفتوح (Desktop app running) |
| **Web Clipper** | مفعّل من داخل Joplin (Enabled) |
| **Authorization Token** | 96 حرف hex — من Joplin → Tools → Options → Web Clipper → Advanced options |
| **Python 3.10+** | مع `pip` |

**تفعيل Web Clipper:**
1. افتح Joplin → **Tools → Options → Web Clipper**
2. فعّل **Enable Web Clipper Service**
3. تأكد أن المنفذ **41184** ظاهر في الإعدادات
4. انسخ **Authorization token** من Advanced options

---

## 🛠️ التركيب خطوة بخطوة / Installation

### 1️⃣ اجلب المشروع
```bash
git clone https://github.com/<your-username>/joplin-mcp-server.git
cd joplin-mcp-server
```

### 2️⃣ ثبّت المتطلبات
```bash
pip install -r requirements.txt
```

### 3️⃣ اضبط متغيرات البيئة
```bash
cp .env.example .env          # ثم حرّر الملف وضع توكنك
# أو مباشرة في البيئة:
export JOPLIN_TOKEN="YOUR_TOKEN_HERE"        # Linux / macOS
$env:JOPLIN_TOKEN = "YOUR_TOKEN_HERE"        # Windows PowerShell
```

| المتغير | إلزامي | الوصف |
|---|---|---|
| `JOPLIN_TOKEN` | ✅ نعم | توكن Web Clipper (96 حرف hex) |
| `JOPLIN_URL` | ❌ اختياري | عنوان API — الافتراضي `http://127.0.0.1:41184` |

### 4️⃣ أضف السيرفر إلى عميلك / Configure your AI client

#### 🤖 Claude Desktop — `claude_desktop_config.json`
```json
{
  "mcpServers": {
    "joplin": {
      "command": "python",
      "args": ["-m", "joplin_server"],
      "env": { "JOPLIN_TOKEN": "YOUR_TOKEN_HERE" }
    }
  }
}
```

#### ⚡ opencode — `opencode.json` (قسم `mcp`)
```json
{
  "mcp": {
    "joplin": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "joplin_server"],
      "env": { "JOPLIN_TOKEN": "YOUR_TOKEN_HERE" }
    }
  }
}
```

#### 🧩 VS Code Copilot — `.vscode/mcp.json`
```json
{
  "servers": {
    "joplin": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "joplin_server"],
      "env": { "JOPLIN_TOKEN": "YOUR_TOKEN_HERE" }
    }
  }
}
```

> 💡 قد تحتاج إلى المسار الكامل لـ `python` (مثل `C:/Python310/python.exe`) حسب إعدادات PATH. أعد تشغيل العميل بعد التعديل.

---

## 🔬 اختبار السيرفر / Testing

**1. اختبار Joplin مباشرة (تأكد أن Web Clipper يعمل):**
```bash
curl "http://127.0.0.1:41184/ping?token=YOUR_TOKEN_HERE"
# المتوقع: JoplinClipperServer
```

**2. فحص المنفذ:**
```powershell
Test-NetConnection 127.0.0.1 -Port 41184
```

**3. تشغيل السيرفر:**
```bash
python -m joplin_server
```

ثم اطلب من مساعد الذكاء الاصطناعي استدعاء أداة **`joplin_ping`** — إذا أعادت `JoplinClipperServer` فكل شيء يعمل.

---

## 🛠️ الأدوات المتاحة / Available Tools (20)

| الأداة | الوصف | المدخلات |
|---|---|---|
| `joplin_ping` | فحص اتصال Joplin | — |
| `joplin_list_folders` | قائمة المجلدات (الدفاتر) | — |
| `joplin_get_folder` | تفاصيل مجلد واحد | `folder_id` |
| `joplin_create_folder` | إنشاء مجلد جديد | `title` |
| `joplin_list_notes` | ملاحظات مجلد | `folder_id`, `limit` |
| `joplin_get_note` | قراءة ملاحظة كاملة | `note_id` |
| `joplin_create_note` | إنشاء ملاحظة | `title`, `body`, `parent_id` |
| `joplin_update_note` | تحديث جزئي | `note_id`, `title`/`body`/`parent_id` |
| `joplin_delete_note` | حذف ملاحظة | `note_id` |
| `joplin_search_notes` | بحث نصي كامل | `query`, `limit` |
| `joplin_list_todos` | قائمة المهام | `limit`, `completed` |
| `joplin_toggle_todo` | تبديل حالة مهمة | `note_id`, `completed` |
| `joplin_list_tags` | قائمة الوسوم | `limit` |
| `joplin_get_tag` | تفاصيل وسم | `tag_id` |
| `joplin_add_tag_to_note` | ربط وسم بملاحظة | `tag_id`, `note_id` |
| `joplin_remove_tag_from_note` | فك ربط وسم | `tag_id`, `note_id` |
| `joplin_bulk_move_notes` | نقل ملاحظات متعددة | `note_ids`, `target_folder_id` |
| `joplin_bulk_delete_notes` | حذف ملاحظات متعددة | `note_ids` |
| `joplin_bulk_add_tag` | وسم ملاحظات متعددة | `note_ids`, `tag_id` |
| `joplin_bulk_remove_tag` | فك وسم متعدد | `note_ids`, `tag_id` |

كل أداة تعيد JSON منسّقاً: `{"success": true, "id": "...", "data": {...}}`

---

## 🧑‍💻 أمثلة استخدام / Usage Examples

**"اعرض لي مجلداتي"** → `joplin_list_folders()`

**"ابحث عن ملاحظات فيها 'خطة العمل'"** → `joplin_search_notes(query="خطة العمل")`

**"أنشئ ملاحظة عن ميزات المشروع في مجلد العمل"** → `joplin_create_note(title="ميزات", body="...", parent_id="<folder_id>")`

**"ما المهام غير المكتملة؟"** → `joplin_list_todos(completed=false)`

---

## 🧯 استكشاف الأخطاء / Troubleshooting

| المشكلة | الحل |
|---|---|
| `Not connected` | تأكد أن Joplin مفتوح و Web Clipper مفعّل |
| `401 / 403` | التوكن خاطئ — أعد نسخه من Advanced options |
| المنفذ `41184` مغلق | `Test-NetConnection 127.0.0.1 -Port 41184` أو `curl .../ping` |
| العربية تظهر `؟` | مشكلة عرض فقط — البيانات مخزّنة صحيحة (UTF-8) |
| `JOPLIN_TOKEN is not set` | اضبط المتغير في البيئة أو `.env` قبل التشغيل |

---

## 🔐 ملاحظة أمان / Security

- ⚠️ **لا تشارك توكنك أبداً** ولا تضعه في الكود أو README
- استخدم متغير بيئة أو ملف `.env` فقط (وهو مستثنى في `.gitignore`)
- كل الاتصال محلي على `127.0.0.1` — لا يُرسل أي شيء إلى الإنترنت

---

## 🤝 المساهمة في التطوير / Contributing

المساهمات مرحّب بها! اقرأ [CONTRIBUTING.md](CONTRIBUTING.md) للتفاصيل كاملة.

**افكار للمساهمة:**
- إضافة أدوات جديدة (المرفقات، الملاحظات المشتركة، التقويم)
- موارد (Resources) و Prompts ضمن MCP
- اختبارات آلية (pytest)
- تحسين التوثيق أو الترجمة

---

## 📁 هيكل الملفات / Project Structure

```
joplin-mcp-server/
├── __main__.py          # نقطة تشغيل `python -m joplin_server`
├── joplin_server.py     # أدوات MCP (FastMCP) — 20 أداة
├── joplin_client.py     # طبقة REST API — مستقلة عن MCP
├── requirements.txt     # mcp + requests
├── CONTRIBUTING.md      # دليل المساهمة
├── LICENSE              # MIT
├── .gitignore
├── .env.example
└── README.md
```

---

## 📄 الترخيص / License

[MIT](LICENSE) © Joplin MCP Server