Skip to main content
Glama
ANGERchen

SmartCommerce Agent MCP Server

by ANGERchen
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

SmartCommerce Agent

电商售后与智能物流多智能体系统

SmartCommerce Agent 是一个基于 LangGraph 的开源电商客服平台。系统将用户请求路由到 FAQ、订单、智能物流、退款、支付、人工转接等专家 Agent，并通过 RAG、MCP 工具、会话记忆和服务端安全校验完成可追踪的业务闭环。

项目支持两种运行模式：不配置模型密钥时使用确定性离线流程，便于本地开发和持续集成；配置 OpenAI 兼容模型后启用在线意图路由与 Function Calling。

核心能力

  • 七类专家 Agent：FAQ、订单、智能物流、退款、支付、人工转接和通用接待。

  • 智能物流异常处理：识别快递丢失、物流停滞、包裹破损和错误签收。

  • 安全工具链：物流异常必须按 get_order → create_logistics_ticket 顺序执行。

  • RAG 引用：从企业政策知识库检索依据，并在答案中展示来源。

  • MCP 工具服务：订单、支付、退款、物流工单和人工工单能力由 FastMCP 独立提供。

  • 多层记忆：LangGraph Checkpointer 保存会话状态，SQLite 保存跨会话业务记忆。

  • 故障转人工：业务接口失败后自动创建高优先级人工工单并保留工具轨迹。

  • 可量化评测：覆盖意图、工具顺序、RAG 来源、多轮指代、安全规则和响应延迟。

Related MCP server: Commerce Operations MCP Server

系统架构

Streamlit UI / FastAPI
          │
          ▼
   LangGraph Supervisor
          │
  ┌───────┼──────────┬────────┬────────┬──────────┐
  ▼       ▼          ▼        ▼        ▼          ▼
 FAQ    Order    Logistics  Refund   Payment   Escalation
 Agent   Agent      Agent     Agent    Agent       Agent
  │       │          │        │        │          │
 RAG      └──────────┴────────┴────────┴──────────┘
知识库                       MCP Tools
                              │
                 SQLite 订单 / 退款 / 工单 / 记忆

物流异常采用受控写入流程：

识别物流异常
  → 查询当前用户订单
  → 校验订单归属
  → 分类 lost / stalled / damaged / wrong_delivery
  → 创建物流异常工单
  → 返回工单号和物流政策来源

详细设计见 架构文档。

技术栈

  • Python 3.10～3.12

  • FastAPI + Streamlit

  • LangChain + LangGraph

  • FastMCP + LangChain MCP Adapters

  • SQLite + LangGraph SQLite Checkpointer

  • Pydantic + pytest + Ruff

快速开始

Windows PowerShell

powershell -ExecutionPolicy Bypass -File scripts/setup.ps1

安装完成后，在两个终端中分别启动：

.\scripts\start-api.ps1
.\scripts\start-ui.ps1

macOS / Linux

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
cp .env.example .env
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

在另一个终端中运行：

source .venv/bin/activate
streamlit run frontend.py --server.port 8501

服务地址：

模型配置

复制 .env.example 为 .env。不设置 LLM_API_KEY 时系统运行在 offline_rule 模式，MCP、RAG、Memory 和评测仍然可用。

LLM_API_KEY=
LLM_MODEL=gpt-4o-mini
LLM_BASE_URL=

使用其他 OpenAI 兼容服务时，填写对应的模型名与 Base URL。不要提交真实 .env 或 API 密钥。

示例请求

用户

问题

预期行为

u001

查询 ORD-1001 的物流

调用 get_order

u001

ORD-1002 三天没有物流更新了

查询订单后创建物流工单

u001

ORD-1001 显示签收但我没收到

创建错误签收工单并引用政策

u002

ORD-1002 的包裹丢了

拒绝越权订单，不创建工单

u001

七天无理由退货有什么条件？

RAG 回答并引用退款政策

u001

这个订单能退款吗？

使用多轮记忆解析订单号

内置数据仅用于本地开发与自动测试。

测试与评测

.\.venv\Scripts\python.exe -m pytest --cov=app --cov-report=term-missing
.\.venv\Scripts\python.exe -m evaluation.run_eval

配置模型后，可运行在线评测：

.\.venv\Scripts\python.exe -m evaluation.run_eval --online

当前离线基准：

指标

结果

自动测试

64/64

代码覆盖率

86%

单轮评测集

70 条

智能物流专项

100%（10/10）

物流工具顺序

100%（10/10）

多轮场景

100%（6/6）

安全检查

100%（9/9）

P95 响应时间

28.76 ms

这些数字来自确定性离线回归基准，用于验证工程流程，不代表在线大模型的泛化准确率。评测定义和限制见 评测文档，最近一次原始结果见 latest.json。

安全设计

  • user_id 由服务端上下文强制注入，忽略模型或用户伪造的身份参数。

  • 不存在和越权订单统一返回 ORDER_NOT_FOUND，避免泄露其他用户数据。

  • 写入型工具在数据库业务层再次验证订单归属与参数白名单。

  • 工具异常与业务拒绝分开记录，接口异常才触发自动转人工。

  • .env、本地数据库、虚拟环境和缓存文件均被 Git 忽略。

项目结构

app/
├── agent/graph.py          # LangGraph 编排与安全工具流
├── mcp_server/server.py    # FastMCP 工具服务
├── skills/loader.py        # Skill 动态加载
├── database.py             # 数据模型与业务安全规则
├── context.py              # Context Engineering
├── rag.py                  # 知识库检索与引用
├── router.py               # 意图路由
├── runtime.py              # MCP、模型与 Checkpointer 生命周期
└── main.py                 # FastAPI 应用
skills/                     # 七类 Agent 的 YAML 与 Prompt
knowledge/                  # 企业政策知识库
evaluation/                 # 70 条单轮、6 组多轮与安全评测
tests/                      # 单元、集成与端到端测试
docs/                       # 架构与评测文档
frontend.py                 # Streamlit UI

参与贡献

提交代码前请阅读 CONTRIBUTING.md。安全问题请按照 SECURITY.md 私下报告。

致谢

项目实现参考了 LangGraph、LangChain MCP Adapters 以及以下公开项目的工程思路：

License

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers