跳转到主要内容
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 命令。