AI Agent（Crush / Codex）
                 │
            MCP Protocol
                 │
         a-share-mcp（本服务）
         ┌───────┼───────┐
      Account  Risk  Trade
         │       │       │
      查询账户 交易检查 下单执行
                 │
        券商通道（模拟 / 待接入）

.
├── server.py              MCP Server 入口
├── config.yaml            模式与风控配置
├── mcp.json               标准 MCP 客户端配置示例
├── requirements.txt       依赖清单
├── LICENSE                双许可证说明（GPL v2+ / LGPL v2.1+）
├── LICENSE.GPLv2          GPL v2 全文
├── LICENSE.LGPLv2.1       LGPL v2.1 全文
├── tools/
│   ├── account.py         账户查询
│   ├── position.py        持仓查询
│   ├── order.py           下单 / 撤单 / 交易日志
│   └── risk.py            风控引擎
├── drivers/
│   └── tonghuashun.py     券商驱动（预留接口）
├── data/portfolio.json    模拟账户状态（示例数据，请自行替换）
├── tests/test_smoke.py    冒烟自检
└── logs/                  交易日志（运行时生成，不入库）

git clone git@github.com:RicalLiu/a-share-mcp.git
cd a-share-mcp
pip install -r requirements.txt

# 1. 启动 MCP Server（stdio 模式，供 AI Agent 调用）
python server.py

# 2. 冒烟自检（不启动服务，直接验证交易全流程）
python tests/test_smoke.py

{
  "cash": 500000.0,
  "positions": {
    "600519": {"name": "贵州茅台", "cost": 1500.0, "amount": 100}
  },
  "day": "2026-08-07",
  "day_pnl": 0.0
}

{"cash": 500000.0, "total_asset": 650000.0, "available": 500000.0,
 "positions_value": 150000.0, "day_pnl": 0.0}

{
  "status": "need_confirm",
  "preview": "交易确认：\n股票：贵州茅台\n代码：600519\n数量：100股\n价格：1500\n预计金额：150000元\n账户占比：23.1%\n风险：需重点确认",
  "confirm": "确认交易"
}

mode: simulation  # simulation（模拟）| real（真实，待接入）
risk:
  max_single_stock_ratio: 0.2
  max_daily_loss_ratio: 0.03
  require_confirm_ratio: 0.05
  forbid_all_sell: true

2026-08-07 10:30
BUY
300750
100股
价格220
用户确认
SUCCESS

mcp add stock-trader --type stdio --command python --args "/path/to/a-share-mcp/server.py"

你是我的A股交易助手。你可以调用stock-trader MCP。规则：
1. 任何交易必须经过risk检查。
2. 任何真实交易必须获得用户明确确认。
3. 交易前必须展示：股票、代码、数量、价格、金额、风险。
4. 禁止自行扩大交易数量。
5. 禁止连续交易。
6. 所有交易必须记录日志。

class Tonghuashun:
    def login(self)                                  # 登录
    def get_account(self)                            # 查询账户
    def get_position(self)                           # 查询持仓
    def buy(self, code, amount, price=None)          # 买入
    def sell(self, code, amount, price=None)         # 卖出
    def cancel(self, order_id=None)                  # 撤单