---
url: https://docs.ogmabox.com/uk/reference/mcp-tools.md
description: >-
  Повний довідник Ogma MCP із призначенням і вхідними даними інструментів,
  ресурсами, запитами, дозволами, пагінацією та обробкою результатів.
---

# Ресурси та інструменти MCP {#mcp-resources-and-tools}

Сервер Ogma MCP призначений для зовнішніх клієнтів 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 або stdio](../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` | Читає контрольні точки й активність інструментів від найновіших. Час подано в мілісекундах Unix 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, код PoC і посилання. | **`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` | Надсилає запити multipart form-data з текстовими й файловими полями для тестування вивантажень. | **`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` | Отримує cookie браузера. | `tab_id` |
| `ogma_browser_set_cookie` | Задає 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` | Задає поле через рівно один CSS `selector` або `element_ref` зі знімка; порожнє значення очищує поле. Не надсилає форму. | **`selector`**, `value`, `tab_id`, **`element_ref`**, `snapshot_id`, `expect`, `observation`, `result_detail` |
| `ogma_browser_fill_form` | Замінює текст кількох полів введення, textarea або елементів contenteditable за один виклик у наданому порядку; кожне поле використовує рівно один `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 дії кожної форми, метод, фактичний тип вмісту, елементи керування, які включаються в надсилання, з їхніми поточними значеннями, елементи надсилання й схожі на CSRF `token_candidates`. Форми multipart посилаються на `ogma_multipart_upload` замість синтезованого тіла. Потребує дозволу `send_requests`. | `tab_id`, `include_templates` |
| `ogma_browser_form_to_replay` | Створює сеанс повторного надсилання з форми поточної сторінки, читаючи поточні значення полів і актуальні cookie браузера в цей момент; заголовки 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` | Створює чистий контекст або копіює cookie вихідного контексту з `clone_mode: authenticated`; це не повне клонування сховища. | **`context_id`**, `clone_mode`, `label` |
| `ogma_browser_context_close` | Закриває контекст і його вкладки, очищуючи сховище, якщо збереження не було запитане під час створення. | **`context_id`** |
| `ogma_browser_context_list` | Перелічує контексти браузера та їх стан. | Немає. |
| `ogma_browser_auth_state_capture` | Захоплює cookie й вебсховище як іменований стан автентифікації в пам’яті; повертає метадані з прихованими секретами. | **`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` | Перелічує cookie й записи вебсховища зі скороченим переглядом значень. | `origin`, `storage_type` |
| `ogma_browser_storage_get` | Переглядає один cookie або ключ сховища зі скороченим переглядом значення. | **`storage_type`**, **`key`**, `origin` |
| `ogma_browser_storage_set` | Записує значення cookie/сховища; приймає посилання Ogma `env:VARIABLE_NAME`. | **`storage_type`**, **`key`**, **`value`**, `origin`, `domain`, `path`, `http_only`, `secure`, `expires` |
| `ogma_browser_storage_delete` | Видаляє один cookie або ключ вебсховища. | **`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` | Захоплює cookie, сховище, виявлені токени автентифікації й кандидати 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 із поточної сторінки, cookie, сховища, метатегів і прихованих полів. | `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, cookie та необов’язковий перевірочний запит відносно поточного сеансу. | **`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` | Надсилає один запит одночасно й повідомляє найчастіший стан, відповіді з відхиленнями від нього та висновок. Використовуйте для одноразових операцій: кілька успішних відповідей на операцію, яка має спрацьовувати раз, показують її неатомарність. Передайте `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 у ньому дозволяє перевірити кінцеву точку, яка потребує облікових даних; без заголовків запити не містять cookie й автентифікації, тому варіант, який нічого не змінює на захищеній входом кінцевій точці, нічого не доводить. | **`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).