---
url: https://docs.ogmabox.com/zh/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` | 规划 Web 挑战调查和证据收集。 |

## 工具权限 {#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` 对已保存的句柄进行有界的只读检查；它不会重复执行操作。重新使用元素引用前，请刷新浏览器快照。

交接或长时间暂停前保存检查点。工具活动记录执行过什么；无法推断你打算进行的下一项测试。明确记录目标、结论、不确定性和后续步骤，并通过 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 和 Web 存储捕获为具名的内存身份验证状态；返回脱敏后的元数据。 | **`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 和 Web 存储条目，使用截短的值预览。 | `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 或 Web 存储键。 | **`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)。