usmart-mcp

# usmart-mcp `usmart-mcp` 是面向 uSmart SG OpenAPI 用户的本地交易 MCP Server。它通过标准 MCP Tools 向 Kiro、Codex、Claude Desktop 等客户端提供订单预检、订单查询、下单和改单能力。 本项目采用本地运行模式：每位用户使用自己的 uSmart 账户、渠道号和签名密钥；凭证仅保存在 用户电脑中，不随 PyPI 包分发，也不通过 MCP 工具参数传递。 > 当前仅支持 SG。服务可连接生产交易账户；启用写工具后可能产生真实资金交易。 > 本工具不提供投资建议，所有委托均由账户所有者负责。 ## 主要特性 - 基于官方 MCP Python SDK v2，使用 stdio 传输； - 自动执行 SG 渠道密码登录，并在进程内短期缓存 Authorization； - 凭证默认存放于 `~/.usmart`，支持 `USMART_HOME` 覆盖； - 提供服务端只读模式，写工具在协议层完全不注册； - 写操作要求显式确认，且绝不自动重试； - 下单前可查询每手股数、最大可买卖数量和购买力； - 支持单笔金额、单日金额和单日笔数限额； - 写操作在本地生成脱敏审计流水； - 不提供行情服务，也不解析股票名称。 ## 使用前提 使用者必须拥有独立的 uSmart SG OpenAPI 权限，并准备： - uSmart 账户区号、手机号和登录密码； - 可选的 6 位交易密码； - 与个人渠道配对的渠道号和签名私钥； - uSmart 提供的隐私数据加密公钥； - Python 3.10 或更高版本； - [uv](https://docs.astral.sh/uv/getting-started/installation/)。 PyPI 包不包含任何账户、Token、渠道号或密钥。 ## 快速开始 ### 1. 初始化当前用户的本地凭证 每个用户都有自己的主目录。默认路径会按运行 MCP 的系统用户动态解析：macOS/Linux 通常为 `~/.usmart`，Windows 通常为 `%USERPROFILE%\.usmart`，并不是所有人共用 `/Users/A/.usmart`。 运行一条命令即可创建目录、JSON 模板、审计目录并设置安全权限： ```bash uvx --from "usmart-mcp==1.0.3" usmart-mcp init ``` 生成结构： ```text 当前用户的 .usmart/ ├── config.json # 自动生成模板，填写个人渠道号和限额 ├── credentials.json # 自动生成模板，填写个人账号，POSIX 权限 600 ├── sign_private.pem # 用户自己的渠道签名私钥 ├── privacy_public.pem # uSmart 提供的隐私加密公钥 └── audit/ # 自动创建 ``` 初始化模板默认将 `maxDailyOrderCount` 设为 `0`，即使误开写工具也不能提交订单。 需要交易时，用户必须先根据自身风控要求配置单笔、单日金额和笔数上限。 密钥可以手工放入，也可以在本机终端安全复制： ```bash uvx --from "usmart-mcp==1.0.3" usmart-mcp init \ --sign-private "/path/to/sign_private.pem" \ --privacy-public "/path/to/privacy_public.pem" ``` `init` 绝不覆盖已有文件。账号密码只填写到本机生成的 `credentials.json`，不要通过 聊天、邮件或 MCP 参数传递。完成后执行本地脱敏检查（不会登录或联网）： ```bash uvx --from "usmart-mcp==1.0.3" usmart-mcp doctor ``` 如需使用其他目录，可在初始化时传 `--home /path/to/usmart-home`，并在 MCP 配置的 `env` 中设置相同的 `USMART_HOME`。Windows 用户还应使用 `icacls` 限制目录仅当前账户可访问。 ### 2. 接入 Kiro（推荐先只读） 在 Kiro 的 `mcp.json` 中加入： ```json { "mcpServers": { "usmart": { "command": "uvx", …