Metadata-Version: 2.5
Name: usmartsg-mcp-directory
Version: 1.0.0
Summary: Read-only remote MCP server edition for the uSmart SG OpenAPI, for ChatGPT and Claude directories
Project-URL: Homepage, https://www.usmart.sg
Project-URL: Documentation, https://api-doc.usmart.sg/zh-cn/trade.html
Project-URL: Repository, https://git.yxzq.com/usmart/usmart-mcp
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: mcp,openapi,singapore,trading,usmart
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.10
Requires-Dist: cryptography>=42
Requires-Dist: httpx2<3,>=2
Requires-Dist: mcp<3,>=2.0.0
Requires-Dist: tzdata>=2024.1; sys_platform == 'win32'
Requires-Dist: uvicorn>=0.31
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# 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)。
