MCP Commerce Server Starter

MCP Commerce 服务入门模板

用于 Commerce MCP 服务的克隆即部署模板。五分钟即可在 Vercel 上线。Claude、ChatGPT、Gemini、Cursor 及所有其他兼容 MCP 的客户端均可访问。

完整构建指南（逐行讲解缘由）： 如何在 2026 年构建 MCP 服务

---

你将获得

• 产品目录资源 — Agent 在采取行动前读取完整目录
• search_products 工具 — 按关键词、类别和最高价格筛选
• initiate_checkout 工具 — 返回订单摘要和结账 URL
• 可选 API 密钥身份验证 — 使用 X-API-Key 标头，通过 REQUIRE_AUTH=true 切换
• /health 健康检查端点
• 适配 Vercel — 一条命令即可部署，可使用免费 Hobby 套餐

技术栈：Python · FastMCP · FastAPI · Vercel

---

快速开始（本地）

git clone https://github.com/NewPlanetWW/mcp-commerce-starter
cd mcp-commerce-starter

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

python server.py
# Server running at http://localhost:8000
# MCP endpoint: http://localhost:8000/mcp
# Health check: http://localhost:8000/health

测试健康检查端点：

curl http://localhost:8000/health
# {"status":"ok","server":"Commerce MCP Server","version":"1.0.0"}

---

部署到 Vercel（免费）

Vercel CLI 需要 Node 18+。无需 GitHub — CLI 会直接上传。

npm i -g vercel
vercel login
vercel --prod

CLI 会打印你的生产环境 URL。你的 MCP 端点位于：

https://your-project.vercel.app/mcp

在 Vercel 控制台中设置环境变量（Settings → Environment Variables）：

变量	默认值	备注
API_KEY	dev-secret-key	上线前请更改
REQUIRE_AUTH	false	设置为 true 以强制要求密钥

---

接入 Claude Desktop

选项 A — 本地 stdio（开发期间快速迭代）：

在 macOS 上编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（Windows/Linux 路径请参阅完整指南）：

{
  "mcpServers": {
    "commerce-catalog": {
      "command": "uvicorn",
      "args": ["server:app", "--host", "127.0.0.1", "--port", "8001"],
      "env": {
        "REQUIRE_AUTH": "false"
      },
      "cwd": "/path/to/mcp-commerce-starter"
    }
  }
}

选项 B — 远程（部署到 Vercel 后），使用 mcp-remote：

{
  "mcpServers": {
    "commerce-catalog-remote": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote@latest",
        "https://your-project.vercel.app/mcp",
        "--header", "Authorization: Bearer ${MCP_API_KEY}"
      ],
      "env": { "MCP_API_KEY": "your-secret-key" }
    }
  }
}

完全退出并重新启动 Claude Desktop。提问：“你有哪些价格低于 $100 的产品？” — Claude 会调用 search_products 并返回你的产品目录。

---

自定义

替换示例产品

编辑 server.py 中的 PRODUCTS 列表。每个产品需要包含：sku、name、price、description、availability、category、image_url。

要接入实际库存，请将该列表替换为数据库调用：

# server.py — swap PRODUCTS for a live query
import psycopg2  # or SQLAlchemy, Supabase, etc.

def get_products():
    # your DB query here
    return [...]

PRODUCTS = get_products()

添加 Stripe 结账

将 initiate_checkout 中的桩代码替换为真实的 Stripe 会话：

import stripe
stripe.api_key = os.getenv("STRIPE_SECRET_KEY")

session = stripe.checkout.Session.create(
    line_items=[{"price": price_id, "quantity": quantity}],
    mode="payment",
    success_url="https://yourstore.com/success",
    cancel_url="https://yourstore.com/cancel",
)
return {"success": True, "checkout_url": session.url, ...}

---

你会遇到的 5 个错误（以及修复方法）

完整指南中有详细介绍：30daypivot.com/agentmall_spoke_mcp

1. MCP error -32600 — 初始化顺序违规
2. 422 Unprocessable Entity — Pydantic 模型与普通参数不匹配
3. 405 Method Not Allowed — CORS 允许的方法中缺少 DELETE
4. stateless_http not set — Vercel 无服务器环境要求设置 stateless_http=True
5. ModuleNotFoundError: mcp — 包名称错误（应为 mcp[cli]，而不是 fastmcp）

---

项目结构

mcp-commerce-starter/
├── server.py          # FastMCP app — resource, tools, middleware, FastAPI mount
├── requirements.txt   # Pinned dependencies
├── vercel.json        # Vercel deployment config
├── mcp.json           # MCP server manifest
├── .env.example       # Environment variable template
└── README.md

---

深入了解

此入门模板是 30DayPivot 上 AgentMall 系列配套代码的一部分：

• MCP 服务构建指南 — 本代码库背后的完整操作指南
• Agent 可读的产品数据 — 使用 Schema.org 标记，让 Agent 无需调用服务即可找到你的产品
• FastAPI Commerce API — 与 MCP 服务并行运行的 REST 层
• 免费转付费 / Stripe 按量计费 — 将你刚构建的服务变现
• AgentMall 路线图 — Agent Commerce 基础设施的完整“卖铲子”路线图

---

许可证

MIT