<div align="center">

📝 Joplin MCP Server

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

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

</div>

---

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

Joplin MCP Server هو خادم Model Context Protocol (MCP) يربط أدوات الذكاء الاصطناعي بملاحظاتك في 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️⃣ اجلب المشروع

git clone https://github.com/<your-username>/joplin-mcp-server.git
cd joplin-mcp-server

2️⃣ ثبّت المتطلبات

pip install -r requirements.txt

3️⃣ اضبط متغيرات البيئة

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

{
  "mcpServers": {
    "joplin": {
      "command": "python",
      "args": ["-m", "joplin_server"],
      "env": { "JOPLIN_TOKEN": "YOUR_TOKEN_HERE" }
    }
  }
}

⚡ opencode — opencode.json (قسم mcp)

{
  "mcp": {
    "joplin": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "joplin_server"],
      "env": { "JOPLIN_TOKEN": "YOUR_TOKEN_HERE" }
    }
  }
}

🧩 VS Code Copilot — .vscode/mcp.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 يعمل):

curl "http://127.0.0.1:41184/ping?token=YOUR_TOKEN_HERE"
# المتوقع: JoplinClipperServer

2. فحص المنفذ:

Test-NetConnection 127.0.0.1 -Port 41184

3. تشغيل السيرفر:

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 للتفاصيل كاملة.

افكار للمساهمة:

• إضافة أدوات جديدة (المرفقات، الملاحظات المشتركة، التقويم)
• موارد (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 © Joplin MCP Server