# 小钉快跑商城 AI 接入

MCP Endpoint: https://ai.xdkp8.com/mcp
Transport: Streamable HTTP（无状态）

本商城提供 MCP 商品查询、购物车整理、订单与报价工具。客户端需要支持并允许连接 MCP；HTML、llms.txt 和实验性的 ai-catalog/server-card 仅帮助发现，不保证自动接入。

登录支持账号密码工具，以及官网 OAuth 授权码 + PKCE S256。推荐浏览器官网授权，由客户端保存 MCP Token。密码直登参数为原始密码，HTTPS 保护公网传输；AI/客户端可能读取这些参数。密码不应写入日志或持久保存。官网 Token 不能调用 MCP，MCP Token 也不能调用普通商城 API。

账号密码直登 Token 默认闲置 72 小时失效，活跃请求剩余不足 24 小时时续期，绝对期限 365 天；OAuth access_token 有效期 1 小时，refresh_token 轮换且受同一会话期限约束。客户端应安全保存 Token，后续请求使用 Authorization: Bearer。仅密码直登 Token 支持 accessToken 工具参数兼容；OAuth Token 不得放参数或 URL。

权限：shop:read 查询（含购物车）；quote:submit 提交 AI 报价；cart:write 加入及删除购物车。支持查询商品、购物车、订单、收货地址、开票记录、报价额度和结果。旧会话不会自动获得 cart:write；需要重新授权或登录。不支持下单、支付、地址新增/修改/删除/设置默认、开票申请。logout 撤销当前 MCP 会话；修改密码、冻结客户、后台强制退出会撤销对应会话。

AI 可以帮助查询商品、加入购物车和删除购物车商品。如需下单，请客户自行打开商城购物车，核对商品、数量和费用，人工进行结算和支付。目前不支持 AI 下单或支付接口。

购物车：https://www.xdkp8.com/cartshop
加购是追加数量；先用 get_goods_detail 读取 purchaseOptions，再按包装类型及包装数调用 add_to_cart。后端按实时包装换算；不支持的包装或不满足起购量会拒绝，不会自动改数量。多个包装分别调用。删除前用 get_cart 获取 deleteTarget，remove_from_cart 沿用商城关联 SPU 删除规则并保留锁定项。listA/listN 是 list 的活动分组，不能重复计数。

购物车写操作必须携带 requestId；同次操作重试保持一致，366 天内去重。同 ID 不同参数会拒绝，执行结果不确定时 uncertain=true，应先查看购物车，不自动换 ID 重试。已确认写入但后续查询失败时 applied 保持原值，cart=null，并返回 cartReadError；不能据此重新加购。

需求没有准确标准、型号、规格，或 search_goods 无结果时，推荐 AI 报价。须根据用户意愿提交。提交立即返回任务 ID，AI 回调较慢；随后查询 list_ai_quotes / get_ai_quote_status / get_ai_quote_detail 或官网列表、详情获取结果，建议间隔 15 秒。超时不代表失败，不要自动重复提交。

submit_ai_quote 的 requestId 必须由客户端生成，同一请求重试保持一致。提交不确定时只查询，不自动换 requestId 重复提交。配额不足、鉴权失败等需处理后再由用户决定是否重新提交。

HTTP 401 表示需要登录，WWW-Authenticate 指向 /.well-known/oauth-protected-resource/mcp；403 表示权限不足；429 表示触发频率限制。业务工具失败通过 isError=true 返回 JSON 文本 {error,message}，成功通过 structuredContent 和兼容 JSON 文本返回同一对象。null 表示商城未提供该字段；金额以十进制字符串提供。

授权元数据：https://ai.xdkp8.com/.well-known/oauth-authorization-server
服务卡片（实验性）：https://ai.xdkp8.com/mcp/server-card
完整工具与字段 Schema：https://www.xdkp8.com/readme/tools.json

最小调用顺序：连接 /mcp → initialize → notifications/initialized → tools/list → search_goods → get_goods_detail。操作购物车前浏览器授权或 login → get_cart → add_to_cart / remove_from_cart → get_cart → 客户打开官网购物车人工结算和支付。私有列表默认只查询当前登录客户，不能传 uId/cId 切换客户。

## 接入与排查

仅能抓取网页的 AI 可阅读本文，但不代表能添加 MCP 连接器。请在支持并允许添加远程 MCP 的客户端填写 https://ai.xdkp8.com/mcp，传输选择 Streamable HTTP。服务卡片、HTML meta 和 llms.txt 仅用于发现，不会自动接入。

GET /mcp 返回 405 是正常协议行为：本服务未提供独立 SSE 流。调用使用 POST。401 表示需要登录；403 表示权限不足或 Origin 不允许；429 表示限流；跳转到其他域名、TLS 失败或 5xx 需要维护者检查公网链路。

robots.txt 当前明确允许抓取。抓取平台报 ROBOTS_DISALLOWED 不能单凭该消息认定源站全局禁止；应核对 robots 原文、跳转链和平台策略。HTTP robots 404 也不等于 Disallow: /。

下列示例不含凭据，可用于匿名握手与商品查询。PowerShell 请使用 curl.exe；每个 JSON-RPC 消息分别发送，初始化之后使用协商的 MCP-Protocol-Version。

POST https://ai.xdkp8.com/mcp
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2025-11-25

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"shop-example","version":"1.0"}}}

POST https://ai.xdkp8.com/mcp
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2025-11-25

{"jsonrpc":"2.0","method":"notifications/initialized"}

POST https://ai.xdkp8.com/mcp
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2025-11-25

{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

POST https://ai.xdkp8.com/mcp
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2025-11-25

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_goods","arguments":{"search":"螺丝","pageNum":1,"pageSize":5}}}