الاتصالات
الاتصال عبر MCP
اتصل من Claude Desktop أو Claude Code أو Cursor أو Codex أو أي عميل MCP آخر بأدوات المشاريع المحلية في Oleafly.
يمكن لـ Oleafly أن يعمل كخادم MCP (Model Context Protocol). يستطيع عملاء MCP مثل Claude Desktop وClaude Code وCursor وCodex وGrok CLI قراءة مشاريع Oleafly وتعديلها والبحث فيها وتجميعها. لا تحتاج إلى مفتاح مزود ذكاء اصطناعي في Oleafly لأن العميل هو الذي يوفر النموذج.
هذا هو الخيار المناسب عندما يكون لديك بالفعل اشتراك في Claude (أو ما شابه) وتريد أن يقود تطبيق المحادثة هذا Oleafly، دون لصق مفتاح API في Settings.
تفعيل الخادم
قسم بعنوان “تفعيل الخادم”- افتح Settings → Integrations → Oleafly MCP.
- شغّل مفتاح التبديل Enable MCP server.
يعمل الخادم فقط أثناء بقاء عملية Oleafly مفتوحة. يستمع على 127.0.0.1 فقط، ولا يستمع على شبكتك المحلية أبدًا. إغلاق نافذة المشروع لا يوقف الخادم؛ أما إيقاف تشغيل MCP أو إنهاء Oleafly فيوقفه.
يفضّل Oleafly المنفذ 5323 (http://127.0.0.1:5323/mcp). وإذا لم يكن متاحًا، يرتبط الخادم تلقائيًا بمنفذ محلي حر آخر ويحفظه للإطلاق التالي. تعرض Settings عنوان URL النشط. ويعيد زر إعادة التشغيل فيها استخدام المنفذ الحالي متى أمكن أو يختار منفذًا حرًا آخر.
اتصال عميلك
قسم بعنوان “اتصال عميلك”تعرض Settings مقتطفات جاهزة للنسخ واللصق للعملاء الشائعين. انسخ عنوان URL الفعلي لأن المنفذ المختار قد يختلف عن 5323، ثم استبدل <token> برمز الحامل من Settings (Reveal / Copy).
Claude Code
قسم بعنوان “Claude Code”claude mcp add --transport http oleafly http://127.0.0.1:5323/mcp --header "Authorization: Bearer <token>"Claude Desktop
قسم بعنوان “Claude Desktop”أضف إلى claude_desktop_config.json (جسر stdio عبر mcp-remote، لأن Desktop يفضّل stdio):
{ "mcpServers": { "oleafly": { "command": "npx", "args": [ "-y", "mcp-remote@latest", "http://127.0.0.1:5323/mcp", "--header", "Authorization: Bearer <token>", "--transport", "http-only" ] } }}إضافة Claude Desktop
قسم بعنوان “إضافة Claude Desktop”يتضمن كل إصدار الملف oleafly.mcpb، وهو إضافة لتطبيق Claude Desktop، فلا تحتاج إلى ملف الإعدادات ولا إلى الرمز المميز. نزّله من أحدث إصدار (يفتح في علامة تبويب جديدة) وافتحه باستخدام Claude Desktop لتثبيته.
تشغّل الإضافة الأمر oleafly المرفق مع التطبيق وتعمل على المشروع المفتوح في Oleafly، لذا أبقِ Oleafly قيد التشغيل مع تفعيل خادم MCP. إذا لم يجد Claude Desktop الأمر، فاختره من إعدادات الإضافة: oleafly-cli داخل Oleafly.app/Contents/MacOS على macOS، أو oleafly-cli.exe في %LOCALAPPDATA%\Oleafly على Windows.
يُدرج سجل MCP الإضافة نفسها باسم io.github.Oleafly/oleafly.
Cursor / VS Code
قسم بعنوان “Cursor / VS Code”في .cursor/mcp.json (أو إعدادات MCP لعميلك):
{ "mcpServers": { "oleafly": { "url": "http://127.0.0.1:5323/mcp", "headers": { "Authorization": "Bearer <token>" } } }}Grok CLI
قسم بعنوان “Grok CLI”في ~/.grok/config.toml:
[mcp_servers.oleafly]url = "http://127.0.0.1:5323/mcp"headers = { Authorization = "Bearer <token>" }Codex CLI
قسم بعنوان “Codex CLI”استخدم مقتطف Codex CLI في إعدادات Oleafly، فهو يوفر جسر stdio إلى الخادم قيد التشغيل. أضف المدخل إلى إعدادات Codex لديك واستخدم عنوان URL والرمز الفعليين اللذين يعرضهما Oleafly:
[mcp_servers.oleafly]command = "npx"args = [ "-y", "mcp-remote@latest", "http://127.0.0.1:5323/mcp", "--header", "Authorization: Bearer <token>", "--transport", "http-only"]يتطلب الجسر Node.js وnpx. أعد تشغيل العميل أو أعد الاتصال به بعد تغيير إعداداته.
يحمل ملف mcp.json الموجود بجوار بيانات Oleafly (الموضحة في Settings) عنوان URL والرمز نفسيهما إذا فضّلت إتمام الإعداد برمجيًا. ولا يُكتب هذا الملف إلا أثناء تشغيل الخادم (بالوضع 0600 على Unix) ويُحذف عند توقفه. تعامل معه كما تتعامل مع أي سر محلي آخر.
ماذا تستطيع الأدوات فعله
قسم بعنوان “ماذا تستطيع الأدوات فعله”تشترك معظم أدوات MCP في أسمائها ومخططاتها مع المساعد المدمج في التطبيق. وتوفر الواجهة الخلفية لسطح المكتب أدوات اكتشاف المشاريع وتوجيهها.
تستهدف الأدوات المشروع المفتوح في التطبيق عند توفر مشروع. ومع نافذة متصلة، استخدم list_projects وopen_project لاختيار مشروع آخر.
بعد إغلاق النافذة الأخيرة، تُبقي الواجهة الخلفية الأدوات read_file وlist_files وsearch_project متاحة. وتبقى عمليات الكتابة الأصلية والاستبدال والإنشاء وإعادة التسمية متاحة أيضًا عندما تسمح سياسة الاعتماد بذلك. لا تستخدم هذه الأدوات إلا آخر مشروع أبلغ عنه التطبيق، وترفض الاستدعاء إذا لم يعد ذلك المشروع صالحًا. وهي لا تخمّن أبدًا من مشاريع أخرى في المكتبة. أما الحالة واختيار المشروع والحذف والتجميع والسجلات وفحص PDF وتغيير السمة وأدوات الأشكال فتتطلب نافذة متصلة.
التعرّف على المشاريع
قسم بعنوان “التعرّف على المشاريع”| الأداة | ما تفعله |
|---|---|
get_status | إصدار Oleafly، والمشروع المفتوح، ومحرك مستنداته، ومستنده الرئيسي، وآخر حالة تجميع، وسبب فشل آخر تجميع أو تعذّر تشغيله |
list_projects | المشاريع بمعرّفاتها وأسمائها ومحركاتها وأنواعها ومستنداتها الرئيسية وطوابعها الزمنية وألوانها وحالة معاينتها وسجل تصديرها |
open_project | فتح مشروع بمعرّفه لتستهدفه الأدوات الأخرى |
list_files | شجرة ملفات المشروع |
project_map | المخطط التفصيلي، والتسميات، والاستشهادات، ووحدات الماكرو، ومخطط المدخلات، والمراجع غير المحلولة |
search_project | البحث عن نص في المشروع الحالي |
القراءة
قسم بعنوان “القراءة”| الأداة | ما تفعله |
|---|---|
read_file | قراءة ملف من المشروع |
get_log | آخر سجل تجميع |
get_pdf_text | النص المستخرج من ملف PDF المجمّع |
verify_pdf_pages | فحص صفحات PDF المصيَّرة بحثًا عن مشكلات التخطيط، من صور الصفحات أو من نصها |
تقرأ get_pdf_text وverify_pdf_pages آخر ملف PDF لدى Oleafly. وحين فشل آخر تجميع أو تعذّر تشغيله، تقول نتيجتهما إن ملف PDF قديم وتذكر السبب، لأنه من تجميع سابق أو ملف جزئي من التجميع الفاشل. وتقول get_log الشيء نفسه حين تعذّر تشغيل آخر تجميع، لأن سجلها حينئذ من تجميع سابق.
التحرير
قسم بعنوان “التحرير”| الأداة | ما تفعله |
|---|---|
write_file | كتابة ملف أو الكتابة فوقه |
replace_in_file | البحث والاستبدال داخل ملف |
create_file | إنشاء ملف أو مجلد |
rename_file | إعادة تسمية مسار أو نقله |
delete_file | حذف ملف أو مجلد |
set_main_doc | تعيين مستند الإدخال للتجميع |
التجميع والأشكال
قسم بعنوان “التجميع والأشكال”| الأداة | ما تفعله |
|---|---|
compile | تجميع المشروع إلى PDF |
preview_figure | تصيير شكل على حدة وإرجاع صورة PNG |
insert_figure | إدراج آخر شكل عُاين في المستند |
load_image | تحميل صورة من المشروع لأعمال الأشكال |
تقول compile ما إذا نجح البناء، وتسرد أخطاءه، وتقول ما إذا كان هناك ملف PDF، وتنتهي بالجزء الأخير من السجل. والبناء الذي انتهى يبلّغ أيضًا بتحذيراته. وحين يتعذر تشغيل البناء، أو لا ينتهي، أو يحتاج إلى شيء خارج المصدر، مثل تثبيت TeX أو إصدار Typst غير موجود، تعطي النتيجة السبب وتسمّي الإصلاح الذي يعرضه Oleafly عليك في التطبيق. وتطلب الأداة من العميل أن يخبرك وأن يترك مصدرك وشأنه. والتجميع الذي أوقفته يُعلَّم بأنه أُوقف، فلا يعامله العميل كخطأ في الشيفرة. ويحصل مساعد Oleafly نفسه على النتيجة نفسها.
استدعِ get_status أولًا لتعرف ما إذا كان المشروع LaTeX أم Typst أم Markdown، ثم اكتب المصدر بتلك الصيغة. تعمل preview_figure وinsert_figure في مشاريع LaTeX وTypst:
- في LaTeX، يكون الشكل كود TikZ يُجمَّع في مستند مستقل صغير، ويلفّه
insert_figureداخل بيئةfigure. - في Typst، يكون الشكل ترميز Typst، مثل لوحة CeTZ أو مخطط fletcher، ويُصيَّر بإصدار Typst الخاص بالمشروع. يلفّه
insert_figureداخل#figure، ويضع التسمية بعده، وينقل أسطر#importالخاصة به إلى ما فوقه. - في مشروع Markdown، ترجع الأداتان خطأ ولا تغيّران شيئًا.
تعمل load_image في كل المشاريع.
التطبيق
قسم بعنوان “التطبيق”| الأداة | ما تفعله |
|---|---|
toggle_theme | التبديل بين الوضع الفاتح / الداكن |
المهارات
قسم بعنوان “المهارات”| الأداة | ما تفعله |
|---|---|
list_skills | سرد المهارات المثبتة مع معرّفها واسمها ووصفها وهل هي مفعّلة |
load_skill | تحميل تعليمات مهارة واحدة كاملة وقائمة ملفاتها |
read_skill_file | قراءة مرجع أو نص برمجي من مجلد مهارة |
تعمل أدوات المهارات فور الاتصال مباشرة، دون مشروع مفتوح ودون نافذة Oleafly. يرى العميل كل مهارة صالحة، بما فيها المهارات المطفاة في Settings: فمفاتيح التبديل تقرر أي المهارات يستخدمها مساعد Oleafly نفسه، لا ما يستطيع العميل قراءته. أما الوكلاء الذين يقرؤون المهارات من مجلد بدلًا من ذلك فيمكنهم استخدام Share skills with other agents on this computer في Settings → AI Assistant → Skills. راجع المهارات.
الملاحظات
قسم بعنوان “الملاحظات”هذه الأدوات متاحة ما دام Notes مفعّلًا في Settings → Experimentation، كما يصف تفعيل الملاحظات. وهي تعمل على ملاحظاتك لا على المشروع المفتوح، وتحتاج إلى نافذة متصلة.
| الأداة | ما تفعله |
|---|---|
list_knowledge_notes | سرد ملاحظاتك، الأحدث أولًا، مع المعرّفات والعناوين والوسوم والمشاريع المرتبطة وملخصات قصيرة. رشّح بالوسم أو بالمشروع |
search_notes | البحث في ملاحظاتك وإرجاع المعرّفات والعناوين والوسوم والروابط والمقتطفات المطابقة |
read_note_by_id | قراءة ملاحظة بصيغة Markdown مع واجهتها الأمامية |
today_note | قراءة ملاحظة اليوم اليومية، أو العنوان الذي ستحمله إن لم تكن موجودة بعد |
list_note_tasks | سرد مهام مربعات الاختيار في ملاحظاتك، بدءًا بأحدث ملاحظة. رشّح بالملاحظة وبكونها مفتوحة أو منجزة |
note_backlinks | سرد الملاحظات التي ترتبط بملاحظة ما، مع النص المحيط بكل رابط |
append_to_note | إضافة Markdown إلى نهاية ملاحظة أو ملاحظة اليوم اليومية |
edit_note_section | إعادة كتابة الجزء الواقع تحت عنوان واحد من ملاحظة، أو الإضافة إلى نهايته |
create_note | إنشاء ملاحظة بعنوان ونص Markdown ووسوم ومشروع مرتبط |
لا تكتب append_to_note وedit_note_section في الملاحظة. وتظهر تغييراتهما فيها كاقتراحات إلى أن تقبلها في Oleafly. وينتظر create_note موافقتك في Oleafly، وكذلك append_to_note عندما يضطر إلى إنشاء ملاحظة اليوم اليومية أولًا. وتحت Trust this connection لا يطلب إنشاء ملاحظة موافقة. والملاحظة المشتركة عبر خادم تعاون يمكن قراءتها لكن لا يمكن تغييرها بهذه الطريقة. ويزيل Read-only الأدوات الثلاث التي تغيّر الملاحظات.
الاعتمادات والسلامة
قسم بعنوان “الاعتمادات والسلامة”يطلب كثير من عملاء MCP التأكيد قبل استدعاء أداة. ويطبّق Oleafly أيضًا السياسة المختارة في Settings → Integrations → Oleafly MCP:
- Confirm every change هي السياسة الافتراضية. تعرض عمليات الكتابة وإعادة التسمية والحذف بطاقة اعتماد أثناء اتصال نافذة من التطبيق. وبدون نافذة، تُرفض تلك العمليات لعدم وجود مكان لعرض البطاقة.
- تتيح Auto-approve edits, confirm deletes تشغيل عمليات الكتابة وإعادة التسمية في الواجهة الخلفية. وما زال الحذف يتطلب نافذة متصلة للتأكيد.
- تتيح Trust this connection تشغيل عمليات الكتابة وإعادة التسمية في الواجهة الخلفية دون مطالبة من Oleafly. وما زال الحذف يتطلب نافذة متصلة. لا تستخدم هذه السياسة إلا عندما تثق بالعميل وبضوابط الاعتماد المدمجة فيه.
ويدعم ذلك مفتاحا تبديل إضافيان:
- يزيل Read-only (مفتاح تبديل منفصل) الأدوات المغيِّرة من
tools/listكليًا، فيستطيع تطبيق خارجي القراءة والتجميع لكنه لا يعدّل الملفات أبدًا، أيًّا كانت السياسة أعلاه. - Bearer token: قيمة عشوائية بطول 256 بت مخزنة في مخزن محلي مشفّر ومصادَق عليه تحت
~/.oleafly/. أعِد توليدها لإبطال العملاء القدامى. قراءات الإعدادات العامة لا تكشف الرمز أبدًا. ولا يمكن كشفه في Settings إلا من مفاتيح التحكم في الاتصال الخاصة بالخادم قيد التشغيل.
وأمران ثابتان لا تضبطهما بنفسك:
- Localhost only: عنوان الارتباط هو
127.0.0.1. تُرفض الطلبات التي تحمل ترويسةOriginصادرة من متصفح، ويجب أن تكون قيمةHostعنوان ارتداد. - Project confinement: تقبل أدوات الملفات في الواجهة الخلفية مسارات نسبية إلى المشروع، وتحصر المسارات المعيارية داخل المشروع الذي أبلغ عنه التطبيق. لا يستطيع استدعاء الأداة أن يمرر معرّف مشروع آخر أو يجعل الواجهة الخلفية تختار مشروعًا مختلفًا من المكتبة.
مشاهدته أثناء العمل
قسم بعنوان “مشاهدته أثناء العمل”أثناء اتصال نافذة، تسجّل علامة تبويب MCP activity الاستدعاءات الواردة. ويمكن أن تستمر استدعاءات الواجهة الخلفية بعد إغلاق النافذة الأخيرة، لكن لا لوحة نشاط ولا بطاقة اعتماد حتى تتصل نافذة من جديد.
لماذا لا يستطيع claude.ai في المتصفح الاتصال
قسم بعنوان “لماذا لا يستطيع claude.ai في المتصفح الاتصال”لا تستطيع خدمة محادثة سحابية الوصول إلى 127.0.0.1 على جهازك. استخدم Claude Desktop (أو Claude Code أو Cursor أو نحوها) بدلًا من ذلك. لا تنشئ نفقًا يوصل منفذ MCP إلى الإنترنت العام: فذلك سيتيح لأي شخص يملك عنوان URL تعديل ملفات مشروعك المحلية وحذفها.
استكشاف الأخطاء وإصلاحها
قسم بعنوان “استكشاف الأخطاء وإصلاحها”| العَرَض | ما يمكنك تجربته |
|---|---|
| بعض الأدوات غير متاحة | تحتاج معاينات الأشكال وغيرها من أدوات الواجهة فقط إلى نافذة Oleafly. افتح التطبيق والمشروع ثم أعِد تجربة tools/list. |
تغيّر المنفذ عن 5323 | لم يكن المنفذ المفضل متاحًا، فاختار Oleafly منفذًا حرًا. انسخ عنوان URL الفعلي من Settings. |
| HTTP 401 | عدم تطابق الرمز (مثلًا بعد Regenerate). انسخ الرمز الجديد إلى العميل. |
| HTTP 403 | أرسل العميل ترويسة Origin أو قيمة Host ليست عنوان ارتداد. استخدم عميل MCP أصليًا لا تبويب متصفح. |
| انتهت مهلة الاستدعاء | ينتظر كل استدعاء أداة حتى 5 دقائق (300 ثانية) لعمليات التجميع أو لنقرك Approve. اعتمد البطاقات المعلقة أو ارفضها، أو أعِد المحاولة. وقد يستغرق التجميع وقتًا أطول، حتى ساعة لدفتر Quarto أو Calepin. ويواصل العمل في Oleafly بعد انتهاء مهلة الاستدعاء، وتنتظره الأدوات التي تحتاج إلى نافذة Oleafly، فدعه ينتهي قبل أن تعيد المحاولة. |
تعيد compile سببًا بدل أخطاء | تعذّر تشغيل البناء، مثلًا لأن TeX غير مثبّت. استخدم الإصلاح الذي يعرضه Oleafly في التطبيق، مثل تثبيت TinyTeX، ثم جمّع مرة أخرى. |
| يتعذر الاتصال | يجب أن يكون Oleafly قيد التشغيل مع تفعيل MCP. يتوقف هذا الخادم عند إنهاء التطبيق؛ وللحصول على أدوات المشروع والتطبيق مغلق، اربط العميل بـ oleafly mcp بدلًا من ذلك. |
إضافة أدوات خارجية إلى Oleafly
قسم بعنوان “إضافة أدوات خارجية إلى Oleafly”
لمنح المساعد المدمج مزيدًا من الأدوات، افتح Settings → AI Assistant → MCP.
- استخدم Browse registry للعثور على خادم ومراجعة خطوات إعداده.
- استخدم Import from other tools لاختيار إعدادات خوادم موجودة. راجع المدخلات المختارة قبل الاستيراد.
- استخدم Add server لإدخال خادم بنفسك، ثم تحقق من الاتصال.
تعرض الخوادم المتصلة أدواتها للمساعد. يمكنك فحص حالة الاتصال وتمكين الخوادم أو تعطيلها من الصفحة نفسها. تنتمي بيانات الاعتماد والأوامر إلى إعدادات كل خادم؛ راجعها قبل توصيل خادم جديد.
يتصل alphaXiv أيضًا كخادم MCP، لكنك تضبطه في Settings → Integrations → alphaXiv بمفتاح API بدلًا من هنا. وبمجرد الاتصال، يظهر في هذه القائمة باسم alphaXiv. يغطي توصيل مصادر البحث الخطوات.
تهيئة خادم خارجي يدويًا
قسم بعنوان “تهيئة خادم خارجي يدويًا”
ضمن Settings → AI Assistant → MCP، اختر Add server. يشغّل الخادم المحلي أمرًا عبر stdio؛ أما الخادم البعيد فيتصل بعنوان URL. يستخدم نموذج JSON تنسيق الخوادم في Oleafly:
{ "name": "Research tools", "enabled": true, "transport": "stdio", "command": "your-mcp-server", "args": ["--stdio"], "env": {}}استبدل الأمر والوسائط بما وثّقه الخادم الذي ثبّته. وتنتمي قيم متغيرات البيئة إلى الكائن env.
{ "name": "Research service", "enabled": true, "transport": "remote", "url": "https://your-server.example/mcp", "headers": { "Authorization": "Bearer YOUR_TOKEN" }}استبدل عنوان URL والرمز المثالين بتفاصيل اتصال الخدمة. استخدم Validate لفحص الاتصال، ثم راجع الأدوات التي يعرضها الخادم. مكّن الخادم أو عطّله من صفه. واستخدم إجراء التحرير الخاص به لتغيير الإعدادات، وإجراء الإزالة لقطع اتصاله.
استيراد إعدادات MCP موجودة
قسم بعنوان “استيراد إعدادات MCP موجودة”اختر Import from other tools، وافحص الإعدادات المكتشفة، وحدد الخوادم التي تريدها. راجع مسارات الملفات التنفيذية ومتغيرات البيئة وعناوين URL وبيانات الاعتماد قبل الاستيراد. يستورد هذا إعدادات الاتصال؛ ولا يثبّت لك الملف التنفيذي للخادم.
تجربة الاتصال
قسم بعنوان “تجربة الاتصال”- افتح مشروعًا تدريبيًا صغيرًا في Oleafly.
- صِل العميل الخارجي باستخدام المقتطف المنسوخ من التطبيق.
- اطلب من العميل استدعاء
get_statusوسرد ملفات المشروع. - اطلب منه قراءة المستند الرئيسي واقتراح تغيير على العنوان.
- راجع الإجراء في Oleafly قبل اعتماد عملية كتابة.
- جمّع المشروع ثم افحص ملف PDF.
بالنسبة لأداة خارجية متصلة داخل Oleafly، ابدأ بطلب قراءة فقط بسيط يدعمه ذلك الخادم، وافحص بطاقة الأداة الناتجة في المحادثة.