# الاتصال عبر 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](/docs/ai-setup/).

## تفعيل الخادم

1. افتح **Settings → Integrations → Oleafly MCP**.
2. شغّل مفتاح التبديل **Enable MCP server**.

يعمل الخادم فقط أثناء بقاء عملية Oleafly مفتوحة. يستمع على `127.0.0.1` فقط، ولا يستمع على شبكتك المحلية أبدًا. إغلاق نافذة المشروع لا يوقف الخادم؛ أما إيقاف تشغيل MCP أو إنهاء Oleafly فيوقفه.

يفضّل Oleafly المنفذ `5323` (`http://127.0.0.1:5323/mcp`). وإذا لم يكن متاحًا، يرتبط الخادم تلقائيًا بمنفذ محلي حر آخر ويحفظه للإطلاق التالي. تعرض Settings عنوان URL النشط. ويعيد زر إعادة التشغيل فيها استخدام المنفذ الحالي متى أمكن أو يختار منفذًا حرًا آخر.

## اتصال عميلك

:::tip[لا رمز لنسخه]
للأمر `oleafly` خادم MCP خاص به يتحدث عبر الإدخال والإخراج القياسيين. يجد التطبيق قيد التشغيل ورمزه بنفسه، فلا تنسخ عنوان URL ولا رمزًا، ولا تحتاج إلى Node.js. يطبع `oleafly mcp config --client claude-desktop` خطوات الإعداد؛ وأسماء العملاء هي `claude-code` و`claude-desktop` و`codex` و`cursor` و`gemini`. انظر [أداة سطر الأوامر](/docs/cli/#connect-an-agent-over-mcp).
:::

تعرض Settings مقتطفات جاهزة للنسخ واللصق للعملاء الشائعين. انسخ عنوان URL الفعلي لأن المنفذ المختار قد يختلف عن `5323`، ثم استبدل `<token>` برمز الحامل من Settings (Reveal / Copy).

### Claude Code

```bash
claude mcp add --transport http oleafly http://127.0.0.1:5323/mcp --header "Authorization: Bearer <token>"
```

### Claude Desktop

أضف إلى `claude_desktop_config.json` (جسر stdio عبر `mcp-remote`، لأن Desktop يفضّل stdio):

```json
{
  "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

يتضمن كل إصدار الملف `oleafly.mcpb`، وهو إضافة لتطبيق Claude Desktop، فلا تحتاج إلى ملف الإعدادات ولا إلى الرمز المميز. نزّله من [أحدث إصدار](https://github.com/Oleafly/Oleafly/releases/latest) وافتحه باستخدام 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/mcp.json` (أو إعدادات MCP لعميلك):

```json
{
  "mcpServers": {
    "oleafly": {
      "url": "http://127.0.0.1:5323/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}
```

### Grok CLI

في `~/.grok/config.toml`:

```toml
[mcp_servers.oleafly]
url = "http://127.0.0.1:5323/mcp"
headers = { Authorization = "Bearer <token>" }
```

### Codex CLI

استخدم مقتطف **Codex CLI** في إعدادات Oleafly، فهو يوفر جسر stdio إلى الخادم قيد التشغيل. أضف المدخل إلى إعدادات Codex لديك واستخدم عنوان URL والرمز الفعليين اللذين يعرضهما Oleafly:

```toml title="~/.codex/config.toml"
[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**. راجع [المهارات](/docs/skills/).

### الملاحظات

هذه الأدوات متاحة ما دام **Notes** مفعّلًا في **Settings → Experimentation**، كما يصف [تفعيل الملاحظات](/docs/notes/#turn-on-notes). وهي تعمل على ملاحظاتك لا على المشروع المفتوح، وتحتاج إلى نافذة متصلة.

| الأداة | ما تفعله |
|---|---|
| `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 في المتصفح الاتصال

لا تستطيع خدمة محادثة سحابية الوصول إلى `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

![Settings → AI Assistant → MCP. أضف خادمًا، أو تصفح السجل، أو استورد الإعدادات من أداة أخرى.](https://cdn.oleafly.com/images/screenshots/desktop/docs/settings-mcp-dark-window-v2.png#view=519,89,883,568)

لمنح المساعد المدمج مزيدًا من الأدوات، افتح **Settings → AI Assistant → MCP**.

- استخدم **Browse registry** للعثور على خادم ومراجعة خطوات إعداده.
- استخدم **Import from other tools** لاختيار إعدادات خوادم موجودة. راجع المدخلات المختارة قبل الاستيراد.
- استخدم **Add server** لإدخال خادم بنفسك، ثم تحقق من الاتصال.

تعرض الخوادم المتصلة أدواتها للمساعد. يمكنك فحص حالة الاتصال وتمكين الخوادم أو تعطيلها من الصفحة نفسها. تنتمي بيانات الاعتماد والأوامر إلى إعدادات كل خادم؛ راجعها قبل توصيل خادم جديد.

يتصل alphaXiv أيضًا كخادم MCP، لكنك تضبطه في **Settings → Integrations → alphaXiv** بمفتاح API بدلًا من هنا. وبمجرد الاتصال، يظهر في هذه القائمة باسم **alphaXiv**. يغطي [توصيل مصادر البحث](/docs/integrations/research-sources/#alphaxiv) الخطوات.

## تهيئة خادم خارجي يدويًا

![Add server → Form. اختر Local command أو Remote URL، واملأ حقول الاتصال، ثم استخدم Add وتحقق من الصحة.](https://cdn.oleafly.com/images/screenshots/desktop/docs/mcp-add-server-dark-window-v2.png#view=670,228,578,625)

ضمن **Settings → AI Assistant → MCP**، اختر **Add server**. يشغّل الخادم المحلي أمرًا عبر stdio؛ أما الخادم البعيد فيتصل بعنوان URL. يستخدم نموذج JSON تنسيق الخوادم في Oleafly:

```json title="إعدادات الخادم المحلي"
{
  "name": "Research tools",
  "enabled": true,
  "transport": "stdio",
  "command": "your-mcp-server",
  "args": ["--stdio"],
  "env": {}
}
```

استبدل الأمر والوسائط بما وثّقه الخادم الذي ثبّته. وتنتمي قيم متغيرات البيئة إلى الكائن `env`.

```json title="إعدادات الخادم البعيد"
{
  "name": "Research service",
  "enabled": true,
  "transport": "remote",
  "url": "https://your-server.example/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_TOKEN"
  }
}
```

استبدل عنوان URL والرمز المثالين بتفاصيل اتصال الخدمة. استخدم **Validate** لفحص الاتصال، ثم راجع الأدوات التي يعرضها الخادم. مكّن الخادم أو عطّله من صفه. واستخدم إجراء التحرير الخاص به لتغيير الإعدادات، وإجراء الإزالة لقطع اتصاله.

## استيراد إعدادات MCP موجودة

اختر **Import from other tools**، وافحص الإعدادات المكتشفة، وحدد الخوادم التي تريدها. راجع مسارات الملفات التنفيذية ومتغيرات البيئة وعناوين URL وبيانات الاعتماد قبل الاستيراد. يستورد هذا إعدادات الاتصال؛ ولا يثبّت لك الملف التنفيذي للخادم.

## تجربة الاتصال

1. افتح مشروعًا تدريبيًا صغيرًا في Oleafly.
2. صِل العميل الخارجي باستخدام المقتطف المنسوخ من التطبيق.
3. اطلب من العميل استدعاء `get_status` وسرد ملفات المشروع.
4. اطلب منه قراءة المستند الرئيسي واقتراح تغيير على العنوان.
5. راجع الإجراء في Oleafly قبل اعتماد عملية كتابة.
6. جمّع المشروع ثم افحص ملف PDF.

بالنسبة لأداة خارجية متصلة داخل Oleafly، ابدأ بطلب قراءة فقط بسيط يدعمه ذلك الخادم، وافحص بطاقة الأداة الناتجة في المحادثة.
