跳到主要内容

MCP 故障排查

适合对象

需要修正 MCP 连接、登录、权限、预览、应用或验证问题的管理员。

开始之前​

  • 确认 AI 客户端使用 https://mcp.x1.tech/mcp。
  • 确认你可以用正确 X1 账号登录。
  • 确认你知道目标品牌和门店。
  • 故障排查期间避免批准写入动作。

助理无法连接​

  1. 确认服务器地址完全是 https://mcp.x1.tech/mcp。
  2. 确认客户端支持远程 HTTPS MCP 服务器。
  3. 在 AI 客户端中重新连接 MCP 服务器。
  4. 如客户端要求授权，请重新登录。
  5. 尝试只读提示：“列出我可以访问的品牌和门店。”

在浏览器打开 https://mcp.x1.tech/mcp 可能会显示 method error。这不一定代表服务器故障，因为 MCP 客户端使用端点的方式与浏览器页面不同。

登录或授权失败​

  1. 确认你使用正确 X1 账号。
  2. 确认弹出窗口或外部登录窗口未被阻止。
  3. 登出 AI 客户端后重新登录。
  4. 要求店主/管理员确认你的 X1 角色可访问目标品牌和门店。

助理看不到正确品牌或门店​

  1. 询问：“列出我可以访问的所有品牌和门店。”
  2. 确认缺少的门店是否属于其他品牌或工作区。
  3. 要求店主/管理员检查你的 HQ 访问权限。
  4. 权限更改后重新连接 MCP。

助理建议错误范围​

批准前停止。

要求助理显示：

  • 已选品牌
  • 已选门店
  • 已选渠道
  • 受影响分类、品项或设置
  • 每项记录被包含的原因

修正范围后，要求重新预览。

预览看起来不正确​

  1. 不要批准应用。
  2. 要求助理显示所使用的来源数据。
  3. 修正品项名称、分类、加配项、价格或套餐规则。
  4. 要求重新预览。
  5. 将新预览与来源文件或当前 HQ 设置比较。

已应用更改但看不到结果​

  1. 要求助理检查任务状态。
  2. 刷新 HQ 页面。
  3. 确认你正在查看被更改的同一品牌、门店和渠道。
  4. 检查使用该数据的位置：POS、在线点餐、报表或目标门店。
  5. 要求助理重新读取受影响记录。

上传菜单导入不清楚​

要求助理暂停，并先显示解析出的数据。

检查：

  • 分类名称
  • 品项名称
  • 价格列
  • 必选加配项
  • 可选加配项
  • 套餐或餐组规则
  • 可能不属于菜单的备注

只有当解析结构正确时，才要求预览。

何时要求店主/管理员协助​

  • 你无法登录或授权 MCP 连接。
  • 你的账号看不到预期品牌或门店。
  • 预览包含非预期门店、渠道或记录。
  • 应用完成但实时结果不正确。
  • 问题影响营业、顾客点餐、付款或报表。