agent-network-protocol · Moshiii · Nov 28, 2025
diff --git a/docs/jwt_rs256/RS256-private.pem b/docs/jwt_rs256/RS256-private.pem
@@ -0,0 +1,28 @@
+-----BEGIN PRIVATE KEY-----
+MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC3TZRcRRlW27FX
+YcfPYD70Ap5HP755cC5e/AT8Ccct1L3YiMNz9NXPKEphTlo4PO/OrfDra/rkdO5l
+OlijOi+c/40a8REkIqlzbMO+Ug9MbKtQVQ57M7o1RneYhIGlx8Z7B7QEpXisxlv7
+NaKLXOe6YpEiLMUC9emASztx1EUg65NLT57Ja4xteEcmWv2IPyByNfc8SK/U+sQH
+43wq47uEiXLqe29cIBmz85BdWDf4GrYHNdOMSkhIakPUIrCqVSl2G8OhZSXvMfsr
+hY68WjtbU9/Zj1LPyytTDbXmrzDN7PUtNw2vTltRGcoKDjvnUnXQgJ5i0zqfuLr5
+Nk4K2Z5pAgMBAAECggEAFW1nM2YMcT/bOji+77nzgfiwYenMrUt00DurpX7LHsto
+qeBK4Mo1GDNAhqFvIHXXHpTsvchwmrYkjAbHB8WsfTDOYODfPRckMc78Dspu6WMm
+n4xh1fsVAFdNcbHDqgpxZD5hR83EDoZdiD8b0ii5GeudxZ3wJclzU0D4IPVMY22T
+OpGH+KlDX/5ahmkqNpwGeqS4/xwsZYEKBqAwthM58IPvrRu8zPANK+XpZg07Irqp
+ksuQcH8ArdtAHi/HW4vVP3OkfIoyp8IfDC+9JzdtkchQT4nO1rMSXv3POrq/3LWc
+88CJIFbUH3KyoB9khfw/pyYvTVxwHLohnjsB82s1UQKBgQD4YZ25V8metFLfPLhd
+G4poE2zZ0lGQtdiMWNQhyJZ1qnFX7X68oed4TUkNK9RFb7VWmI8MZBsiC4/B8oIv
+pN742kuLG09gFY0JFHNg+d3ZiitZel28ybhCE5xydt605dE4fkE982bnvYJ0vu+K
+M0QburpTiDMP+QI6HUcRVEqNHQKBgQC87PG8eCyak1yXgUEH9HeZcCe6RjRbLlLJ
+Y4hXVZKLMuJ3YcoTcbajeXn7hpJPXSEG5eALjrkeQYi9PzqImI10TMnGCNGqHcl5
+0M3mBFzgweQehRVezbQ9wTlibcbXJoN4vItRl7/fGZhmaI8M8ycxK6rgTjhk48oK
+SXwUXaIwvQKBgAtHY4InGmC6j4jTmQuhVIelWiwKAOoxV8QHxJpEIZD2TG9RuY+X
+SouL9uVCOEFu8S0dgGFvqkvBeqWz/XVsZzOltgh7FP+n+t+Ori6ZKhnWzGEjzV3l
+Sxi1C0WnYDWWugl2sj+97c5YLLRgd0AvU8hukkd4x9jR1egNrEx9J2WBAoGAExnZ
+rvZvfAleGStGSemblfXS7nBepsFeOWJIzJuoP06buvo2FhUvJAQKIzYN4NxHlIz1
+Q/XgHYD+tDOKVXknBBUnaVBG8m4kip5j0teqFEdGKxfFe1pM2NmKVbtHmUUZkcFu
+TIeNLJ9H20LDA8opsjz5/8eox/qH2NZpJx34YfkCgYEApr9XoMPoG9N2MzIh+Yf8
+qgGO/NaxAcnOaRiKMbqge71WLHHS3TZzHRxk64z9NA7rl58AbKsxfB7UJ9+2TC1E
+XNJF3JUpV2gT5FyGa4z9rHrfWajvbfveTW2YIipKq7bsCYTHzsLUVed4kI3oXtQY
+ab0b7yv8irlkhzf3xkJ94h8=
+-----END PRIVATE KEY-----
diff --git a/docs/jwt_rs256/RS256-public.pem b/docs/jwt_rs256/RS256-public.pem
@@ -0,0 +1,9 @@
+-----BEGIN PUBLIC KEY-----
+MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAt02UXEUZVtuxV2HHz2A+
+9AKeRz++eXAuXvwE/AnHLdS92IjDc/TVzyhKYU5aODzvzq3w62v65HTuZTpYozov
+nP+NGvERJCKpc2zDvlIPTGyrUFUOezO6NUZ3mISBpcfGewe0BKV4rMZb+zWii1zn
+umKRIizFAvXpgEs7cdRFIOuTS0+eyWuMbXhHJlr9iD8gcjX3PEiv1PrEB+N8KuO7
+hIly6ntvXCAZs/OQXVg3+Bq2BzXTjEpISGpD1CKwqlUpdhvDoWUl7zH7K4WOvFo7
+W1Pf2Y9Sz8srUw215q8wzez1LTcNr05bURnKCg4751J10ICeYtM6n7i6+TZOCtme
+aQIDAQAB
+-----END PUBLIC KEY-----
diff --git a/docs/jwt_rs256/private_key.pem b/docs/jwt_rs256/private_key.pem
@@ -0,0 +1,28 @@
+-----BEGIN PRIVATE KEY-----
+MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC/uStVucqsetGL
+xU0i3JRLsSN8hXMnySUsaN4PGCtgOw0voQOQIMCc0PfNTnRCnYnqCJmPshUPCkP8
+/U+5rqDGOFif/diCynyG9eO7KkckPIjo6+e385gCZzHMTiOfNyt+PPNi/20M1JIB
+uUh45FOX/8pEI5YGrFE7/KvMUrktphSyWKUHvJkW1gTaJS0C1GyRclrCy/fCdfxb
+HYFyugRauXxYoTntlf7+D7DMMPTG4GTbih9OerHYjRZNKi9vSgefqUPnId3xu+EM
+z3sI8cn7noSPaZL3TmPBi+5wBHhB3GvlrAkA1m9JdxhZLa9MU56vYxgPspixL/JC
+iQaTZjMVAgMBAAECggEABvSHO21pildMScdHFJgu8w4CjQ5kTpGv/Qvy3lZQoIWT
+5WHweKaPhkDYdIS/l/kSG0DjnUBnHiwPqlpgLYrFv1sk7+zsEVaaLOU3tT8D5K8j
+gluohNZb8d5fgptlFG4ScFpys+kzQg9mGpTnqacS10VKx60I0MYojkYMz3VCzYKU
+T2jU+hVlwzEqzZEh+KhnUa0C82FO0+THCqOLJ5bROw2bsZEH8q1PipdrK960N1T2
+Mq2XK1BsmnV/ucdG2BJkT/9oAeKwd4CABySLmSlB82OBwJLd90i88RYAcfp5YGEu
+T9lfkO097y24Wbv1VQsnLQkHQBZvUkofHMC8B/jskQKBgQDn1N+UmvTICA1yLHFA
+GvUsd/roV322yQ0qbuBUf8iBokJMRBXjaDILg7o12KgMlhaecLUdsBbmpLXC/+rw
+Cpw+7N1RIwiIiUSsdQekf3A2ZV2lxWmrnDEgNq40JhaemuET4V9dJrPqh9Iv/PS0
+4nopvCGuen2sXU92Q8MhRDMGSQKBgQDTteL50nC5JN1a4IhrjjD6o8t5e85ds7tO
+kSLDaX9yebUuxPKLQoyu2EkfgNG9mc6eBhHp4upl1odbIdpzGBiA4+1hllC/t7gF
+9CiqsNLOXMJIJDgpBaa973EUQRu8YU8mKNXp5SNy5Aeyhu/OGsNORjKvE0aJudoy
+JJV2+RBWbQKBgA5bvdk7W6vD6+lFXWJGCSdO6whW2t9mRl15boVtQKLexNJqaRyj
+iG30I6VQHOBir1XyzxTeohx42RURuqBRV+oBy5dJ3y5tqgYwXV/P0MhdsNYiiu/p
+BZXkLRfnwADkwMn1bG2dhwkgjmEQfqtxV3WcRE3FImF5igFeIwi9a5eZAoGAYgeU
+o+0HeRNS0+OoB3V9xHDXpNbpBYZVstmNaUKOWul0NcXIMSeNkOBha47wj4SKoa1Z
+2hzSQHmHj3Erf6OmpPflUQyTM1LUiR03P2JFGnzlERaEUqplPQmEKMbFGwNL7PV3
+p6gMNATWc5n7rEnEKZhjm6GnRdqi6Bj8hGxrXjkCgYEA2s2a6vn9ltVucZcuPykV
+Tnjlx/g4CGfpHMfahg8dW4KUl5v8YDH5bLoXu/v2kMofbr2h2pbacCDydfTxDT50
+RXiMfS5Fy9+PL7Sm5lGT93Q3F6KoUasp6sNyrMjZoiEbQklIhtrr6PAfTr5G5MoQ
+HJQCcinIQxQt7T8AfKZiLSk=
+-----END PRIVATE KEY-----
diff --git a/docs/jwt_rs256/public_key.pem b/docs/jwt_rs256/public_key.pem
@@ -0,0 +1,9 @@
+-----BEGIN PUBLIC KEY-----
+MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAv7krVbnKrHrRi8VNItyU
+S7EjfIVzJ8klLGjeDxgrYDsNL6EDkCDAnND3zU50Qp2J6giZj7IVDwpD/P1Pua6g
+xjhYn/3Ygsp8hvXjuypHJDyI6Ovnt/OYAmcxzE4jnzcrfjzzYv9tDNSSAblIeORT
+l//KRCOWBqxRO/yrzFK5LaYUslilB7yZFtYE2iUtAtRskXJawsv3wnX8Wx2BcroE
+Wrl8WKE57ZX+/g+wzDD0xuBk24ofTnqx2I0WTSovb0oHn6lD5yHd8bvhDM97CPHJ
++56Ej2mS905jwYvucAR4Qdxr5awJANZvSXcYWS2vTFOer2MYD7KYsS/yQokGk2Yz
+FQIDAQAB
+-----END PUBLIC KEY-----
diff --git a/examples/AP2_QUICKSTART.md b/examples/AP2_QUICKSTART.md
@@ -0,0 +1,156 @@
+# AP2 支付流程快速启动指南
+
+本指南说明如何运行完整的 AP2 支付流程演示。
+
+## 架构说明
+
+AP2 支付流程包含三个组件：
+
+1. **merchant_server.py** - 商户服务器，提供购物车授权和支付授权处理接口
+2. **mcp2anp.ap2_server** - MCP 服务器，将 AP2 支付流程封装为 MCP tools
+3. **mcp_ap2_client_demo.py** - MCP 客户端演示，通过 MCP 协议调用 AP2 功能
+
+## 运行步骤
+
+### 1. 启动商户服务器
+
+在第一个终端中运行：
+
+```bash
+cd examples
+uv run python merchant_server.py
+```
+
+服务器会在默认端口 8889 启动，输出类似：
+```
+============================================================
+AP2 Merchant Server
+============================================================
+Host: 192.168.x.x
+Port: 8889
+[Server] Merchant server started
+[Server]   URL: http://192.168.x.x:8889
+[Server]   DID: did:example:merchant
+[Server] Server is running. Press Ctrl+C to stop.
+```
+
+### 2. 运行 MCP AP2 客户端演示
+
+在第二个终端中运行：
+
+```bash
+cd examples
+uv run python mcp_ap2_client_demo.py
+```
+
+客户端会自动：
+1. 连接到 `mcp2anp.ap2_server`（通过 stdio）
+2. 调用 `ap2.createCartMandate` 创建购物车授权
+3. 调用 `ap2.sendPaymentMandate` 发送支付授权
+4. 完成完整的支付流程
+
+## 工作流程
+
+```
+┌─────────────────┐
+│ merchant_server │  ← HTTP API 服务器
+│   (端口 8889)   │
+└────────┬────────┘
+         │ HTTP POST
+         │ /ap2/merchant/create_cart_mandate
+         │ /ap2/merchant/send_payment_mandate
+         │
+┌────────▼──────────────────────────────┐
+│      mcp_ap2_client_demo.py          │
+│  (MCP 客户端)                         │
+│                                       │
+│  ┌─────────────────────────────────┐ │
+│  │  ap2.createCartMandate          │ │
+│  │  ap2.sendPaymentMandate         │ │
+│  └────────────┬────────────────────┘ │
+└───────────────┼───────────────────────┘
+                │ MCP stdio 协议
+                │
+┌───────────────▼───────────────┐
+│   mcp2anp.ap2_server          │
+│   (MCP 服务器)                 │
+│                               │
+│   - AP2Handler                │
+│   - 封装 shopper client 功能  │
+└───────────────────────────────┘
+```
+
+## 可用的 MCP Tools
+
+### `ap2.createCartMandate`
+
+创建购物车授权请求并发送给商户服务器。
+
+**参数：**
+- `merchant_url` (string, required): 商户服务器URL
+- `merchant_did` (string, required): 商户DID
+- `cart_mandate_id` (string, required): 购物车授权ID
+- `items` (array, required): 商品列表
+- `shipping_address` (object, required): 配送地址
+- `remark` (string, optional): 备注
+
+**返回：**
+- `ok`: 是否成功
+- `cart_mandate_id`: 购物车授权ID
+- `cart_mandate`: 购物车授权详情
+- `cart_hash`: 购物车哈希值
+
+### `ap2.sendPaymentMandate`
+
+构建并发送支付授权给商户服务器。
+
+**参数：**
+- `merchant_url` (string, required): 商户服务器URL
+- `merchant_did` (string, required): 商户DID
+- `cart_mandate_id` (string, required): 之前创建的购物车授权ID
+- `payment_mandate_id` (string, required): 支付授权ID
+- `refund_period` (integer, optional): 退款期限（天，默认30）
+
+**返回：**
+- `ok`: 是否成功
+- `payment_mandate_id`: 支付授权ID
+- `status`: 支付状态
+- `payment_id`: 支付ID
+- `payment_receipt`: 支付收据（如果可用）
+- `fulfillment_receipt`: 履约收据（如果可用）
+
+## 环境变量
+
+可以通过环境变量配置 DID 凭证：
+
+```bash
+export ANP_DID_DOCUMENT_PATH=/path/to/did-doc.json
+export ANP_DID_PRIVATE_KEY_PATH=/path/to/private-key.pem
+```
+
+如果未设置，将使用默认的公共 DID 凭证（`docs/did_public/public-did-doc.json`）。
+
+## 故障排查
+
+### 商户服务器无法启动
+
+- 检查端口 8889 是否被占用
+- 检查 DID 文档和密钥文件是否存在
+
+### MCP 客户端连接失败
+
+- 确保 `mcp2anp.ap2_server` 可以正常导入
+- 检查 Python 环境和依赖是否正确安装
+
+### 支付流程失败
+
+- 确保商户服务器正在运行
+- 检查网络连接和防火墙设置
+- 查看日志输出获取详细错误信息
+
+## 下一步
+
+- 查看 `examples/README.md` 了解更多 MCP 客户端使用方法
+- 查看 `mcp2anp/ap2_server.py` 了解服务器实现细节
+- 查看 `examples/merchant_server.py` 了解商户服务器实现
+
diff --git a/examples/README.md b/examples/README.md
@@ -12,6 +12,17 @@
 ### `simple_example.py`
 简化的使用示例，展示最基本的客户端用法。
 
+### `mcp_ap2_client_demo.py`
+AP2 支付流程演示脚本，展示如何使用 MCP 客户端完成完整的 AP2 支付流程：
+- 创建购物车授权请求
+- 发送支付授权完成支付
+
+### `merchant_server.py`
+AP2 商户服务器示例，提供购物车授权和支付授权处理接口。
+
+### `shopper_client.py`
+AP2 购物者客户端示例（已整合到 `mcp2anp.ap2_server` 中）。
+
 ## 运行演示
 
 ### 前置条件
@@ -32,6 +43,22 @@ cd examples
 uv run python simple_example.py
 ```
 
+### 运行 AP2 支付流程演示
+
+1. **启动商户服务器**（在一个终端中）：
+```bash
+cd examples
+uv run python merchant_server.py
+```
+
+2. **运行 AP2 客户端演示**（在另一个终端中）：
+```bash
+cd examples
+uv run python mcp_ap2_client_demo.py
+```
+
+AP2 客户端会自动连接到 `mcp2anp.ap2_server` 并完成完整的支付流程。
+
 ## 使用方法（基于 MCP 官方 SDK）
 
 ### 基本步骤
@@ -127,6 +154,27 @@ asyncio.run(my_example())
 - `method`: RPC 方法名
 - `params`: RPC 参数
 
+## AP2 支付流程工具
+
+使用 `mcp2anp.ap2_server` 时，以下工具可用：
+
+### `ap2.createCartMandate`
+创建购物车授权请求并发送给商户服务器
+- `merchant_url`: 商户服务器URL
+- `merchant_did`: 商户DID
+- `cart_mandate_id`: 购物车授权ID（唯一标识）
+- `items`: 商品列表（包含 id, quantity, price, currency, label, options, remark）
+- `shipping_address`: 配送地址（包含 recipient_name, phone, region, city, address_line, postal_code）
+- `remark`: 备注信息（可选）
+
+### `ap2.sendPaymentMandate`
+构建并发送支付授权给商户服务器
+- `merchant_url`: 商户服务器URL
+- `merchant_did`: 商户DID
+- `cart_mandate_id`: 之前创建的购物车授权ID
+- `payment_mandate_id`: 支付授权ID（唯一标识）
+- `refund_period`: 退款期限（天，默认30）
+
 ## 注意事项
 
 1. **认证文件**: 要使用 `anp.setAuth` 工具，你需要有效的 DID 文档和私钥文件