小鹅通店铺接入 Codex / Claude Code / 千问办公 / 豆包工作

这个 Skill 解决什么

把一个小鹅通店铺接成本机可查询的 MCP 服务，让商家用自然语言查订单、用户、账单和运营总览。全程只做查询，不做退款、删除、改价、解绑等破坏性操作。

四个客户端共用同一个本地 stdio MCP 服务端，接一次店铺即可多家复用。豆包工作与千问办公只支持在桌面客户端添加自定义连接器，浏览器端和移动端不支持，也不会同步到其他设备。

两个客户端的界面都是表单填写，不支持粘贴 JSON：

• 千问办公：服务器类型 选 STDIO、服务器名称、命令（填完整命令串，如 <python> <server.py>）、环境变量（键/值，支持粘贴 KEY=VALUE 多行一次解析）。含 SSE / Streamable HTTP 选项。
• 豆包工作：伺服器名稱、命令（只填可执行文件，如 python3）、參數（另外一栏填脚本路径）、環境變數（變數名稱/變數值）。HTTP 类型另有 伺服器 URL 与 自定義 Headers。

实测结论（避免重复逆向）

以下结论来自对客户端安装包的静态核对，可直接采信，不要重跑：

Python 解释器建议固定用 /usr/bin/python3（系统自带，路径不随其它应用升级变化）；服务端只用标准库，Python 3.9 与 3.13 均实测通过。全部脚本统一使用该解释器注册，可用 --python 覆盖。

商家需要提供的信息

获取位置：小鹅云控制台 https://admin.cloud.xiaoe-tech.com/#/account → 选择应用 → 应用概况 → 授权信息。

凭证只通过交互式输入或临时环境变量传入，不回显、不写日志、不进 Skill 包。

接入前必须确认的两件事

这两项没配好，接入后一定报错：

1. IP 白名单：把小鹅云应用所在机器的公网出口 IP 加入应用「IP 白名单」。若不确定出口 IP，先跑一次验证，报错信息里会直接给出实际 IP。
2. 权限集：在应用「权限集管理」申请
   - 订单管理-查询（订单列表）
   - 用户管理-查询（用户列表）
   - 资产管理-查询（月度账单、交易明细）

标准流程

第 1 步：一键接入

python3 scripts/setup_xiaoe.py --profile shop_a

脚本会依次完成：创建 ~/.xiaoe-mcp/profiles/shop_a/、写入权限为 0600 的 .env、调用官方 CLI 注册 Codex（全局）与 Claude Code（user scope）、写入千问办公的 ~/.qwenworkcn/mcp.json、跑一次 token 实测。

常用参数：

重复执行是安全的：已存在的 MCP 条目会跳过，已有完整 .env 会沿用而不覆盖。

第 2 步：确认客户端状态

codex mcp list          # 应能看到 xiaoe_shop_a
claude mcp list         # 应显示 ✔ Connected
python3 scripts/doctor_xiaoe.py --profile shop_a   # 一次性核对全部客户端

第 3 步：在对话里验收

重启客户端会话后，直接说：

> 用 xiaoe_shop_a 查一下最近 7 天的订单

或先让它列工具：

> 使用 xiaoe_shop_a，都支持哪些工具

第 4 步：单独补装 / 手动接到千问办公

第 1 步已自动写入；若当时千问办公在运行被跳过，或后来配置被覆盖，单独补一次：

python3 scripts/register_qwenwork.py --profile shop_a

写入 ~/.qwenworkcn/mcp.json（已存在则合并，不动其它服务端条目）。写完后启动/重启千问办公，进 设置 → 连接器 → 自定义 MCP 服务器，应能看到 xiaoe_shop_a。

也可以完全走界面（设置 → 连接器 → 自定义 MCP 服务器 → 添加）：服务器类型 选 STDIO，服务器名称 填 xiaoe_shop_a，命令 填完整命令串 /usr/bin/python3 <profile>/xiaoe_mcp_server.py，环境变量 填 XIAOE_PROFILE_DIR=<profile>。

该文件由应用自己读写，应用运行期间手工改会被回写覆盖，所以要么用脚本（未运行时）、要么用界面。

第 5 步：接到豆包工作（仅界面，无法脚本化）

豆包工作的连接器配置由服务端账号侧持有，本机只找到原生 helper（libmcp_helper.dylib / mcp-helper，支持 stdio / Streamable HTTP / SSE / OAuth），没有可写的本地配置文件。必须走界面：

1. 侧边栏 技能 · 连接器 → 连接器 标签 → 新增自定義連接器。
2. 表单按下面填（命令与参数是分开两栏的）：

3. 保存后如提示「連接器運行失敗」，到 我的技能 里点「重新啟動」。
4. 新开会话，输入「使用 xiaoe_shop_a，都支持哪些工具」验收。

用 python3 scripts/print_connector_config.py --profile shop_a 可直接打印上面这份表单内容。

日常体检与自愈

python3 scripts/doctor_xiaoe.py --profile shop_a          # 只体检
python3 scripts/doctor_xiaoe.py --profile shop_a --fix    # 体检并自动补回丢失的注册

体检脚本共 5 项：① profile 与凭证是否就绪、② token 是否可换（连通性）、③ Codex 是否仍注册、④ Claude Code 是否仍注册、⑤ 千问办公的 mcp.json 是否仍指向本 profile。--fix 会补回缺失的注册（含千问办公）；若千问办公正在运行会跳过写入并提示先退出，避免被回写覆盖。

为什么需要它：Codex 桌面端在某些操作（如从 Claude Code / Cursor 导入 MCP、升级、保存设置）后会重写 ~/.codex/config.toml，把命令行添加的 MCP 条目丢掉。表现为「昨天还能查，今天工具不见了」。遇到这种情况跑 --fix 补回即可。Claude Code 侧配置相对稳定，可作为可靠母本，再用 Codex 图形界面的「从 Claude Code 导入」同步。

可用工具

金额一律以「元」返回；只读，无写操作。

目录结构

~/.xiaoe-mcp/
└── profiles/
    └── shop_a/
        ├── .env                 # 0600，仅本机可读
        ├── .token_cache.json    # 0600，短期 token 缓存
        └── xiaoe_mcp_server.py  # 0700，该店铺专用服务端

一个店铺一个 profile，互不干扰；MCP 名称带店铺后缀，避免多店铺互相覆盖。

四个客户端最终都指向同一个 profile，只是登记位置不同：

改完任何一个都要完全退出并重开该客户端才会生效。

排错速查

错误码完整说明见 references/api_reference.md，排错流程见 references/troubleshooting.md。

安全边界

• 真实 client_secret、access_token、用户手机号、完整订单明细属于敏感数据，不写入 Skill 包、工作区记忆或最终报告。
• 只访问小鹅通官方域名 https://api.xiaoe-tech.com，不把凭证发往其他地址。
• 密钥不放在命令行参数里，不打印 .env，验证输出只给脱敏结果。
• 默认拒绝退款、删除、关闭、解绑、改价、发消息、上传素材等写操作；若未来开放写操作，必须在工具层加入二次确认与幂等保护。
• 不读取浏览器 Cookie、SSH 密钥、云凭证或与目标店铺无关的个人文件。