MCP 接入文档

1. 获取 MCP Access Token

1. 账号需要被设置为 OmniTrack Home 高级用户。
2. 在 Android 应用进入“我的 → 账号与家庭 → MCP 外部访问”。
3. 填写外部应用名称并生成 Token。
4. 立即保存完整 Token。完整值只显示一次，服务端不保存明文。

2. 快速接入

不同 AI 客户端的配置字段名可能不同，核心配置始终是以下三项：

{
  "mcpServers": {
    "omni-home": {
      "type": "streamable-http",
      "url": "https://omni.muyin.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${OMNI_HOME_MCP_TOKEN}"
      }
    }
  }
}

建议把 Token 放入客户端的密钥存储或环境变量 OMNI_HOME_MCP_TOKEN。如果客户端不支持自定义 Header，需要由对接方增加一个保密的服务端代理，不能把 Token 暴露给浏览器用户。

请将 OmniTrack Home 作为远程 MCP Server 接入当前应用。

MCP endpoint: https://omni.muyin.com/api/mcp
Transport: Streamable HTTP, stateless JSON-RPC 2.0 over POST
Authentication: Authorization: Bearer <OMNI_HOME_MCP_TOKEN>
Protocol version: 2025-11-25
Required request headers after initialization:
  Content-Type: application/json
  Accept: application/json, text/event-stream
  MCP-Protocol-Version: 2025-11-25

可用工具：
1. list_recent_expiry_items
   参数：可选 householdId:string。省略时使用 Token 可访问的第一个家庭。
   用途：返回已经过期或未来 30 天内到期的物品，最多 100 项；每项包含 roomName、containerName、containerPath、locationPath 和 location 对象。

2. recognize_shopping_list_image
   参数：imageUrl 或 dataBase64 二选一；Base64 还需 mimeType；mode 可选 standard/precise；householdId 和 idempotencyKey 可选。
   用途：识别购物清单中的商品，同步返回建议位置、到期日和名称文字框，并放入该用户的 Android 待确认队列。

3. recognize_item_photo
   参数：imageUrl 或 dataBase64 二选一；Base64 还需 mimeType；mode 可选 standard/precise；householdId 和 idempotencyKey 可选。
   用途：识别实景物品照片，同步返回物品、位置建议、到期日、边界框及关系，并放入该用户的 Android 待确认队列。

4. search_inventory
   参数：query 必填；householdId、limit 可选。
   用途：按名称、分类、房间、收纳点和内置同义词搜索当前家庭的有效库存。

5. get_inventory_quantity
   参数：query 必填；householdId 可选。
   用途：返回匹配条目数、匹配物品，以及按单位分别汇总的规范化数量。

6. get_inventory_overview
   参数：view 必填，可取 expiry、low_stock、stock_ranking、household_value；householdId 可选。
   用途：确定性返回临期、低库存、库存数量排行或已记录价格的家庭库存总价值。

7. adjust_quantity
   参数：itemId、delta、idempotencyKey 必填；householdId、unit、remainingRatio、reason、expectedUpdatedAt 可选。
   用途：原子增加或消耗库存数量并记录操作人和库存流水。delta 为正表示增加，为负表示消耗。

8. mark_item_used_up
   参数：itemId、idempotencyKey 必填；householdId、reason、expectedUpdatedAt 可选。
   用途：将指定物品标记用完并移出有效库存，同时保留库存流水。

图片约束：仅允许公网 HTTPS URL，或 JPEG/PNG/WebP Base64；最大 12 MB；Base64 不含 data: 前缀。
库存工具自动限定为 Token 用户可访问的家庭，不允许传入 SQL。写工具具有 destructiveHint，客户端应在调用前取得用户明确确认并使用稳定 idempotencyKey 防止重试重复写入。
工具成功结果位于 JSON-RPC result.structuredContent，同时 result.content[0].text 提供 JSON 文本。
工具级失败可能以 HTTP 200 + result.isError=true 返回；鉴权失败为 HTTP 401，限流为 HTTP 429。
每个 Token 限制为每分钟 120 个请求。图片识别结果会同时进入该用户的云端待确认队列，Android 显示“查看并确认”；确认前不会自动保存到库存。

4. 工具说明

库存安全边界：所有库存工具都从 MCP Token 解析当前账号和可访问家庭，调用方不能执行 SQL。写工具标记为破坏性操作，兼容客户端应先展示变更并要求用户确认。

图片识别工具的共同参数

5. JSON-RPC 调用示例

下面的 $TOKEN 表示完整 MCP Access Token。初始化完成后，后续请求携带协商出的 MCP-Protocol-Version。

curl 'https://omni.muyin.com/api/mcp' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-11-25",
      "capabilities": {},
      "clientInfo": { "name": "partner-app", "version": "1.0.0" }
    }
  }'

curl 'https://omni.muyin.com/api/mcp' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  --data '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "list_recent_expiry_items",
      "arguments": {}
    }
  }'

curl 'https://omni.muyin.com/api/mcp' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  --data '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "recognize_shopping_list_image",
      "arguments": {
        "imageUrl": "https://images.example.com/shopping-list.jpg",
        "mode": "standard",
        "idempotencyKey": "shopping-order-20260817-001"
      }
    }
  }'

IMAGE_BASE64="$(base64 < item.jpg | tr -d '\n')"

curl 'https://omni.muyin.com/api/mcp' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  --data "$(jq -n --arg image \"$IMAGE_BASE64\" '{
    jsonrpc: \"2.0\",
    id: 4,
    method: \"tools/call\",
    params: {
      name: \"recognize_item_photo\",
      arguments: { dataBase64: $image, mimeType: \"image/jpeg\", mode: \"precise\" }
    }
  }')"

图片识别的待确认回执

两个图片工具的 structuredContent 除识别 JSON 外还包含以下字段。外部应用可保存 sessionId 用于追踪；库存写入仍由用户在 Android 确认后完成。

"backgroundQueue": {
  "sessionId": "scan-...",
  "status": "draft",
  "replayed": false,
  "itemCount": 8,
  "household": { "id": "...", "name": "我的家庭" },
  "androidAction": "查看并确认"
}

6. 返回结构与错误处理

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      { "type": "text", "text": "{ ...同一份结果的 JSON 文本... }" }
    ],
    "structuredContent": {
      "household": { "id": "...", "name": "我的家庭" },
      "generatedAt": "2026-08-17T08:00:00.000Z",
      "total": 1,
      "items": [
        {
          "id": "...",
          "name": "牛奶",
          "expiryDate": "2026-08-18",
          "daysRemaining": 1,
          "status": "urgent",
          "roomName": "厨房",
          "containerName": "冰箱",
          "containerPath": ["冰箱"],
          "locationPath": "厨房 / 冰箱"
        }
      ]
    }
  }
}

7. 限制与安全

• 每个 Token 最多每分钟 120 个 MCP 请求。
• 每个高级用户最多保留 10 个有效 Token；撤销 Token 或账号降级后立即失效。
• Token 只能访问该用户实际加入的家庭；传入无权限的 householdId 会失败。
• 公网图片必须使用 HTTPS，禁止 localhost、私网 IP、.local 地址、URL 凭证和非标准端口。
• 图片支持 JPEG、PNG、WebP，解码后最大 12 MB；每次工具调用只接收一张图片。
• 图片工具会保存识别草稿与必要的 OSS 图片引用；Android 保存或丢弃后草稿从待确认列表移除。
• 当前端点使用手动生成的 Bearer Token，不提供 OAuth 自动发现；客户端必须支持自定义 Header。
• 当前服务不提供服务器主动消息流；客户端对 GET 收到 405 应视为“不提供 SSE 监听”，正常工具调用使用 POST。

协议实现参考 MCP 2025-11-25 Streamable HTTP。查看 MCP 官方传输规范与生命周期规范。