<div align="center">

# Shopify Agentic MCP Gateway

**The first tri-protocol commerce gateway for autonomous AI agents on Shopify.**

Let AI agents browse, negotiate, cart, pay, and track orders -- fully autonomously.

[![UCP 2026-01](https://img.shields.io/badge/UCP-2026--01--11-blue?style=flat-square)](https://ucp.dev)
[![AP2 Mandates](https://img.shields.io/badge/AP2-Mandate%20Chain-purple?style=flat-square)](https://agentpayments.dev)
[![MCP 1.12+](https://img.shields.io/badge/MCP-1.12%2B-green?style=flat-square)](https://modelcontextprotocol.io)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue?style=flat-square)](https://typescriptlang.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow?style=flat-square)](LICENSE)

</div>

---

## Why This Exists

AI agents are learning to shop. But today, there is no standard way for an agent to discover a merchant's capabilities, negotiate terms, build a cart, authorize payment, and complete a purchase -- all without a human clicking buttons.

**Shopify Agentic MCP Gateway** solves this by implementing three emerging protocols in a single, deployable gateway:

| Protocol | Role | What It Does |
|----------|------|--------------|
| **UCP** (Universal Commerce Protocol) | Discovery + Capabilities | Agents discover your store at `/.well-known/ucp`, negotiate capabilities, and interact via a standard shopping service API |
| **AP2** (Agent Payment Protocol) | Authorization + Security | Three-mandate signature chain (Intent, Cart, Payment) ensures agents can only spend what the user authorized |
| **MCP** (Model Context Protocol) | Agent Interface | Five tool registrations that Claude, GPT, and other LLM agents call directly via stdio or HTTP transport |

---

## Features

- **5 MCP Tools** -- `scout_inventory`, `manage_cart`, `negotiate_terms`, `execute_checkout`, `track_order`
- **UCP Profile Discovery** -- `/.well-known/ucp` endpoint with capability negotiation and transport advertisement
- **AP2 Mandate Chain** -- Cryptographic ES256 signature chain (Intent -> Cart -> Payment) with full verification
- **Guardrails** -- AI hallucination guard validates prices, inventory, mandate amounts, and checkout state transitions
- **Fee Collection** -- Automatic platform fee calculation (configurable rate) with ledger tracking
- **Checkout State Machine** -- Three-state machine (`incomplete` -> `requires_escalation` -> `ready_for_complete`) with auto-detection
- **Dual Runtime** -- Runs locally as stdio MCP server for Claude Desktop, or deploys to AWS Lambda with API Gateway
- **DynamoDB-Ready** -- In-memory stores with annotated DynamoDB migration paths for mandates, sessions, and ledger

---

## Quick Start

### Prerequisites

- Node.js >= 22.0.0
- A Shopify store with Storefront API access
- (Optional) AWS account for Lambda deployment

### 1. Install

```bash
git clone https://github.com/kuro-tomo/shopify-agentic-mcp.git
cd shopify-agentic-mcp
npm install
```

### 2. Configure

```bash
cp .env.example .env
```

Edit `.env` with your Shopify credentials:

```env
SHOPIFY_STORE_DOMAIN=your-store.myshopify.com
SHOPIFY_STOREFRONT_TOKEN=your_storefront_token
SHOPIFY_ACCESS_TOKEN=your_access_token
SHOPIFY_API_KEY=your_api_key
SHOPIFY_API_SECRET=your_api_secret
```

### 3. Build and Run

```bash
npm run build
npm start
```

The MCP server starts in stdio mode, ready for Claude Desktop or any MCP client.

### 4. Connect to Claude Desktop

Add this to your Claude Desktop configuration (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "shopify-agentic": {
      "command": "node",
      "args": ["/absolute/path/to/shopify-agentic-mcp/dist/index.js"],
      "env": {
        "SHOPIFY_STORE_DOMAIN": "your-store.myshopify.com",
        "SHOPIFY_STOREFRONT_TOKEN": "your_token"
      }
    }
  }
}
```

Now ask Claude: *"Search for wireless headphones under $50 and add the best one to my cart."*

---

## Architecture

```
                          +------------------+
                          |   AI Agent       |
                          | (Claude / GPT)   |
                          +--------+---------+
                                   |
                          MCP (stdio / HTTP)
                                   |
                          +--------v---------+
                          |  MCP Server      |
                          |  5 Tool Handlers |
                          +--------+---------+
                                   |
              +--------------------+--------------------+
              |                    |                     |
     +--------v-------+  +--------v--------+  +---------v--------+
     | UCP Layer       |  | AP2 Layer       |  | Middleware        |
     | - Profile       |  | - Signer        |  | - Guardrail      |
     | - Negotiate     |  | - Verifier      |  | - Fee Collector  |
     | - Checkout SM   |  | - Mandate Store |  | - Rate Limiter   |
     | - Discovery     |  |                 |  | - Auth           |
     +--------+--------+  +-----------------+  +------------------+
              |
     +--------v--------+
     | Shopify APIs     |
     | - Storefront GQL |
     | - Admin REST     |
     +------------------+
```

---

## Tool Reference

| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `scout_inventory` | Search the Shopify catalog for products | `query` (string), `category?`, `price_min?`, `price_max?`, `limit?` |
| `manage_cart` | Create, modify, or retrieve a shopping cart | `action` (create/add/remove/get), `cart_id?`, `variant_id?`, `quantity?` |
| `negotiate_terms` | Negotiate capabilities, discounts, and shipping between agent and merchant | `cart_id` (string), `agent_profile_url` (string), `discount_code?` |
| `execute_checkout` | Complete a purchase with AP2 mandate chain verification | `checkout_id`, `intent_mandate`, `cart_mandate`, `payment_mandate` |
| `track_order` | Retrieve order status and fulfillment tracking | `order_id` (string) |

All prices are in **minor units** (cents). A $29.99 product has `price: 2999`.

---

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `SHOPIFY_STORE_DOMAIN` | Yes | Your Shopify store domain (e.g., `store.myshopify.com`) |
| `SHOPIFY_STOREFRONT_TOKEN` | Yes | Storefront API access token |
| `SHOPIFY_ACCESS_TOKEN` | Yes | Admin API access token |
| `SHOPIFY_API_KEY` | Yes | Shopify app API key |
| `SHOPIFY_API_SECRET` | Yes | Shopify app API secret |
| `AP2_SIGNING_PRIVATE_KEY` | Yes | ES256 private key in JWK format for mandate signing |
| `AP2_VERIFICATION_PUBLIC_KEY` | No | ES256 public key in JWK format (defaults to deriving from private key) |
| `GATEWAY_BASE_URL` | No | Public gateway URL (default: `http://localhost:3000`) |
| `FEE_RATE` | No | Platform fee rate as decimal (default: `0.005` = 0.5%) |
| `FEE_WALLET_ADDRESS` | No | Wallet address for fee collection |
| `LOG_LEVEL` | No | Logging level (default: `info`) |

---

## Deployment

### AWS Lambda (Serverless)

```bash
npm run build
npm run deploy
```

This deploys via the Serverless Framework with:
- **Runtime**: Node.js 22.x on ARM64 (Graviton2)
- **Routes**: `/.well-known/ucp` (GET), `/ucp/v1/*` (ANY), `/mcp` (POST), `/a2a` (POST)
- **DynamoDB**: Three tables auto-provisioned (mandates, ledger, sessions) with PAY_PER_REQUEST billing

See [docs/deployment.md](docs/deployment.md) for the full deployment guide.

---

## Documentation

| Document | Description |
|----------|-------------|
| [Architecture](docs/architecture.md) | System architecture, component responsibilities, data flow |
| [UCP Integration](docs/ucp-integration.md) | Profile discovery, capability negotiation, checkout state machine |
| [AP2 Mandates](docs/ap2-mandates.md) | Mandate types, signature chain, verification process |
| [Deployment Guide](docs/deployment.md) | AWS Lambda setup, CloudFront, monitoring |
| [Developer Kit](docs/developer-kit.md) | Pricing, support, what's included |

---

## Examples

- [`examples/claude-desktop.json`](examples/claude-desktop.json) -- Claude Desktop MCP configuration
- [`examples/autonomous-purchase.ts`](examples/autonomous-purchase.ts) -- Full autonomous purchase flow
- [`examples/mandate-flow.ts`](examples/mandate-flow.ts) -- AP2 mandate generation and verification

---

## License

MIT License. See [LICENSE](LICENSE) for details.

---

<div align="center">

**Built for the agentic commerce era.**

[Documentation](docs/) | [Examples](examples/) | [Issues](https://github.com/kuro-tomo/shopify-agentic-mcp/issues)

</div>