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

​
安裝

直接用 npm 執行 MCP server: 
npx -y hermai-mcp
或全域安裝: 
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 形狀如下: 
{
  "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 命令。