Ucp MCP Server

ucp-mcp服务器

让AI助手购物。 MCP服务器，使Claude、Cursor和任何兼容MCP的AI能够与支持UCP的商家进行交互。

UCP （通用商务协议）是谷歌新的代理商务开放标准，由Shopify、Stripe、Visa、万事达卡、Target、沃尔玛和20多个合作伙伴支持。 主控程序 （模型上下文协议）是让AI助手访问工具的标准。 这个项目将他们联系起来。

______________________________________________________________________

它能做什么？

您的AI助手可以结构化、类型安全地访问整个UCP购物流程。没有抓取，没有浏览器自动化，没有脆弱的黑客攻击。

快速开始

安装

pip install ucp-mcp-server

或与 紫外线:

uv pip install ucp-mcp-server

与Claude Desktop一起使用

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "ucp-shopping": {
      "command": "ucp-mcp-server"
    }
  }
}

与光标一起使用

添加到您的 .cursor/mcp.json:

{
  "mcpServers": {
    "ucp-shopping": {
      "command": "ucp-mcp-server"
    }
  }
}

直接运行

# As a module
python -m ucp_mcp_server

# Or via the entry point
ucp-mcp-server

工具参考

ucp_discover

在购物前了解UCP商家支持什么。

Arguments:
  merchant_url (str): Base URL of a UCP-enabled merchant

Returns:
  capabilities: List of supported UCP capabilities (checkout, discount, fulfillment)
  payment_handlers: Accepted payment methods (Shop Pay, Google Pay, etc.)
  ucp_version: Protocol version the merchant implements

ucp_checkout_create

创建新的购物车/结账会话。

Arguments:
  merchant_url (str): Base URL of the merchant
  items (list): Items to buy, each with "id" and "quantity"
  buyer_name (str): Full name of the buyer
  buyer_email (str): Email address
  currency (str): Currency code (default: "USD")

Returns:
  checkout_id: Session ID for tracking this purchase
  status: Current checkout status
  total: Total price in smallest currency unit (cents)
  subtotal: Subtotal before discounts
  line_items: What's in the cart

ucp_checkout_update

应用折扣码或修改现有结账。

Arguments:
  merchant_url (str): Base URL of the merchant
  checkout_id (str): The checkout session to update
  discount_codes (list[str]): Promo codes to apply

Returns:
  checkout_id: Session ID
  total: Updated total after discounts
  discount_applied: How much was saved
  discounts: Details of applied discounts

ucp_checkout_set_fulfillment

设置收银发货。自动选择第一个可用地址和投递选项。

Arguments:
  merchant_url (str): Base URL of the merchant
  checkout_id (str): The checkout session

Returns:
  checkout_id: Session ID
  status: Current status
  total: Updated total (may include shipping costs)
  fulfillment: Details of selected shipping method

ucp_checkout_complete

通过提交付款完成结账。这将完成购买并返回订单ID。

Arguments:
  merchant_url (str): Base URL of the merchant
  checkout_id (str): The checkout session to complete
  payment_handler_id (str): Payment handler to use (from ucp_discover)
  card_token (str): Payment token from the provider
  card_brand (str): Card brand (e.g., "Visa")
  card_last_digits (str): Last 4 digits of the card

Returns:
  checkout_id: Session ID
  status: "complete" or "completed"
  total: Final amount charged
  order_id: Order ID for tracking
  order_url: Permalink to the order

对话示例

你： “看看花店在哪里http://flowers.example.com支持” 克劳德： *调用ucp-discover* “此商家支持结账、折扣和订单跟踪。他们接受Shop Pay和Google Pay。” 你： “给我买两束玫瑰” 克劳德： *调用ucp_checkout_create* “我为2束红玫瑰创建了一个结账。总计：70.00美元。您想继续吗？" 你： “先试试代码10OFF” 克劳德： *调用ucp_checkout_update* “申请了10OFF-节省了7.00美元！新总计：63.00美元。”

为什么存在

每个AI应用程序都需要购物功能。UCP规范了商家如何公开商业API。MCP规范了AI助手使用工具的方式。这个项目就是桥梁。

如果没有这一点，将人工智能与商业联系起来意味着：

• 抓取网站（易碎，不断损坏）
• 为每个商家构建自定义集成（不可扩展）
• 浏览器自动化（缓慢、不可靠、昂贵）

使用UCP+MCP：

• 一个协议，每个商家
• 结构化数据输入，结构化数据输出
• 可与任何兼容MCP的AI助手配合使用

发展

# Clone the repo
git clone https://github.com/nguthrie/ucp-mcp-server.git
cd ucp-mcp-server

# Install dependencies
uv sync --extra dev

# Run tests
uv run pytest -v

# Run integration tests (requires a live UCP server on port 8182)
uv run pytest -v -m integration --run-integration

项目结构

ucp-mcp-server/
├── src/ucp_mcp_server/
│   ├── __init__.py        # Package version
│   ├── __main__.py        # python -m entry point
│   ├── server.py          # MCP server + tool definitions
│   ├── ucp_client.py      # HTTP client for UCP APIs
│   └── models.py          # Pydantic models for UCP data
└── tests/
    ├── conftest.py         # Test fixtures with mock UCP responses
    ├── test_discovery.py   # Discovery tool tests
    ├── test_checkout.py    # Checkout tool tests
    ├── test_errors.py      # Error handling tests
    └── test_integration.py # Live server integration tests

路线图

• \[x\] 商户能力发现
• \[x\] 创建结账会话
• \[x\] 折扣码申请
• \[x\] 配送/装运设置
• \[x\] 采购完成/付款提交
• \[\]订单履行跟踪
• \[\]退货和换货
• \[\]多商家比较购物
• \[\]托管托管版本（因此您不必自托管）

资源

• UCP规范 -通用商业协议
• UCP Python SDK
• MCP文件 -模型上下文协议
• 谷歌UCP博客文章

许可证

麻省理工学院