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

# منابع و ابزارهای MCP {#mcp-resources-and-tools}

سرور MCP در Ogma برای کلاینت‌های خارجی MCP مانند Codex، Claude Code، Cursor و دیگر میزبان‌های Model Context Protocol است. این سرور از دستیار هوش مصنوعی داخل برنامه جداست.

MCP چهار رابط برای کشف ارائه می‌کند:

* **منابع**: مقصدهای خواندن نام‌گذاری‌شده که کلاینت MCP می‌تواند باز کند.
* **قالب‌های منابع**: مقصدهای خواندن پارامتری برای یک ورودی، یافته، گردش کار، اجرا، خروجی یا شیء بازپخش مشخص.
* **ابزارها**: عملیات قابل فراخوانی. برخی فقط خواندنی‌اند. برخی به گزینه‌های راه‌اندازی سرور نیاز دارند.
* **پرامپت‌ها**: دستورالعمل‌های قابل استفادهٔ مجدد که به عامل در برنامه‌ریزی بررسی، آزمون مجدد یا گزارش کمک می‌کنند. دریافت پرامپت، ابزارهای آن را اجرا نمی‌کند.

برای نقاط پایانی اتصال و پیکربندی کلاینت، به [راه‌اندازی MCP](../mcp-setup.md) مراجعه کنید. برای یک توالی تعامل کامل، [خودکارسازی مرورگر با MCP](../guide/mcp-browser.md) را ببینید.

این مرجع پیاده‌سازی فعلی را پوشش می‌دهد: **255 ابزار**، 17 منبع، 9 قالب منبع و 12 پرامپت. همهٔ ابزارها معرفی می‌شوند؛ هنگام فراخوانی همچنان محدودیت‌های مجوز اعمال می‌شوند. نسخه‌های قدیمی نصب‌شده ممکن است ابزارهای کمتری ارائه کنند. پیش از انتخاب ابزار، فهرست را از سرور در حال اجرای خود کشف کنید.

## متدهای پروتکل {#protocol-methods}

این‌ها نام متدهای JSON-RPC هستند، نه مسیرهای URL جداگانه. کلاینت MCP چرخهٔ عمر اتصال را از طریق [HTTP یا ورودی و خروجی استاندارد](../mcp-setup.md#connection-addresses) مدیریت می‌کند.

| متد | کاربرد |
| --- | --- |
| `initialize` | توافق بر سر نسخهٔ پروتکل و قابلیت‌های سرور و کلاینت. |
| `notifications/initialized` | اطلاع دادن تکمیل مقداردهی اولیه به سرور؛ این اعلان شناسهٔ درخواست ندارد. |
| `tools/list` | کشف ابزارها و طرح‌وارهٔ آرگومان‌هایشان، با دنبال کردن `nextCursor`. |
| `tools/call` | اجرای ابزار با `name` و `arguments`. |
| `resources/list` | فهرست کردن منابع نام‌گذاری‌شدهٔ فقط خواندنی. |
| `resources/templates/list` | فهرست کردن قالب‌های URI برای خواندن اشیای منفرد. |
| `resources/read` | خواندن منبع با `uri` کامل آن. |
| `prompts/list` | کشف پرامپت‌های قابل استفادهٔ مجدد و آرگومان‌هایشان. |
| `prompts/get` | دریافت پیام‌های پرامپت با `name` و آرگومان‌های رشته‌ای اختیاری. |

## کشف و فراخوانی ابزارها {#discover-and-call-tools}

نام‌هایی مانند `ogma_search_http_history` شناسهٔ ابزارهای MCP هستند، نه مسیرهای مستقل HTTP. آن‌ها را از طریق `tools/call` در اتصال MCP خود فراخوانی کنید.

1. اتصال را با کلاینت MCP خود مقداردهی اولیه کنید.
2. `tools/list` را فراخوانی کنید. Ogma حداکثر **40 ابزار در هر صفحه** برمی‌گرداند. هر `nextCursor` دریافت‌شده را به‌عنوان `params.cursor` بازگردانید تا دیگر وجود نداشته باشد؛ در غیر این صورت بیشتر ابزارهای مرورگر در کلاینت نمایش داده نخواهند شد.
3. برای شناخت نوع فیلدها، مقادیر شمارشی، پیش‌فرض‌ها، محدودیت‌ها و قالب اشیای تودرتو، `inputSchema` هر ابزار را بخوانید. آرگومان‌ها را از نام ابزار حدس نزنید.
4. پیش از هر اقدامی، `ogma://mcp/permissions` و `ogma://mcp/tool-guide` را بخوانید.
5. ابزار انتخاب‌شده را با یک شیء JSON در `arguments` فراخوانی کنید.

نمونهٔ درخواست JSON-RPC روی اتصال مقداردهی‌شده:

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "ogma_search_http_history",
    "arguments": {
      "q": "req.host.eq:\"example.com\"",
      "limit": 20,
      "offset": 0
    }
  }
}
```

از شناسه‌هایی که ابزارهای فهرست یا جست‌وجو برمی‌گردانند استفاده کنید، نه شناسه‌های حدسی. جست‌وجوی تاریخچه و یافته‌ها از `limit`/`offset` استفاده می‌کند؛ ابزارهای تغییرات مرورگر از `since_entry_id` استفاده می‌کنند. هیچ‌کدام نشانگر غیرشفاف مورد استفادهٔ `tools/list` نیستند.

## خواندن نتایج {#reading-results}

`result.structuredContent` را ترجیح دهید. بلوک محتوای متنی همان پوشش JSON را برای کلاینت‌هایی دارد که فقط نتایج متنی را پشتیبانی می‌کنند. استثنا: نتیجهٔ پیش‌فرض `ogma_browser_snapshot` محتوای ساخت‌یافته ندارد و محتوای متنی آن، درخت خوانا است؛ برای عناصر ساخت‌یافتهٔ آن از `result_detail: "full"` استفاده کنید. در پل محلی REST، به‌جای آن رشتهٔ JSON در `result` را تجزیه کنید؛ آن پل، لایهٔ انتقال MCP نیست.

در صورت شکست ابزار در پل REST، مقدار تجزیه‌شده `{ "error": "..." }` است و پوشش خطای سریال‌شدهٔ ابزار درون آن رشته قرار دارد. وضعیت موفقیت HTTP از پل به‌تنهایی به معنای موفقیت ابزار نیست.

| فیلد پوشش | معنا |
| --- | --- |
| `ok` | اینکه عملیات ابزار موفق بوده است یا نه. `isError` در نتیجهٔ MCP را نیز بررسی کنید. |
| `workflow_stage`, `summary` | زمینهٔ عملیات و توضیح کوتاه. |
| `evidence`, `hypotheses` | شواهد مشاهده‌شده و تفسیرهای جداگانه و تأییدنشده. |
| `next_actions`, `use_next_tools` | کارهای پیگیری پیشنهادی و هدایت ابزارها. |
| `artifacts` | ارجاع به شواهد یا فایل‌های تولیدشده، در صورت وجود. |
| `raw` | دادهٔ مخصوص ابزار. در مسیرهای ساخت‌یافته وجود دارد؛ ابزارهای فشرده فقط با `result_detail: "full"` آن را شامل می‌شوند. ممکن است شیء، آرایه یا متن باشد؛ یک شکل همگانی را فرض نکنید. |

ابزارهای اسکرین‌شات یک بلوک تصویر بومی MCP نیز برمی‌گردانند. بلوک تصویر را بخوانید و انتظار دادهٔ تصویر base64 در فرادادهٔ JSON نداشته باشید. تصویر لحظه‌ای مرورگر به‌صورت پیش‌فرض یک درخت متنی فشرده برمی‌گرداند؛ مقدار `result_detail: "full"` را ارسال کنید تا عناصر ساخت‌یافتهٔ آن را زیر `raw.elements` دریافت کنید. تغییرات شبکه و کنسول مرورگر شامل ورودی‌های ساخت‌یافته‌اند.

فراخوانی موفق اعتبارسنجی همچنان ممکن است `valid: false` را در داده‌هایش برگرداند. شکست اجرای ابزار از `isError: true` استفاده می‌کند؛ درخواست‌های نامعتبر پروتکل از خطاهای JSON-RPC استفاده می‌کنند. پیش از تلاش مجدد، اطلاعات تشخیصی را بخوانید. خطاهای بک‌اند می‌توانند شامل وضعیت HTTP، نقطهٔ پایانی و متن تشخیصی محدود باشند؛ `[truncated]` یعنی متن تشخیصی کوتاه شده است، نه اینکه عملیات موفق بوده است.

این قراردادهای نتیجه از [قالب نتیجهٔ ابزار](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#tool-result) در MCP استفاده می‌کنند.

## منابع {#resources}

| منبع | مقدار برگشتی |
| --- | --- |
| `ogma://status` | سلامت و وضعیت فعلی بک‌اند. |
| `ogma://projects` | همهٔ پروژه‌های Ogma. |
| `ogma://project/current` | پروژهٔ فعال فعلی. |
| `ogma://instances` | نمونه‌های شنوندهٔ پروکسی. |
| `ogma://http-history/recent` | 20 ورودی اخیر HTTP بدون محتوای بدنه. |
| `ogma://ws-history/recent` | 20 اتصال اخیر WebSocket. |
| `ogma://findings` | حداکثر 50 یافته. |
| `ogma://workflows` | گردش‌های کار پیکربندی‌شده. |
| `ogma://workflow-runs/recent` | 20 رکورد اخیر اجرای گردش کار. |
| `ogma://migration/workflows` | گزارش سازگاری مهاجرت گردش کار. |
| `ogma://exports/recent` | 10 کار اخیر خروجی‌گیری. |
| `ogma://capabilities` | خلاصهٔ قابلیت‌های سرور MCP. |
| `ogma://mcp/permissions` | گزینه‌های مجوز فعلی MCP. |
| `ogma://mcp/tool-guide` | هدایت ابزار عامل، قراردادهای خروجی و توالی‌های پیشنهادی مرورگر و تست. |
| `ogma://mcp/report-guide` | توالی تهیهٔ گزارش، الزامات شواهد و بررسی‌های کیفیت. |
| `ogma://mcp/resume` | زمینهٔ بازیابی پایدار پروژهٔ فعال: نقاط ذخیرهٔ ثبت‌شده و فعالیت اخیر ابزارها. |
| `ogma://replay/sessions/recent` | 20 نشست اخیر بازپخش. |

## قالب‌های منابع {#resource-templates}

| قالب | مقدار برگشتی |
| --- | --- |
| `ogma://http-history/{entry_id}` | یک ورودی تاریخچهٔ HTTP. |
| `ogma://ws-history/{connection_id}` | یک اتصال WebSocket. |
| `ogma://findings/{finding_id}` | یک یافته. |
| `ogma://workflows/{workflow_id}` | یک گردش کار. |
| `ogma://workflow-runs/{run_id}` | یک اجرای گردش کار. |
| `ogma://exports/{export_id}` | یک کار خروجی‌گیری. |
| `ogma://replay/sessions/{session_id}` | یک نشست بازپخش. |
| `ogma://replay/attempts/{session_id}/{attempt_id}` | یک تلاش بازپخش. |
| `ogma://workflow-safety/{workflow_id}` | طبقه‌بندی ایمنی گردش کار و مجوزهای لازم. |

این URIها را با `resources/read` بخوانید، نه با درخواست HTTP GET به `ogma://`. پیش از خواندن قالب منبع، شناسه را در آن جای‌گذاری کنید. منابع متن را در `contents` برمی‌گردانند؛ از پوشش نتیجهٔ ابزار بالا استفاده نمی‌کنند.

## پرامپت‌ها {#prompts}

با `prompts/list` کشف کنید، سپس `prompts/get` را همراه با `name` و شیء `arguments` به کار ببرید. مقادیر آرگومان پرامپت رشته هستند. آرگومان‌های الزامی در زیر پررنگ شده‌اند.

| پرامپت | آرگومان‌ها | آنچه آماده می‌کند |
| --- | --- | --- |
| `analyze_http_entry` | **`entry_id`** | بررسی یک تبادل ثبت‌شدهٔ HTTP برای مشکلات امنیتی متکی به شواهد. |
| `summarize_project_security_state` | ندارد | خلاصه کردن یافته‌ها و اولویت‌های رفع مشکل برای پروژهٔ فعال. |
| `triage_findings` | `severity` | اولویت‌بندی یافته‌ها، با امکان محدود کردن به یک شدت. |
| `investigate_suspicious_host` | **`host`** | بازبینی ترافیک ثبت‌شده برای نام میزبان یا IP. |
| `review_workflow_migration_report` | ندارد | توضیح مشکلات سازگاری گردش کار و مراحل مهاجرت. |
| `generate_retest_plan` | **`finding_id`** | آماده کردن مراحل بازتولید و معیارهای قبولی یا شکست برای یک یافته. |
| `create_finding_from_http_evidence` | **`entry_id`** | تحلیل شواهد و هدایت ایجاد یافته در صورت داشتن مجوز. |
| `prepare_evidence_export` | **`export_kind`** | برنامه‌ریزی خروجی‌گیری `http_history`، `findings` یا `automate_results`. |
| `retest_http_entry_with_replay` | **`entry_id`** | هدایت توالی پیش‌نمایش و تأیید بازپخش. |
| `run_workflow_safely` | **`workflow_id`** | بررسی اثرات جانبی گردش کار، پیش‌نمایش و اجرا در صورت داشتن مجوز. |
| `pentest_web_target` | **`target_url`**, `objective` | برنامه‌ریزی ارزیابی مرحله‌ای و مبتنی بر شواهد برای هدفی با مجوز تست. |
| `solve_web_challenge` | **`challenge_url`**, `goal` | برنامه‌ریزی بررسی چالش وب و گردآوری شواهد. |

## مجوزهای ابزارها {#tool-permissions}

بیشتر ابزارهای بررسی همواره در دسترس‌اند. اقداماتی که وضعیت را تغییر می‌دهند یا ترافیک خروجی می‌فرستند، با گزینه‌های راه‌اندازی `ogma-mcp` کنترل می‌شوند:

| گزینهٔ مجوز | قابلیت‌های فعال‌شده |
| --- | --- |
| `--allow-write-findings` | نوشتن یافته و تولید گزارش؛ همچنین تغییرات مشترک پروژه مانند ویرایش متغیر محیطی و تطبیق و جایگزینی. |
| `--allow-export-data` | ایجاد کار خروجی‌گیری. خواندن فرادادهٔ خروجی‌های موجود و اطلاعات دانلود به این گزینه نیاز ندارد. |
| `--allow-read-secrets` | مقادیر متغیر محیطی بدون پوشاندن آن‌ها. این مجوز از مجوز تغییر متغیرها جداست. |
| `--allow-send-requests` | ارسال از طریق بازپخش و خودکارسازی، درخواست‌های مستقیم و دسته‌ای، تعامل مرورگر، کشف، خزش، مسیرهای احراز هویت، کاوش‌های فعال، WebSocket و تغییر پروژه. |
| `--allow-run-workflows` | ابزارهای پیش‌نمایش، اجرا و لغو گردش کار. اجرای خودکارسازی به‌جای آن از مجوز ارسال استفاده می‌کند. |
| `--allow-intercept-control` | خواندن وضعیت و صف رهگیری، تغییر صف و کنترل وضعیت رهگیری. |

مجوزها هنگام فراخوانی ابزار بررسی می‌شوند؛ فهرست شدن ابزار به معنای فعال بودن اقدامات آن نیست. ابزارهای مشاهدهٔ مرورگر می‌توانند مرورگری را که از قبل در حال اجراست بررسی کنند، اما کنترل آن و مدیریت زمینه‌هایش به `allow_send_requests` نیاز دارد. مسیرهای ورود نیز به این مجوز نیاز دارند، از جمله فراخوانی‌های فهرست و تأیید. یادداشت‌ها و کارهای محلی نشست به مجوز نوشتن در پروژه نیاز ندارند.

سهمیهٔ فعالیت در هر دقیقه یا هر نشست وجود ندارد. هر ابزار همچنان اندازهٔ ورودی‌ها و دسته‌ها، مهلت‌ها و بررسی‌های محدودهٔ خود را اعمال می‌کند. اجرای گردش کار ممکن است بسته به عملیات آن، به مجوز اضافی ارسال یا نوشتن یافته نیاز داشته باشد. [راه‌اندازی و مجوزها](../mcp-setup.md#permissions) را ببینید.

همهٔ ابزارها مستقل از مجوزها معرفی می‌شوند. گزینه‌های قدیمی پروفایل دیگر فهرست ابزارها را فیلتر نمی‌کنند. [کشف و هدایت ابزارها](#tool-discovery-and-dispatch) را ببینید.

## فهرست ابزارها {#tool-catalog}

### بازیابی پس از از دست رفتن زمینه {#recovering-after-context-loss}

پس از اتصال مجدد یا از دست رفتن زمینهٔ گفتگو، پیش از آغاز ارزیابی دیگر، `ogma_resume_session` را فراخوانی کنید. پروژهٔ فعال، آخرین نقطهٔ ذخیره و نتایج اخیر ابزارها را بررسی کنید. از `check_live: true` برای بررسی‌های فقط خواندنی و محدود روی ارجاع‌های ذخیره‌شده استفاده کنید؛ این کار اقدامات را تکرار نمی‌کند. پیش از استفادهٔ مجدد از ارجاع عناصر، تصویرهای لحظه‌ای مرورگر را تازه کنید.

پیش از واگذاری کار یا توقف طولانی، یک نقطهٔ ذخیره ثبت کنید. فعالیت ابزارها مشخص می‌کند چه چیزی اجرا شده است؛ نمی‌تواند آزمون بعدی مورد نظر شما را استنتاج کند. هدف، نتیجه‌گیری‌ها، ابهام‌ها و گام‌های بعدی را صریح نگه دارید و به‌جای کپی کردن بدنه‌های بزرگ پاسخ در نقطهٔ ذخیره، با شناسه به شواهد ارجاع دهید.

```json
{
  "name": "ogma_save_checkpoint",
  "arguments": {
    "assessment_id": "authorization-review",
    "objective": "Compare access to invoices across two test identities",
    "progress": "Captured the owner request; the second identity has not been tested yet",
    "next_steps": ["Resume the saved context", "Verify the active project and both identities before replaying"],
    "uncertainties": ["Whether the server checks invoice ownership"]
  }
}
```

```json
{
  "name": "ogma_resume_session",
  "arguments": {
    "assessment_id": "authorization-review",
    "check_live": true
  }
}
```

پیش از واگذاری کار یا فشرده‌سازی زمینه، یک نقطهٔ ذخیره ثبت کنید. هدف، کار انجام‌شده، ابهام‌ها، شناسهٔ شواهد و گام‌های بعدی را صریح ثبت کنید: لاگ خودکار فعالیت، ارجاع‌ها و نتایج را ذخیره می‌کند، نه محتوای درخواست‌ها یا نیت شما را. فراخوانی آغازشده بدون نتیجهٔ کامل، نتیجه‌ای نامعلوم دارد؛ پیش از تلاش مجدد برای ارسال، وضعیت فعلی را بررسی کنید.

سوابق بازیابی پایدار و محدود به پروژه‌اند. با `assessment_id`، خواندن به همان ارزیابی محدود می‌شود؛ برای بررسی فعالیت کل پروژه، آن را از خواندن‌های بازیابی حذف کنید. یادداشت‌ها و کارهای محلی نشست هدف دیگری دارند و نباید با واگذاری پایدار کار اشتباه گرفته شوند.

| ابزار | عملکرد | ورودی‌ها |
| --- | --- | --- |
| `ogma_save_checkpoint` | افزودن رکورد پایدار واگذاری کار. `next_steps` آرایه‌ای از اقدامات صریح است؛ `references` نام‌ها را به شناسه‌های ذخیره‌شده نگاشت می‌کند. برنامه را اجرا نمی‌کند. | **`objective`**, **`progress`**, **`next_steps`**, `uncertainties`, `references` |
| `ogma_resume_session` | خواندن پروژهٔ فعال، آخرین نقطهٔ ذخیره، فعالیت اخیر و راهنمای بازیابی. بررسی‌های زندهٔ اختیاری، ارجاع‌های ذخیره‌شده را بدون تکرار اقدامات بررسی می‌کنند. | `check_live` |
| `ogma_get_session_activity` | خواندن نقاط ذخیره و فعالیت ابزارها از جدیدترین به قدیمی‌ترین. زمان‌ها بر حسب میلی‌ثانیهٔ یونیکس با مبنای UTC هستند. برای صفحه‌بندی، هر دو `before_ms` و `before_id` را از نشانگر برگشتی ارسال کنید. | `kind`, `id`, `since_ms`, `until_ms`, `before_ms`, `before_id`, `search`, `limit` |

هر ردیف ابزار را توضیح می‌دهد و ورودی‌های سطح بالای آن را فهرست می‌کند. **ورودی‌های پررنگ طبق طرح‌وارهٔ ابزار الزامی هستند**؛ بقیه اختیاری‌اند. برخی ابزارها به انتخاب میان ورودی‌ها نیاز دارند، مثلاً منبع بازپخش یا هدف کلیک؛ توضیحات و اعتبارسنجی زمان اجرا این ترکیب‌ها را شرح می‌دهند. برای فیلدهای تودرتو و نوع‌های دقیق، `inputSchema` ابزار در حال اجرا را بخوانید.

هر ابزار یک `assessment_id` اختیاری نیز می‌پذیرد: رشته‌ای غیرخالی با حداکثر 200 نویسه. آن را دوباره استفاده کنید تا زمینهٔ بازیابی یک ارزیابی یکپارچه بماند. این مقدار پروژهٔ فعال را تغییر نمی‌دهد و مجوزی نمی‌دهد. این ورودی مشترک در جدول‌های زیر تکرار نشده است.

### کشف و هدایت ابزارها {#tool-discovery-and-dispatch}

سرور همهٔ ابزارهای ثبت‌شده را معرفی می‌کند. برای شناسایی عملیات و بررسی ورودی‌هایش پیش از فراخوانی، از ابزارهای کشف قابلیت و قرارداد استفاده کنید؛ برای نمایان کردن آن نیازی به تغییر پروفایل ندارید. [راه‌اندازی MCP](../mcp-setup.md#tool-discovery) را ببینید.

از `ogma_browser` برای اقدامات مرورگر تعبیه‌شده، از جمله `snapshot`، `fill_input`، `fill_form`، `console_delta`، `network_delta` و سایر اعضای خانوادهٔ مرورگر استفاده کنید؛ از `ogma_search` برای حوزه‌های جست‌وجو مانند `http_history`، `findings` و `ws_history` استفاده کنید. ابزارهای اختصاصی معادل همچنان در دسترس‌اند.

| ابزار | عملکرد | ورودی‌ها |
| --- | --- | --- |
| `ogma_find_tools` | جست‌وجوی کل فهرست با کلیدواژه‌های وظیفه. پرس‌وجوی دقیق نام ابزار، قرارداد کامل آن را برمی‌گرداند؛ `include_schema` برای تطابق‌های کلیدواژه‌ای نیز قراردادها را درخواست می‌کند. همهٔ واژه‌های جست‌وجو باید مطابقت داشته باشند و نتیجهٔ کوتاه‌شده یا خالی، نبود قابلیت را اثبات نمی‌کند. حد پیش‌فرض 5 و حداکثر 10 است. | **`query`**, `limit`, `include_schema` |
| `ogma_call_tool` | اجرای یک ابزار ثبت‌شدهٔ Ogma با نام. ورودی‌های غیر از `tool` به ابزار نام‌برده ارسال می‌شوند؛ مجوزهای آن همچنان اعمال می‌شوند. | **`tool`** |
| `ogma_browser` | کنترل مرورگر تعبیه‌شده با نام اقدام. هر ابزار دیگر `ogma_browser_*` با پسوند نامش در دسترس است؛ مثلاً `action: "snapshot"` برای `ogma_browser_snapshot`. | **`action`**, `selector`, `tab_id`, `url`, `js`, `text`, `value`, `key`, `cookie`, `timeout_ms` |
| `ogma_search` | جست‌وجوی حوزه‌های دادهٔ Ogma از یک نقطهٔ ورود. هر ابزار دیگر `ogma_search_*` با پسوند نامش در دسترس است. | **`domain`**, `q`, `limit`, `offset` |

### تاریخچهٔ HTTP و پرس‌وجو {#http-history-and-querying}

| ابزار | عملکرد | ورودی‌ها |
| --- | --- | --- |
| `ogma_search_http_history` | جست‌وجوی تاریخچهٔ HTTP با HTTPQL و برگرداندن فرادادهٔ درخواست و پاسخ. | `q`, `limit`, `offset`, `result_detail` |
| `ogma_get_http_entry` | دریافت یک ورودی HTTP با شناسه، با پیش‌نمایش اختیاری بدنه‌ها. | **`entry_id`**, `include_body_preview`, `result_detail` |
| `ogma_get_http_entry_body` | دریافت بدنهٔ کامل درخواست و/یا پاسخ برای یک ورودی HTTP. | **`entry_id`**, **`part`**, `search_pattern`, `result_detail` |
| `ogma_validate_httpql` | اعتبارسنجی عبارت HTTPQL. | **`query`** |
| `ogma_analyze_http_entry_security` | بازبینی یک ورودی HTTP برای رفتار و شواهد مرتبط با امنیت. | **`entry_id`** |
| `ogma_search_by_vulnerability_pattern` | جست‌وجوی ترافیک ثبت‌شده برای الگوهای مرتبط با آسیب‌پذیری. | **`pattern_type`**, `limit` |

### WebSocket و SSE {#websocket-and-sse}

| ابزار | عملکرد | ورودی‌ها |
| --- | --- | --- |
| `ogma_search_ws_history` | جست‌وجوی تاریخچهٔ اتصال WebSocket با StreamQL. | `q`, `limit`, `offset` |
| `ogma_get_ws_messages` | دریافت پیام‌های ذخیره‌شدهٔ یک اتصال WebSocket. | **`connection_id`**, `limit`, `offset` |
| `ogma_get_ws_message` | خواندن یک پیام کامل بدون کوتاه‌سازی پیش‌نمایش فهرست؛ متن UTF-8 و محتوای باینری یا کنترلی base64 است. | **`message_id`** |
| `ogma_validate_streamql` | اعتبارسنجی عبارت StreamQL. | **`query`** |
| `ogma_get_ws_messages_live` | دریافت پیام‌های زندهٔ WebSocket که با ابزارهای پایش مرورگر ثبت شده‌اند. | `host`, `limit` |
| `ogma_create_ws_replay_session` | ایجاد نشست بازپخش WebSocket. | **`ws_connection_id`** |
| `ogma_connect_ws_replay` | برقراری اتصال نشست بازپخش WebSocket. | **`ws_session_id`** |
| `ogma_send_ws_replay_message` | ارسال پیام از طریق نشست بازپخش WebSocket. | **`ws_session_id`**, **`payload`**, `message_type` |
| `ogma_list_ws_replay_sessions` | فهرست کردن نشست‌های بازپخش WebSocket. | `result_detail` |
| `ogma_get_ws_replay_messages` | خواندن متن تبادل نشست بازپخش WebSocket، نه تاریخچهٔ ثبت‌شده. برای شروع، `cursor` را حذف کنید؛ `next_cursor` برگشتی را ارسال کنید و تا زمانی که `has_more` برقرار است همهٔ صفحات را دریافت کنید. | **`ws_session_id`**, `cursor`, `limit`, `result_detail` |
| `ogma_get_ws_replay_message` | خواندن یک پیام بازپخش WebSocket بدون کوتاه‌سازی پیش‌نمایش محتوا؛ `payload_base64` بایت‌های کدگذاری‌شده با base64 را مشخص می‌کند. | **`message_id`**, `result_detail` |
| `ogma_disconnect_ws_replay` | قطع اتصال نشست بازپخش WebSocket با حفظ نشست و متن تبادل؛ اتصال در انتظار را نیز لغو می‌کند. | **`ws_session_id`** |
| `ogma_browser_get_ws_frames` | خواندن فریم‌های WebSocket ثبت‌شده توسط مرورگر تعبیه‌شده. | `limit`, `connection_url`, `direction` |
| `ogma_browser_start_ws_capture` | شروع ثبت فریم‌های WebSocket در سمت مرورگر. | ندارد |
| `ogma_browser_send_ws_message` | ارسال پیام WebSocket از زمینهٔ مرورگر. | **`payload`**, `connection_url` |

### یافته‌ها و شواهد {#findings-and-evidence}

| ابزار | عملکرد | ورودی‌ها |
| --- | --- | --- |
| `ogma_search_findings` | جست‌وجوی یافته‌ها بر اساس شدت، گزارش‌دهنده، متن، حد و جابه‌جایی. | `severity`, `reporter`, `q`, `limit`, `offset` |
| `ogma_get_finding` | دریافت یک یافته با شناسه. | **`finding_id`** |
| `ogma_preview_finding_from_evidence` | پیش‌نمایش پیش‌نویس یافته از یک ورودی HTTP بدون ایجاد آن. | **`entry_id`**, `reporter` |
| `ogma_create_finding` | ایجاد یافته با فراداده، برچسب‌ها، میزان اطمینان، راهکار رفع و پیوندهای اختیاری شواهد. | **`title`**, `severity`, `status`, `description`, `reporter`, `tags`, `dedupe_key`, `entry_id`, `replay_attempt_id`, `automate_result_id`, `ws_message_id`, `confidence`, `remediation`, `skip_dedup_check` |
| `ogma_update_finding` | به‌روزرسانی یافتهٔ موجود. | **`finding_id`**, **`title`**, `severity`, `status`, `description`, `reporter`, `tags`, `dedupe_key`, `confidence`, `remediation` |
| `ogma_add_finding_tag` | افزودن برچسب به یافته بدون جایگزینی برچسب‌های موجود. | **`finding_id`**, **`tags`** |
| `ogma_link_finding_evidence` | افزودن شواهد HTTP، بازپخش، خودکارسازی، WebSocket ثبت‌شده یا پیام بازپخش WS به یافته. پیوندهای پشتیبان جایگزین شواهد اصلی آن نمی‌شوند. | **`finding_id`**, `entry_id`, `replay_attempt_id`, `automate_result_id`, `ws_message_id`, `ws_replay_message_id` |
| `ogma_delete_finding` | حذف یافته. | **`finding_id`** |
| `ogma_create_finding_from_entry` | ایجاد یافته از ورودی ثبت‌شدهٔ HTTP. هدرها و بدنه‌های درخواست و پاسخ را به‌عنوان شواهد HTTP با قالب Markdown درج می‌کند و بدنهٔ پاسخ را به 3000 نویسه محدود می‌کند. امتیاز CVSS را از جزئیات ارائه‌شده، همراه با CWE، کد اثبات مفهوم و منابع اضافه می‌کند. | **`entry_id`**, **`title`**, **`severity`**, **`vulnerability_type`**, **`description`**, **`impact`**, **`remediation`**, `confidence`, `reporter`, `tags`, `affected_parameter`, `proof_of_concept`, `cvss_breakdown`, `cwe`, `poc_code`, `references`, `skip_dedup_check` |
| `ogma_get_finding_evidence_summary` | خلاصه کردن شواهد پیوندشده به یافته. | **`finding_id`** |
| `ogma_record_finding_verification` | ثبت نتیجهٔ مستقل آزمون مجدد برای یافته: `verified`، `refuted` یا `inconclusive`. جدیدترین نتیجه معتبر است؛ بنابراین رد بعدی جای تأیید قبلی را می‌گیرد و ابزار ردیف ذخیره‌شده را گزارش می‌کند. | **`finding_id`**, **`state`**, **`method`**, **`reason`**, `evidence_entry_id`, `control_entry_id`, `canary_id` |
| `ogma_check_canary` | ایجاد توکن با `label` و `purpose`، یا بررسی مجدد توکن موجود با `canary_id` بدون ایجاد توکن دیگر. ترافیک ثبت‌شده را برای ورودی‌های مطابق جست‌وجو می‌کند. تطابق در بدنهٔ پاسخ، شاهد بازیابی توکن است؛ تطابق در بدنهٔ درخواست فقط نشان می‌دهد توکن ارسال شده است. | **`canary_id`** یا **`label`** و **`purpose`**, `finding_id`, `hosted_path`, `limit` |
| `ogma_export_findings_report` | ایجاد خروجی گزارش یافته‌ها. | **`format`**, `title`, `summary`, `scope`, `tester`, `include_evidence` |

### خروجی‌گیری {#exports}

| ابزار | عملکرد | ورودی‌ها |
| --- | --- | --- |
| `ogma_preview_export_plan` | پیش‌نمایش محتوا و قالب خروجی بدون ایجاد کار. | **`kind`**, **`format`**, `limit`, `q`, `severity`, `reporter` |
| `ogma_create_export_job` | ایجاد کار خروجی‌گیری برای تاریخچه، نتایج جست‌وجو، یافته‌ها یا نتایج خودکارسازی. | **`name`**, **`kind`**, **`format`**, `limit`, `offset`, `scope`, `q`, `severity`, `reporter`, `run_id` |
| `ogma_get_export_job` | دریافت یک کار خروجی‌گیری با شناسه. | **`export_id`** |
| `ogma_list_export_jobs` | فهرست کردن کارهای خروجی‌گیری. | `limit`, `offset` |
| `ogma_get_export_download_info` | دریافت فرادادهٔ دانلود برای خروجی کامل‌شده. | **`export_id`** |

### بازپخش و ارسال درخواست {#replay-and-request-sending}

| ابزار | عملکرد | ورودی‌ها |
| --- | --- | --- |
| `ogma_preview_replay_send` | پیش‌نمایش ارسال بازپخش و برگرداندن توکن تأیید. | `http_entry_id`, `replay_session_id`, `method`, `path`, `query`, `body`, `result_detail` |
| `ogma_send_replay_request` | ارسال درخواست بازپخش با توکن تأیید. | **`confirmation_token`**, **`request_hash`**, `result_detail` |
| `ogma_create_replay_session_from_history` | ایجاد نشست بازپخش از یک ورودی ثبت‌شدهٔ HTTP. | **`entry_id`**, `name`, `result_detail` |
| `ogma_create_replay_session_raw` | ایجاد نشست بازپخش از تعریف خام درخواست. | `name`, **`host`**, **`port`**, `tls`, `method`, `path`, `headers`, `body` |
| `ogma_get_replay_session` | دریافت فرادادهٔ نشست بازپخش و فهرست صفحه‌بندی‌شدهٔ تلاش‌ها. | **`session_id`**, `attempts_limit`, `attempts_offset`, `result_detail` |
| `ogma_get_replay_attempt` | دریافت یک تلاش بازپخش. | **`session_id`**, **`attempt_id`**, `result_detail` |
| `ogma_list_replay_sessions` | فهرست کردن نشست‌های بازپخش. | `limit`, `offset`, `result_detail` |
| `ogma_create_replay_sequence` | ایجاد توالی چندمرحله‌ای بازپخش از نشست‌های بازپخش موجود، به ترتیب اجرای مراحل؛ `collection_id` متغیرهای آن مجموعه را هنگام اجرا اعمال می‌کند. | **`name`**, **`session_ids`**, `collection_id` |
| `ogma_run_replay_sequence` | اجرای توالی ذخیره‌شدهٔ بازپخش که ترافیک واقعی به بیرون می‌فرستد. `plan` شاخص مراحل را به ترتیب اجرا فهرست می‌کند؛ ورودی‌ها می‌توانند مراحل را تکرار، حذف یا بازچینی کنند و حذف `plan` هر مرحلهٔ ذخیره‌شده را یک بار به ترتیب اجرا می‌کند. `plan` خالی پذیرفته نمی‌شود. | **`sequence_id`**, `plan` |
| `ogma_repeat_request` | تکرار درخواست موجود با تغییرات اختیاری. | **`request_id`**, `params`, `headers`, `body`, `cookies`, `url`, `method`, `method_override`, `path`, `path_override`, `entry_id`, `headers_add`, `headers_remove`, `body_text`, `body_json`, `body_b64`, `body_base64`, `raw_request_base64`, `result_detail` |
| `ogma_replay_with_modifications` | بازپخش درخواست ثبت‌شدهٔ HTTP با تغییر مقادیر در سطح فیلد و برگرداندن پاسخ همراه با خلاصهٔ تفاوت‌ها. | **`entry_id`**, `method_override`, `path_override`, `headers_add`, `headers_remove`, `body`, `body_text`, `body_json`, `body_b64`, `body_base64`, `raw_request_base64`, `request_id`, `method`, `path`, `headers`, `follow_redirects`, `timeout_secs`, `result_detail` |
| `ogma_http_request` | ارسال درخواست مستقیم HTTP از طریق رابط ابزار MCP. با `raw_request_base64`، ورودی `max_responses` چند فریم پاسخ را از همان اتصال می‌خواند و در اولین پاسخ متوقف نمی‌شود؛ `followup_raw_request_base64` پس از خواندن اولین پاسخ، درخواستی را روی همان اتصال می‌نویسد. پاسخ به درخواستی که بایت‌های ارسالی مطرح نکرده‌اند، عدم همگامی درخواست را تأیید می‌کند، نه صرفاً حدس می‌زند. هر دو ورودی فقط در حالت خام کاربرد دارند. | **`host`**, `port`, `tls`, `method`, `path`, `headers`, `body_b64`, `method_override`, `path_override`, `headers_add`, `headers_remove`, `body`, `body_text`, `body_json`, `body_base64`, `raw_request_base64`, `max_responses`, `followup_raw_request_base64`, `result_detail` |
| `ogma_bulk_send_requests` | ارسال دسته‌ای از درخواست‌ها. | **`base_session_id`**, **`payloads`**, **`placeholder`**, `max_requests` |
| `ogma_fetch_url` | دریافت URL و برگرداندن وضعیت، هدرها و پیش‌نمایش بدنهٔ پاسخ. | **`url`**, `method`, `headers`, `body_b64`, `max_bytes` |
| `ogma_follow_redirect` | دریافت URL، دنبال کردن زنجیرهٔ تغییر مسیر و گزارش هر گام. | **`url`**, `method`, `headers`, `body_b64`, `max_hops`, `timeout_secs` |
| `ogma_fuzz_parameter` | جایگزین کردن جای‌نگهدار `{{FUZZ}}` با مقادیر فهرست واژه و خوشه‌بندی پاسخ‌ها بر اساس وضعیت و اندازه. | **`url`**, `method`, `headers`, `body_template`, **`wordlist`**, `timeout_secs`, `stop_on_match` |
| `ogma_multipart_upload` | ارسال درخواست‌های فرم چندبخشی با فیلدهای متن و فایل برای تست بارگذاری. | **`url`**, **`fields`**, `headers`, `timeout_secs` |
| `ogma_test_login` | تست نقطهٔ پایانی ورود با جفت‌های اطلاعات احراز هویت ارائه‌شده یا پیش‌فرض و گزارش شواهد. | **`url`**, `credentials`, `username_field`, `password_field`, `submit_selector`, `success_pattern`, `failure_pattern`, `max_attempts` |

### گردش‌های کار و خودکارسازی {#workflows-and-automate}

| ابزار | عملکرد | ورودی‌ها |
| --- | --- | --- |
| `ogma_search_workflows` | فهرست و فیلتر کردن گردش‌های کار. | `workflow_type`, `enabled`, `limit`, `offset` |
| `ogma_get_workflow` | دریافت یک گردش کار با شناسه. | **`workflow_id`** |
| `ogma_get_workflow_run` | دریافت یک رکورد اجرای گردش کار. | **`run_id`** |
| `ogma_validate_workflow_import` | اعتبارسنجی بستهٔ گردش کار برای سازگاری با وارد کردن آن. | **`bundle_json`** |
| `ogma_get_workflow_safety` | دریافت طبقه‌بندی ایمنی و مجوز گردش کار. | **`workflow_id`** |
| `ogma_preview_workflow_run` | پیش‌نمایش اجرای گردش کار پیش از اجرا. | **`workflow_id`**, `input`, `trigger_entry_id` |
| `ogma_run_workflow` | اجرای گردش کار. | **`confirmation_token`**, **`definition_hash`**, `input_hash`, `input` |
| `ogma_cancel_workflow_run` | لغو اجرای گردش کار. | **`run_id`** |
| `ogma_list_automate_sessions` | فهرست کردن نشست‌های خودکارسازی. | `limit`, `offset` |
| `ogma_get_automate_session` | دریافت یک نشست خودکارسازی. | **`session_id`** |
| `ogma_create_automate_session` | ایجاد نشست خودکارسازی با یک نقطهٔ تزریق. `inject_into` آن را به‌صورت `query:<name>`، `header:<name>` یا `body` انتخاب می‌کند؛ پیش‌فرض، اولین پارامتر پرس‌وجو و سپس بدنه است. | **`entry_id`**, `name`, **`payloads`**, `inject_into`, `placeholder_start`, `placeholder_end`, `worker_count`, `delay_ms` |
| `ogma_run_automate_session` | اجرای نشست خودکارسازی. | **`session_id`** |
| `ogma_list_automate_runs` | فهرست کردن اجراهای خودکارسازی. | **`session_id`**, `limit`, `offset` |
| `ogma_get_automate_run` | دریافت یک اجرای خودکارسازی. | **`run_id`** |
| `ogma_cancel_automate_run` | لغو اجرای خودکارسازی. | **`run_id`** |
| `ogma_list_automate_results` | فهرست کردن نتایج خودکارسازی. | **`run_id`**, `limit`, `offset`, `min_status`, `max_status` |
| `ogma_get_automate_result` | دریافت یک نتیجهٔ خودکارسازی. | **`run_id`**, **`seq`** |
| `ogma_load_skill` | بارگذاری راهنمای مهارت‌های داخلی MCP در زمینهٔ دستیار. | **`skills`** |

### اسکنر {#scanner}

شروع اسکن‌های پسیو یا فعال به مجوز نوشتن یافته نیاز دارد، زیرا اسکن‌ها می‌توانند یافته ایجاد کنند. فهرست کردن قواعد اسکنر و دسته‌های بررسی فعال به این مجوز نیاز ندارد.

| ابزار | عملکرد | ورودی‌ها |
| --- | --- | --- |
| `ogma_run_passive_scan` | اجرای بررسی‌های اسکنر پسیو روی یک ورودی HTTP. | **`entry_id`** |
| `ogma_run_passive_scan_all` | اجرای بررسی‌های اسکنر پسیو روی تاریخچهٔ ثبت‌شده. | ندارد |
| `ogma_list_scanner_rules` | فهرست کردن قواعد تشخیص اسکنر. | ندارد |
| `ogma_list_active_checks` | فهرست کردن دسته‌های بررسی اسکنر فعال با شناسه و توضیح آن‌ها و گزارش تعداد دسته‌هایی که یافته ایجاد می‌کنند. دسته‌های پیاده‌سازی‌نشده فهرست می‌شوند، اما هرگز یافته تولید نمی‌کنند. | ندارد |
| `ogma_scan_active` | اجرای اسکنر فعال که محتوای اثبات می‌فرستد و فقط برای دسته‌هایی یافته ایجاد می‌کند که از پاسخ تأییدشان کند. برای اسکن یک ورودی، `entry_id` را ارسال کنید یا برای بررسی تاریخچهٔ اخیر آن را حذف کنید. طولانی است و به‌صورت وظیفه ارائه می‌شود؛ مسیر همگام وضعیت کار را تا رسیدن به حالت نهایی بررسی می‌کند و `job_id`، شمارنده‌های پیشرفت و `findings_created` را گزارش می‌کند. به مجوز نوشتن یافته نیاز دارد. | `entry_id`, `checks`, `concurrency`, `delay_ms`, `scan_headers` |

### رهگیری {#intercept}

| ابزار | عملکرد | ورودی‌ها |
| --- | --- | --- |
| `ogma_get_intercept_status` | دریافت وضعیت فعلی رهگیری. | ندارد |
| `ogma_set_intercept_enabled` | فعال یا غیرفعال کردن رهگیری. | `request_enabled`, `response_enabled`, `websocket_enabled` |
| `ogma_list_intercept_queue` | فهرست کردن موارد رهگیری‌شده در صف. | ندارد |
| `ogma_get_intercept_item` | دریافت یک مورد رهگیری‌شده از صف. | **`id`** |
| `ogma_forward_intercept_item` | عبور دادن یک مورد رهگیری‌شده، با تغییرات اختیاری. | **`id`**, `method`, `path`, `headers`, `body`, `status_override` |
| `ogma_drop_intercept_item` | حذف یک مورد رهگیری‌شده. | **`id`** |
| `ogma_intercept_and_modify` | انتظار برای درخواست یا پاسخ زندهٔ رهگیری‌شده، اعمال وصله‌های JSON، جایگزینی‌های عبارت منظم یا جایگزینی کامل بدنه و سپس عبور دادن آن. | **`direction`**, `host_pattern`, `path_pattern`, `wait_secs`, `json_patches`, `regex_replacements`, `body_b64`, `status_override`, `forward_unmatched` |

### پروکسی، محدوده و شبکه {#proxy-scope-and-network}

| ابزار | عملکرد | ورودی‌ها |
| --- | --- | --- |
| `ogma_list_proxy_listeners` | فهرست کردن شنونده‌های پروکسی. | ندارد |
| `ogma_start_proxy_listener` | راه‌اندازی شنوندهٔ پروکسی. | **`listener_id`** |
| `ogma_stop_proxy_listener` | توقف شنوندهٔ پروکسی. | **`listener_id`** |
| `ogma_list_scope_presets` | فهرست کردن تنظیمات ازپیش‌تعریف‌شدهٔ محدوده. | ندارد |
| `ogma_create_scope_preset` | ذخیرهٔ تنظیم ازپیش‌تعریف‌شدهٔ محدوده بدون فعال کردن آن. به مجوز ارسال نیاز دارد. هر قاعده به `pattern` و `include` نیاز دارد؛ `rule_type` اختیاری تطبیق میزبان، CIDR، مسیر یا عبارت منظم را انتخاب می‌کند. قواعد مسیر از `pattern` برای میزبان و `path_pattern` برای مسیر استفاده می‌کنند. تنظیم برگشتی را جداگانه با `ogma_set_active_scope` فعال کنید. | **`name`**, **`rules`**, `httpql_expression` |
| `ogma_get_active_scope` | دریافت محدودهٔ فعال. | ندارد |
| `ogma_set_active_scope` | تنظیم محدودهٔ فعال. | `preset_id` |
| `ogma_local_ips` | فهرست کردن نشانی‌های IP محلی مفید برای شنونده‌ها و تماس‌های برگشتی. | ندارد |
| `ogma_get_tls_info` | دریافت اطلاعات TLS برای هدف یا اتصال ثبت‌شده. | **`host`**, `port` |

### نقشهٔ سایت، نقاط پایانی و OAST {#sitemap-endpoints-and-oast}

| ابزار | عملکرد | ورودی‌ها |
| --- | --- | --- |
| `ogma_get_sitemap` | دریافت نقشهٔ سایت ثبت‌شده. | `host`, `show_api_only` |
| `ogma_get_sitemap_parameters` | دریافت پارامترهای کشف‌شده برای یک مسیر نقشهٔ سایت. | **`host`**, **`port`**, **`path`** |
| `ogma_list_extracted_endpoints` | فهرست کردن نقاط پایانی استخراج‌شده از ترافیک و محتوای فرانت‌اند. | `limit`, `offset` |
| `ogma_discovery_start` | شروع کار کشف محتوا در پس‌زمینه برای میزبان و درگاه داخل محدوده؛ شناسهٔ کار را برمی‌گرداند. | **`host`**, **`port`**, `tls`, `base_path`, `config` |
| `ogma_discovery_list` | فهرست کردن کارهای کشف و پیشرفت آن‌ها در پروژهٔ فعال. | ندارد |
| `ogma_discovery_get` | دریافت وضعیت کار کشف و نتایج کشف‌شده. | **`job_id`** |
| `ogma_discovery_cancel` | درخواست لغو کار کشف در حال اجرا. | **`job_id`** |
| `ogma_import_openapi_spec` | وارد کردن مشخصات OpenAPI برای ایجاد نقاط پایانی اولیه و ساختارهای درخواست. | **`spec_content`**, `base_url`, `collection_name` |
| `ogma_get_oast_config` | دریافت پیکربندی شنوندهٔ OAST. | ندارد |
| `ogma_get_oast_reachability` | گزارش اینکه میزبان تماس برگشتی پیکربندی‌شدهٔ OAST از هدف قابل دسترسی است یا نه، همراه با علت عدم دسترسی و مراحل رفع آن. پیش از اعتماد به محتوای تست کور آن را بررسی کنید: تماس برگشتی غیرقابل دسترسی، نتیجهٔ منفی کاذب ایجاد می‌کند که به‌صورت نبود آسیب‌پذیری تعبیر می‌شود. | ندارد |
| `ogma_list_oast_interactions` | فهرست کردن تعامل‌های OAST. همهٔ فیلترها در بک‌اند پیش از جدا کردن صفحه اعمال می‌شوند؛ بنابراین تعداد کل شامل همهٔ تطابق‌هاست، نه طول صفحه، و محدود کردن به یک برچسب توکن یا نشانی مبدأ هرگز تماس برگشتی مطابقی را در ادامهٔ جریان پنهان نمی‌کند. `token_label` نقطهٔ تزریقی است که توکن را حمل کرده است: نام پارامتر پرس‌وجو، نام هدر یا `body`. برچسب‌ها همراه با توکن‌هایشان در حافظه نگهداری می‌شوند؛ بنابراین برچسبی که توکنش از حافظه کنار رفته است، به‌جای تطبیق ردیف‌های قدیمی با هیچ‌چیز مطابقت ندارد. | `limit`, `offset`, `token_id`, `token_label`, `protocol`, `source_ip`, `since` |

### افزودن نشانه به تاریخچه {#history-annotation}

| ابزار | عملکرد | ورودی‌ها |
| --- | --- | --- |
| `ogma_set_entry_color` | تنظیم برچسب رنگی ورودی تاریخچه. | **`entry_id`**, **`color`** |
| `ogma_add_entry_tag` | افزودن برچسب به ورودی تاریخچه. | **`entry_id`**, **`tag`** |
| `ogma_remove_entry_tag` | حذف برچسب از ورودی تاریخچه. | **`entry_id`**, **`tag`** |

### کنترل مرورگر {#browser-control}

برای انتخاب میان تصویرهای لحظه‌ای، انتخابگرها و اسکرین‌شات‌ها، [راهنمای مرورگر](../guide/mcp-browser.md) را ببینید. فرض نکنید هر ابزار مرورگر `tab_id` یا `element_ref` را می‌پذیرد؛ فقط ورودی‌های فهرست‌شده برای همان ابزار را استفاده کنید.

| ابزار | عملکرد | ورودی‌ها |
| --- | --- | --- |
| `ogma_browser_launch` | راه‌اندازی مرورگر Ogma. | `proxy_port` |
| `ogma_browser_navigate` | بردن مرورگر به یک URL. | **`url`**, `tab_id`, `wait_for_load`, `timeout_ms`, `result_detail` |
| `ogma_browser_get_dom` | رفتن به صفحه و برگرداندن DOM رندرشده همراه با نتایج اختیاری انتخابگر، پس از اجرای JavaScript. | **`url`**, `wait_secs`, `selectors`, `js_eval`, `include_full_html` |
| `ogma_browser_screenshot` | ثبت وضعیت صفحهٔ مرورگر. | `tab_id`, `result_detail` |
| `ogma_browser_execute_js` | اجرای JavaScript در مرورگر. | **`script`**, `tab_id` |
| `ogma_browser_get_source` | دریافت منبع DOM صفحهٔ فعلی. | `tab_id`, `format`, `max_chars` |
| `ogma_browser_get_cookies` | دریافت کوکی‌های مرورگر. | `tab_id` |
| `ogma_browser_set_cookie` | تنظیم کوکی مرورگر. | **`name`**, **`value`**, `domain`, `path`, `http_only`, `secure` |
| `ogma_browser_new_tab` | باز کردن زبانهٔ جدید مرورگر. | `url` |
| `ogma_browser_close_tab` | بستن زبانهٔ مرورگر. | `tab_id` |
| `ogma_browser_get_tabs` | فهرست کردن زبانه‌های مرورگر. | `result_detail` |
| `ogma_browser_click` | کلیک روی `element_ref` از تصویر لحظه‌ای، یا مختصات صریح `x` و `y`. | `element_ref`, `snapshot_id`, `x`, `y`, `button`, `click_count`, `modifiers`, `offset_x`, `offset_y`, `force`, `timeout_ms`, `tab_id`, `expect`, `observation`, `result_detail` |
| `ogma_browser_type_text` | تایپ متن در مرورگر. | **`text`**, `tab_id`, `snapshot_id` |
| `ogma_browser_fill_input` | تنظیم ورودی با دقیقاً یک `selector` در CSS یا `element_ref` از تصویر لحظه‌ای؛ مقدار خالی آن را پاک می‌کند. فرم را ارسال نمی‌کند. | **`selector`**, `value`, `tab_id`, **`element_ref`**, `snapshot_id`, `expect`, `observation`, `result_detail` |
| `ogma_browser_fill_form` | جایگزینی متن چند ورودی، ناحیهٔ متن یا عنصر با محتوای قابل ویرایش در یک فراخوانی و به ترتیب ارائه‌شده؛ هر فیلد از دقیقاً یک `element_ref` یا `selector` همراه با `value` استفاده می‌کند. در اولین شکست متوقف می‌شود و فرم را ارسال نمی‌کند. | **`fields`**, `snapshot_id`, `tab_id`, `expect`, `observation`, `result_detail` |
| `ogma_browser_click_selector` | کلیک روی عنصر با انتخابگر. | **`selector`**, `tab_id`, `expect`, `observation`, `result_detail` |
| `ogma_browser_submit_form` | ارسال فرم. | `selector`, `tab_id`, `expect`, `observation`, `result_detail` |
| `ogma_browser_get_page_links` | استخراج پیوندهای صفحهٔ فعلی. | `tab_id` |
| `ogma_browser_get_page_forms` | استخراج فرم‌های صفحهٔ فعلی. مقدار `include_templates` را `true` تنظیم کنید، با پیش‌فرض `false`، تا URL مطلق مقصد هر فرم، متد، نوع محتوای مؤثر، کنترل‌های قابل ارسال با مقادیر فعلی، کنترل‌های ارسال و `token_candidates` شبیه CSRF اضافه شوند. فرم‌های چندبخشی به‌جای بدنهٔ ساخته‌شده به `ogma_multipart_upload` ارجاع می‌دهند. به مجوز `send_requests` نیاز دارد. | `tab_id`, `include_templates` |
| `ogma_browser_form_to_replay` | ایجاد نشست بازپخش از فرم صفحهٔ زنده، با خواندن مقادیر فعلی فیلدها و کوکی‌های زندهٔ مرورگر در همان لحظه، همراه با هدرهای Origin و Referer برگرفته از صفحه. درخواست را ارسال نمی‌کند. | **`form_selector`**, `tab_id`, `name` |
| `ogma_browser_scroll` | پیمایش صفحهٔ فعلی. | `selector`, `x`, `y`, `tab_id` |
| `ogma_browser_wait_for_selector` | انتظار برای عنصر مطابق انتخابگر. | **`selector`**, `timeout_ms`, `tab_id`, `snapshot_id` |
| `ogma_browser_get_network_log` | دریافت رویدادهای شبکهٔ مرورگر. | `host`, `since_ms`, `limit` |
| `ogma_browser_go_back` | بازگشت در تاریخچهٔ مرورگر. | `tab_id`, `snapshot_id` |
| `ogma_browser_go_forward` | رفتن به جلو در تاریخچهٔ مرورگر. | `tab_id`, `snapshot_id` |
| `ogma_browser_reload` | بارگذاری مجدد صفحه. | `tab_id`, `snapshot_id` |
| `ogma_browser_find_text` | پیدا کردن متن در صفحهٔ فعلی. | **`text`**, `tab_id`, `snapshot_id` |
| `ogma_browser_clear_data` | پاک کردن داده‌های مرورگر. | `types` |
| `ogma_crawl_site` | خزش هدف از طریق مرورگر تعبیه‌شده در محدودهٔ فعال و برگرداندن دادهٔ پوشش. | **`start_url`**, `max_pages`, `max_depth`, `wait_ms`, `tab_id` |

### عناصر مرورگر و انتظار {#browser-elements-and-waits}

| ابزار | عملکرد | ورودی‌ها |
| --- | --- | --- |
| `ogma_browser_snapshot` | خواندن درخت معنایی فشردهٔ صفحه با ارجاع و وضعیت عناصر؛ `result_detail: "full"` به‌جای آن پوشش ساخت‌یافته را با عناصر زیر `raw.elements` برمی‌گرداند. امکان درخواست تغییرات نسبت به تصویر لحظه‌ای قبلی وجود دارد. | `tab_id`, `previous_snapshot_id`, `changes_only`, `focus_ref`, `text`, `max_elements`, `max_text_length`, `include_hidden`, `max_depth`, `result_detail` |
| `ogma_browser_hover` | نگه داشتن نشانگر روی عنصر ارجاع‌شده و گزارش منوها یا راهنماهای تازه ظاهرشده. | **`element_ref`**, `snapshot_id`, `offset_x`, `offset_y`, `modifiers`, `timeout_ms`, `tab_id` |
| `ogma_browser_select_option` | انتخاب گزینه‌های فهرست کشویی با مقدار، برچسب یا شاخص و گزارش مقادیر انتخاب‌شده. | **`element_ref`**, `snapshot_id`, **`values`**, `match_mode`, `allow_first_match`, `timeout_ms`, `tab_id` |
| `ogma_browser_check` | تنظیم صریح وضعیت کادر انتخاب یا دکمهٔ رادیویی، به‌جای تغییر بدون آگاهی از وضعیت. | **`element_ref`**, `snapshot_id`, `checked`, `timeout_ms`, `tab_id` |
| `ogma_browser_press_key` | ارسال کلید یا ترکیب کلید به صفحهٔ دارای تمرکز یا عنصر ارجاع‌شده. | **`key`**, `element_ref`, `snapshot_id`, `modifiers`, `repeat`, `delay_ms`, `tab_id` |
| `ogma_browser_focus` | تمرکز روی عنصر ارجاع‌شده و گزارش قابلیت‌های ورودی آن. | **`element_ref`**, `snapshot_id`, `tab_id` |
| `ogma_browser_blur` | برداشتن تمرکز از عنصر فعلی دارای تمرکز. | `tab_id`, `snapshot_id` |
| `ogma_browser_drag_and_drop` | کشیدن یک عنصر ارجاع‌شده و رها کردن روی عنصر دیگر. | **`source_ref`**, **`target_ref`**, `snapshot_id`, `steps`, `tab_id` |
| `ogma_browser_scroll_to` | پیمایش به عنصر، موقعیت صفحه یا درون محفظهٔ پیمایش ارجاع‌شده. | `target`, `element_ref`, `snapshot_id`, `container_ref`, `direction`, `amount`, `behavior`, `timeout_ms`, `tab_id` |
| `ogma_browser_wait_for` | انتظار برای شرط عنصر، متن، URL، پیمایش، پنجرهٔ گفتگو یا پایداری صفحه؛ در صورت نیاز از مکث صریح پشتیبانی می‌کند. | **`condition`**, `target`, `timeout_ms`, `stability_ms`, `tab_id`, `snapshot_id`, `result_detail` |
| `ogma_browser_handle_dialog` | پذیرش یا رد پنجرهٔ گفتگوی JavaScript با متن ورودی اختیاری و بررسی‌های پنجرهٔ مورد انتظار. | **`action`**, `prompt_text`, `expected_type`, `expected_message`, `tab_id`, `snapshot_id` |
| `ogma_browser_dialog_status` | گزارش هر پنجرهٔ گفتگوی JavaScript در انتظار، بدون رد کردن آن. | ندارد |

### فایل‌ها، پنجره‌های بازشو و دانلودهای مرورگر {#browser-files-popups-and-downloads}

| ابزار | عملکرد | ورودی‌ها |
| --- | --- | --- |
| `ogma_list_hosted_files` | فهرست کردن فایل‌های میزبانی‌شدهٔ پروژهٔ فعال و شناسه‌هایشان برای بارگذاری و بررسی فایل‌های خروجی. | `limit`, `offset` |
| `ogma_artifact_read_range` | خواندن بازهٔ محدودی از بایت‌های فایل میزبانی‌شده به‌جای برگرداندن کل فایل. | **`artifact_id`**, `offset`, `length` |
| `ogma_artifact_search` | جست‌وجوی متن عیناً در بازهٔ محدودی از فایل میزبانی‌شدهٔ UTF-8 و برگرداندن موقعیت بایتی تطابق‌ها. | **`artifact_id`**, **`query`**, `offset`, `max_bytes`, `max_matches` |
| `ogma_browser_file_upload` | تنظیم ورودی فایل از شناسه‌های فایل‌های میزبانی‌شدهٔ موجود در Ogma، نه مسیرهای دلخواه سیستم فایل کلاینت. | **`element_ref`**, `snapshot_id`, **`artifact_ids`**, `tab_id` |
| `ogma_browser_wait_for_popup` | آماده کردن تشخیص پنجرهٔ بازشو پیش از اقدام، انتظار برای پنجرهٔ بازشو یا بررسی وضعیت تشخیص. | **`action`**, `timeout_ms`, `switch_to_new_tab` |
| `ogma_browser_download_wait` | تشخیص دانلود در حال انجام یا کامل‌شدهٔ مرورگر. شناسه و وضعیت آن را بررسی کنید؛ تشخیص به معنای تکمیل یا جدیدترین بودن دانلود نیست. | `timeout_ms` |
| `ogma_browser_download_get` | بررسی یک دانلود و ذخیرهٔ محتوای کامل‌شده به‌عنوان فایل خروجی، در صورت وجود. | **`download_id`** |
| `ogma_browser_download_status` | فهرست کردن دانلودهای مرورگر و پیشرفت یا وضعیت فعلی آن‌ها. | ندارد |

### هویت‌ها، فضای ذخیره‌سازی و مجوزهای مرورگر {#browser-identities-storage-and-permissions}

ابزارهای مجوز مرورگر در زیر، مجوزهای وب‌سایت مانند دوربین یا موقعیت جغرافیایی را کنترل می‌کنند. آن‌ها مجوزهای ابزار سرور MCP را تغییر نمی‌دهند.

| ابزار | عملکرد | ورودی‌ها |
| --- | --- | --- |
| `ogma_browser_context_create` | ایجاد هویت جداگانهٔ مرورگر و زبانهٔ اولیه؛ `context_id` و `tab_id` را برمی‌گرداند. | `label`, `auth_profile_id`, `initial_url`, `retain_on_close` |
| `ogma_browser_context_clone` | ایجاد زمینهٔ پاک یا کپی کوکی‌های زمینهٔ مبدأ با `clone_mode: authenticated`؛ کپی کامل فضای ذخیره‌سازی نیست. | **`context_id`**, `clone_mode`, `label` |
| `ogma_browser_context_close` | بستن زمینه و زبانه‌های آن، و پاک کردن فضای ذخیره‌سازی مگر اینکه هنگام ایجاد، نگهداری درخواست شده باشد. | **`context_id`** |
| `ogma_browser_context_list` | فهرست کردن زمینه‌های مرورگر و وضعیت آن‌ها. | ندارد |
| `ogma_browser_auth_state_capture` | ثبت کوکی‌ها و فضای ذخیره‌سازی وب به‌عنوان وضعیت احراز هویت نام‌گذاری‌شده در حافظه؛ فرادادهٔ دارای اطلاعات پوشانده‌شده را برمی‌گرداند. | **`name`**, `tab_id`, `context_id`, `role`, `url` |
| `ogma_browser_auth_state_apply` | بازیابی وضعیت احراز هویت ثبت‌شده؛ فرادادهٔ انقضا اثبات نمی‌کند که سرور نشست را می‌پذیرد. | **`auth_state_id`**, `tab_id`, `context_id`, `url` |
| `ogma_browser_auth_state_list` | فهرست کردن وضعیت‌های احراز هویت ثبت‌شده بدون مقادیر کامل اسرار. | ندارد |
| `ogma_browser_auth_state_delete` | حذف یک وضعیت احراز هویت ثبت‌شده. | **`auth_state_id`** |
| `ogma_browser_storage_list` | فهرست کردن کوکی‌ها و ورودی‌های فضای ذخیره‌سازی وب با پیش‌نمایش کوتاه‌شدهٔ مقادیر. | `origin`, `storage_type` |
| `ogma_browser_storage_get` | بررسی یک کوکی یا کلید ذخیره‌سازی با پیش‌نمایش کوتاه‌شدهٔ مقدار. | **`storage_type`**, **`key`**, `origin` |
| `ogma_browser_storage_set` | نوشتن مقدار کوکی یا ذخیره‌سازی؛ ارجاع متغیر محیطی Ogma با قالب `env:VARIABLE_NAME` را می‌پذیرد. | **`storage_type`**, **`key`**, **`value`**, `origin`, `domain`, `path`, `http_only`, `secure`, `expires` |
| `ogma_browser_storage_delete` | حذف کوکی یا کلید فضای ذخیره‌سازی وب. | **`storage_type`**, **`key`**, `origin` |
| `ogma_browser_permissions_set` | دادن، رد کردن یا بازنشانی مجوزهای مشخص وب‌سایت برای یک مبدأ. | **`origin`**, **`permissions`**, `setting`, `context_id` |
| `ogma_browser_permissions_reset` | پاک کردن تنظیمات جایگزین مجوز مرورگر. | `context_id` |
| `ogma_browser_permissions_get` | پرس‌وجوی وضعیت مجوزهای وب‌سایت برای یک مبدأ. | **`origin`**, `permissions` |

### عیب‌یابی مرورگر، شواهد و بازیابی {#browser-diagnostics-evidence-and-recovery}

| ابزار | عملکرد | ورودی‌ها |
| --- | --- | --- |
| `ogma_browser_network_delta` | دریافت تعداد محدودی ورودی شبکه پس از نشانگر، با حفظ URL کامل، زمان‌بندی، خطاها و شناسه‌های تاریخچهٔ HTTP در صورت وجود. | `since_entry_id`, `resource_types`, `status_filter`, `failed_only`, `max_entries` |
| `ogma_browser_console_delta` | دریافت ورودی‌های جدید کنسول، شامل URL منبع، خط و ستون در صورت ارائه توسط مرورگر. | `since_entry_id`, `levels`, `max_entries` |
| `ogma_browser_action_correlation` | دریافت ترافیک یا رویدادهای مرتبط با بازهٔ زمانی اقدام، یا فهرست کردن اقدامات اخیر. زمان‌بندی به‌تنهایی رابطهٔ علّی را اثبات نمی‌کند. | `browser_action_id`, `limit` |
| `ogma_browser_snapshot_save` | بایگانی تصویر لحظه‌ای فعلی برای مقایسهٔ بعدی؛ بایگانی حداکثر 20 تصویر لحظه‌ای نگه می‌دارد. | `label` |
| `ogma_browser_page_state_compare` | مقایسهٔ دو تصویر لحظه‌ای بایگانی‌شده و گزارش تفاوت عناصر و وضعیت، با امکان نادیده گرفتن مقادیر متغیر و نقش‌ها. | **`snapshot_id_a`**, **`snapshot_id_b`**, `ignore_volatile`, `ignore_roles` |
| `ogma_browser_trace_start` | شروع ردگیری سبک اقدامات؛ `detailed` ارجاع‌های کنسول و شبکه را اضافه می‌کند. | `level`, `label`, `context_id` |
| `ogma_browser_trace_stop` | توقف ردگیری و نگهداری رویدادهای آن در حافظه. | **`trace_id`** |
| `ogma_browser_trace_export` | ذخیرهٔ ردگیری متوقف‌شده به‌عنوان فایل خروجی میزبانی‌شدهٔ JSON در پروژهٔ فعال. | **`trace_id`** |
| `ogma_browser_trace_list` | فهرست کردن ردگیری‌ها و وضعیت ثبت یا خروجی‌گیری آن‌ها. | ندارد |
| `ogma_browser_trace_note` | افزودن یادداشت به همهٔ ردگیری‌های در حال ثبت. | **`note`** |
| `ogma_browser_human_takeover_start` | توقف موقت اقدامات عامل در مرورگر برای نقطهٔ بررسی دستی، با مهلت محدود. | `reason`, `context_id`, `tab_id`, `timeout_ms` |
| `ogma_browser_human_takeover_complete` | بازگرداندن کنترل پس از تعامل دستی و تازه کردن تصویر لحظه‌ای صفحه. | **`takeover_id`** |
| `ogma_browser_human_takeover_status` | بررسی فعال بودن کنترل دستی و گزارش زمان باقی‌مانده. | ندارد |
| `ogma_browser_health` | گزارش سلامت پل اشکال‌زدا و اطلاعات اخیر خرابی یا قطع اتصال. | ندارد |
| `ogma_browser_recover` | تلاش برای بازیابی پل با حفظ شواهد به‌صورت پیش‌فرض؛ ممکن است `relaunch_required` را گزارش کند. | `preserve_evidence` |

### تست احراز هویت و مجوز دسترسی {#authentication-and-authorization-testing}

| ابزار | عملکرد | ورودی‌ها |
| --- | --- | --- |
| `ogma_auth_capture_profile` | ثبت کوکی‌ها، فضای ذخیره‌سازی، توکن‌های احراز هویت شناسایی‌شده و گزینه‌های احتمالی CSRF از مرورگر تعبیه‌شده. | **`name`**, `role`, `url`, `tab_id`, `wait_ms` |
| `ogma_auth_list_profiles` | فهرست کردن پروفایل‌های احراز هویت ثبت‌شده با خلاصه کردن مقادیر اسرار. | ندارد |
| `ogma_auth_apply_profile` | اعمال پروفایل احراز هویت ثبت‌شده در مرورگر تعبیه‌شده برای تغییر نقش یا حساب. | **`profile_id`**, `url`, `tab_id`, `wait_ms` |
| `ogma_auth_refresh_csrf` | تازه کردن گزینه‌های احتمالی توکن CSRF از صفحهٔ فعلی، کوکی‌ها، فضای ذخیره‌سازی، تگ‌های متا و ورودی‌های پنهان. | `profile_id`, `url`, `tab_id`, `wait_ms` |
| `ogma_login_replay_auto` | تشخیص خودکار فرم ورود، ارسال اطلاعات احراز هویت در مرورگر تعبیه‌شده و ثبت پروفایل احراز هویت. | **`login_url`**, **`username`**, **`password`**, **`profile_name`**, `role`, `tab_id`, `wait_ms` |
| `ogma_authz_matrix_test` | بازپخش یک درخواست ثبت‌شده با چند پروفایل احراز هویت برای مقایسهٔ نتایج کنترل دسترسی. | **`request_id`**, **`profile_ids`**, `mutations`, `entry_id` |

### مسیرهای ورود قابل استفادهٔ مجدد {#reusable-login-journeys}

برخلاف پروفایل‌های احراز هویت در حافظه، مسیرهای ورود برای هر پروژه به‌صورت پایدار ذخیره می‌شوند. اطلاعات احراز هویت به شناسهٔ متغیرهای محیطی Ogma ارجاع می‌دهند. همهٔ بررسی‌های تأیید پیکربندی‌شده باید موفق شوند؛ ارسال فرم ورود به‌تنهایی احراز هویت موفق نیست.

| ابزار | عملکرد | ورودی‌ها |
| --- | --- | --- |
| `ogma_auth_journey_record` | ذخیرهٔ مراحل ورود، ارجاع اطلاعات احراز هویت، بررسی‌های تأیید و نقاط بررسی دستی اختیاری MFA. این کار مسیر را تعریف می‌کند؛ کلیک‌های دلخواه را خودکار ضبط نمی‌کند. | **`name`**, `role`, **`login_url`**, **`username_env_var_id`**, **`password_env_var_id`**, `username_selectors`, `password_selectors`, `submit_selectors`, `steps`, **`verification`**, `mfa`, `mfa_reason`, `mfa_timeout_ms` |
| `ogma_auth_journey_list` | فهرست کردن مسیرهای ورود ذخیره‌شده در پروژهٔ فعال با پوشاندن اسرار نشست. | ندارد |
| `ogma_auth_journey_replay` | اجرای مسیر ورود ذخیره‌شده، تأیید احراز هویت و ذخیرهٔ نشست تازه‌شده؛ در صورت پیکربندی، برای MFA دستی مکث می‌کند. | **`journey_id`**, `tab_id` |
| `ogma_auth_journey_verify` | بررسی URL، DOM، کوکی‌ها و درخواست تأیید اختیاری در برابر نشست فعلی. | **`journey_id`**, `tab_id` |
| `ogma_auth_journey_ensure` | تأیید نشست فعلی، تلاش برای بازیابی وضعیت ذخیره‌شده و بازاجرای ورود فقط اگر همچنان لازم باشد. | **`journey_id`**, `tab_id` |
| `ogma_auth_journey_resume` | ادامهٔ مسیر پس از نقطهٔ بررسی دستی و تأیید نشست حاصل. | **`journey_id`**, **`takeover_id`**, `tab_id` |

### ابزارهای کمکی و تحلیل {#utilities-and-analysis}

| ابزار | عملکرد | ورودی‌ها |
| --- | --- | --- |
| `ogma_fetch_sourcemap` | دریافت و بررسی نقشهٔ منبع JavaScript. | **`url`**, `base_url` |
| `ogma_proto_decode` | کدگشایی محتوای protobuf با طرح‌واره‌های پیکربندی‌شده. | **`data_b64`**, `content_type` |
| `ogma_decode_jwt` | کدگشایی هدرها و ادعاهای JWT. | **`token`** |
| `ogma_decode_response` | کدگشایی، باز کردن فشرده‌سازی یا تبدیل بدنه‌های پاسخ با عملیات مرتب‌شده، مانند پردازش base64، gzip، deflate، brotli، URL، موجودیت HTML و هگز. | **`input`**, `input_is_b64`, **`operations`**, `max_output_bytes` |
| `ogma_search_js_secrets` | جست‌وجوی پاسخ‌های JavaScript برای اسرار افشاشده و نقاط پایانی. | `host`, `patterns` |
| `ogma_compare_responses` | مقایسهٔ دو پاسخ. | **`entry_id_a`**, **`entry_id_b`**, `mode` |
| `ogma_bytes_transform` | انجام تبدیل‌های بایتی مانند کدگذاری، کدگشایی، XOR، هش کردن و استخراج. | **`operation`**, **`data`**, `key`, `output_encoding`, `offset`, `length`, `min_len` |
| `ogma_wasm_inspect` | بررسی ماژول WebAssembly. | **`wasm_b64`**, `data_encoding` |
| `ogma_fingerprint_target` | شناسایی فناوری هدف از ترافیک و پاسخ‌های ثبت‌شده. | `host`, `entry_limit` |
| `ogma_sign_request` | محاسبهٔ هدرهای امضای درخواست HMAC-SHA256 برای برنامه‌هایی که از روش‌های امضای سمت کلاینت استفاده می‌کنند. | **`key`**, **`method`**, **`path`**, `params` |
| `ogma_find_in_response` | دریافت حداکثر 10 URL و جست‌وجوی بدنه‌های پاسخ برای عبارت منظم با زمینهٔ فشرده. | **`urls`**, **`pattern`**, `headers`, `context_chars`, `max_matches_per_url`, `case_insensitive`, `timeout_secs` |
| `ogma_think` | ثبت استدلال ساخت‌یافته یا متن برنامه در نشست MCP. | **`thought`** |
| `ogma_explain_capabilities` | برگرداندن خلاصهٔ قابلیت‌های سرور MCP. | ندارد |

### ابزارهای کمکی کاوش فعال {#active-probe-helpers}

| ابزار | عملکرد | ورودی‌ها |
| --- | --- | --- |
| `ogma_run_active_probe_workflow` | اجرای کاوش محدود مخصوص یک آسیب‌پذیری روی درخواست ثبت‌شده. ماژول‌ها شامل IDOR/BOLA، CORS، SSRF OAST، بازتاب یا ذخیرهٔ XSS، زمان‌بندی یا خطای SQLi، پیمایش مسیر، SSTI، دور زدن محدودیت بارگذاری، درون‌نگری یا مجوز دسترسی GraphQL، دست‌کاری JWT و بررسی محدودیت نرخ هستند. | **`probe`**, **`request_id`**, `entry_id`, `target_param`, `profile_ids`, `values`, `origins`, `max_cases` |
| `ogma_test_race` | ارسال هم‌زمان یک درخواست و گزارش پرتکرارترین کد وضعیت HTTP، پاسخ‌های متفاوت با آن و یک نتیجهٔ نهایی. برای عملیات یک‌بارمصرف استفاده کنید: چند پاسخ موفق به عملیاتی که باید فقط یک بار موفق شود، نشان می‌دهد عملیات اتمی نیست. برای ورودی ثبت‌شده، `request_id` را ارسال کنید یا `host` و `port` را همراه با بقیهٔ درخواست به‌صورت صریح بدهید. `http2` را تنظیم کنید تا همهٔ درخواست‌ها به‌صورت جریان‌های هم‌زمان روی یک اتصال ارسال شوند، با یک بسته؛ این حالت در بازه‌های بسیار کوتاه، زمانی که هدف از HTTP/2 استفاده می‌کند، موفق‌تر است؛ پیش‌فرض برای هر درخواست یک اتصال باز می‌کند. تفاوت فقط شاهدی دربارهٔ مدیریت هم‌زمانی است و یکسان بودن پاسخ‌ها در تمام دسته، اتمی بودن را اثبات نمی‌کند؛ بنابراین با بررسی وضعیتی که عملیات تغییر داده است تأیید کنید. | `request_id`, `entry_id`, `method`, `host`, `port`, `tls`, `path`, `query`, `params`, `headers`, `body_b64`, `concurrency`, `stagger_ms`, `http2` |
| `ogma_test_smuggling` | ارسال کاوش‌های عدم همگامی CL.TE و TE.CL روی TCP خام و گزارش نتایج کاوش، موارد مشکوک و نتیجهٔ نهایی. هدرهای ارسال‌شده در `headers` فقط همراه درخواست کاوش هستند؛ درخواست پیگیری که عدم همگامی را اندازه می‌گیرد، همواره بدون آن‌ها ارسال می‌شود. کاوش اکتشافی است و اغلب در هر دو جهت خطا دارد: بخش جلویی که اتصال را پس از اولین درخواست می‌بندد یا قالب‌بندی متعارض را با 400 رد می‌کند، همان نتیجهٔ کاوش بخش آسیب‌پذیر را می‌دهد؛ نتیجهٔ منفی نیز ایمنی را اثبات نمی‌کند. پیش از گزارش تأیید کنید: بایت‌های کاوش را با `ogma_http_request` در حالت خام بازپخش کنید و آن‌ها را به‌صورت `raw_request_base64` بدهید؛ `max_responses` را روی 2 بگذارید تا پاسخی را بخوانید که بایت‌ها درخواست نکرده‌اند، سپس با `followup_raw_request_base64` درخواست معمولی روی همان اتصال بفرستید و دو وضعیت را مقایسه کنید. فقط HTTP/1.x. | **`host`**, **`port`**, `tls`, `path`, `timeout_ms`, `headers` |
| `ogma_test_hpp` | ارسال گونه‌های آلودگی پارامتر HTTP برای پارامترهای نام‌برده و سپس گزارش گونه‌ای که وضعیت یا بدنهٔ پاسخ را تغییر داده است، همراه با نتیجهٔ نهایی. وقتی پارامتر در یک مؤلفه اعتبارسنجی و در دیگری مصرف می‌شود استفاده کنید؛ نام تکراری ممکن است در هر کدام متفاوت تفسیر شود. پاسخ تغییرکرده نشان می‌دهد پارامترهای تکراری متفاوت پردازش می‌شوند؛ به‌تنهایی ثابت نمی‌کند کنترلی دور زده شده است. `headers` در همهٔ درخواست‌ها، از جمله درخواست مبنا، ارسال می‌شود؛ بنابراین Cookie یا Authorization در آن، نقطهٔ پایانی نیازمند اطلاعات احراز هویت را کاوش می‌کند. بدون هدر، درخواست‌ها کوکی و احراز هویت ندارند؛ پس گونه‌ای که در نقطهٔ پایانی نیازمند ورود چیزی را تغییر نمی‌دهد، هیچ‌چیز را اثبات نمی‌کند. | **`host`**, **`port`**, **`params`**, `tls`, `path`, `base_value`, `test_value`, `timeout_ms`, `headers` |
| `ogma_list_nuclei_templates` | فهرست کردن قالب‌های اسکنر قالب همراه Ogma، با شدت و معنای تطابق. پیش از `ogma_run_nuclei` آن را بخوانید تا قالب را با نام انتخاب کنید. | ندارد |
| `ogma_run_nuclei` | اجرای یک قالب روی URL هدف و گزارش همهٔ تطابق‌ها. یافته ایجاد نمی‌کند. برای قالب همراه، `template` یا برای سند خود، `template_yaml` را بدهید، نه هر دو. تجزیه‌گر زیرمجموعه‌ای از nuclei است: تطبیق وضعیت، واژه و عبارت منظم، `matchers-condition` و استخراج‌گرهای عبارت منظم. نوع‌های تطبیق خارج از این زیرمجموعه، از جمله عبارت‌های DSL، به‌جای ارزیابی کنار گذاشته می‌شوند؛ ابزار همهٔ قالب‌هایی را که نصب کامل nuclei می‌پذیرد اجرا نمی‌کند. قالب‌ها سطح‌های افشا و پیکربندی نادرست را بررسی می‌کنند که اسکنر پسیو نمی‌تواند ببیند، مانند `.env` یا `.git/config` افشاشده، نقطهٔ پایانی actuator یا صفحهٔ وضعیت سرور. | **`target`**, `template`, `template_yaml` |
| `ogma_record_test_attempt` | ثبت اینکه یک نقطهٔ پایانی، پارامتر یا بردار تست شده است و نتیجهٔ آن چه بوده، تا نشست بعدی بتواند مسیر بی‌نتیجه را از نقطهٔ تست‌نشده تشخیص دهد. فقط `no_signal` نقطه را از بررسی بیشتر کنار می‌گذارد؛ `transport_error` یعنی کاوش هرگز به هدف نرسیده است، پس چیزی دربارهٔ بردار اثبات نمی‌کند. | **`host`**, **`port`**, **`path`**, **`vector`**, **`outcome`**, **`reason`**, `parameter`, `payload_label`, `evidence_entry_id` |
| `ogma_list_test_attempts` | فهرست کردن تلاش‌های تست ثبت‌شده از جدیدترین به قدیمی‌ترین و گروه‌بندی بر اساس میزبان، درگاه، مسیر، پارامتر و بردار، همراه با گزارش تلاش تعیین‌کنندهٔ هر نقطه، تعداد تلاش‌ها و تمام شدن امکان بررسی آن. یک نقطه فقط وقتی تمام‌شده است که نتیجهٔ تعیین‌کنندهٔ آن `no_signal` باشد؛ `transport_error` بعدی این وضعیت را از بین نمی‌برد. | `host`, `port`, `path`, `vector`, `limit` |

### تست مستقیم WebSocket {#direct-websocket-testing}

| ابزار | عملکرد | ورودی‌ها |
| --- | --- | --- |
| `ogma_websocket_connect` | اتصال به URL با `ws://` یا `wss://`، ارسال پیام‌ها و برگرداندن متن تبادل. | **`url`**, **`messages`**, `headers`, `timeout_secs` |
| `ogma_ws_capture_history` | ذخیرهٔ متن تبادل WebSocket از `ogma_websocket_connect` به‌عنوان تاریخچهٔ ساخت‌یافتهٔ Ogma برای بازبینی و پیوند شواهد. | **`url`**, **`transcript`**, `label` |

### تطبیق و جایگزینی {#match-and-replace}

| ابزار | عملکرد | ورودی‌ها |
| --- | --- | --- |
| `ogma_list_match_replace_rules` | فهرست کردن قواعد تطبیق و جایگزینی. | ندارد |
| `ogma_create_match_replace_rule` | ایجاد قاعدهٔ تطبیق و جایگزینی؛ عملیات گردش کار به workflow\_id نیاز دارند. | **`name`**, `enabled`, **`direction`**, **`operation`**, **`match_value`**, `match_mode`, `replace_value`, `filter_method`, `filter_host`, `filter_path`, `filter_httpql`, `position`, `workflow_id` |
| `ogma_toggle_match_replace_rule` | فعال یا غیرفعال کردن قاعدهٔ تطبیق و جایگزینی. | **`rule_id`**, **`enabled`** |
| `ogma_delete_match_replace_rule` | حذف قاعدهٔ تطبیق و جایگزینی. | **`rule_id`** |

### متغیرهای محیطی {#environment-variables}

| ابزار | عملکرد | ورودی‌ها |
| --- | --- | --- |
| `ogma_list_env_vars` | فهرست کردن نام و فرادادهٔ متغیرهای محیطی. | ندارد |
| `ogma_set_env_var` | ایجاد یا به‌روزرسانی متغیر محیطی. | **`name`**, **`value`**, `scope`, `is_secret` |
| `ogma_get_env_var_value` | خواندن مقدار متغیر محیطی در صورت داشتن مجوز. | **`name`** |

### پروژه‌ها، یادداشت‌ها، کارها و نشست {#projects-notes-todos-and-session}

تغییر پروژه بر پروژهٔ فعال در Ogma اثر می‌گذارد، نه فقط بر عامل درخواست‌کننده. با کلاینت‌های دیگر هماهنگ کنید. ابزارهای یادداشت و کار در زیر، **دفترچهٔ موقت نشست MCP در حافظه** هستند، نه صفحهٔ یادداشت‌های پایدار برنامه. پیش از قطع اتصال یا راه‌اندازی مجدد MCP، گزارش نشست را نگه دارید.

| ابزار | عملکرد | ورودی‌ها |
| --- | --- | --- |
| `ogma_list_projects` | فهرست کردن پروژه‌ها. | ندارد |
| `ogma_switch_project` | تغییر پروژهٔ فعال. | `project_id`, `project_name` |
| `ogma_start_pentest_session` | ایجاد برنامهٔ ارزیابی ساخت‌یافته و به‌صورت پیش‌فرض یادداشت یا فهرست بررسی محلی نشست برای هدف. اسکن کامل را خودکار اجرا نمی‌کند. | **`target_url`**, `objective`, `mode`, `create_scratchpad` |
| `ogma_get_coverage_status` | خلاصه کردن پیشرفت فهرست بررسی نشست فعلی و پوشش باقی‌مانده؛ اثبات تست کامل نیست. | ندارد |
| `ogma_recommend_skills` | پیشنهاد راهنمای مهارت داخلی از فناوری‌ها، مسیرها، هدرها و سایر زمینه‌های ارائه‌شده و مشاهده‌شده. | `observations`, `paths`, `content_types`, `headers`, `technologies`, `response_snippets`, `notes` |
| `ogma_note_create` | ایجاد یادداشت. | **`title`**, **`content`**, `category` |
| `ogma_note_list` | فهرست کردن یادداشت‌ها. | `category` |
| `ogma_note_get` | دریافت یک یادداشت. | **`id`** |
| `ogma_note_update` | به‌روزرسانی یادداشت. | **`id`**, `title`, `content`, `category` |
| `ogma_note_delete` | حذف یادداشت. | **`id`** |
| `ogma_todo_create` | ایجاد کار. | **`task`**, `priority` |
| `ogma_todo_list` | فهرست کردن کارها. | `status`, `priority` |
| `ogma_todo_update` | به‌روزرسانی کار. | **`id`**, `task`, `priority`, `status` |
| `ogma_todo_mark_done` | علامت‌گذاری کار به‌عنوان انجام‌شده. | **`id`** |
| `ogma_todo_delete` | حذف کار. | **`id`** |
| `ogma_finish_session` | نهایی کردن نشست MCP با خلاصه، روش‌شناسی و توصیه‌ها. | **`summary`**, **`methodology`**, **`recommendations`** |
| `ogma_get_session_report` | دریافت گزارش نشست فعلی MCP. | ندارد |

## ارتباط با هوش مصنوعی فضای کاری {#relationship-to-workspace-ai}

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