cartai-mcp-server

<p align="center"> <img src="images/cartai-logo.png" alt="CartAI" height="50" /> </p> # CartAI MCP 服务器 > **<a href="https://cartai.ai" target="_blank" rel="noopener noreferrer">CartAI</a> 提供 MCP 服务器，用于自主产品发现、代理支付和结账。** > **<a href="https://portal.cartai.ai/" target="_blank" rel="noopener noreferrer">在 CartAI 门户注册并试用 →</a>** 一个 <a href="https://modelcontextprotocol.io" target="_blank" rel="noopener noreferrer">MCP（模型上下文协议）</a> 服务器，暴露 CartAI 目录、支付和结账 API 作为 Claude Desktop、Claude Code、Cursor 或任何 MCP 兼容的 AI 主机的工具。完全由 CartAI 提供支持 - 搜索产品、获取详细的变体和定价信息、获取结账前的运费和税费估算、获取客户的卡授权用于代理支付，并自主、异步地执行整个结账流程，并带有完整的状态跟踪。 <br/> <a href="https://nodejs.org" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen" alt="Node.js ≥ 18"/></a> <a href="https://modelcontextprotocol.io" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/MCP-compatible-blue" alt="MCP Compatible"/></a> <a href="LICENSE" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License: Apache 2.0"/></a> --- ## 目录 - [什么是 MCP？](#什么是-mcp) - [此服务器的作用](#此服务器的作用) - [先决条件](#先决条件) - [安装](#安装) - [配置](#配置) - [Claude Desktop](#claude-desktop) - [VS Code](#vs-code) - [MCP 检验器](#mcp-检验器) - [工具](#工具) - [示例提示](#示例提示) - [工作原理](#工作原理) - [环境变量](#环境变量) - [故障排除](#故障排除) - [资源和支持](#资源和支持) - [许可证](#许可证) --- ## 什么是 MCP？ <a href="https://modelcontextprotocol.io" target="_blank" rel="noopener noreferrer">模型上下文协议</a> 是一个开放标准，允许 AI 助手通过通用接口调用外部工具 - API、数据库、文件系统。将其视为 AI 的 USB-C 端口：一个标准，任何设备。 此服务器将 CartAI 的结账能力插入该端口。 --- ## 此服务器的作用 | 工具 | 描述 | |------|-------------| | `create_checkout` | 为一个或多个产品启动异步结账 | | `get_checkout` | 获取结账任务的当前状态 | | `cancel_checkout` | 取消正在进行的结账 | | `get_status_history` | 获取任务的完整生命周期事件日志 | | `search_products` | 按名称搜索跨商户的产品 | | `get_product_details` | 检索产品 URL 的详细资料、变体和定价 | | `get_checkout_estimates` | 计算结账前的运费和税费估算 | | `create_payment_session` | 创建托管支付会话 URL | 在内部，每个工具都与 CartAI REST 端点一对一映射 - MCP 服务器是一个薄的、类型安全的桥梁，没有额外的逻辑。 --- ## 先决条件 | 要求 | 版本 / 备注 | |-------------|-----------------| | **Node.js** | `>= 18.0.0`（使用原生 `fetch` 和 ES 模块） | | **CartAI API 密钥** | 从 <a href="https://cartai.ai" target="_blank" rel="noopener noreferrer">CartAI 管理门户</a> 获取 - 参见 <a href="https://docs.cartai.ai/" target="_blank" rel="noopener noreferrer">API 文档</a> 获取完整参考 | | **MCP 主机** | Claude Desktop、VS Code（带有 MCP 扩展）、MCP 检验器 | --- ## 安装 ```bash # 1. 克隆仓库 git clone https://github.com/your-username/cartai-mcp.git cd cartai-mcp # 2. 安装依赖 npm install # 3. 设置 API 密钥 export CARTAI_API_KEY=your_api_key_here # 4. 验证它启动 npm start # → [cartai-mcp] Running on stdio ✓ ``` > **永远不要提交您的 API 密钥。** 仓库附带一个 `.gitignore`，排除 `.env`。 --- ## 配置 ### Claude Desktop 编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）： ```json { "mcpServers": { "cartai": { "command": "node", "args": ["/absolute/path/to/cartai-mcp/src/index.js"], "env": { "CARTAI_API_KEY": "your_api_key_here" } } } } ``` 重启 Claude Desktop - 您应该在工具选择器中看到 CartAI 工具。 --- ### VS Code 安装适用于 VS Code 的 **MCP 扩展**，然后将以下内容添加到您的 `.vscode/mcp.json`（或用户级 `settings.json`下的 `"mcp.servers"`）： ```json { "servers": { "cartai": { "type": "stdio", "command": "node", "args": ["/absolute/path/to/cartai-mcp/src/index.js"], "env": { "CARTAI_API_KEY": "your_api_key_here" } } } } ``` 重新加载 VS Code 窗口 - CartAI 工具将可用于编辑器中的任何 MCP 感知代理。 --- ### MCP 检验器 <a href="https://github.com/modelcontextprotocol/inspector" target="_blank" rel="noopener noreferrer">MCP 检验器</a> 是官方的基于浏览器的工具，用于在不需要完整 AI 客户端的情况下测试和调试 MCP 服务器。 ```bash # 在一个命令中针对此服务器运行检验器 npx @modelcontextprotocol/inspector node /absolute/path/to/cartai-mcp/src/index.js ``` 在检验器内的**环境变量**面板中设置 API 密钥（`CARTAI_API_KEY = your_api_key_here`），然后使用**工具**选项卡交互式地调用 `create_checkout`、`get_checkout` 等。 > MCP 检验器是验证工具输入/输出的最快方式，无需连接完整的客户端。 --- ## 工具 ### `create_checkout` 创建新的异步结账任务。 CartAI 在后台运行结账并通过 Webhook 发送状态更新。 返回用于跟踪的 `taskId`。 **必填输入：** | 字段 | 类型 | 描述 | |-------|------|-------------| | `customer.contact.firstName` | `string` | — | | `customer.contact.lastName` | `string` | — | | `customer.contact.phone` | `string` | — | | `customer.contact.email` | `string` | — | | `customer.shippingAddress.addressLine1` | `string` | — | | `customer.shippingAddress.addressLine2` | `string` | — | | `customer.shippingAddress.city` | `string` | — | | `customer.shippingAddress.province` | `string` | 省/州代码，例如 `NY` | | `customer.shippingAddress.postalCode` | `string` | 邮政编码 | | `customer.shippingAddress.country` | `string` | 国家代码，例如 `US` | | `customer.payment.data` | `object` | `{ sessionId }` 用于代理支付，或原始卡信息，当 `provider` 为 `"test"` 时 | | `tasks[].url` | `string` | 完整产品页面 URL | | `tasks[].quantity` | `integer` | 购买单位（最小 1） | **可选输入：** | 字段 | 类型 | 默认值 | 描述 | |-------|------|---------|-------------| | `customer.customerId` | `UUID` | `null` | 现有 CartAI 客户 ID | | `customer.billingAddress` | object | `null` | 与 `shippingAddress` 相同的形状；如果省略，则默认为运费地址 | | `customer.shippingMethod.strategy` | `string` | `"cheapest"` | `"cheapest"` \| `"fastest"` \| `"standard"` | | `customer.payment.data.sessionId` | `string` | `null` | `create_payment_session` 返回的 sessionId，客户授权其卡后。不需要 `provider`。 | | `customer.payment.provider` | `string` | `null` | 设置为 `"test"` 以传递原始卡信息到 `data` 而不是 sessionId | | `tasks[].selectedVariant.color` | `string` | `null` | — | | `tasks[].selectedVariant.size` | `string` | `null` | — | | `tasks[].metadata.title` | `string` | `null` | 仅显示 - 不用于结账逻辑 | | `tasks[].metadata.description` | `string` | `null` | 仅显示 | | `tasks[].metadata.primaryImage` | `string` | `null` | 仅显示 | | `tasks[].metadata.price` | `string` | `null` | 仅显示 | | `options.cartId` | `UUID` | `null` | 将结账与现有购物车关联 | | `options.verifyBeforePlacement` | `boolean` | `false` | 在下单前暂停客户确认 | | `options.failTaskIfNotConfirmed` | `boolean` | `false` | 如果未收到确认，则取消任务 | | `options.allowPartialCheckout` | `boolean` | `true` | 允许多 SKU 订单的部分成功 | | `options.isRetryEnable` | `boolean` | `false` | 自动重试失败的结账尝试 | | `options.loginForLoyaltyDiscounts` | `boolean` | `false` | 登录以应用忠诚度/奖励折扣 | | `metadata.profile_id` | `string` | `null` | 用于跟踪的内部配置文件标识符 | **返回：** `taskId` 和初始任务状态，确认结账已排队。 --- ### `get_checkout` 检索结账任务的当前状态。 **必填：** `taskId` - 由 `create_checkout` 返回。 > 提示：将其连接到 CartAI Webhook 事件，而不是轮询。 **返回：** 当前任务状态、客户信息、任务项目和派生的定价/运费详细信息。 --- ### `cancel_checkout` 取消正在进行的结账任务。 **必填：** `taskId` **返回：** 确认结账任务已停止，不会进一步进行。 --- ### `get_status_history` 返回完整的生命周期事件日志 - 所有步骤、时间戳和消耗的积分。 **必填：** `taskId` **返回：** 有序的生命周期事件列表，包含状态、时间戳和每个步骤消耗的积分。 --- ### `search_products` 按名称搜索跨商户的产品。 返回具有定价、图像和购买链接的排名结果。 **必填输入：** | 字段 | 类型 | 描述 | |-------|------|-------------| | `name` | `string` | 产品名称或搜索查询 | **可选输入：** | 字段 | 类型 | 描述 | |-------|------|-------------| | `merchant` | `string` | 优先考虑结果的商户名称（例如 `"amazon"`、`"walmart"`）。其他零售商仍然返回。 | **返回：** 排名 `products[]` 每个包含 `name`、`brand`、`merchant`、`image`、`priceFrom`、`currency` 和 `directUrl`（用作 `create_checkout` 或 `get_product_details` 的 `url`）。还返回 `targetMerchant` 和 `targetMatchCount`。 --- ### `get_product_details` 检索给定产品页面 URL 的详细产品信息，包括所有可用的变体、定价和可用性。 **必填输入：** | 字段 | 类型 | 描述 | |-------|------|-------------| | `url` | `string` (URI) | 完整产品页面 URL | **可选输入：** | 字段 | 类型 | 默认值 | 描述 | |-------|------|---------|-------------| | `allVariants` | `boolean` | `true` | 当 `true` 时，返回所有可用的变体（颜色、尺寸等） | **返回：** 产品元数据（`name`、`brand`、`retailer`、`image`）、`directUrl`、`monetizationUrl`、变体 `dimensions` 和 `variants[]` 列表，包含每个变体的 `price`、`available`、`attributes`、`url` 和 `monetizationUrl`。 --- ### `get_checkout_estimates` 计算给定商户、目的地和商品列表的结账前成本估算 - 在下单前。 **必填输入：** | 字段 | 类型 | 描述 | |-------|------|-------------| | `merchant` | `string` | 用于估算成本的商户名称（例如 `"amazon"`） | | `destination` | `object` | 运费和税费计算的交货目的地 | | `destination.city` | `string` | — | | `destination.province` | `string` | 省/州代码，例如 `NY` | | `destination.postalCode` | `string` | 邮政编码 | | `destination.country` | `string` | 国家代码，例如 `US` | | `items` | `array` | 要估算的商品列表 | | `items[].url` | `string` (URI) | 完整产品页面 URL | | `items[].quantity` | `integer` | 单位数量（最小 1） | **可选输入：** | 字段 | 类型 | 描述 | |-------|------|-------------| | `destination.addressLine1` | `string` | 街道地址行 1 | | `destination.addressLine2` | `string` | 街道地址行 2 | | `items[].selectedVariant.color` | `string` | 变体颜色 | | `items[].selectedVariant.size` | `string` | 变体尺寸 | **返回：** 完整的成本明细，包括 `subtotal`、`shipping`、`shippingKnown`、`tax`、`total`、`currency` 和每个商品的 `items[]` 明细 - 均在解析的 `destination` 上下文中。 --- ### `create_payment_session` 创建托管支付会话并返回安全 URL，供客户授权其卡。 会话自动启动 Visa Intelligent Commerce 或 Mastercard Agent Pay，基于客户电子邮件中记录的卡 - 无需额外集成。 > 工具结果包括会话 `url` 作为可点击的 Markdown 链接 - 原样呈现（可点击的“打开”按钮），而不是重写或重新格式化，以便客户可以点击授权其卡。 **必填：** `email` **可选输入：** | 字段 | 类型 | 默认值 | 描述 | |-------|------|---------|-------------| | `price` | `string` | `"500"` | 支付金额（美元，无货币符号） | | `currency` | `string` | `"USD"` | 货币代码 | | `purpose` | `string` | `"CartAI Purchase Agent"` | 在支付流程中显示给客户 | | `expiry` | `string` (ISO 8601) | 创建后 1 周 | 当会话 URL 停止有效时 | **返回：** `sessionId`、托管的 `url`（格式化为客户的可点击链接）和会话的 `authorization` 详细信息（价格、货币、目的、到期日期）。 --- ## 示例提示 一旦服务器连接，尝试在 Claude 中输入这些： ``` 订购 2 件 https://example.com/product/sneakers，尺码 10，黑色。 运送给约翰·多伊，123 主街，纽约州，纽约 10001。 使用卡号 4242 4242 4242 4242，CVV 123，有效期 12/2034。 ``` ``` 检查结账任务 abc-123-def 的状态。 ``` ``` 取消执行 ID xyz-789 的结账任务 abc-123-def。 ``` ``` 显示任务 abc-123-def 的完整状态历史，包括使用了多少积分。 ``` ``` 为 customer@example.com 创建支付会话，支付金额为 700 美元的“Carol 的购买代理”。 ``` --- ## 工作原理 CartAI 暴露了三个功能集：**目录**（发现和评估产品）、**支付**（授权客户的卡用于代理使用）和**结账**（自主下订单）。 ### 目录流程 使用目录工具查找产品并在承诺购买之前验证详细信息： 1. **`search_products`** - 按名称跨商户搜索以获取每个结果的排名列表，包含定价和 `directUrl`。 2. **`get_product_details`** - 传递 `directUrl` 以检索所有变体、库存可用性和每个变体的定价。 3. **`get_checkout_estimates`** - 为给定目的地计算运费和税费，然后再下单。 ### 支付流程 在 `create_checkout` 可以收取客户真实卡的费用之前，客户必须通过托管的支付会话授权一次： ``` 您的应用 CartAI 客户 | | | |— POST /payment/session ——>| | |<— { sessionId, url } ————| | | | | |———————————— 将网址分享给客户 ———————>| | |<——————— 打开网址 ———————| | | 添加卡，授权 | | |<— 授权完成 ————————| ``` 1. **`create_payment_session`** - 传递客户的 `email`（以及可选的 `price`、`currency`、`purpose`、`expiry`）。返回 `sessionId` 和托管的 `url`。 2. **点击网址链接** - 客户添加其卡并授权 CartAI 在其上进行交易，使用 Visa Intelligent Commerce 或 Mastercard Agent Pay。 3. **保留 sessionId** - 客户授权后，将其传递到 `create_checkout` 作为 `customer.payment.data.sessionId`（无需 `provider`）。 ### 结账流程 一旦您拥有产品网址、客户详细信息和授权的 `sessionId` 或测试卡信息，请将其交给 CartAI： ``` 您的应用 CartAI 代理 商户网站 | | | |— POST /checkout ————————>| | |<— { taskId } ———————————| | | |— 导航网站 ————————>| | | 添加到购物车 | | | 选择运输选项 | | | 完成支付 | | |<— 订单确认 ————————| |<— Webhook：COMPLETED ————| | ``` 1. **`create_checkout`** - 传递产品网址、客户收货地址和支付凭证。支持两种支付方式： - **代理（推荐）：** `{ "data": { "sessionId": "<sessionId from create_payment_session>" } }` - **直接卡（测试）：** `{ "provider": "test", "data": { "cardNumber": "...", "cvv": "...", "name": "...", "expiryMonth": "...", "expiryYear": "..." } }` 2. **立即接收 taskId** - 异步下单流程在后台运行。 3. **跟踪进度** - 使用 `get_checkout` 或 `get_status_history` 监控任务；随时使用 `cancel_checkout` 取消。 --- ## 环境变量 | 变量 | 必需 | 描述 | |----------|----------|-------------| | `CARTAI_API_KEY` | 是 | 您的 CartAI API 密钥，来自管理门户 | 如果缺少密钥，服务器将启动，但所有 API 调用都将被拒绝，并显示身份验证错误。 如果在启动时缺少密钥，则会在标准错误中打印警告。 --- ## 故障排除 **启动时出现“所有 API 调用都将被拒绝”警告** 未设置 `CARTAI_API_KEY` 环境变量。 在 MCP 配置的 `env` 块中传递它（参见 [配置](#配置)），或在运行前导出它。 **工具未出现在 Claude 中** - 确认 MCP 配置中的绝对路径是否正确（`node /full/path/to/src/index.js`）。 - 编辑配置后重启 Claude Desktop / 重新加载 MCP 会话。 - 直接在终端中运行 `node src/index.js` 以检查启动错误。 **来自 CartAI 的 HTTP 401** 您的 API 密钥无效或已过期。 在 CartAI 管理门户中重新生成。 **HTTP 404 于 get_checkout / get_status_history** `taskId` 不存在或属于不同的帐户。 **Node 版本错误** 此包使用原生 `fetch` 和 ES 模块 - 需要 Node.js 18 或更高版本。 运行 `node --version` 进行检查。 --- ## 资源和支持 - **API 文档：** <a href="https://docs.cartai.ai/" target="_blank" rel="noopener noreferrer">docs.cartai.ai</a> - **网站：** <a href="https://cartai.ai" target="_blank" rel="noopener noreferrer">cartai.ai</a> - **电子邮件：** <a href="mailto:arb@cartai.ai">arb@cartai.ai</a> - **门户：** <a href="https://portal.cartai.ai/" target="_blank" rel="noopener noreferrer">注册、探索和管理您的帐户</a> --- ## 许可证 在 <a href="LICENSE" target="_blank" rel="noopener noreferrer">Apache License 2.0</a> 下许可。