---
url: https://docs.ogmabox.com/zh-Hant/reference/mcp-tools.md
description: 完整的 Ogma MCP 參考，涵蓋工具用途與輸入、資源、提示詞、權限、分頁及結果處理。
---

# MCP 資源與工具 {#mcp-resources-and-tools}

Ogma MCP 伺服器供 Codex、Claude Code、Cursor 及其他 Model Context Protocol 主控端等外部 MCP 用戶端使用。它與應用程式內的 AI 助理是分開的功能。

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` | 通知伺服器初始化已完成；此通知沒有請求 ID。 |
| `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 路由。請透過 MCP 連線上的 `tools/call` 呼叫它們。

1. 使用 MCP 用戶端初始化連線。
2. 呼叫 `tools/list`。Ogma **每頁最多傳回 40 個工具**。將每次傳回的 `nextCursor` 以 `params.cursor` 傳回，直到不再傳回游標；否則用戶端會缺少大部分瀏覽器工具。
3. 閱讀各工具的 `inputSchema`，確認欄位類型、列舉值、預設值、限制及巢狀物件格式。不要根據工具名稱自行猜測引數。
4. 採取操作前，先閱讀 `ogma://mcp/permissions` 與 `ogma://mcp/tool-guide`。
5. 在 `arguments` 中傳入 JSON 物件，呼叫選定的工具。

已初始化連線上的 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
    }
  }
}
```

請使用列表/搜尋工具傳回的 ID，不要猜測。歷程記錄與檢測發現搜尋使用 `limit`/`offset`；瀏覽器增量工具使用 `since_entry_id`。兩者都不是 `tools/list` 使用的不透明游標。

## 讀取結果 {#reading-results}

優先使用 `result.structuredContent`。對於只支援文字結果的用戶端，文字內容區塊包含相同的 JSON 封裝。例外是預設的 `ogma_browser_snapshot` 結果：它沒有結構化內容，文字內容就是可讀的樹狀結構；使用 `result_detail: "full"` 才能取得結構化元素。若透過本機 REST 橋接，則應解析 `result` 中的 JSON 字串；該橋接並不是 MCP 傳輸方式。

REST 橋接中的工具失敗時，解析後的值為 `{ "error": "..." }`，工具序列化後的錯誤封裝位於該字串內。橋接傳回 HTTP 成功狀態，本身不代表工具執行成功。

| 封裝欄位 | 意義 |
| --- | --- |
| `ok` | 工具操作是否成功。也請檢查 MCP 結果的 `isError`。 |
| `workflow_stage`, `summary` | 操作脈絡與簡短說明。 |
| `evidence`, `hypotheses` | 觀察到的證據，以及分開列出的未經確認的解釋。 |
| `next_actions`, `use_next_tools` | 建議的後續工作與工具路由。 |
| `artifacts` | 可用時，指向產生的證據或檔案的參照。 |
| `raw` | 工具專屬資料。結構化結果路徑會包含此欄位；精簡工具只在 `result_detail: "full"` 時包含它。可能是物件、陣列或文字；不要假設所有結果的結構都相同。 |

螢幕擷取工具也會傳回原生 MCP 圖像區塊。請讀取圖像區塊，不要預期 JSON 中繼資料中會包含 base64 圖像資料。瀏覽器快照預設傳回精簡的文字樹狀結構；傳入 `result_detail: "full"`，可在 `raw.elements` 下取得結構化元素。瀏覽器網路與主控台增量包含結構化項目。

成功的驗證呼叫仍可能在資料中傳回 `valid: false`。工具執行失敗使用 `isError: true`；無效的通訊協定請求使用 JSON-RPC 錯誤。重試前請先閱讀診斷資訊。後端錯誤可能包含 HTTP 狀態、端點，以及有長度限制的診斷文字；`[truncated]` 表示診斷已截短，不是操作成功。

這些結果慣例使用 MCP 的[工具結果格式](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#tool-result)。

## 資源 {#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}` | 工作流程安全分類與所需權限。 |

請使用 `resources/read` 讀取這些 URI，不要對 `ogma://` 發送 HTTP GET。讀取前，先將 ID 代入資源範本。資源會在 `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` | 攔截狀態/佇列讀取、佇列修改，以及攔截狀態控制。 |

呼叫工具時才會檢查權限；工具列在目錄中，不代表其操作已啟用。瀏覽器觀察工具可以檢查已執行的瀏覽器，但操作瀏覽器與管理瀏覽器環境（context）需要 `allow_send_requests`。身分驗證流程也需要該權限，包括列出與驗證呼叫。工作階段本地筆記與待辦事項不需要專案寫入權限。

沒有每分鐘或每個工作階段的活動配額。個別工具仍會限制輸入大小、批次大小、逾時及測試範圍。依工作流程的操作內容，執行時可能需要額外的傳送或檢測發現寫入權限。請參閱[設定與權限](../mcp-setup.md#permissions)。

無論權限如何，所有工具都會公布。舊版設定檔參數不再篩選工具列表。請參閱[工具探索與分派](#tool-discovery-and-dispatch)。

## 工具目錄 {#tool-catalog}

### 遺失脈絡後的復原 {#recovering-after-context-loss}

重新連線或遺失對話脈絡後，請先呼叫 `ogma_resume_session`，再開始另一項評估。檢查使用中的專案、最後一個檢查點與近期工具結果。使用 `check_live: true`，可對已儲存的控制代碼進行有界的唯讀檢查；它不會重複執行操作。重新使用元素參照前，請重新取得瀏覽器快照。

交接或長時間暫停前，請儲存檢查點。工具活動會記錄執行過的操作，但無法推斷你打算進行的下一項測試。請明確記錄目標、結論、不確定之處及後續步驟，並以 ID 參照證據，不要將大量回應本文複製到檢查點。

```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
  }
}
```

交接或壓縮脈絡前，請儲存檢查點。明確記錄目標、已完成工作、不確定之處、證據 ID 及後續步驟：自動活動記錄儲存的是控制代碼與結果，不是請求酬載或你的意圖。已開始但沒有完成結果的呼叫，其結果未知；重試傳送前，請先檢查目前狀態。

復原記錄會持久保存，並以專案為範圍。指定 `assessment_id` 時，讀取僅限該評估；復原讀取時省略它，則可檢查整個專案的活動。現有的工作階段本地筆記/待辦事項用途不同，不應誤認為持久交接記錄。

| 工具 | 功能 | 輸入 |
| --- | --- | --- |
| `ogma_save_checkpoint` | 附加持久交接記錄。`next_steps` 是明確操作的陣列；`references` 將名稱對應至已儲存的 ID。不會執行計畫。 | **`objective`**, **`progress`**, **`next_steps`**, `uncertainties`, `references` |
| `ogma_resume_session` | 讀取使用中的專案、最新檢查點、近期活動及復原指引。選用的即時檢查會檢查已儲存的控制代碼，不會重複操作。 | `check_live` |
| `ogma_get_session_activity` | 由新到舊讀取檢查點與工具活動。時間採用 UTC Unix 毫秒。分頁時，請同時傳入傳回游標中的 `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)。

內嵌瀏覽器操作（`snapshot`、`fill_input`、`fill_form`、`console_delta`、`network_delta` 及其餘瀏覽器系列工具）請使用 `ogma_browser`；`http_history`、`findings` 及 `ws_history` 等搜尋領域請使用 `ogma_search`。對應的專用工具仍然可用。

| 工具 | 功能 | 輸入 |
| --- | --- | --- |
| `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` | 使用 HTTPQL 搜尋 HTTP 歷程記錄，並傳回請求/回應中繼資料。 | `q`, `limit`, `offset`, `result_detail` |
| `ogma_get_http_entry` | 依 ID 取得一筆 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` | 使用 StreamQL 搜尋 WebSocket 連線歷程記錄。 | `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` | 依 ID 取得一筆檢測發現。 | **`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 項目建立檢測發現。將請求與回應的標頭及本文嵌入為 Markdown HTTP 證據，回應本文截短至 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` | 依 ID 取得一個匯出作業。 | **`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` | 透過 MCP 工具介面直接傳送 HTTP 請求。使用 `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` | 依 ID 取得一個工作流程。 | **`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` | 列出主動掃描器檢查類別及其 ID 與說明，並報告其中多少類別會建立檢測發現。尚未實作的占位類別也會列出，但絕不會產生檢測發現。 | 無。 |
| `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` | 針對測試範圍內的主機與連接埠，啟動背景內容探索作業；傳回作業 ID。 | **`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` | 導覽並在 JavaScript 執行後，傳回轉譯完成的 DOM 與選用的選取器結果。 | **`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` | 按提供的順序，在一次呼叫中取代多個輸入欄位、文字區域或 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`），可加入每個表單的絕對 action URL、方法、實際內容類型、會納入表單提交資料的控制項及其目前值、提交控制項，以及類似 CSRF 的 `token_candidates`。多部分表單會指向 `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` | 列出使用中專案的代管檔案及其 ID，用於上傳與產物檢查。 | `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 代管檔案 ID 設定檔案輸入欄位，不接受任意用戶端檔案系統路徑。 | **`element_ref`**, `snapshot_id`, **`artifact_ids`**, `tab_id` |
| `ogma_browser_wait_for_popup` | 在操作前啟用彈出視窗偵測、等待彈出視窗，或檢查偵測狀態。 | **`action`**, `timeout_ms`, `switch_to_new_tab` |
| `ogma_browser_download_wait` | 偵測進行中或已完成的瀏覽器下載。請檢查其 ID 與狀態；偵測到下載不代表已完成，也不代表它是最新的下載。 | `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` 複製來源瀏覽器環境的 Cookie；不是完整的儲存複製。 | **`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 歷程記錄 ID。 | `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` | 從目前頁面、Cookie、儲存資料、meta 標籤與隱藏輸入欄位，重新取得 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 環境變數 ID。所有已設定的驗證檢查都必須通過；只提交登入表單，不代表身分驗證成功。

| 工具 | 功能 | 輸入 |
| --- | --- | --- |
| `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` | 透過原始 TCP 傳送 CL.TE 與 TE.CL 失同步探測，並報告探測結果、候選項目及結論。`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 端點或 server-status 頁面。 | **`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` | 連接 `ws://` 或 `wss://` URL、傳送訊息，並傳回對話記錄。 | **`url`**, **`messages`**, `headers`, `timeout_secs` |
| `ogma_ws_capture_history` | 將 `ogma_websocket_connect` 的 WebSocket 對話記錄儲存為結構化 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 工作階段報告。 | 無。 |

## 與工作區 AI 的關係 {#relationship-to-workspace-ai}

MCP 伺服器是外部工具使用的通訊協定伺服器。應用程式內的工作區 AI 是 Vue/瀏覽器功能，會直接呼叫已設定的 AI 服務提供者，並提供自己的前端工具列表。請參閱[工作區 AI](../guide/workspace-ai.md)。