usmartsg-mcp-directory

# usmartsg-mcp-directory uSmart SG OpenAPI 的**只读远程 MCP 发行版**，供 ChatGPT / Claude 官方目录的远程 服务端部署使用。它由同一仓库的 `usmartsg-mcp` 源码生成，但构建期固定为目录只读形态： - 只注册 5 个只读工具：`get_profile`、`preview_order`、`list_today_orders`、 `list_all_orders`、`get_order_detail`； - 不注册 `place_order` / `modify_order`，也不注册本地 OAuth 授权与凭证自检工具； - `USMART_PROFILE` 被固定为 `directory`：显式设为 `local` 或拼写错误都会在启动时 报错退出，不会静默回退到暴露写工具的本地版； - 工具描述、服务端说明与错误信息使用英文，且不回显本机路径、账户标识或令牌； - 查询与预检工具返回 V2 结构化字段，失败统一为错误信封（见仓库 `README.md` 「工具返回契约 V2」）。 ## 安装与启动 ```bash pip install usmartsg-mcp-directory # 或固定版本：uvx --from "usmartsg-mcp-directory==1.0.0" usmartsg-mcp-directory usmartsg-mcp-directory \ --transport streamable-http \ --host 0.0.0.0 --port 8000 \ --allow-unauthenticated-http \ --allowed-host <你的公网域名> ``` 需要放在带认证、限流与审计的反向代理 / API 网关之后：本包的 HTTP 传输不包含 MCP 层认证，`--allow-unauthenticated-http` 只解除回环地址绑定限制。 `--allowed-host` 必填：`--host 0.0.0.0` 时若缺省，真实域名 Host 会被 MCP 传输层 以 421 拒绝。 ## 域名验证 ChatGPT 门户连接 MCP 时会给出一个验证 token，部署时通过环境变量注入： ```bash USMART_OPENAI_CHALLENGE=<门户给的 token> ``` 服务在 `GET /.well-known/openai-apps-challenge` 以纯文本原样返回该 token；未配置时 返回 404。 ## 凭证与配置 与本地版相同：使用 `~/.usmart/config.json`（OAuth2 配置），可用 `USMART_HOME` 覆盖目录。 本发行版不提供本地授权工具，OAuth 授权由远程部署的网关或后续的 broker 完成。 ## 与本地交易版的关系 | 发行版 | 入口命令 | 运行形态 | 用途 | |---|---|---|---| | `usmartsg-mcp` | `usmartsg-mcp` | 默认 `local`，可显式切换 | 本地客户端，可启用真实交易 | | `usmartsg-mcp-directory` | `usmartsg-mcp-directory` | 构建期固定 `directory` | 远程只读部署，目录上架 | 两个发行版的顶层 import 包不同（`usmart_mcp` / `usmart_mcp_directory`），可以同时 安装而不会互相覆盖；但同一个进程里只能运行其中一个。 本发行版采用 [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0) 发布， 许可全文见 [LICENSE](LICENSE)。