> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orriven.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 工具参考

> orriven MCP 服务提供的全部工具：参数定义、权限要求与返回值说明。

orriven MCP 服务提供十八个管理与开发运维工具，与[命令行工具](/zh/developers/cli)及控制台开发者功能保持严格对齐。

作用于业务单元的工具均需提供 `workspaceId`，可通过 `list_workspaces` 获取。无访问权限或不存在的业务单元将统一返回 `not found` 错误。

## 账号与组织范围

用于查询当前授权身份与组织层级结构的工具。

| 工具                   | 参数               | 说明与返回值                                             |
| -------------------- | ---------------- | -------------------------------------------------- |
| `whoami`             | —                | 返回当前认证用户的账号信息及已连接客户端应用标识。                          |
| `list_organizations` | —                | 列出当前账号具备访问权限的所有组织及其组织级角色。                          |
| `list_workspaces`    | `organizationId` | 列出指定组织下的业务单元，包含有效角色、`restricted` 状态与 `archivedAt`。 |

## API 密钥

管理开发者凭据。需要目标业务单元的**所有者**（Owner）或**管理员**（Admin）角色。

| 工具                            | 参数                                                    | 说明与返回值                                                                  |
| ----------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------- |
| `list_api_keys`               | `workspaceId`、`includeRevoked?`                       | 列出业务单元下的 API 密钥：Secret 密钥（`ok_…` 标识，仅前缀）与 Publishable 密钥（`opk_…`，完整令牌）。 |
| `create_api_key`              | `workspaceId`、`label`、`expiresAt?`                    | 生成新的 Secret 密钥，并在响应中**仅返回一次**明文 `secret`（`osk_…`）。                      |
| `create_publishable_key`      | `workspaceId`、`label`、`allowedOrigins[]`、`expiresAt?` | 生成绑定到指定浏览器 Origin（`https://…` 或 `http://localhost…`）的 Publishable 密钥。   |
| `set_publishable_key_origins` | `workspaceId`、`apiKeyId`、`allowedOrigins[]`           | 更新既有 Publishable 密钥允许的 Origin 列表。                                       |
| `revoke_api_key`              | `workspaceId`、`apiKeyId`                              | 吊销指定的 API 密钥。吊销操作立即生效且不可撤销。                                             |

<Note>
  `apiKeyId` 是 `list_api_keys` 返回的数据行主键 ID，与公开密钥标识（`ok_…` 或 `opk_…`）不同。`expiresAt` 需为 ISO 8601 格式的时间戳字符串。
</Note>

## Webhook

配置与监控 Webhook 事件订阅。需要目标业务单元的**所有者**（Owner）或**管理员**（Admin）角色。

| 工具                         | 参数                                                                                                      | 说明与返回值                                                          |
| -------------------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `list_webhook_event_types` | —                                                                                                       | 列出所有支持订阅的事件类型。                                                  |
| `list_webhook_endpoints`   | `workspaceId`                                                                                           | 列出已配置的端点，包含运行状态、事件订阅列表、签名密钥标识、失败计数及最近投递时间。                      |
| `create_webhook_endpoint`  | `workspaceId`、`url`、`subscribedEvents[]`、`description?`                                                 | 创建 Webhook 端点并返回签名密钥。`url` 必须使用 HTTPS（`localhost` 允许使用 `http`）。 |
| `update_webhook_endpoint`  | `workspaceId`、`endpointId`、`url?`、`description?`、`subscribedEvents?`、`status?`（`enabled` \| `disabled`） | 更新端点配置。未指定的字段保持不变。                                              |
| `ping_webhook_endpoint`    | `workspaceId`、`endpointId`                                                                              | 向已启用的端点发送带签名的测试事件。返回 `{ sent: true }`。                          |
| `list_webhook_deliveries`  | `workspaceId`、`endpointId`                                                                              | 按时间倒序获取端点的投递日志：投递状态、尝试次数、HTTP 响应码、响应主体与 `nextAttemptAt`。        |
| `resend_webhook_delivery`  | `workspaceId`、`deliveryId`                                                                              | 重新发起投递尝试，保留原始事件 ID。                                             |

## 请求日志与指标

查询 API 访问日志与性能指标。需要目标业务单元的**所有者**（Owner）或**管理员**（Admin）角色。

| 工具                      | 参数                                                                                                 | 说明与返回值                                                                     |
| ----------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `list_api_request_logs` | `workspaceId`、`limit?`（1–200，默认 50）、`before?`、`method?`、`status?`（`2xx`…`5xx`）、`path?`、`apiKeyId?` | 查询业务单元内密钥发起的 API 请求日志。通过传入上一页末尾的 `createdAt` 作为 `before` 游标实现分页。           |
| `get_api_request_log`   | `workspaceId`、`logId`                                                                              | 获取单条请求的完整信息：来源 IP、User-Agent、API 版本、请求与响应主体（超过 16 KB 自动截断；`/auth/` 路径已脱敏）。 |
| `get_api_metrics`       | `workspaceId`、`days?`（1、7 或 30；默认 7）                                                               | 获取按 48 个时间桶聚合的请求量、错误计数与延迟指标，以及总计统计。                                        |

## 错误处理

当操作无法完成时，工具将返回明确的结构化错误信息说明原因（例如 `Business unit not found.`、`Insufficient permissions for role (viewer).` 或 `Origin must follow scheme://host[:port] format.`）。

参数校验在工具执行前完成，缺失或非法的参数将被直接拒绝并指明具体字段。

## 业务数据接口

MCP 服务专注于管理与开发者运维能力。如需读写活动业务数据（如创建活动、配置票种、审批报名或处理订单），请先通过 `create_api_key` 生成 Secret 密钥，然后直接调用 [Developer API](/zh/developers/overview)。