---
url: https://docs.ogmabox.com/fa/mcp-setup.md
description: >-
  اتصال عامل‌های هوش مصنوعی به Ogma از طریق Streamable HTTP یا stdio، پیکربندی
  مجوزها و استفاده از نقاط پایانی محلی مدیریت MCP.
---

# راه‌اندازی سرور MCP متعلق به Ogma {#ogma-mcp-server-setup}

سرور MCP متعلق به Ogma (`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. آن را به‌عنوان سرور **Streamable HTTP** به کلاینت MCP خود اضافه کنید.
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 بومی از نقطهٔ پایانی نمایش‌داده‌شده در تنظیمات استفاده کنید. سرویس گفت‌وگوی ابری بدون کلاینت یا رابط محلی نمی‌تواند به نشانی لوپ‌بک شما دسترسی داشته باشد.

نقطهٔ پایانی HTTP حالت‌مند است: اجازه دهید کلاینت مقداردهی اولیه و هدرهای جلسه را مدیریت کند. نقطهٔ پایانی قدیمی و جداگانهٔ `/sse` وجود ندارد. کلاینت‌های سفارشی باید از [مشخصات انتقال](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports) MCP پیروی کنند.

## چه زمانی از MCP استفاده کنیم {#when-to-use-mcp}

وقتی می‌خواهید دستیار خارجی در این کارها کمک کند، از MCP استفاده کنید:

* خلاصه‌سازی ترافیک ثبت‌شده.
* اولویت‌بندی یافته‌ها.
* تهیهٔ پیش‌نویس گزارش مبتنی بر شواهد.
* بررسی گردش‌های کار و جلسات بازپخش.
* آماده‌سازی اقدامات در محدوده که صریحا تأیید می‌کنید.

اگر در عوض پنجرهٔ دستیار تعبیه‌شده در Ogma را می‌خواهید، از [هوش مصنوعی فضای کاری](./guide/workspace-ai.md) استفاده کنید.

## الزامات اجرای مستقل {#standalone-requirements}

وقتی کلاینت شما به‌جای اتصال به نقطهٔ پایانی HTTP تعبیه‌شده باید یک فایل اجرایی محلی اجرا کند، از stdio استفاده کنید.

* بک‌اند 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 تعبیه‌شده را برای نمونهٔ فعال شروع یا متوقف کند، از صفحهٔ تنظیمات استفاده کنید.

وقتی کلاینت هوش مصنوعی شما انتظار دارد سرور MCP را مستقیما اجرا کند، از فایل اجرایی مستقل `ogma-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 در صورت اجرا. برگرداندن پیکربندی پذیرفته‌شده یا خطا. فقط میزبان‌های اتصال لوپ‌بک مجاز هستند. |
| `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 متفاوت است، از همان استفاده کنید. برای محدوده‌های پیکربندی و گزینه‌های stdio، [پیکربندی MCP در Claude Code](https://code.claude.com/docs/en/mcp) را ببینید. با این پرسش بررسی کنید: «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 escape کنید. برخی کلاینت‌ها به `"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 باشد؛ خروجی همهٔ ابزارها را محدود نمی‌کند. برای بدنهٔ کامل HTTP یا جست‌وجوی هدفمند در بدنه از `ogma_get_http_entry_body`، و برای پیام کامل WebSocket از `ogma_get_ws_message` استفاده کنید.

## ابزارهای نوشتن یافته {#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 | اتصال به URL از نوع 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 | ارسال هم‌زمان یک درخواست و گزارش پاسخ‌هایی که کد وضعیت HTTP آن‌ها با پرتکرارترین کد وضعیت تفاوت دارد |
| `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 وب را مرور کنید.