feat: Add MCP (Model Context Protocol) sample implementation

[dihannahdi]

Summary

This PR adds a new MCP (Model Context Protocol) binding sample for UCP, enabling AI agents to interact with UCP-compliant merchants through the standardized Model Context Protocol.

Motivation

While the samples repo currently has REST and A2A bindings, there's no MCP sample. MCP is increasingly important for AI agent integration, allowing LLMs like Claude, GPT, and Gemini to perform commerce operations through a standardized protocol. This sample fills that gap.

Changes

New Files

File	Description
mcp/python/ucp_mcp_server.py	FastMCP server exposing UCP capabilities as tools, resources, and prompts
mcp/python/ucp_mcp_client.py	Example client demonstrating complete shopping flow
mcp/python/README.md	Comprehensive documentation with architecture, quick start, and integration guide
mcp/python/pyproject.toml	Project configuration with dependencies

Updated Files

File	Changes
README.md	Added MCP binding section with comparison table of all protocol bindings

MCP Server Features

Tools (Actions with Side Effects)

• list_products - Browse product catalog
• get_product - Get product details
• create_checkout - Create checkout session
• add_to_checkout / remove_from_checkout - Cart management
• set_shipping_address - Configure delivery
• complete_payment - Process payment
• get_order / cancel_checkout - Order management

Resources (Read-Only Data)

• ucp://catalog/products - Product catalog
• ucp://checkout/{id} - Checkout state
• ucp://orders/{id} - Order details
• ucp://discovery/profile - UCP discovery profile

Prompts (Conversation Templates)

• shopping_intro - Shopping assistant introduction
• order_confirmation - Order confirmation message
• recommend_products - Product recommendations

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         AI Agent / LLM                          │
│                    (Claude, GPT, Gemini, etc.)                  │
└─────────────────────────────┬───────────────────────────────────┘
                              │ MCP Protocol
                              │ (stdio / HTTP / SSE)
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      UCP MCP Server                             │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │     Tools       │  │   Resources     │  │    Prompts      │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
└─────────────────────────────┬───────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                   Mock Data Store / Real UCP Server             │
└─────────────────────────────────────────────────────────────────┘

Testing

cd mcp/python
uv sync

# Run server (terminal 1)
uv run ucp-mcp-server

# Run client demo (terminal 2)
uv run ucp-mcp-client

The client demonstrates a complete shopping flow: browse → checkout → pay → track.

Claude Desktop Integration

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "ucp-shopping": {
      "command": "uv",
      "args": ["run", "ucp-mcp-server"],
      "cwd": "/path/to/samples/mcp/python"
    }
  }
}

Protocol Binding Comparison

Binding	Use Case	Transport	Best For
REST	Traditional APIs	HTTP	Web/mobile apps, service integration
MCP	AI Agents	stdio/HTTP/SSE	LLM integration, conversational commerce
A2A	Agent Communication	HTTP	Multi-agent systems, automated workflows

Checklist

• Code follows project conventions
• Added comprehensive README documentation
• Includes example client demonstrating usage
• Updated main README with new sample
• Added proper license headers

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.