---
url: https://docs.ogmabox.com/ar/mcp-setup.md
description: >-
  ربط وكلاء الذكاء الاصطناعي بـ Ogma عبر Streamable HTTP أو stdio وضبط الأذونات
  واستخدام نقاط نهاية إدارة MCP المحلية.
---

# إعداد خادم Ogma MCP {#ogma-mcp-server-setup}

يتيح خادم Ogma MCP (`ogma-mcp`) لمساعدي الذكاء الاصطناعي المتوافقين فحص سياق المشروع، وعند التفعيل، التحكم في المتصفح المضمن وإرسال الطلبات وتشغيل مسارات العمل وجمع الأدلة. أدوات الملاحظات والمهام فيه عبارة عن مساحة تدوين في الذاكرة خاصة بجلسة MCP، منفصلة عن صفحة الملاحظات الدائمة في التطبيق.

MCP مخصص للأدوات الخارجية مثل Codex وClaude Code وCursor وعملاء بروتوكول سياق النموذج الآخرين. وهو ليس ميزة مساعد الذكاء الاصطناعي لمساحة العمل داخل التطبيق نفسها.

للاطلاع على القائمة الكاملة للموارد والأدوات، راجع [موارد MCP وأدواته](./reference/mcp-tools.md).

## البدء السريع: تطبيق سطح المكتب {#quick-start-desktop-app}

1. شغّل Ogma وافتح المشروع الذي ينبغي للوكيل فحصه.
2. افتح **الإعدادات > MCP**، واختر الأذونات المطلوبة واحفظها. يتطلب التفاعل مع المتصفح إذن **الإرسال في أداة إعادة الإرسال**.
3. انقر على **بدء** وانسخ نقطة النهاية المعروضة، وهي عادة `http://127.0.0.1:3000/mcp`.
4. أضفها إلى عميل MCP لديك كخادم **Streamable HTTP**.
5. اطلب من الوكيل استدعاء `ogma_explain_capabilities` وقراءة `ogma://project/current` للتحقق من الاتصال والمشروع النشط.

لا يحتاج هذا المسار إلى بناء ملف تنفيذي منفصل. للتنقل بين الصفحات والنماذج ومسارات تسجيل الدخول واستكشاف الأخطاء، راجع [أتمتة المتصفح باستخدام MCP](./guide/mcp-browser.md).

### عناوين الاتصال {#connection-addresses}

| الواجهة | العنوان الافتراضي | الغرض |
| --- | --- | --- |
| نقل MCP | `http://127.0.0.1:3000/mcp` | يتصل عملاء MCP الأصليون هنا. |
| REST API للواجهة الخلفية | `http://127.0.0.1:8181` | قيمة `--api-url` لـ MCP المستقل ومسارات الإدارة والجسر أدناه. |
| منفذ استماع الوكيل | `127.0.0.1:8080` | يلتقط حركة المتصفح؛ وليس نقطة نهاية MCP. |

قد تعيّن مثيلات سطح المكتب منفذ API للواجهة الخلفية ديناميكيا. استخدم عنوان المثيل الفعلي قيد التشغيل لتكاملات stdio/REST، ونقطة النهاية المعروضة في الإعدادات لـ MCP الأصلي. لا تستطيع خدمة محادثة سحابية الوصول إلى عنوان loopback المحلي لديك دون عميل أو موصل محلي.

تحتفظ نقطة نهاية HTTP بالحالة: دع العميل يتولى التهيئة وترويسات الجلسة. لا توجد نقطة نهاية قديمة منفصلة `/sse`. ينبغي للعملاء المخصصين اتباع [مواصفة النقل](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports) الخاصة بـ MCP.

## متى تستخدم MCP {#when-to-use-mcp}

استخدم MCP عندما تريد من مساعد خارجي مساعدتك في:

* تلخيص حركة المرور الملتقطة.
* فرز نتائج الفحص.
* صياغة نص تقرير مستند إلى الأدلة.
* مراجعة مسارات العمل وجلسات إعادة الإرسال.
* إعداد إجراءات ضمن النطاق توافق عليها صراحة.

استخدم [الذكاء الاصطناعي لمساحة العمل](./guide/workspace-ai.md) عندما تريد نافذة المساعد المضمنة داخل Ogma بدلا من ذلك.

## متطلبات التشغيل المستقل {#standalone-requirements}

استخدم stdio عندما يحتاج عميلك إلى تشغيل ملف تنفيذي محلي بدلا من الاتصال بنقطة نهاية HTTP المضمنة.

* واجهة Ogma الخلفية قيد التشغيل على عنوان API الفعلي الخاص بها (افتراضي CLI: `http://127.0.0.1:8181`)
* الملف التنفيذي `ogma-mcp` (المبني من المصدر)

## البناء {#build}

```bash
cargo build --locked --bin ogma-mcp --release
```

المخرج الافتراضي هو `target/release/ogma-mcp` (`ogma-mcp.exe` على Windows)، ما لم تخصص مجلد الهدف في Cargo.

## التشغيل {#run}

```bash
# Connect to Ogma running on the default port
./ogma-mcp

# Connect to a custom address
./ogma-mcp --api-url http://127.0.0.1:9090

# Use a larger body preview
./ogma-mcp --body-preview-bytes 2048
```

يخرج الخادم إذا تعذر عليه الوصول إلى API الخاص بـ Ogma. اضبط عميل MCP لتشغيل هذا الأمر؛ ينقل stdout رسائل MCP وينقل stderr بيانات التشخيص. تأتي أذونات stdio من أعلامه الخاصة، وليس من إعدادات MCP المضمن.

## اكتشاف الأدوات {#tool-discovery}

يعلن الخادم الحالي دائما عن فهرس أدواته الكامل. لا يوجد محدد لملف تعريف الأدوات في الإعدادات. تُقبل القيم القديمة `--tool-profile` و`--mcp-tool-profile` و`OGMA_MCP_TOOL_PROFILE` للتوافق، لكنها لا تخفي الأدوات ولا تمنح أذونات.

عند التعامل مع فهرس كبير، ابدأ بـ `ogma_explain_capabilities` و`ogma_find_tools` بدلا من تخمين المدخلات. ابحث بكلمات المهمة المفتاحية لتكوين قائمة مختصرة من الأدوات، ثم استعلم باسم أداة دقيق لفحص عقدها. توفر أدوات توجيه المتصفح والبحث نقاط دخول مريحة؛ وتظل الأدوات المتخصصة متاحة مباشرة. راجع [اكتشاف الأدوات وتوجيه الاستدعاءات](./reference/mcp-tools.md#tool-discovery-and-dispatch).

## إعدادات MCP داخل التطبيق {#in-app-mcp-settings}

يمكن لإصدارات Ogma المجمعة إدارة MCP من **الإعدادات > MCP**. استخدم شاشة الإعدادات عندما تريد أن يبدأ Ogma عملية MCP المضمنة أو يوقفها للمثيل النشط.

استخدم الملف التنفيذي المستقل `ogma-mcp` عندما يتوقع عميل الذكاء الاصطناعي لديك تشغيل خادم MCP مباشرة.

يؤدي حفظ الإعدادات إلى إعادة تشغيل عملية MCP المضمنة قيد التشغيل تلقائيا. أعد توصيل العملاء بعدها؛ لا يمكن إعادة استخدام معرفات الجلسات ورموز التأكيد القديمة. يعرض **تشخيص وقت التشغيل** مخرجات العملية الأخيرة.

يتيح Ogma أيضا إدارة MCP عبر REST API المحلي. توجد هذه المسارات على **منفذ API للواجهة الخلفية**، وليس على منفذ MCP المخصص. وتستخدمها شاشة الإعدادات وجسر الذكاء الاصطناعي داخل التطبيق:

| نقطة النهاية | الغرض |
| --- | --- |
| `GET /mcp/status` | إرجاع `{ running, pid, endpoint, config, diagnostics }`. تكون `endpoint` بقيمة null عند التوقف؛ وتتضمن بيانات التشخيص سجلات `{ stream, message }` الأخيرة. |
| `POST /mcp/start` | بدء MCP المضمن بالإعدادات المحفوظة وإرجاع الحالة. لا يوجد جسم للطلب. يُرجع تعارضا إذا كان قيد التشغيل بالفعل. |
| `POST /mcp/stop` | إيقاف عملية MCP المضمنة الفرعية. |
| `GET /settings/mcp` | إرجاع إعدادات MCP المحفوظة. |
| `PUT /settings/mcp` | قبول كائن إعدادات كامل وحفظه وإعادة تشغيل MCP إن كان يعمل. إرجاع الإعدادات المقبولة أو خطأ. لا يُسمح بالربط إلا بعناوين loopback المحلية. |
| `GET /mcp/tools` | إرجاع `{ tools, config }`، بما في ذلك `inputSchema` لكل أداة. فهرس REST هذا غير مقسم إلى صفحات. |
| `POST /mcp/tools/call` | استدعاء أداة واحدة باستخدام `{ "name": "ogma_explain_capabilities", "arguments": {} }`. يُرجع `{ "result": "..." }`؛ حلّل هذا النص بوصفه غلاف JSON للأداة. ليست هذه نتيجة MCP أصلية تتضمن كتل صور. |

يستخدم جسر REST الأذونات المحفوظة، لكنه لا يتطلب بدء عملية HTTP MCP الفرعية المنفصلة. ويتشارك جلسة جسر واحدة للواجهة الخلفية والإعدادات. فضّل MCP الأصلي لعزل جلسات العملاء وإخراج الصور.

عند فشل الجسر، ينتج عن تحليل `result` الكائن `{ "error": "..." }` الذي يحتوي على غلاف الخطأ المتسلسل. تحقق من هذه القيمة بدلا من اعتبار حالة نجاح HTTP نجاحا للأداة.

إعدادات MCP المحفوظة الافتراضية:

```json
{
  "bind_host": "127.0.0.1",
  "port": 3000,
  "allow_write_findings": false,
  "allow_export_data": false,
  "allow_read_secrets": false,
  "allow_send_requests": false,
  "allow_run_workflows": false,
  "allow_intercept_control": false,
  "tool_profile": "full"
}
```

مضيفو الربط المسموح بهم هم `127.0.0.1` و`localhost` و`::1`؛ ويجب أن تكون المنافذ من `1024` إلى `65535`. لا يضبط هذا الإصدار مصادقة لـ MCP المكشوف على الشبكة، لذلك تُرفض عناوين الربط العامة. لا تتجاوز الحقول القديمة `allow_public_bind` و`acknowledge_write_tool_risk` هذا القيد.

## Claude Code {#claude-code}

لنقطة نهاية سطح المكتب قيد التشغيل:

```bash
claude mcp add --transport http ogma http://127.0.0.1:3000/mcp
```

استخدم نقطة النهاية التي يعرضها Ogma إن كانت مختلفة. راجع [إعداد MCP في Claude Code](https://code.claude.com/docs/en/mcp) لمعرفة نطاقات الإعداد وخيارات stdio. تحقق بالسؤال: "ما المشاريع الموجودة في Ogma؟"

## Cursor {#cursor}

ادمج هذا الإدخال في `.cursor/mcp.json` الخاص بمشروعك أو `~/.cursor/mcp.json` على مستوى المستخدم:

```json
{
  "mcpServers": {
    "ogma": {
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}
```

فعّل الاتصال في إعدادات MCP في Cursor. راجع [توثيق MCP في Cursor](https://cursor.com/docs/mcp).

### إعداد عميل stdio {#stdio-client-configuration}

يمكن للعملاء الذين يشغّلون ملفا تنفيذيا استخدام إدخال الخادم هذا، مع تعديل موقع ملف الإعداد بحسب الحاجة:

```json
{
  "mcpServers": {
    "ogma": {
      "command": "/absolute/path/to/ogma-mcp",
      "args": ["--api-url", "http://127.0.0.1:8181"]
    }
  }
}
```

على Windows، استخدم المسار الكامل للملف التنفيذي ومثّل الشرطات المائلة العكسية بمحارف هروب في JSON. يتطلب بعض العملاء أيضا `"type": "stdio"`. أضف أعلام الأذونات إلى `args` بحسب الحاجة.

## الأذونات {#permissions}

القدرات الست ذات الامتيازات معطلة افتراضيا. اقرأ قيمها الحالية من `ogma://mcp/permissions`. قد تظل أداة مدرجة ترفض التنفيذ إلى أن تُفعّل قدرتها. يوجد جدول الأعلام ومتغيرات البيئة الكامل في [مرجع CLI](./reference/cli.md#standalone-ogma-mcp-flags).

يتطلب التفاعل مع المتصفح وإدارة السياق وتبديل المشاريع وجميع استدعاءات مسارات المصادقة `--allow-send-requests`. تستطيع مراقبة المتصفح فحص متصفح قيد التشغيل بالفعل دون تفعيل أدوات التحكم فيه. يسمح `--allow-read-secrets` (أو `OGMA_MCP_ALLOW_READ_SECRETS=true`) على نحو مستقل بقيم متغيرات البيئة غير المحجوبة.

لا يفرض الخادم **حصصا للنشاط في الدقيقة أو في الجلسة**. تظل الأدوات الفردية تفرض أحجام مدخلاتها وأحجام الدفعات وفحوص النطاق ومهلاتها. لم تعد أعلام حصص الإرسال وسير العمل القديمة مدعومة.

## وضع القراءة فقط {#read-only-mode}

يعمل خادم MCP بوضع القراءة فقط افتراضيا. لا تتاح العمليات التالية إلا عند تفعيلها صراحة:

* إرسال الطلبات (إعادة الإرسال)
* التحكم في المتصفح المضمن والزاحف والتقاط المصادقة ومساعدات الاختبار النشط
* تشغيل مسارات العمل
* إنشاء النتائج أو تعديلها
* تعديل النطاق أو قواعد المطابقة والاستبدال
* تعديل حركة المرور المعترضة أو تمريرها
* حذف البيانات
* الوصول إلى قيم متغيرات البيئة السرية
* تصدير البيانات

تبلغ معاينات الجسم 512 بايت افتراضيا. يضبط `--body-preview-bytes` المعاينات ويجب ألا يقل عن 1؛ لكنه لا يحد مخرجات جميع الأدوات. استخدم `ogma_get_http_entry_body` للحصول على جسم HTTP كامل أو بحث مستهدف في الجسم، و`ogma_get_ws_message` للحصول على رسالة WebSocket كاملة.

## أدوات كتابة النتائج {#finding-write-tools}

لتفعيل إنشاء النتائج بمساعدة الذكاء الاصطناعي، أعد تشغيل ogma-mcp بأذونات الكتابة:

```bash
./ogma-mcp --allow-write-findings
```

أو عيّن متغير البيئة:

```bash
OGMA_MCP_ALLOW_WRITE_FINDINGS=true ./ogma-mcp
```

### أدوات الكتابة المتاحة {#write-tools-available}

| الأداة | الوصف |
|------|-------------|
| `ogma_preview_finding_from_evidence` | معاينة مسودة نتيجة من إدخال HTTP (للقراءة فقط، متاحة دائما) |
| `ogma_create_finding` | إنشاء نتيجة مع الخطورة والحالة والوسوم وروابط الأدلة |
| `ogma_update_finding` | تحديث نتيجة موجودة |
| `ogma_add_finding_tag` | إضافة وسوم إلى نتيجة دون استبدال الوسوم الموجودة |
| `ogma_link_finding_evidence` | ربط إدخال HTTP أو محاولة إعادة الإرسال أو نتيجة الأتمتة أو رسالة WS بنتيجة |
| `ogma_delete_finding` | حذف نتيجة واحدة |
| `ogma_export_findings_report` | توليد تقرير HTML أو Markdown أو PDF |

يستخدم التنفيذ الحالي أيضا إذن كتابة النتائج لأدوات الكتابة المشتركة، مثل تحديث متغيرات البيئة وتعليقات السجل واختيار النطاق وتعديلات المطابقة والاستبدال. راجع [فهرس الأدوات](./reference/mcp-tools.md) لهذه الإجراءات.

### مثال: إنشاء نتيجة بمساعدة الذكاء الاصطناعي {#example-ai-assisted-finding-creation}

مع `--allow-write-findings`:

1. "حلّل إدخال HTTP {id} بحثا عن مشكلات أمنية. إذا وجدت مشكلة حقيقية، فاستخدم ogma\_create\_finding لتوثيقها."
2. سيستدعي الذكاء الاصطناعي `ogma_get_http_entry` لفحص الطلب
3. إذا دعمت الأدلة نتيجة، فسيستدعي `ogma_create_finding` مع ربط الأدلة

### ما يظل غير متاح بإذن كتابة النتائج وحده {#still-not-available-with-finding-writes-only}

* الإرسال في أداة إعادة الإرسال
* تنفيذ سير العمل
* إنشاء ملفات التصدير
* التحكم في قائمة انتظار الاعتراض
* تبديل المشروع

## أدوات التصدير {#export-tools}

لتفعيل إنشاء مهام التصدير بمساعدة الذكاء الاصطناعي، أعد تشغيل ogma-mcp بأذونات التصدير:

```bash
./ogma-mcp --allow-export-data
```

أو عيّن متغير البيئة:

```bash
OGMA_MCP_ALLOW_EXPORT_DATA=true ./ogma-mcp
```

### أدوات التصدير المتاحة {#export-tools-available}

| الأداة | الإذن المطلوب | الوصف |
|------|--------------------|-------------|
| `ogma_preview_export_plan` | لا يوجد (للقراءة فقط) | معاينة ما سيُضمن في التصدير |
| `ogma_list_export_jobs` | لا يوجد (للقراءة فقط) | سرد مهام التصدير الأخيرة |
| `ogma_get_export_job` | لا يوجد (للقراءة فقط) | التحقق من حالة مهمة التصدير |
| `ogma_get_export_download_info` | لا يوجد (للقراءة فقط) | الحصول على عنوان URL لتنزيل التصدير المكتمل |
| `ogma_create_export_job` | export\_data | إنشاء مهمة تصدير |

### أنواع التصدير وصيغه المدعومة {#supported-export-kinds-and-formats}

| النوع | الوصف | الصيغ |
|------|-------------|---------|
| `http_history` | جميع طلبات HTTP المارة عبر الوكيل | json, csv, raw\_http |
| `search` | طلبات HTTP المصفاة | json, csv, raw\_http |
| `findings` | النتائج الأمنية | json, csv |
| `automate_results` | نتائج جلسة الأتمتة | json, csv |

ملاحظة: صيغة `raw_http` صالحة فقط لنوعي `http_history` و`search`.

### تحذير أمني {#security-warning}

قد تحتوي ملفات التصدير على أجسام طلبات HTTP واستجاباتها كاملة، بما قد يشمل كلمات مرور ورموزا وبيانات شخصية. تعامل مع ملفات التصدير بالعناية المناسبة.

### ما يظل غير متاح بأذونات التصدير وحدها {#still-not-available-with-export-permissions-only}

* حذف ملفات التصدير
* إعادة تسمية ملفات التصدير
* بث محتوى التصدير عبر MCP
* الإرسال في أداة إعادة الإرسال
* تنفيذ سير العمل

## إرسال طلبات إعادة الإرسال {#replay-request-sending}

تحذير: يتيح هذا إرسال حركة HTTP صادرة حقيقية عبر أداة إعادة الإرسال في Ogma.

للتفعيل:

```bash
./ogma-mcp --allow-send-requests
```

أو عبر متغيرات البيئة:

```bash
OGMA_MCP_ALLOW_SEND_REQUESTS=true ./ogma-mcp
```

### المتطلبات المسبقة {#prerequisites}

1. يجب أن يكون وكيل Ogma قيد التشغيل
2. يجب ضبط نطاق نشط في **نطاقات الاختبار** لإرسالات إعادة الإرسال الخاضعة للضوابط
3. يجب أن يكون المضيف المستهدف ضمن النطاق النشط

### أدوات الإرسال {#send-tools}

| الأداة | الإذن | الوصف |
|------|-----------|-------------|
| `ogma_preview_replay_send` | send\_requests | إعداد إرسال والحصول على رمز تأكيد |
| `ogma_send_replay_request` | send\_requests | تنفيذ الإرسال باستخدام رمز التأكيد |
| `ogma_create_replay_session_from_history` | send\_requests | إنشاء جلسة إعادة الإرسال |
| `ogma_create_replay_session_raw` | send\_requests | إنشاء جلسة إعادة الإرسال من تعريف طلب خام |
| `ogma_browser_form_to_replay` | send\_requests | إنشاء جلسة إعادة الإرسال من نموذج في الصفحة الحالية |
| `ogma_create_scope_preset` | send\_requests | تخزين إعداد نطاق مسبق؛ وتفعيله بشكل منفصل باستخدام `ogma_set_active_scope` |
| `ogma_repeat_request` | send\_requests | تكرار طلب ملتقط مع تعديلات اختيارية |
| `ogma_replay_with_modifications` | send\_requests | إعادة إرسال طلب ملتقط مع تجاوزات على مستوى الحقول |
| `ogma_http_request` | send\_requests | إرسال طلب HTTP مباشر |
| `ogma_fetch_url` | send\_requests | جلب عنوان URL وإرجاع الحالة والترويسات والمعاينة |
| `ogma_follow_redirect` | send\_requests | تتبع سلسلة إعادة توجيه والإبلاغ عن كل انتقال |
| `ogma_bulk_send_requests` | send\_requests | إرسال دفعة محدودة من الطلبات |
| `ogma_fuzz_parameter` | send\_requests | استبدال العنصر النائب `{{FUZZ}}` بقيم قائمة الكلمات |
| `ogma_multipart_upload` | send\_requests | إرسال طلبات multipart form-data لاختبار الرفع |
| `ogma_websocket_connect` | send\_requests | الاتصال بعنوان WebSocket وتبادل الرسائل |
| `ogma_login_replay_auto` | send\_requests | إرسال نموذج تسجيل دخول في المتصفح والتقاط ملف تعريف مصادقة |
| `ogma_auth_capture_profile` | send\_requests | التقاط ملفات تعريف الارتباط والتخزين ورموز المصادقة ورموز CSRF المحتملة من المتصفح |
| `ogma_auth_apply_profile` | send\_requests | تطبيق ملف تعريف مصادقة ملتقط على المتصفح |
| `ogma_auth_refresh_csrf` | send\_requests | تحديث رموز CSRF المحتملة من حالة المتصفح |
| `ogma_authz_matrix_test` | send\_requests | إعادة إرسال طلب واحد باستخدام ملفات تعريف مصادقة متعددة |
| `ogma_run_active_probe_workflow` | send\_requests | تشغيل اختبارات نشطة محدودة خاصة بثغرات معينة |
| `ogma_test_race` | send\_requests | إرسال طلب واحد بشكل متزامن والإبلاغ عن الاستجابات التي تختلف عن الحالة الأكثر تكرارا |
| `ogma_test_smuggling` | send\_requests | إرسال اختبارات عدم تزامن الطلبات CL.TE وTE.CL عبر TCP خام |
| `ogma_test_hpp` | send\_requests | إرسال تنويعات تلوث معلمات HTTP |
| `ogma_run_nuclei` | send\_requests | تشغيل قالب واحد لماسح القوالب، مضمن أو مقدم، على عنوان URL مستهدف |
| `ogma_browser_navigate` وأدوات التفاعل مع المتصفح | send\_requests | التحكم في المتصفح المضمن والتقاط حركة المرور الناتجة |
| `ogma_crawl_site` | send\_requests | الزحف إلى هدف ضمن النطاق عبر المتصفح المضمن |
| `ogma_get_replay_session` | لا يوجد | عرض بيانات جلسة إعادة الإرسال الوصفية |
| `ogma_get_replay_attempt` | لا يوجد | عرض بيانات محاولة إعادة الإرسال الوصفية |
| `ogma_list_replay_sessions` | لا يوجد | سرد جلسات إعادة الإرسال |

### سير عمل من خطوتين {#two-step-workflow}

يستخدم زوج أدوات إعادة الإرسال القائم على التأكيد استدعاءين:

1. `ogma_preview_replay_send` - مراجعة الطلب والحصول على رمز تأكيد
2. `ogma_send_replay_request` - التأكيد والإرسال باستخدام الرمز

تنتهي صلاحية رموز التأكيد بعد 5 دقائق، وتُستخدم مرة واحدة، وتنتمي إلى جلسة MCP التي أنشأتها. أجر معاينة جديدة بعد تغيير الطلب أو إعادة تشغيل MCP. لا تنطبق قاعدة الخطوتين هذه على كل أداة إرسال: تستطيع أدوات HTTP المباشرة ومساعدات التكرار وإجراءات المتصفح الإرسال فور تفعيلها.

### جلسة مثال {#example-session}

```
User: Resend HTTP entry abc123 and check the response
AI: (calls ogma_preview_replay_send with http_entry_id="abc123")
    - shows request preview, confirmation token, scope status --
AI: (calls ogma_send_replay_request with confirmation_token and request_hash)
    - shows response status, timing, response preview --
```

### ما يظل غير متاح بأذونات إرسال الطلبات وحدها {#still-not-available-with-request-sending-permissions-only}

* تنفيذ سير العمل
* إنشاء النتائج أو تحديثها
* الحذف

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

## التحكم في الاعتراض {#intercept-control}

تحذير: يسمح التحكم في الاعتراض لعميل MCP بتمرير حركة المرور الحية المحتجزة حاليا في قائمة انتظار اعتراض Ogma أو إسقاطها أو تعديلها.

للتفعيل:

```bash
./ogma-mcp --allow-intercept-control
```

أو عبر متغير البيئة:

```bash
OGMA_MCP_ALLOW_INTERCEPT_CONTROL=true ./ogma-mcp
```

### أدوات الاعتراض {#intercept-tools}

| الأداة | الإذن | الوصف |
|------|-----------|-------------|
| `ogma_get_intercept_status` | intercept\_control | قراءة حالة اعتراض الطلبات والاستجابات وWebSocket |
| `ogma_set_intercept_enabled` | intercept\_control | تفعيل أو تعطيل أوضاع الاعتراض |
| `ogma_list_intercept_queue` | intercept\_control | سرد العناصر المحتجزة حاليا |
| `ogma_get_intercept_item` | intercept\_control | فحص عنصر واحد في قائمة الانتظار |
| `ogma_forward_intercept_item` | intercept\_control | تمرير عنصر في قائمة الانتظار مع تعديل اختياري |
| `ogma_drop_intercept_item` | intercept\_control | إسقاط عنصر في قائمة الانتظار |
| `ogma_intercept_and_modify` | intercept\_control | انتظار عنصر مطابق وتعديله وتمريره |

## تنفيذ سير العمل {#workflow-execution}

تحذير: يشغّل تنفيذ سير العمل منطق سير العمل. ترسل بعض مسارات العمل حركة HTTP أو تنشئ نتائج.

للتفعيل:

```bash
./ogma-mcp --allow-run-workflows
```

### أدوات تنفيذ سير العمل {#workflow-execution-tools}

| الأداة | الإذن | الوصف |
|------|-----------|-------------|
| `ogma_get_workflow_safety` | لا يوجد (للقراءة فقط) | تصنيف الآثار الجانبية لسير العمل |
| `ogma_preview_workflow_run` | run\_workflows | المعاينة والحصول على رمز تأكيد |
| `ogma_run_workflow` | run\_workflows | التنفيذ باستخدام رمز التأكيد |
| `ogma_cancel_workflow_run` | run\_workflows | إلغاء سير عمل نشط قيد التشغيل |

أجر المعاينة باستخدام `workflow_id`، مع `input` لسير عمل تحويل أو `trigger_entry_id` لمدخل ملتقط لسير عمل نشط. نفّذ باستخدام `confirmation_token` و`definition_hash` المعادين؛ تحتاج مسارات عمل التحويل أيضا إلى `input_hash` و`input` نفسه. تنتهي صلاحية الرموز بعد خمس دقائق وتُستخدم مرة واحدة. اقرأ التشغيل الناتج باستخدام `ogma_get_workflow_run`.

يتاح تنفيذ الأتمتة عبر أدوات جلساتها وتشغيلها باستخدام **إذن إرسال الطلبات**، وليس إذن تشغيل سير العمل. لا يتطلب سرد عمليات التشغيل الموجودة وفحصها إذن الإرسال.

### متطلبات الأذونات المشتركة {#cross-permission-requirements}

تتطلب مسارات العمل التي تستخدم `sdk.requests.send` أيضا `--allow-send-requests`.
تتطلب مسارات العمل التي تستخدم `sdk.findings.create` أيضا `--allow-write-findings`.

يعتمد الكشف على التحليل الساكن للنص؛ راجع الملاحظة التحذيرية أدناه.

### ملاحظة تحذيرية بشأن تصنيف الأمان {#safety-classification-advisory-note}

يفحص تصنيف أمان سير العمل نص مصدر JavaScript بحثا عن أنماط مثل `sdk.requests.send`. هذا الكشف غير شامل؛ فقد لا تُكتشف استدعاءات طرق SDK المموهة أو المبنية ديناميكيا. راجع دائما مصدر JavaScript لسير العمل قبل تشغيل مسارات عمل غير موثوقة.

### ما يظل غير متاح بأذونات سير العمل وحدها {#still-not-available-with-workflow-permissions-only}

* تشغيل سير العمل السلبي يدويا
* الحذف
* تعديل متغيرات البيئة

## أمثلة على الطلبات {#example-prompts}

بعد الاتصال:

* "اعرض آخر 20 طلب HTTP إلى example.com"
* "هل توجد نتائج عالية أو حرجة الخطورة في هذا المشروع؟"
* "ما مسارات العمل المفعلة حاليا؟"
* "تحقق من صلاحية استعلام HTTPQL `req.method.eq:\"POST\"`"
* "لخّص الحالة الأمنية للمشروع الحالي"
* "حلّل إدخال HTTP {id} بحثا عن مشكلات أمنية"

## استكشاف الأخطاء وإصلاحها {#troubleshooting}

**رُفض الاتصال:** شغّل Ogma أولا (`ogma --data-dir ./ogma-data`).

**لا يعرض عميل MCP أي أدوات:** تحقق من عنوان URL للنقل أو مسار الملف التنفيذي. يجب على العملاء متابعة جميع مؤشرات `tools/list`؛ تحتوي كل صفحة على ما يصل إلى 40 أداة. تحقق من التصفية لدى العميل وما إذا كان الإصدار المثبت لديك يتضمن الأداة المفقودة.

**جلسة أو رمز تأكيد غير صالح:** أعد الاتصال بعد إعادة التشغيل وأنشئ رمز معاينة جديدا.

**المتصفح غير متاح أو فشل الإجراء:** أبق تطبيق سطح المكتب قيد التشغيل. تحقق من `ogma_browser_health` ومربعات الحوار و[استعادة المتصفح](./guide/mcp-browser.md#recover-from-errors). لا توفر الواجهة الخلفية عديمة الواجهة وحدها جسر متصفح سطح المكتب.

**لا تحتوي لقطة الشاشة على نص مقروء:** استخدم عميلا يدعم محتوى صور MCP الأصلي أو افحص اللقطة الدلالية.

**نتائج فارغة:** يحتاج Ogma إلى التقاط حركة مرور أولا. تصفح مع ضبط الوكيل لتمرير حركة المرور عبر Ogma.