{"$schema":"https://wellknown.network/schemas/agent-record-v1.json","schemaVersion":"1","id":"ag_rp6gvftftxjf","handle":"usmartsg-mcp","url":"https://wellknown.network/agents/usmartsg-mcp","links":{"self":"https://wellknown.network/agents/usmartsg-mcp/record.json","html":"https://wellknown.network/agents/usmartsg-mcp","markdown":"https://wellknown.network/agents/usmartsg-mcp/record.md","api":"https://wellknown.network/api/v1/agents/usmartsg-mcp","status":"https://wellknown.network/api/v1/agents/usmartsg-mcp/status","claim":"https://wellknown.network/agents/usmartsg-mcp/claim","claimApi":"https://wellknown.network/api/v1/claims","claimDescriptor":"https://wellknown.network/agents/usmartsg-mcp/claim.json","badge":"https://wellknown.network/agents/usmartsg-mcp/badge.svg","openapi":"https://wellknown.network/openapi.json","history":"https://wellknown.network/api/v1/agents/usmartsg-mcp/history","tools":"https://wellknown.network/api/v1/agents/usmartsg-mcp/tools"},"ard":{"identifier":"urn:air::server:usmartsg-mcp","type":"application/mcp-server-card+json"},"kind":"mcp_server","declared":{"name":"usmartsg-mcp","summary":"Local MCP server for uSmart SG trading with user-owned credentials and a read-only safety mode","description":"# usmartsg-mcp\n\n面向 [uSmart SG](https://www.usmart.sg) OpenAPI 用户的本地交易 MCP Server。它通过标准\nMCP Tools 向 Kiro、Codex、Claude Desktop、Cursor 等客户端提供订单预检、订单查询、下单和\n改单能力。\n\n本项目在本地以 stdio 运行：每位用户使用自己的 uSmart 账户和授权，凭证只保存在本机，\n不随 PyPI 包分发，也不通过 MCP 工具参数传递。\n\n> 当前仅支持 SG。服务可连接生产交易账户；默认即注册下单/改单工具，调用时可能产生真实资金交易。\n> 本工具不提供投资建议，所有委托均由账户所有者负责。\n\n## 主要特性\n\n- 基于官方 MCP Python SDK，默认使用 stdio 传输；\n- 使用 OAuth2 授权码 + PKCE：在浏览器用 uSmart 账户授权，令牌自动续期，无需自行申请 App ID 或密钥；\n- 首次运行自动生成 OAuth2 配置，装完即可授权，无需手写 JSON；\n- 凭证默认存放在 `~/.usmart`，支持 `USMART_HOME` 覆盖；\n- 默认注册全部 11 个工具（含 `place_order` / `modify_order`），装完即可下单；\n- 可选的服务端只读模式：写工具在 MCP 协议层完全不注册；\n- 写操作必须显式确认，且绝不自动重试；\n- 下单前可查询每手股数、最大可买卖数量和购买力；\n- 写操作在本地生成脱敏审计流水；\n- 查询类工具返回结构化结果，失败统一为错误信封；\n- 不提供行情服务，也不解析股票名称。\n\n## 环境要求\n\n- Python 3.10 或更高版本；\n- [uv](https://docs.astral.sh/uv/getting-started/installation/)；\n- 独立的 uSmart SG OpenAPI 权限：使用 uSmart 账户在浏览器完成 OAuth2 授权即可，无需自行申请\n  App ID 或密钥。\n\nPyPI 包不包含任何账户、Token 或密钥。\n\n## 安装\n\n推荐用 `uvx` 固定版本运行：\n\n```bash\nuvx --from \"usmartsg-mcp==1.1.0\" usmartsg-mcp\n```\n\n也可以先安装再运行：\n\n```bash\npip install \"usmartsg-mcp==1.1.0\"\nusmartsg-mcp\n```\n\n从源码安装：克隆本仓库后执行\n\n```bash\ncd usmartsg-mcp\nuv sync --extra dev\nuv run usmartsg-mcp\n```\n\n该命令会保持运行并等待 MCP stdio 消息，属于正常行为，应由 MCP 客户端启动。\n\n## 快速开始\n\n### 1. 首次运行自动生成配置\n\n**不需要手工创建配置文件**：首次启动时，如果 `~/.usmart/config.json` 不存在，服务会按内置\n默认值自动生成一份；随后调用 `oauth_login` 在浏览器完成授权即可使用。\n\n| 配置项 | 生产（默认） | UAT（`USMART_ENV=uat`） |\n|---|---|---|\n| `baseUrl` | `https://open2-jy.usmartsg.com` | `https://open2-jy-uat.usmartsg.com` |\n| `auth.oauth.baseUrl` | `https://jy.usmartsg.com` | `https://jy-uat.usmartsg.com` |\n| `auth.oauth.clientId` | `ai-agent` | `agent-uat` |\n| `auth.oauth.redirectUri` | `http://localhost:5100/callback` | 同左 |\n| `auth.oauth.scopes` | `order:all` | 同左 |\n\n生成后的目录：\n\n```text\n~/.usmart/                    # macOS/Linux 建议权限 700\n├── config.json               # 自动生成：固定 OAuth2 配置，可按需修改\n├── oauth_session.json        # OAuth 授权成功后自动生成（600）\n├── credentials.json          # 可选：账户开启交易密码校验时创建，只写 tradePassword\n└── audit/              …","publisher":null,"homepage":"https://api-doc.usmart.sg/zh-cn/trade.html","repository":null,"version":"1.1.0","license":null,"protocols":["mcp"],"tags":["mcp","openapi","singapore","trading","usmart"],"pricing":null,"endpoints":[{"url":"pypi:usmartsg-mcp","type":"package_pypi","auth":null,"probeable":false}],"skills":null,"tools":null,"extra":null,"attribution":{"kind":"pypi","name":"pypi","summary":"pypi","version":"pypi","description":"pypi","homepageUrl":"pypi"}},"derived":{"capabilities":[{"slug":"data.apis","name":"API Access","confidence":1,"provenance":"declared"},{"slug":"finance.markets","name":"Markets & Trading","confidence":1,"provenance":"declared"},{"slug":"security.identity","name":"Identity & Access","confidence":0.745,"provenance":"derived"}],"categories":["data","finance","security"],"language":"en"},"observed":{"status":"unknown","statusReason":"Distributed as a package to run locally; no network endpoint to check.","lastOkAt":null,"lastProbedAt":null,"statusComputedAt":null,"reliability30d":null,"latestObservations":[],"tools":null,"package":{"name":"usmartsg-mcp","registry":"pypi","observedAt":"2026-11-05T22:26:36.687Z","publishedAt":"2026-11-04T06:51:54.960098Z","latestVersion":"1.1.0"},"toolSurface":null,"endpointFacts":[]},"verification":{"claimed":false,"claimedAt":null,"proofs":[]},"provenance":{"sources":[{"source":"pypi","key":"usmartsg-mcp","url":"https://pypi.org/project/usmartsg-mcp/","firstSeenAt":"2026-11-05T22:26:02.537Z","fetchedAt":"2026-11-05T22:26:02.537Z","normalizedAt":"2026-11-05T22:26:02.537Z"}]},"firstSeenAt":"2026-11-05T22:26:02.537Z","updatedAt":"2026-11-05T22:26:36.687Z"}