{"openapi": "3.0.3", "info": {"title": "Mock Taobao MCP", "version": "1.0.0", "description": "试跑请打开 **/docs**，不要在 Swagger 里点 POST /mcp。\n\n- 试跑：`POST /docs/try` 或 `POST /tools/{name}`，结果与 MCP `tools/call` 相同\n- 接入 Cursor：`mcpServers` + `headers.Authorization`\n- 接入 Codex：`~/.codex/config.toml` 写 `url` + `bearer_token_env_var`，JWT 放环境变量，不要 `codex mcp login`\n- `shop_id` 必须和票里的店铺一致；填 `demo_shop` 而票绑了别的店会 `shop_isolated`\n- 缺数：`ok=false, reason=not_found`，不编造。HTTP 仍可能是 200\n- 柜台调用日志记录 IP、User-Agent、会话，不存 token"}, "servers": [{"url": "/", "description": "当前主机"}], "tags": [{"name": "MCP", "description": "正式 JSON-RPC 入口"}, {"name": "元数据"}, {"name": "商品"}, {"name": "万相台"}, {"name": "DMP"}, {"name": "生意参谋"}, {"name": "市场"}], "paths": {"/mcp": {"post": {"tags": ["MCP"], "summary": "MCP Streamable HTTP", "description": "给 Cursor / Codex 用，不要在 Swagger 里试 tools/call。\nCursor 配 mcpServers + headers.Authorization。\nCodex 配 ~/.codex/config.toml 的 url + bearer_token_env_var，不要贴 Cursor JSON，不要 codex mcp login。\n缺 `mcp-session-id` 会 400 Missing session ID。\n握手：initialize → notifications/initialized → tools/list → tools/call。协议 2025-11-25。试跑请用下面的 POST /tools/{name}。", "security": [{"bearerAuth": []}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object"}, "example": {"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-11-25", "capabilities": {}, "clientInfo": {"name": "swagger", "version": "1.0.0"}}}}}}, "responses": {"200": {"description": "JSON-RPC 或 SSE。响应头 mcp-session-id 给后续请求用。"}, "400": {"description": "Missing session ID：先 initialize，再带 mcp-session-id"}, "401": {"description": "invalid_token"}}}}, "/tools/health_check": {"post": {"tags": ["元数据"], "operationId": "health_check", "summary": "检查 Mock MCP 与 PostgreSQL", "description": "与 MCP 工具 `health_check` 相同。Swagger 点 Try it out 即可。", "security": [{"bearerAuth": []}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "required": [], "properties": {}}, "example": {}}}}, "responses": {"200": {"description": "MCP 工具结果。ok=false 时看 reason，HTTP 仍是 200。", "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean"}, "tool": {"type": "string"}, "query": {"type": "object"}, "count": {"type": "integer"}, "rows": {"type": "array", "items": {"type": "object"}}, "reason": {"type": "string", "description": "not_found / shop_isolated / item_id_required / shop_id_required / invalid_report_type / invalid_section / invalid_pack_type / invalid_peer_type"}}}}}}, "401": {"description": "缺少或无效 Bearer"}, "400": {"description": "未知工具或参数不合法"}}}}, "/tools/list_catalog": {"post": {"tags": ["元数据"], "operationId": "list_catalog", "summary": "列出已导入契约", "description": "与 MCP 工具 `list_catalog` 相同。Swagger 点 Try it out 即可。", "security": [{"bearerAuth": []}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "required": [], "properties": {"tool_name": {"type": "string", "description": "英文工具名", "example": "get_item_detail"}, "plate": {"type": "string", "description": "板块", "example": "万相台"}}}, "example": {"tool_name": "get_item_detail"}}}}, "responses": {"200": {"description": "MCP 工具结果。ok=false 时看 reason，HTTP 仍是 200。", "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean"}, "tool": {"type": "string"}, "query": {"type": "object"}, "count": {"type": "integer"}, "rows": {"type": "array", "items": {"type": "object"}}, "reason": {"type": "string", "description": "not_found / shop_isolated / item_id_required / shop_id_required / invalid_report_type / invalid_section / invalid_pack_type / invalid_peer_type"}}}}}}, "401": {"description": "缺少或无效 Bearer"}, "400": {"description": "未知工具或参数不合法"}}}}, "/tools/get_item_detail": {"post": {"tags": ["商品"], "operationId": "get_item_detail", "summary": "商品明细 13 维", "description": "与 MCP 工具 `get_item_detail` 相同。Swagger 点 Try it out 即可。", "security": [{"bearerAuth": []}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "required": ["item_id"], "properties": {"item_id": {"type": "string", "description": "商品 ID", "example": "10001"}, "shop_id": {"type": "string", "description": "店铺 ID", "example": "demo_shop"}}}, "example": {"item_id": "10001", "shop_id": "demo_shop"}}}}, "responses": {"200": {"description": "MCP 工具结果。ok=false 时看 reason，HTTP 仍是 200。", "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean"}, "tool": {"type": "string"}, "query": {"type": "object"}, "count": {"type": "integer"}, "rows": {"type": "array", "items": {"type": "object"}}, "reason": {"type": "string", "description": "not_found / shop_isolated / item_id_required / shop_id_required / invalid_report_type / invalid_section / invalid_pack_type / invalid_peer_type"}}}}}}, "401": {"description": "缺少或无效 Bearer"}, "400": {"description": "未知工具或参数不合法"}}}}, "/tools/get_wx_report": {"post": {"tags": ["万相台"], "operationId": "get_wx_report", "summary": "万相台投放报表", "description": "与 MCP 工具 `get_wx_report` 相同。Swagger 点 Try it out 即可。", "security": [{"bearerAuth": []}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "required": ["shop_id", "report_type"], "properties": {"shop_id": {"type": "string", "description": "店铺 ID", "example": "demo_shop"}, "report_type": {"type": "string", "description": "英文码或中文名，如 plan / 计划报表", "example": "计划报表", "enum": ["scene", "plan", "crowd", "item", "content", "creative", "region", "realtime", "unit", "keyword", "benefit", "营销场景报表", "计划报表", "人群报表", "商品报表", "内容报表", "创意报表", "地域报表", "实时报表", "单元报表", "关键词报表", "权益报表"]}, "date_from": {"type": "string", "description": "YYYY-MM-DD", "example": "2026-08-25"}, "date_to": {"type": "string", "description": "YYYY-MM-DD", "example": "2026-08-25"}, "item_id": {"type": "string", "description": "商品 ID", "example": "10001"}}}, "example": {"shop_id": "demo_shop", "report_type": "计划报表"}}}}, "responses": {"200": {"description": "MCP 工具结果。ok=false 时看 reason，HTTP 仍是 200。", "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean"}, "tool": {"type": "string"}, "query": {"type": "object"}, "count": {"type": "integer"}, "rows": {"type": "array", "items": {"type": "object"}}, "reason": {"type": "string", "description": "not_found / shop_isolated / item_id_required / shop_id_required / invalid_report_type / invalid_section / invalid_pack_type / invalid_peer_type"}}}}}}, "401": {"description": "缺少或无效 Bearer"}, "400": {"description": "未知工具或参数不合法"}}}}, "/tools/get_wx_traffic_insight": {"post": {"tags": ["万相台"], "operationId": "get_wx_traffic_insight", "summary": "无界流量解析", "description": "与 MCP 工具 `get_wx_traffic_insight` 相同。Swagger 点 Try it out 即可。", "security": [{"bearerAuth": []}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "required": ["shop_id"], "properties": {"shop_id": {"type": "string", "description": "店铺 ID", "example": "demo_shop"}, "keyword": {"type": "string", "description": "关键词", "example": "便携咖啡杯"}}}, "example": {"shop_id": "demo_shop", "keyword": "便携咖啡杯"}}}}, "responses": {"200": {"description": "MCP 工具结果。ok=false 时看 reason，HTTP 仍是 200。", "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean"}, "tool": {"type": "string"}, "query": {"type": "object"}, "count": {"type": "integer"}, "rows": {"type": "array", "items": {"type": "object"}}, "reason": {"type": "string", "description": "not_found / shop_isolated / item_id_required / shop_id_required / invalid_report_type / invalid_section / invalid_pack_type / invalid_peer_type"}}}}}}, "401": {"description": "缺少或无效 Bearer"}, "400": {"description": "未知工具或参数不合法"}}}}, "/tools/get_item_crowd_lifecycle": {"post": {"tags": ["商品"], "operationId": "get_item_crowd_lifecycle", "summary": "单品新回老", "description": "与 MCP 工具 `get_item_crowd_lifecycle` 相同。Swagger 点 Try it out 即可。", "security": [{"bearerAuth": []}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "required": ["item_id"], "properties": {"item_id": {"type": "string", "description": "商品 ID", "example": "10001"}, "shop_id": {"type": "string", "description": "店铺 ID", "example": "demo_shop"}}}, "example": {"item_id": "10001", "shop_id": "demo_shop"}}}}, "responses": {"200": {"description": "MCP 工具结果。ok=false 时看 reason，HTTP 仍是 200。", "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean"}, "tool": {"type": "string"}, "query": {"type": "object"}, "count": {"type": "integer"}, "rows": {"type": "array", "items": {"type": "object"}}, "reason": {"type": "string", "description": "not_found / shop_isolated / item_id_required / shop_id_required / invalid_report_type / invalid_section / invalid_pack_type / invalid_peer_type"}}}}}}, "401": {"description": "缺少或无效 Bearer"}, "400": {"description": "未知工具或参数不合法"}}}}, "/tools/get_dmp_category": {"post": {"tags": ["DMP"], "operationId": "get_dmp_category", "summary": "竞店类目分析", "description": "与 MCP 工具 `get_dmp_category` 相同。Swagger 点 Try it out 即可。", "security": [{"bearerAuth": []}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "required": ["shop_id"], "properties": {"shop_id": {"type": "string", "description": "店铺 ID", "example": "demo_shop"}, "category_id": {"type": "string", "description": "类目 ID", "example": "50014463"}}}, "example": {"shop_id": "demo_shop", "category_id": "50014463"}}}}, "responses": {"200": {"description": "MCP 工具结果。ok=false 时看 reason，HTTP 仍是 200。", "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean"}, "tool": {"type": "string"}, "query": {"type": "object"}, "count": {"type": "integer"}, "rows": {"type": "array", "items": {"type": "object"}}, "reason": {"type": "string", "description": "not_found / shop_isolated / item_id_required / shop_id_required / invalid_report_type / invalid_section / invalid_pack_type / invalid_peer_type"}}}}}}, "401": {"description": "缺少或无效 Bearer"}, "400": {"description": "未知工具或参数不合法"}}}}, "/tools/get_sycm_customer": {"post": {"tags": ["生意参谋"], "operationId": "get_sycm_customer", "summary": "客户分层", "description": "与 MCP 工具 `get_sycm_customer` 相同。Swagger 点 Try it out 即可。", "security": [{"bearerAuth": []}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "required": ["shop_id"], "properties": {"shop_id": {"type": "string", "description": "店铺 ID", "example": "demo_shop"}}}, "example": {"shop_id": "demo_shop"}}}}, "responses": {"200": {"description": "MCP 工具结果。ok=false 时看 reason，HTTP 仍是 200。", "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean"}, "tool": {"type": "string"}, "query": {"type": "object"}, "count": {"type": "integer"}, "rows": {"type": "array", "items": {"type": "object"}}, "reason": {"type": "string", "description": "not_found / shop_isolated / item_id_required / shop_id_required / invalid_report_type / invalid_section / invalid_pack_type / invalid_peer_type"}}}}}}, "401": {"description": "缺少或无效 Bearer"}, "400": {"description": "未知工具或参数不合法"}}}}, "/tools/get_sycm_item": {"post": {"tags": ["生意参谋"], "operationId": "get_sycm_item", "summary": "商品板块", "description": "与 MCP 工具 `get_sycm_item` 相同。Swagger 点 Try it out 即可。", "security": [{"bearerAuth": []}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "required": [], "properties": {"item_id": {"type": "string", "description": "商品 ID", "example": "10001"}, "shop_id": {"type": "string", "description": "店铺 ID", "example": "demo_shop"}, "section": {"type": "string", "description": "板块英文码或中文名", "example": "rank", "enum": ["rank", "sale", "traffic_source", "detail", "refund", "price", "title", "content", "crowd", "bundle", "related", "商品排行", "销售分析", "流量来源", "详情分析", "退款分析", "价格分析", "标题优化", "内容分析", "客群洞察", "关联搭配", "连带分析"]}, "date_from": {"type": "string", "description": "YYYY-MM-DD", "example": "2026-08-25"}, "date_to": {"type": "string", "description": "YYYY-MM-DD", "example": "2026-08-25"}}}, "example": {"item_id": "10001", "shop_id": "demo_shop", "section": "rank"}}}}, "responses": {"200": {"description": "MCP 工具结果。ok=false 时看 reason，HTTP 仍是 200。", "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean"}, "tool": {"type": "string"}, "query": {"type": "object"}, "count": {"type": "integer"}, "rows": {"type": "array", "items": {"type": "object"}}, "reason": {"type": "string", "description": "not_found / shop_isolated / item_id_required / shop_id_required / invalid_report_type / invalid_section / invalid_pack_type / invalid_peer_type"}}}}}}, "401": {"description": "缺少或无效 Bearer"}, "400": {"description": "未知工具或参数不合法"}}}}, "/tools/get_sycm_traffic": {"post": {"tags": ["生意参谋"], "operationId": "get_sycm_traffic", "summary": "流量搜索词", "description": "与 MCP 工具 `get_sycm_traffic` 相同。Swagger 点 Try it out 即可。", "security": [{"bearerAuth": []}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "required": ["shop_id"], "properties": {"shop_id": {"type": "string", "description": "店铺 ID", "example": "demo_shop"}, "item_id": {"type": "string", "description": "商品 ID", "example": "10001"}}}, "example": {"shop_id": "demo_shop", "item_id": "10001"}}}}, "responses": {"200": {"description": "MCP 工具结果。ok=false 时看 reason，HTTP 仍是 200。", "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean"}, "tool": {"type": "string"}, "query": {"type": "object"}, "count": {"type": "integer"}, "rows": {"type": "array", "items": {"type": "object"}}, "reason": {"type": "string", "description": "not_found / shop_isolated / item_id_required / shop_id_required / invalid_report_type / invalid_section / invalid_pack_type / invalid_peer_type"}}}}}}, "401": {"description": "缺少或无效 Bearer"}, "400": {"description": "未知工具或参数不合法"}}}}, "/tools/get_sycm_marketing": {"post": {"tags": ["生意参谋"], "operationId": "get_sycm_marketing", "summary": "营销玩法", "description": "与 MCP 工具 `get_sycm_marketing` 相同。Swagger 点 Try it out 即可。", "security": [{"bearerAuth": []}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "required": ["shop_id"], "properties": {"shop_id": {"type": "string", "description": "店铺 ID", "example": "demo_shop"}}}, "example": {"shop_id": "demo_shop"}}}}, "responses": {"200": {"description": "MCP 工具结果。ok=false 时看 reason，HTTP 仍是 200。", "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean"}, "tool": {"type": "string"}, "query": {"type": "object"}, "count": {"type": "integer"}, "rows": {"type": "array", "items": {"type": "object"}}, "reason": {"type": "string", "description": "not_found / shop_isolated / item_id_required / shop_id_required / invalid_report_type / invalid_section / invalid_pack_type / invalid_peer_type"}}}}}}, "401": {"description": "缺少或无效 Bearer"}, "400": {"description": "未知工具或参数不合法"}}}}, "/tools/get_market_category": {"post": {"tags": ["市场"], "operationId": "get_market_category", "summary": "类目词包", "description": "与 MCP 工具 `get_market_category` 相同。Swagger 点 Try it out 即可。", "security": [{"bearerAuth": []}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "required": ["shop_id"], "properties": {"shop_id": {"type": "string", "description": "店铺 ID", "example": "demo_shop"}, "pack_type": {"type": "string", "description": "词包英文码或中文名，如 trend / 趋势词包", "example": "趋势词包", "enum": ["trend", "good_word", "leftover", "category", "趋势词包", "好词优选", "捡漏", "类目优选"]}}}, "example": {"shop_id": "demo_shop", "pack_type": "趋势词包"}}}}, "responses": {"200": {"description": "MCP 工具结果。ok=false 时看 reason，HTTP 仍是 200。", "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean"}, "tool": {"type": "string"}, "query": {"type": "object"}, "count": {"type": "integer"}, "rows": {"type": "array", "items": {"type": "object"}}, "reason": {"type": "string", "description": "not_found / shop_isolated / item_id_required / shop_id_required / invalid_report_type / invalid_section / invalid_pack_type / invalid_peer_type"}}}}}}, "401": {"description": "缺少或无效 Bearer"}, "400": {"description": "未知工具或参数不合法"}}}}, "/tools/get_market_overview": {"post": {"tags": ["市场"], "operationId": "get_market_overview", "summary": "市场大盘", "description": "与 MCP 工具 `get_market_overview` 相同。Swagger 点 Try it out 即可。", "security": [{"bearerAuth": []}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "required": [], "properties": {"category_id": {"type": "string", "description": "类目 ID", "example": "50014463"}, "price_band": {"type": "string", "description": "价格带", "example": "50-80"}, "shop_id": {"type": "string", "description": "店铺 ID", "example": "demo_shop"}}}, "example": {"category_id": "50014463", "price_band": "50-80", "shop_id": "demo_shop"}}}}, "responses": {"200": {"description": "MCP 工具结果。ok=false 时看 reason，HTTP 仍是 200。", "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean"}, "tool": {"type": "string"}, "query": {"type": "object"}, "count": {"type": "integer"}, "rows": {"type": "array", "items": {"type": "object"}}, "reason": {"type": "string", "description": "not_found / shop_isolated / item_id_required / shop_id_required / invalid_report_type / invalid_section / invalid_pack_type / invalid_peer_type"}}}}}}, "401": {"description": "缺少或无效 Bearer"}, "400": {"description": "未知工具或参数不合法"}}}}, "/tools/list_shop_items": {"post": {"tags": ["商品"], "operationId": "list_shop_items", "summary": "店铺在售商品", "description": "与 MCP 工具 `list_shop_items` 相同。Swagger 点 Try it out 即可。", "security": [{"bearerAuth": []}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "required": ["shop_id"], "properties": {"shop_id": {"type": "string", "description": "店铺 ID", "example": "demo_shop"}, "status": {"type": "string", "description": "上架状态，如 出售中", "example": "出售中"}}}, "example": {"shop_id": "demo_shop", "status": "出售中"}}}}, "responses": {"200": {"description": "MCP 工具结果。ok=false 时看 reason，HTTP 仍是 200。", "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean"}, "tool": {"type": "string"}, "query": {"type": "object"}, "count": {"type": "integer"}, "rows": {"type": "array", "items": {"type": "object"}}, "reason": {"type": "string", "description": "not_found / shop_isolated / item_id_required / shop_id_required / invalid_report_type / invalid_section / invalid_pack_type / invalid_peer_type"}}}}}}, "401": {"description": "缺少或无效 Bearer"}, "400": {"description": "未知工具或参数不合法"}}}}, "/tools/get_item_profile": {"post": {"tags": ["商品"], "operationId": "get_item_profile", "summary": "商品身份信息", "description": "与 MCP 工具 `get_item_profile` 相同。Swagger 点 Try it out 即可。", "security": [{"bearerAuth": []}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "required": ["item_id"], "properties": {"item_id": {"type": "string", "description": "商品 ID", "example": "10001"}, "shop_id": {"type": "string", "description": "店铺 ID", "example": "demo_shop"}}}, "example": {"item_id": "10001", "shop_id": "demo_shop"}}}}, "responses": {"200": {"description": "MCP 工具结果。ok=false 时看 reason，HTTP 仍是 200。", "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean"}, "tool": {"type": "string"}, "query": {"type": "object"}, "count": {"type": "integer"}, "rows": {"type": "array", "items": {"type": "object"}}, "reason": {"type": "string", "description": "not_found / shop_isolated / item_id_required / shop_id_required / invalid_report_type / invalid_section / invalid_pack_type / invalid_peer_type"}}}}}}, "401": {"description": "缺少或无效 Bearer"}, "400": {"description": "未知工具或参数不合法"}}}}, "/tools/get_item_reviews": {"post": {"tags": ["商品"], "operationId": "get_item_reviews", "summary": "评价与问大家", "description": "与 MCP 工具 `get_item_reviews` 相同。Swagger 点 Try it out 即可。", "security": [{"bearerAuth": []}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "required": ["item_id"], "properties": {"item_id": {"type": "string", "description": "商品 ID", "example": "10001"}, "shop_id": {"type": "string", "description": "店铺 ID", "example": "demo_shop"}}}, "example": {"item_id": "10001", "shop_id": "demo_shop"}}}}, "responses": {"200": {"description": "MCP 工具结果。ok=false 时看 reason，HTTP 仍是 200。", "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean"}, "tool": {"type": "string"}, "query": {"type": "object"}, "count": {"type": "integer"}, "rows": {"type": "array", "items": {"type": "object"}}, "reason": {"type": "string", "description": "not_found / shop_isolated / item_id_required / shop_id_required / invalid_report_type / invalid_section / invalid_pack_type / invalid_peer_type"}}}}}}, "401": {"description": "缺少或无效 Bearer"}, "400": {"description": "未知工具或参数不合法"}}}}, "/tools/get_item_sku_assets": {"post": {"tags": ["商品"], "operationId": "get_item_sku_assets", "summary": "SKU 与素材", "description": "与 MCP 工具 `get_item_sku_assets` 相同。Swagger 点 Try it out 即可。", "security": [{"bearerAuth": []}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "required": ["item_id"], "properties": {"item_id": {"type": "string", "description": "商品 ID", "example": "10001"}, "shop_id": {"type": "string", "description": "店铺 ID", "example": "demo_shop"}}}, "example": {"item_id": "10001", "shop_id": "demo_shop"}}}}, "responses": {"200": {"description": "MCP 工具结果。ok=false 时看 reason，HTTP 仍是 200。", "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean"}, "tool": {"type": "string"}, "query": {"type": "object"}, "count": {"type": "integer"}, "rows": {"type": "array", "items": {"type": "object"}}, "reason": {"type": "string", "description": "not_found / shop_isolated / item_id_required / shop_id_required / invalid_report_type / invalid_section / invalid_pack_type / invalid_peer_type"}}}}}}, "401": {"description": "缺少或无效 Bearer"}, "400": {"description": "未知工具或参数不合法"}}}}, "/tools/get_item_ops": {"post": {"tags": ["商品"], "operationId": "get_item_ops", "summary": "库存履约", "description": "与 MCP 工具 `get_item_ops` 相同。Swagger 点 Try it out 即可。", "security": [{"bearerAuth": []}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "required": ["shop_id"], "properties": {"shop_id": {"type": "string", "description": "店铺 ID", "example": "demo_shop"}, "item_id": {"type": "string", "description": "商品 ID", "example": "10001"}}}, "example": {"shop_id": "demo_shop", "item_id": "10001"}}}}, "responses": {"200": {"description": "MCP 工具结果。ok=false 时看 reason，HTTP 仍是 200。", "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean"}, "tool": {"type": "string"}, "query": {"type": "object"}, "count": {"type": "integer"}, "rows": {"type": "array", "items": {"type": "object"}}, "reason": {"type": "string", "description": "not_found / shop_isolated / item_id_required / shop_id_required / invalid_report_type / invalid_section / invalid_pack_type / invalid_peer_type"}}}}}}, "401": {"description": "缺少或无效 Bearer"}, "400": {"description": "未知工具或参数不合法"}}}}, "/tools/list_competitors": {"post": {"tags": ["市场"], "operationId": "list_competitors", "summary": "竞品竞店", "description": "与 MCP 工具 `list_competitors` 相同。Swagger 点 Try it out 即可。", "security": [{"bearerAuth": []}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "required": ["shop_id"], "properties": {"shop_id": {"type": "string", "description": "店铺 ID", "example": "demo_shop"}, "category_id": {"type": "string", "description": "类目 ID", "example": "50014463"}, "keyword": {"type": "string", "description": "关键词", "example": "便携咖啡杯"}}}, "example": {"shop_id": "demo_shop", "category_id": "50014463"}}}}, "responses": {"200": {"description": "MCP 工具结果。ok=false 时看 reason，HTTP 仍是 200。", "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean"}, "tool": {"type": "string"}, "query": {"type": "object"}, "count": {"type": "integer"}, "rows": {"type": "array", "items": {"type": "object"}}, "reason": {"type": "string", "description": "not_found / shop_isolated / item_id_required / shop_id_required / invalid_report_type / invalid_section / invalid_pack_type / invalid_peer_type"}}}}}}, "401": {"description": "缺少或无效 Bearer"}, "400": {"description": "未知工具或参数不合法"}}}}, "/tools/get_market_share": {"post": {"tags": ["市场"], "operationId": "get_market_share", "summary": "集中度与市占", "description": "与 MCP 工具 `get_market_share` 相同。Swagger 点 Try it out 即可。", "security": [{"bearerAuth": []}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "required": ["shop_id"], "properties": {"shop_id": {"type": "string", "description": "店铺 ID", "example": "demo_shop"}, "section": {"type": "string", "description": "英文码或中文名，如 price / 价格带", "example": "价格带", "enum": ["price", "brand", "shop", "价格带", "品牌市占", "店铺排行"]}}}, "example": {"shop_id": "demo_shop", "section": "价格带"}}}}, "responses": {"200": {"description": "MCP 工具结果。ok=false 时看 reason，HTTP 仍是 200。", "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean"}, "tool": {"type": "string"}, "query": {"type": "object"}, "count": {"type": "integer"}, "rows": {"type": "array", "items": {"type": "object"}}, "reason": {"type": "string", "description": "not_found / shop_isolated / item_id_required / shop_id_required / invalid_report_type / invalid_section / invalid_pack_type / invalid_peer_type"}}}}}}, "401": {"description": "缺少或无效 Bearer"}, "400": {"description": "未知工具或参数不合法"}}}}, "/tools/get_category_crowd": {"post": {"tags": ["市场"], "operationId": "get_category_crowd", "summary": "类目人群画像", "description": "与 MCP 工具 `get_category_crowd` 相同。Swagger 点 Try it out 即可。", "security": [{"bearerAuth": []}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "required": ["shop_id"], "properties": {"shop_id": {"type": "string", "description": "店铺 ID", "example": "demo_shop"}, "dimension": {"type": "string", "description": "维度，如 gender / age / city", "example": "gender"}}}, "example": {"shop_id": "demo_shop", "dimension": "gender"}}}}, "responses": {"200": {"description": "MCP 工具结果。ok=false 时看 reason，HTTP 仍是 200。", "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean"}, "tool": {"type": "string"}, "query": {"type": "object"}, "count": {"type": "integer"}, "rows": {"type": "array", "items": {"type": "object"}}, "reason": {"type": "string", "description": "not_found / shop_isolated / item_id_required / shop_id_required / invalid_report_type / invalid_section / invalid_pack_type / invalid_peer_type"}}}}}}, "401": {"description": "缺少或无效 Bearer"}, "400": {"description": "未知工具或参数不合法"}}}}, "/tools/get_market_seasonality": {"post": {"tags": ["市场"], "operationId": "get_market_seasonality", "summary": "类目淡旺季", "description": "与 MCP 工具 `get_market_seasonality` 相同。Swagger 点 Try it out 即可。", "security": [{"bearerAuth": []}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "required": ["shop_id"], "properties": {"shop_id": {"type": "string", "description": "店铺 ID", "example": "demo_shop"}}}, "example": {"shop_id": "demo_shop"}}}}, "responses": {"200": {"description": "MCP 工具结果。ok=false 时看 reason，HTTP 仍是 200。", "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean"}, "tool": {"type": "string"}, "query": {"type": "object"}, "count": {"type": "integer"}, "rows": {"type": "array", "items": {"type": "object"}}, "reason": {"type": "string", "description": "not_found / shop_isolated / item_id_required / shop_id_required / invalid_report_type / invalid_section / invalid_pack_type / invalid_peer_type"}}}}}}, "401": {"description": "缺少或无效 Bearer"}, "400": {"description": "未知工具或参数不合法"}}}}, "/tools/get_peer_benchmark": {"post": {"tags": ["市场"], "operationId": "get_peer_benchmark", "summary": "同层级竞对基准", "description": "与 MCP 工具 `get_peer_benchmark` 相同。Swagger 点 Try it out 即可。", "security": [{"bearerAuth": []}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "required": ["shop_id"], "properties": {"shop_id": {"type": "string", "description": "店铺 ID", "example": "demo_shop"}, "peer_type": {"type": "string", "description": "英文码或中文名，如 rival_avg / 同层级均值", "example": "同层级均值", "enum": ["rival_avg", "rival_good", "同层级均值", "同层级优秀"]}}}, "example": {"shop_id": "demo_shop", "peer_type": "同层级均值"}}}}, "responses": {"200": {"description": "MCP 工具结果。ok=false 时看 reason，HTTP 仍是 200。", "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean"}, "tool": {"type": "string"}, "query": {"type": "object"}, "count": {"type": "integer"}, "rows": {"type": "array", "items": {"type": "object"}}, "reason": {"type": "string", "description": "not_found / shop_isolated / item_id_required / shop_id_required / invalid_report_type / invalid_section / invalid_pack_type / invalid_peer_type"}}}}}}, "401": {"description": "缺少或无效 Bearer"}, "400": {"description": "未知工具或参数不合法"}}}}}, "components": {"securitySchemes": {"bearerAuth": {"type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "到 /admin 签发，只显示一次。这里只填 JWT 本身，不要再加 Bearer。shop_id 必须和这张票绑定的店铺一致。"}}}}