┌──────────────────────────┐
│ Claude Desktop / Cursor  │
│ （或任何 MCP 客户端）      │
└────────────┬─────────────┘
             │ MCP over stdio（JSON-RPC，不开放端口）
             ▼
┌──────────────────────────┐
│ server.py  (FastMCP)     │  注册 5 个 tool，自动生成 JSON Schema
└────────────┬─────────────┘
             ▼
┌──────────────────────────┐
│ app/tools.py             │  参数校验 / 统一错误码 / 改价护栏
└────────────┬─────────────┘
             ▼
┌──────────────────────────┐
│ app/repo.py              │  查询聚合 / 写操作 / 审计日志
└────────────┬─────────────┘
             ▼
┌──────────────────────────┐
│ SQLAlchemy Core          │
│ SQLite（演示）→ MySQL/PG  │  切换只改 DATABASE_URL
└──────────────────────────┘

git clone <your-repo> && cd mcp-shop-agent
python -m venv .venv

# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

pip install -r requirements.txt
python scripts/seed.py          # 生成 30 天演示数据
python scripts/demo_cli.py      # 不装任何客户端，直接看 7 步效果

mcp-shop-agent/
├── server.py            # MCP 入口：注册工具、启动 stdio 服务
├── app/
│   ├── config.py        # 环境变量与 .env 读取
│   ├── models.py        # 表结构（SQLAlchemy Core，跨数据库）
│   ├── db.py            # 连接池、事务边界、建表
│   ├── repo.py          # 查询聚合、改价、审计
│   ├── tools.py         # 参数校验、错误码、改价护栏
│   └── seed.py          # 固定随机种子的演示数据
├── scripts/
│   ├── seed.py          # 生成演示数据
│   ├── demo_cli.py      # 不装客户端也能跑的 7 步演示
│   └── _console.py      # Windows 控制台 UTF-8 兼容
├── tests/               # 19 条用例
└── docs/
    ├── demo.png         # README 首图
    └── demo-output.txt  # 演示输出样例

{
  "mcpServers": {
    "shop-agent": {
      "command": "D:\\path\\to\\mcp-shop-agent\\.venv\\Scripts\\python.exe",
      "args": ["D:\\path\\to\\mcp-shop-agent\\server.py"],
      "env": {
        "DATABASE_URL": "sqlite:///D:/path/to/mcp-shop-agent/data/shop.db",
        "AGENT_ACTOR": "claude-desktop"
      }
    }
  }
}

{
  "ok": false,
  "error": {
    "code": "NEED_CONFIRM",
    "message": "改价幅度 -96.7% 超过 30% 阈值，已拦截",
    "hint": "如确认执行，请带 confirm=true 和 reason 重新调用：update_price(sku='SKU-1001', new_price=1.0, confirm=True, reason='...')。当前价格 30.0，目标价格 1.0。"
  }
}

pytest

# MySQL
pip install pymysql
set DATABASE_URL=mysql+pymysql://root:pass@127.0.0.1:3306/shop?charset=utf8mb4

# PostgreSQL
pip install "psycopg[binary]"
set DATABASE_URL=postgresql+psycopg://postgres:pass@127.0.0.1:5432/shop