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

# MCP server

> 把 Hermai schema 和 schema request 暴露為 Model Context Protocol tools。

Hermai 提供獨立的 MCP server package。適合你的 agent runtime 支援本地 MCP tools,並希望 agent 查詢 schema 或提交缺失工作流請求,而不是抓網頁或手寫 API 呼叫。

## 安裝

直接用 npm 執行 MCP server:

```bash theme={null}
npx -y hermai-mcp
```

或全域安裝:

```bash theme={null}
npm install -g hermai-mcp
hermai-mcp
```

只讀 catalog 查詢和公開 schema request intake 可在公開速率限制內匿名使用。若在 MCP client 環境中提供 `HERMAI_API_KEY` 或 `HERMAI_PLATFORM_KEY`,則使用 authenticated requests。提供 key 還會啟用 `fetch_schema` 執行工具,它執行託管的 `/v1/fetch` 並消耗 credits。

## 通用 client 配置

MCP client 的配置路徑因 runtime 而異,但 server entry 形狀如下:

```json theme={null}
{
  "mcpServers": {
    "hermai": {
      "command": "npx",
      "args": ["-y", "hermai-mcp"],
      "env": {
        "HERMAI_API_KEY": "hm_sk_..."
      }
    }
  }
}
```

公開查詢和 schema request intake 不強制需要環境變數。

## Tools

### `lookup_schema`

按 domain、task、category 或 verification state 搜尋 Hermai。抓取網站之前先用這個工具。

### `list_public_schemas`

瀏覽公開 schema,支援 `q`、`category`、`verified`、`sort`、`limit` 等可選過濾。

### `fetch_schema`

透過託管的 `/v1/fetch` 執行已註冊的 schema 並回傳即時資料。僅當設定了 `HERMAI_API_KEY`(或 `HERMAI_PLATFORM_KEY`)時才會暴露此工具,且**會消耗 Hermai credits**:標準呼叫消耗 1 credit,部分成本更高的網站消耗 5,且只有成功的呼叫才計費。

先用 `lookup_schema` 解析出確切的 `site` 和 `endpoint`,然後呼叫:

* `site` — 已註冊的 host,例如 `wegmans.com`。
* `endpoint` — schema 中的 endpoint 名稱,例如 `product_search`。區分大小寫。
* `params` — 可選的 endpoint 參數,鍵值對形式。

回傳結果包含上游 `data` 以及一個 meta 摘要(`credits_used`、`credits_remaining`、`latency_ms`、`cached`);失敗的 fetch 會回傳 API 的 `code` 和 `message`,當 workspace 的 credits 用盡時還會回傳 `upgrade_to` 和 `upgrade_url`。僅用於讀取工作流。寫入和需擁有者核准的工作流走 Hermai CLI 的 signed-write 路徑。設定 `HERMAI_FETCH_TIMEOUT_MS` 可覆寫預設的 120 秒逾時。

### `submit_schema_request`

提交缺失或脆弱工作流的六欄位 intake:

* `domain`
* `task`
* `read_or_write`
* `auth_shape`
* `output_shape`
* `failure_mode`

可選上下文字段包括 `source_url`、`requester_agent`、`requester_contact` 和 `idempotency_key`。

不要在 schema request 中包含 cookies、API keys、bearer tokens、私有 session 資料或憑據。

### `classify_browser_workflow`

在本地把自然語言需求分類為 `direct_api`、`hidden_endpoint`、`browser_only`、`needs_owner` 或 `needs_more_fields`。用於決定查詢現有 schema、提交 request,還是向使用者補齊 intake 欄位。

### `check_schema_request_status`

按 id 查詢之前提交的 schema request 狀態。

## 何時使用 MCP

當 agent runtime 可以執行本地 tool server 時,使用 MCP。當 runtime 無法執行 MCP 時,使用直接 HTTP API。需要瀏覽器 cookie import、session bootstrap 或 signed write execution 等終端流程時,直接使用 CLI 命令。