# 小钉快跑：紧固件采购与配送服务

小钉快跑面向企业提供紧固件选型、询报价、采购与配送服务，支持 AI 询报价及 MCP / WebMCP 接入。

平台与采购服务：https://www.xdkp8.com/overview/
AI 接入说明：https://www.xdkp8.com/overview/#ai-access

# 小钉快跑商城远程 MCP 接入

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

本文仅说明远程 MCP 接入。网页内 WebMCP 使用当前商城登录状态，通过浏览器原生 API 注册工具；不通过本文、meta 或远程 MCP 自动连接。

本商城提供 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
商品与购物车复用新版 OpenAPI 业务契约。分类用 get_categories 逐级查询，筛选先用 get_goods_filters 取得候选。search_goods 使用 keyword/categoryId/filters/supplyType/sort/page/pageSize，按 hasMore 翻页。价格排序是活动前基本单位客户价，不同单位不可只比较数字。游客价格与库存为 null，不是免费或无库存。

写入前先 get_cart，再 get_goods_detail 原样取得 optionId，以整数份数 count 操作。add_to_cart 追加；update_cart 使用 itemId/optionId 设置目标份数，0 清除此选项；remove_from_cart 使用 itemIds，按 affected/retained 解释关联删除与保留。旧 search/pageNum/packageType/deleteTarget 不兼容，请重新发现工具。

preview_cart 预览完整选中集合，自动选择合法活动；total 不含运费、优惠券和支付方式费用，不锁价、不留库存、不改变网页活动选择。get_cart 的 previewScope=returnedItems，仅覆盖本次返回商品；preview=null 时看 previewError，不能自行凑全车金额。

三个写工具共用服务端 OpenAPI 幂等回执；同一账号、同一业务意图跨入口保持同一 requestId，366 天内保留，不同操作或参数冲突。先看 receipt.applied、receipt.uncertain、receipt.receiptSaved；cartReadError/cart.previewError 不代表写入失败。超时或结果不确定先查购物车，原 ID 原参数核对回执，禁止自动换 ID 重试。旧版请求 ID 命中历史记录时禁止跨版本重放。

需求没有准确标准、型号、规格，或 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 → preview_cart → add_to_cart / update_cart / remove_from_cart → get_cart → 客户打开官网购物车人工结算和支付。私有列表默认只查询当前登录客户，不能传 uId/cId 切换客户。

发布版本：2.0.1
构建标识：1078890f1dc06d3b8935f825981548bb3311807aa61473566b6ade7d03d3380d
契约摘要：323e87434e10e3ad2ff0eca180516af230635a24d488952b78409641ea987a36

网页 WebMCP 在安全上下文且浏览器提供 document.modelContext.registerTool 时自动注册，不需要构建开关；不支持的浏览器正常使用商城。

协议错误使用 JSON-RPC error：解析失败 -32700，非法请求／批量请求 -32600，未知方法 -32601，未知工具／调用外层参数／无效游标 -32602。已知工具字段校验失败返回 isError=true 和 JSON 文本 {error:"invalid_arguments",message}；输出校验失败为 invalid_service_result。413 表示请求体过大。

429 带 Retry-After 秒数；默认每进程 8 个并发 tools/call，每会话或匿名 IP 4 个，超出立即拒绝。原每分钟频率限制保留。写请求被拒绝前不登记幂等占位；已接收写请求断开或超时后仍须使用原 requestId 查询核对，不得换 ID 重试。

tools/list 一次返回完整工具目录，非空 cursor 无效。其输出 Schema 精简重复说明并使用工具内部引用，字段和校验约束不变；本页及 tools.json 保留完整展开的说明。

## 接入与排查

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

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":{"keyword":"螺丝","page":1,"pageSize":5}}}