兴先达订单与库存 MCP Server

这是一个只使用 Streamable HTTP 的云端 MCP Server。它把下单系统与库存系统 封装成 Agent 可以发现和调用的 MCP 工具。公网入口为：

https://你的域名/mcp

MCP Server 本身不调用模型，Agent 负责决定何时调用工具。服务保留 mcp_connection_test 作为链路检查，并提供 3 个业务工具：

• get_latest_inventory：获取全部库存，或查询一个 SKU 的最新库存。

• update_inventory_from_order：读取一张已存在订单，并把订单中的 inventoryDelta 幂等地应用到库存系统。

• create_order：在订单系统中创建订单，但不会隐式调用库存更新。

部署结构

上游 MCP 客户端 -> 已有 HTTPS 服务 443 -> 127.0.0.1:18080 -> MCP 容器 8000
                                                              -> 订单系统 API
                                                              -> 库存系统 API

项目不再启动 Caddy，也不占用 80、443。MCP 只绑定服务器本机回环地址， 由现有 Nginx、Apache 或 Caddy 使用已有证书反向代理。

Related MCP server: wazza-mcp-test-server

一、准备服务器和域名

1. 云服务器安装 Docker Engine 和 Docker Compose 插件。

2. 准备已有证书覆盖的域名，例如 mcp.example.com。

3. 确认现有 HTTPS 服务能够修改反向代理配置。

MCP_DOMAIN 只填写域名，不要包含 https:// 或路径。

二、上传项目

在本地 Mac 执行，将 SERVER_USER 和 SERVER_IP 换成真实值。这里明确排除 本地 .env 和虚拟环境，避免把旧 API Key 或无关文件上传到服务器：

rsync -av \
  --exclude='.env' \
  --exclude='.venv' \
  --exclude='__pycache__' \
  "/Users/clarence/Desktop/项目/兴先达/MCPtest/" \
  SERVER_USER@SERVER_IP:~/mcp-connection-test/

登录服务器：

ssh SERVER_USER@SERVER_IP
cd ~/mcp-connection-test

三、填写域名并启动

cp deploy.env.example deploy.env

编辑 deploy.env：

MCP_DOMAIN=mcp.example.com
MCP_LOCAL_PORT=18080
PYTHON_IMAGE=public.ecr.aws/docker/library/python:3.12-slim
ORDER_API_BASE_URL=http://host.docker.internal:32769
INVENTORY_API_BASE_URL=http://host.docker.internal:32768

PYTHON_IMAGE 默认使用 AWS Public ECR 中的 Python 官方镜像，构建时不会再访问 Docker Hub。Amazon ECR Public 的公开镜像无需登录即可拉取；若服务器曾保存过 错误的 ECR 登录状态，可先执行 docker logout public.ecr.aws。

如果订单或库存 API 不在 MCP 宿主机，把对应地址换成 Agent 网络能够访问的 http:// 或 https:// 地址。如果业务 API 使用 Bearer Token，再填写 ORDER_API_TOKEN 和 INVENTORY_API_TOKEN；令牌只放在 deploy.env，不要提交 到仓库。

配套库存系统默认固定映射为宿主机端口 32768。不要再使用随机端口；如果因 端口冲突确实需要修改，库存系统的 INVENTORY_PORT 与这里的 INVENTORY_API_BASE_URL 必须同步调整。

如果 18080 已被占用，可以改成其他未使用的高位端口，例如 18081。检查端口：

sudo ss -ltnp | grep ':18080'

构建并后台启动：

docker compose --env-file deploy.env up -d --build

如果之前启动过旧版 Caddy 编排，使用下面的命令同时清理已经移除的 Caddy 容器；不会影响服务器上其他项目的容器：

docker compose --env-file deploy.env up -d --build --remove-orphans

查看运行状态和日志：

docker compose --env-file deploy.env ps
docker compose --env-file deploy.env logs --tail=100

四、接入现有 HTTPS 服务

如果使用 Nginx，将 nginx-mcp-location.conf.example 中的 location = /mcp 配置加入已有证书域名对应的 server { ... } 中。确认反向代理端口与 MCP_LOCAL_PORT 一致，然后执行：

sudo nginx -t
sudo systemctl reload nginx

Nginx 的 proxy_pass 应指向：

http://127.0.0.1:18080

最终公网 MCP 地址仍然是：

https://mcp.example.com/mcp

五、验证工具发现和调用

在本地 Mac 执行，验证公网链路：

/opt/homebrew/Caskroom/miniconda/base/bin/python \
  "/Users/clarence/Desktop/项目/兴先达/MCPtest/verify_remote.py" \
  https://mcp.example.com/mcp

成功时会显示：

发现工具：create_order, get_latest_inventory, mcp_connection_test, update_inventory_from_order
调用返回：MCP连接成功

这一步会真实执行 MCP 初始化、tools/list 和 tools/call，比普通的端口或 HTTP 检查更准确。

六、上游配置

将上游 MCP 客户端的服务器 URL 配置为：

https://mcp.example.com/mcp

获取最新库存

查询全部库存：

{}

查询单个库存：

{
  "sku": "003"
}

sku 同时接受 3、003 或 X-003。返回的 meta.version 可用于后续 需要并发保护的更新。

创建订单

{
  "product_id": 3,
  "quantity": 5
}

成功后记住返回的 order.id。订单系统当前是补货单语义，因此新订单包含 inventoryDelta: 5；创建订单本身不会自动修改独立库存系统。

根据订单更新库存

{
  "order_id": "ORD-20260821153000-ABCD"
}

工具会读取订单，将 X-003 映射为库存 SKU 003，再把 inventoryDelta 应用到库存。库存请求使用订单号生成幂等键，同一订单重复 调用不会重复增加库存。

如果 Agent 刚读取过库存，也可以带版本号进行乐观并发保护：

{
  "order_id": "ORD-20260821153000-ABCD",
  "expected_version": 7
}

如果返回 VERSION_CONFLICT，Agent 应重新调用 get_latest_inventory，确认新 库存后再决定是否重试。普通订单同步不强制填写 expected_version。

推荐的 Agent 调用顺序

1. 需要确认现货时调用 get_latest_inventory。

2. 用户确认下单后调用 create_order。

3. 使用返回的 order.id 调用 update_inventory_from_order。

4. 如需向用户确认最终库存，再调用一次 get_latest_inventory。

订单创建与库存更新是两个独立动作。这样即使第二步之后网络中断，Agent 仍可 用同一订单号安全重试库存同步，也不会重复下单。

本地测试

业务适配层单元测试不需要启动服务：

python -m unittest -v test_mcp_tools.py

三系统联调测试会使用临时数据文件和随机本机端口，不会修改现有测试数据：

python integration_test.py

连接测试

工具 mcp_connection_test 可传空对象 {}，也可传：

{
  "probe": "upstream-health-check"
}

更新与停止

更新代码后重新部署：

docker compose --env-file deploy.env up -d --build

停止服务：

docker compose --env-file deploy.env down

常见问题

• 返回 421 Invalid Host header：deploy.env 中的域名与访问域名不一致。

• MCP 连接出现 Connection refused：检查 MCP_LOCAL_PORT、容器状态及反向代理端口。

• 工具返回“无法连接订单系统/库存系统”：从 MCP 容器内检查 ORDER_API_BASE_URL、INVENTORY_API_BASE_URL 与实际端口。配套库存系统的 默认地址应为 http://host.docker.internal:32768。

• 库存返回 SKU_NOT_FOUND：检查订单 SKU 与库存系统的 001–010 是否对应。

• 库存返回数量不能小于 0：该订单的 inventoryDelta 会使库存越界，需要先核对订单方向和当前库存。

• 查看 MCP 服务日志：docker compose --env-file deploy.env logs mcp-server。

• HTTPS 相关问题继续查看服务器现有 Nginx、Apache 或 Caddy 日志。

安全要求

这个 MCP 现在包含可创建订单和修改库存的写工具，不能把无鉴权入口直接暴露到 公网。正式使用时必须在现有 HTTPS 网关增加访问控制，例如 OAuth、受管 API 网关或固定来源 IP 白名单；业务系统自身也建议启用 Bearer Token。日志中不要 记录 ORDER_API_TOKEN、INVENTORY_API_TOKEN 或完整的 Authorization 请求头。