# uSMART MCP

[![CI](https://github.com/liusheldon238/usmart-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/liusheldon238/usmart-mcp/actions/workflows/ci.yml)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)

本机优先的 uSMART 新加坡 Open API MCP 工具。它只提供账户、持仓、订单、行情、历史 K 线和健康检查等只读能力，不包含下单、撤单、资金划转、交易解锁或密码找回。

> This is an independent, community-maintained project. It is not affiliated
> with, endorsed by, or supported by uSMART.

## 配置与安全

- 在 Codex 中调用 **Configure uSMART MCP**，即可打开内嵌设置页面；它不是独立 macOS App。
- 填写渠道号、区号、手机号、登录密码、API 加密公钥 PEM 与 API 签名私钥 PEM。
- 凭证只保存至 macOS Keychain；设置 UI 仅显示脱敏状态，不会回显密码或 PEM。
- Docker 镜像、Compose 文件、Git 仓库和日志均不保存券商凭证。
- MCP 仅监听 `127.0.0.1:8080`；连接器仅监听 `127.0.0.1:8787`。

## 前置条件

- macOS 14+、Node 22+、pnpm、Docker Desktop。
- 已获批准的 uSMART SG Open API 账户。请在 uSMART 个人中心的 My API 获取所需材料；不要把凭证粘贴到聊天或源码中。

## 启动与接入 Codex

```sh
pnpm install
pnpm build:ui
pnpm start:mock
```

在 Codex 中注册 Streamable HTTP MCP 端点：

```text
http://127.0.0.1:8080/mcp
```

首次使用调用 `configure_usmart` 打开内嵌设置表单。保存完真实凭证后，重启为真实只读模式：

```sh
pnpm stop
pnpm start:real
```

停止本地服务：

```sh
pnpm stop
```

## 验证

```sh
pnpm test
pnpm typecheck
pnpm test:integration
```

集成测试使用模拟券商，完成 MCP 握手、工具发现和全部六个只读工具调用。真实账户仅在你已通过内嵌页面保存经批准凭证后，执行一次只读健康检查和查询验证。

## 开源协作

- [贡献指南](CONTRIBUTING.md)
- [安全披露](SECURITY.md)
- [行为准则](CODE_OF_CONDUCT.md)
- [支持与使用边界](SUPPORT.md)
- [变更记录](CHANGELOG.md)
- [Apache-2.0 许可证](LICENSE)