Linkfox Mercado Product Selection

Mercado Libre Product Selection

This skill queries Mercado Libre product, catalog, keyword, category, trend, seller, review, exchange-rate, and plan-usage data through the LinkFox gateway. The gateway exposes one unified route, POST /mercado/productSelection, and the skill selects one of 24 supported toolName values with matching arguments.

Core Concepts

• Call only ${LINKFOX_TOOL_GATEWAY}/mercado/productSelection. Do not call the upstream XP-MCP server directly, and do not ask the user for upstream secret-key / X-API-Key — upstream credentials are owned by the backend.
• The request body is always {"toolName":"...","arguments":{...}}. The script takes this whole object as a single JSON argument.
• Field names inside arguments must match references/mercado-tool-reference.md exactly, including camelCase names such as siteId, itemId, productId, categoryId, runDate, runMonth, pageNo, pageSize.
• Read data first when presenting results. Read contentText when data is text or ambiguous. Show rawResponse only when the user asks for raw diagnostics.
• Paid tools currently cost 16000 tokens per call; free tools cost 0. Trust the backend costToken field.

Reference Files

• references/api.md: LinkFox gateway contract, request/response structure, error codes, curl example, and Feedback API.
• references/mercado-tool-reference.md: detailed Chinese reference for the 24 Mercado Libre tools — parameters, site IDs, pagination, sorting, and billing status.

Tool Selection

Free tools: categorySearch, categorySmallSearch, reviewSearch, rateInfo, myUsage. All others are paid.

Parameter Guide

• toolName (string, required): one of the 24 tools above.
• arguments (object, required): the tool's parameter object. Must be a JSON object, not an array/string/number. The backend strips uId/uid/memberId and trims empty values.
• Sites: MLM (Mexico), MLB (Brazil), MLA (Argentina), MLC (Chile), MCO (Colombia — only for tools whose reference explicitly lists it).
• When the user gives a category name instead of a categoryId, call categorySearch or categorySmallSearch first, then use the returned category ID for paid trend/product/catalog tools.
• reviewSearch takes itemId only (no siteId). myUsage takes {}.
• For broad research questions, narrow paid calls with site, category, keyword, date/month, pagination, price, sales, or sorting filters. Avoid exploratory paid calls not anchored to the user's goal.

调用方式

• API 端点：POST /mercado/productSelection（完整参数/响应/错误码见 references/api.md）
• Python 脚本：python scripts/linkfox_mercado_product_selection.py '<JSON 参数>' [--inline]
• 成本约束：本工具会消耗算力；同一会话同一参数组合默认只调用一次，脚本带 24h 本地缓存。失败/空结果不得自动换关键词、翻页或改邮编连续试探；需要继续检索时先向用户说明会产生额外消耗。

输出策略（脚本默认行为）：

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-mercado-product-selection-<timestamp>.json（<cwd> 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；<session> 取自环境变量 SESSION_ID，按用户任务自动聚合；禁止写入 /tmp，当前目录不可写则报错）
• 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout
• 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 total/costToken、最大列表字段的长度 + 前 3 条样本）
• 加 --inline 强制全量打印到 stdout（同样落盘）

读数据建议：先看摘要判断是否足够；需要具体字段时优先用 jq或ConvertFrom-Json 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。

解决认证和算力问题

发生以下异常情况时，采用 references/onboarding.md 引导解决问题：

异常情况

• 未配置API Key：环境变量未配置 LINKFOX_AGENT_API_KEY，也未配置 LINKFOXAGENT_API_KEY。
• 响应401或402状态码
• 响应提示算力或余额不足：消息含"算力余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值"，或类似含义的内容。

Usage Examples

The single JSON argument is the full payload {"toolName":...,"arguments":{...}}.

# Free: search Mexico categories by name
python scripts/linkfox_mercado_product_selection.py '{"toolName":"categorySearch","arguments":{"siteId":"MLM","searchText":"Auriculares"}}'

# Paid: product detail for a real MLM item
python scripts/linkfox_mercado_product_selection.py '{"toolName":"itemInfo","arguments":{"siteId":"MLM","itemId":"MLM4979447466"}}'

# Free: my plan usage (no arguments)
python scripts/linkfox_mercado_product_selection.py '{"toolName":"myUsage","arguments":{}}'

# Paid: monthly hot keywords for Brazil, 2026-06
python scripts/linkfox_mercado_product_selection.py '{"toolName":"keywordMonthSearch","arguments":{"siteId":"MLB","runMonth":"202606"}}'

On PowerShell, wrap the JSON in single quotes the same way; if quoting is troublesome, write the payload to a file and pass it via --inline after loading, or use ConvertTo-Json to build the argument.