AgentMall

智能体原生的日用消费品采购 MCP Server（开源 MVP） Agent-native daily-needs shopping via MCP — open source MVP.

🚧 当前状态：Phase 2 路演雏形（用户侧闭环已通，管理员/商户侧进行中） 数据与支付均为演示数据：商品是整理/采集的公开价格，支付是模拟网关，不发生任何真实交易。

这是什么

用户不用打开 App，直接对自己的 AI 智能体说"帮我买最便宜的抽纸"， 智能体通过本项目的 MCP 接口完成搜索、比价、下单——买的是 1688 源头价的日用刚需品 （纸巾、垃圾袋、洗衣液、收纳等）。

• MCP 优先：为智能体设计接口，而非为人设计网页

• 源头价格：对接 1688 一件代发，零库存、现金流正向

• 合规先行：只做"辅助支付"（智能体下单、用户自己点链接付款），不做自动扣款

Related MCP server: clishop

快速开始

python3 -m venv .venv && source .venv/bin/activate   # Linux/macOS
pip install -r requirements.txt

# 终端 A：Web 前端（注册/登录/个人中心/订单/模拟收银台）→ http://127.0.0.1:8000
uvicorn agentmall.web.app:app --port 8000

# 终端 B：MCP Server（给 AI 客户端接）→ http://127.0.0.1:8001/mcp
python -m agentmall.http_server

本地 AI 客户端（Claude Code / Cursor 等）也可以直接用 stdio：

python -m agentmall.server

Windows 用 .venv\Scripts\activate。若系统 pip 报 externally-managed-environment （PEP 668），说明该 Python 禁止全局装包——用上面的 venv 即可，这是推荐做法。

⚠️ 必须装 mcp<2：requirements.txt 已锁 mcp>=1.8,<2。 mcp 2.x 把 FastMCP 更名为 MCPServer，mcp.server.fastmcp 会直接 ImportError， 导致 Server 无法启动。迁 v2 属后续事项。

三角色接入（per-agent key）

每个请求带 Authorization: Bearer <key>，key 决定角色，Server 只注册该角色的 tool：

stdio 模式下用环境变量指定角色：AGENTMALL_API_KEY=ak_demo_admin_secret python -m agentmall.server GET /whoami 可以随时查当前 key 被解析成什么角色、能看到哪些 tool。

一键验证（不用接客户端）

想快速确认整条链路是否正常，可直接跑内置的 MCP stdio client——它以真实 MCP 协议 逐个调用 4 个 tool，复现 demo/演示脚本.md 的全链路：

python tests/demo_chain.py       # 用户侧全链路（stdio 真实协议），17 项断言
python tests/test_readonly.py    # 只读边界守卫
python tests/test_roles.py       # 管理员/商户权限与审核流
python tests/test_http_auth.py   # streamable-http 接入 + 越权拒绝 + 审计

最近一次完整输出见 demo/演示输出.md。

MCP Tools（一期）

演示

按 demo/演示脚本.md 走一遍，即可在 2 分钟内看到完整链路： 搜索"纸巾" → 比价 → 下单 → 拿到订单号 → 查询"待支付"状态。

路线图

• Phase 1（本仓库当前）：本地商品库 + 用户智能体 MCP 接口（搜索/比价/下单/查单）+ 辅助支付占位， 验证"智能体能帮人买日用品"

• Phase 2：接入 1688 开放平台真实商品/库存/价格；接入真实支付网关替换占位链接； 用户授权与额度管理；商户智能体（上架/改价/订单履约）+ 管理员智能体（审核/风控/仲裁）上线， 三角色权限隔离（见 docs/角色架构.md）

• Phase 3：智能体间议价、集采拼单、订阅式自动补货（A2A）

三智能体（用户 / 商户 / 管理员）功能与权限边界已定死，详见 docs/角色架构.md。Phase 1 只做用户侧，不许混。

合规声明

本项目采用 "checkout hands off"（结账交接） 范式——这是 Anthropic 官方 commerce-agents 蓝图确立的智能体电商安全模式，也是 northcinder "Buying stays a separate decision"（购买是独立决策）理念的中文落地： 下单是智能体的事，付钱永远是用户的事。智能体只建单， 支付发生在用户自己的浏览器/App 里，模型碰不到钱。

一期仅实现"智能体辅助支付"，不实现、不鼓励任何形式的智能体自动扣款。 该设计同时符合中国支付清算协会《智能体支付应用自律公约》第一阶段 （辅助支付）的要求；真实支付能力上线前将完成合规评估与报备。

设计参考

本项目站在以下开源项目的基础上设计：

• anthropics/commerce-agents —— "checkout hands off" 范式与 start-small 方法论

• cinderline/northcinder —— human-in-the-loop 结账流程与 Adapter 货源模式

• jackwangfeng/keel —— per-agent key 分级权限与写操作提案队列

• shopmanagerai/shopify-mcp —— CI 强制只读保证与 operation ledger

差异化：以上没有一个覆盖"1688 一件代发 + 用户/商户/管理员三角色 + 中国支付合规" 这个组合——这正是 AgentMall 的位置。

License

MIT