Agent API 与 MCP

适用对象：LLM Agent、Tool Calling 运行时、MCP 客户端（Cursor、Claude Desktop 等）。人类后端与商城集成请用 /v1/* + OpenAPI 。

AI 集成：MCP 与 hiobuy-agent-api Skill 向 LLM Agent 暴露 1688、淘宝、微店的 China sourcing 工具——关键词搜索、以图搜货、双语商品详情，适用于 Cursor / Claude Desktop 中的 shopping agent 工作流。

鉴权： 仅支持 hio_live_* Live 密钥。** 沙箱密钥（hio_test_*）与沙箱环境的 Fixture 不适用 /ai/v1 与 /mcp。

相关：鉴权 · 商品 · 响应结构 · 错误 · 限流

选用哪套接口

集成方式	路径前缀	密钥	说明
商城 / 后端 REST	`/v1/*`	`hio_live_` 或 `hio_test_`	本站各章节；仅 `/v1` 可选 `response_format=upstream`
Agent Tool Calling（HTTP）	`/ai/v1/*`	*仅 `hio_live_`**	标准 JSON envelope；映射现有 API Key scope
MCP（Streamable HTTP）	`/mcp`	*仅 `hio_live_`**	与 `/ai/v1` 相同 tools；另含 prompts、resources、SSE 会话
OpenAPI 代码生成	`/v1/*`	二者皆可	不包含 `/ai/v1` 与 `/mcp`

Tool 返回的 data 始终为 standard 结构，与商品数据结构及列表接口一致，无 upstream 原始格式。

前置条件（Live Key）

调用 /ai/v1 或 /mcp 前：

在 HIOBuy 开发者门户注册应用并通过审核。
授权渠道（1688、淘宝、微店等）——与门户授权相同。
在 API Keys 创建 Live 密钥（hio_live_*，创建时仅完整展示一次）。
至少勾选 Phase 1 所需 scope：
- product:detail — product.get_detail
- product:search — product.search、product.upload_image、product.search_by_image

未授权渠道或 scope 不足 → 401 / 403。Live 调用计入渠道配额并写入请求日志，与 /v1 一致。

Base URL 与认证

与 Public API 相同，例如 https://api.hiobuy.com。

Authorization: Bearer hio_live_<your_key>

每个 tool 对应既有 API Key scope，没有单独的 tools:* scope。

HTTP 端点（`/ai/v1`）

方法	路径	说明
GET	`/ai/v1/tools`	列出当前密钥可调用的 tools（含 `input_schema`）
POST	`/ai/v1/tools/call`	按 `tool_id` + `arguments` 调用

列出 tools

curl -s https://api.hiobuy.com/ai/v1/tools \
  -H "Authorization: Bearer hio_live_xxx"

仅返回当前密钥 scope 允许的 tools；每项含 id、version、domain、description 与 JSON Schema input_schema。

调用 tool

POST /ai/v1/tools/call
Authorization: Bearer hio_live_xxx
Content-Type: application/json
 
{
  "tool_id": "product.get_detail",
  "arguments": {
    "channel": "1688",
    "product_id": "554456348334",
    "language": "en"
  }
}

成功 envelope（所有 tool 统一）：

字段	说明
`tool_id`	与请求一致
`ok`	成功时为 `true`
`data`	业务数据（见下）
`request_id`	追踪 ID，联系支持时请提供

失败： HTTP 4xx/5xx，{ "error": { "code", "message", "request_id" } }，无 ok 字段。常见码见错误（INVALID_API_KEY、FORBIDDEN、RATE_LIMITED 等）。

Phase 1 Tools（商品）

`tool_id`	Scope	对应 REST 文档
`product.get_detail`	`product:detail`	商品详情
`product.search`	`product:search`	关键词搜索
`product.upload_image`	`product:search`	上传商品图
`product.search_by_image`	`product:search`	以图搜商品

`product.get_detail`

Channel： taobao | 1688 | weidian
必填： channel + product_id | url | mi_id | tao_password 之一
可选： language（默认 en）
data： { "product": StandardProduct }

`product.search`

必填： channel、keyword
可选： page、page_size、language、sort、price_start、price_end
data： StandardProductList（与 POST /v1/products/search 响应体相同）

`product.upload_image`

Channel： 1688 | taobao
1688： image_base64 与 image_url 二选一
淘宝： 必填 image_base64
data： { "channel", "image_id" } — 翻页图搜时复用 image_id

`product.search_by_image`

Channel： 1688 | taobao（不支持微店）
输入： image_id | image_url | image_base64
推荐翻页： 先 product.upload_image，再多次 product.search_by_image（仅传 image_id）

Agent 工作流（HTTP）

1. GET /ai/v1/tools → 缓存 metadata / input_schema
2. 根据用户意图选择 tool_id + arguments
3. POST /ai/v1/tools/call（Bearer hio_live_…）
4. 摘要 data 返回用户

典型链路：

单次图搜： product.search_by_image（image_url / image_base64）
翻页图搜： product.upload_image → product.search_by_image（image_id + page）
用户选中商品： product.get_detail

MCP 服务（`/mcp`）— AI Agent China 选品

在 Cursor、Claude Desktop 等 MCP 客户端中，Agent 可调用 1688（批发）、淘宝（零售）、微店的 China sourcing 与 代购选品 工具——关键词搜索、以图搜货、上传商品图与双语详情。典型 shopping agent 链路：在 1688 比工厂价、找淘宝同款、浏览微店橱窗，再通过 product.get_detail 查看 SKU/库存。

同一套 Tool Runtime 以 Streamable HTTP 暴露为 MCP Server（Cursor、Claude Desktop 等）。

方法	路径	MCP 用途
POST	`/mcp`	JSON-RPC：`initialize`、`tools/list`、`tools/call`、`prompts/`、`resources/` 等
GET	`/mcp`	SSE 长连接（需 `Mcp-Session-Id`）

认证： 同上 Authorization: Bearer hio_live_*。

能力概览：

Tools — tools/list、tools/call（与 /ai/v1 相同 tool_id）
Prompts — 内置商品搜索 / 图搜 / 调研工作流
Resources — hiobuy://agent/* URI（resources/list、resources/read、templates）
Subscriptions — resources/subscribe → SSE notifications/resources/updated
Streaming — GET /mcp 开 SSE；POST 带 Accept: text/event-stream 可流式返回 JSON-RPC
Sampling — 服务端经 SSE 发 sampling/createMessage；客户端 POST /mcp 回传（202）

推荐连接流程：

POST initialize → 保存响应头 Mcp-Session-Id
GET /mcp（带 session）打开 SSE
POST notifications/initialized
POST tools/list / tools/call

tools/call 成功时，result.content[0].text 与 /ai/v1/tools/call 的 JSON envelope 相同。

Cursor 配置（shopping agent MCP）

在 Settings → MCP 或 .cursor/mcp.json 中添加，为 Cursor 接入 1688 / 淘宝 / 微店 China sourcing 工具：

{
  "mcpServers": {
    "hiobuy": {
      "url": "https://api.hiobuy.com/mcp",
      "headers": {
        "Authorization": "Bearer hio_live_xxx"
      }
    }
  }
}

将 hio_live_xxx 替换为你的 Live 密钥。密钥仅放服务端，勿提交到公开仓库。

Cursor Agent Skill（`hiobuy-agent-api`）— China shopping agent

可选 hiobuy-agent-api Cursor Agent Skill 帮助编码 Agent 接入 1688、淘宝、微店 的 China sourcing 流程——Live 密钥 scope、/ai/v1 envelope、MCP 会话头，以及搜索 → 图搜 → 详情 tool 链路。商城 REST 集成请用 /v1/* 与 OpenAPI。

Skill 帮助模型理解：

1688 / 淘宝 / 微店 商品 tools 的 Live 密钥前置条件与 scope
/ai/v1 请求/响应 envelope 与 Phase 1 参数
China shopping 工作流的 MCP 会话头与 Cursor mcp.json 配置
错误码与选品链路（搜索 → 图搜 → 详情）

从公开仓库 hiobuy-agent-skills 克隆或复制 SKILL.md 到 Cursor skills 路径（见 Cursor Agent Skills ）。

git clone https://github.com/hubinjie/hiobuy-agent-skills.git

Skill 补充本文——本站仍是 scope、配额与字段语义的权威 API 参考。

速查

BASE=https://api.hiobuy.com
KEY=hio_live_xxx
 
curl -s "$BASE/ai/v1/tools" -H "Authorization: Bearer $KEY"
 
curl -s "$BASE/ai/v1/tools/call" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool_id":"product.search","arguments":{"channel":"1688","keyword":"phone case","page":1,"page_size":5}}'

Agent API 与 MCP

选用哪套接口

前置条件（Live Key）

Base URL 与认证

HTTP 端点（/ai/v1）

列出 tools

调用 tool

Phase 1 Tools（商品）

product.get_detail

product.search

product.upload_image

product.search_by_image