内容
# Sezzle 商户 MCP
一款非官方、实验性、专注于安全的 Model Context Protocol 服务器，用于安全的 Sezzle 商户操作、结算对账、Webhook 监控和集成诊断。
> **该项目是非官方的，与 Sezzle 无关，不受 Sezzle 维护或认可。**
未使用任何 Sezzle 徽标。Sezzle 商标归其各自所有者所有。
## 项目成熟度
该项目是一个非官方、实验性的集成。
其确定性的业务逻辑、权限模型、变异防护和模拟 API 集成已经过测试。然而，Sezzle API 适配器尚未使用真实的商户沙盒凭证进行验证。
在完成 [沙盒验证检查清单](docs/SANDBOX_VALIDATION.md) 之前，请勿启用生产财务变异。
生产导向和安全为中心的设计并不意味着生产就绪。在生产使用之前，仍然需要进行实时的 Sezzle 沙盒验证。
> 分析今天的 Sezzle 订单，识别未捕获的授权和退款不匹配，核对最新的结算，检查 Webhook 健康状况，并准备安全的操作，在我批准之前不会执行任何操作。
Sezzle Merchant MCP 并不是一个薄 API 包装器。它添加了确定性的资金验证、变异预览、显式审批门控、基于权限的工具注册、对账证据、Webhook 相关性、集成医生发现、安全支持路由和红acted 审计记录，围绕着记录的 Sezzle 商户 API。
## 功能
- 默认启用沙盒优先启动和只读模式。
- 记录的 Sezzle v2 商户 API 适配器，带有内存令牌续期。
- 捕获、退款、释放、会话、参考、结账和 Webhook 变异预览。
- 字面 `confirm: true`、过期预览绑定、新鲜状态验证和幂等性。
- 整数小单位货币和 `bigint` 算术；不进行浮点金融计算。
- 无损解析结算小数和四小数利息账户值。
- 确定性结算匹配、重复抑制、不匹配检测、预期支出、置信度和证据。
- 原始字节 HMAC-SHA256 Webhook 验证，解析前、幂等摄入和发生时间线。
- 稳定代码集成医生发现和上线检查清单。
- PII 最小化支持策略工具，带有商户参考所有权验证。
- 结构化 JSON 日志输出到 stderr、redacted 资源和耐用审计元数据。
- MCP stdio 和无状态 Streamable HTTP 传输。
- 内存和 SQLite 存储、Docker、Compose、CI、Dependabot、ESLint、Prettier 和 Vitest。
## 架构
```mermaid
flowchart LR
Client[MCP client] --> Transport[stdio or Streamable HTTP]
Transport --> Registry[Permission-filtered MCP registry]
Registry --> Services[Operation services]
Services --> Guards[Preview, confirmation, ownership, idempotency]
Services --> Domain[Money, reconciliation, diagnostics, support policy]
Services --> API[Versioned Sezzle v2 adapter]
API --> Auth[In-memory token manager]
API --> HTTP[Timeout, retry, concurrency, correlation]
HTTP --> Sezzle[Documented Sezzle merchant API]
Services --> Storage[Memory or SQLite]
Storage --> Audit[Redacted audit evidence]
Storage --> Events[Verified webhook event timeline]
```
MCP 注册故意保持简单。服务拥有工作流，领域模块拥有确定性计算，API 模块拥有路径和线路模式，存储模块拥有预览、幂等性、审计事件和 Webhook 记录。有关设计决策和记录的 API 模糊性的详细信息，请参见 [ARCHITECTURE.md](ARCHITECTURE.md)。
## 安全模型
默认配置为：
```env
SEZZLE_ENV=sandbox
SEZZLE_READ_ONLY=true
SEZZLE_REQUIRE_CONFIRMATION=true
SEZZLE_PERMISSION_PROFILE=read
MCP_TRANSPORT=stdio
```
在 `SEZZLE_READ_ONLY=true` 的情况下，变异工具不会注册。它们不会出现在 `tools/list` 中；它们不会保持可见并返回权限错误。
金融和高影响操作使用两个步骤：
1. 调用预览工具，或调用带有 `confirm: false` 的组合变异工具。
2. 审查当前状态、请求更改、财务影响、验证、警告、过期和审计 ID。
3. 用返回的 `preview_id` 和字面 `confirm: true` 重复不变的请求。
如果预览已过期、已使用、属于其他商户/目标/环境、具有不同的请求哈希或状态已更改，则执行失败。模型无法从自然语言中推断出确认。
示例捕获：
```json
{
"tool": "sezzle_preview_capture",
"arguments": {
"order_uuid": "order-uuid",
"amount": { "amount_in_cents": 2500, "currency": "USD" }
}
}
```
在审查预览后：
```json
{
"tool": "sezzle_capture_order",
"arguments": {
"order_uuid": "order-uuid",
"amount": { "amount_in_cents": 2500, "currency": "USD" },
"preview_id": "preview-from-first-call",
"confirm": true
}
}
```
仅在成功的 Sezzle API 响应后，才会报告执行成功。重新授权还需要 `authorization.approved === true`；仅 HTTP 200 不被视为批准。
## 支持的工具
生成的 [工具库存](docs/TOOL_INVENTORY.md) 目前验证了 55 个工具、6 个资源和 5 个提示。活动权限配置文件和只读设置决定了哪些工具已注册。
### 身份验证、会话和订单
- `sezzle_authenticate_merchant`
- `sezzle_get_merchant_context`
- `sezzle_create_payment_session`
- `sezzle_get_payment_session`
- `sezzle_cancel_active_checkout`
- `sezzle_get_order`
- `sezzle_update_order_reference`
- `sezzle_preview_capture`
- `sezzle_capture_order`
- `sezzle_preview_refund`
- `sezzle_refund_order`
- `sezzle_preview_release_authorization`
- `sezzle_release_authorization`
- `sezzle_reauthorize_order`
### 结算、报告和对账
- `sezzle_list_settlement_summaries`
- `sezzle_get_settlement_details`
- `sezzle_get_order_report`
- `sezzle_get_interest_balance`
- `sezzle_get_interest_activity`
- `sezzle_reconcile_settlement`
- `sezzle_find_unmatched_orders`
- `sezzle_detect_refund_mismatches`
- `sezzle_detect_capture_mismatches`
- `sezzle_detect_fee_anomalies`
- `sezzle_explain_payout_difference`
- `sezzle_generate_finance_daily_brief`
### Webhook
- `sezzle_list_webhooks`
- `sezzle_create_webhook`
- `sezzle_update_webhook`
- `sezzle_delete_webhook`
- `sezzle_send_test_webhook`
- `sezzle_verify_webhook_signature`
- `sezzle_ingest_webhook_event`
- `sezzle_list_webhook_events`
- `sezzle_get_webhook_event`
- `sezzle_inspect_webhook_health`
- `sezzle_find_missing_order_events`
- `sezzle_detect_out_of_order_events`
- `sezzle_detect_duplicate_webhook_events`
### 集成医生
- `sezzle_diagnose_integration`
- `sezzle_validate_session_payload`
- `sezzle_validate_redirect_urls`
- `sezzle_audit_auth_capture_flow`
- `sezzle_detect_stuck_authorizations`
- `sezzle_detect_uncaptured_orders`
- `sezzle_detect_duplicate_refunds`
- `sezzle_test_webhook_configuration`
- `sezzle_generate_go_live_checklist`
### 支持和审计
- `sezzle_explain_order_status_for_support`
- `sezzle_classify_support_request`
- `sezzle_draft_customer_response`
- `sezzle_determine_safe_support_route`
- `sezzle_identify_required_escalation`
- `sezzle_list_audit_events`
- `sezzle_get_audit_event`
## 权限配置文件
将 `SEZZLE_PERMISSION_PROFILE` 设置为一个配置文件：
| 配置文件 | 已注册的功能 |
| --- | --- |
| `read` | 身份验证上下文、会话、订单、结算、报告和集成医生 |
| `finance` | 读取功能加上捕获/退款/释放/会话/订单预览、对账和写入工具（启用时） |
| `webhooks` | 订阅管理、签名验证、摄入、时间线和健康状况 |
| `support` | 五个隔离的支持工具；原始订单读取工具未注册 |
| `admin` | 所有功能和审计检查 |
`read` 是默认配置文件。只读模式独立地从任何配置文件中删除每个变异工具。
## 安装
要求：
- Node.js 20 或更高版本
- npm
- 用于 API 支持测试的 Sezzle 沙盒商户账户
```bash
git clone https://github.com/onatozmenn/sezzle-merchant-mcp.git
cd sezzle-merchant-mcp
npm ci
npm run build
npm run inspect-tools
```
可用脚本：
```text
npm run dev
npm run build
npm run start
npm run test
npm run test:watch
npm run test:coverage
npm run lint
npm run typecheck
npm run format
npm run format:check
npm run inspect-tools
npm run docker:build
npm run docker:run
```
## 沙盒设置
1. 创建或获取 Sezzle 沙盒商户账户。
2. 在沙盒商户仪表板中生成沙盒 API 密钥。
3. 复制 `.env.example` 到 `.env`。
4. 初始保持 `SEZZLE_ENV=sandbox`、`SEZZLE_READ_ONLY=true` 和 `SEZZLE_PERMISSION_PROFILE=read`。
5. 设置 `SEZZLE_MERCHANT_UUID`、`SEZZLE_API_KEY` 和 `SEZZLE_API_SECRET`。
6. 构建并连接 MCP 客户端。
7. 在启用写入之前验证身份验证、读取工具、集成医生和预览。
默认基准 URL 为 `https://sandbox.gateway.sezzle.com`。仅在模拟集成测试中接受自定义循环 HTTP 基准 URL。
## 生产设置
生产环境是故障关闭的。它需要以下所有内容：
```env
SEZZLE_ENV=production
SEZZLE_API_BASE_URL=https://gateway.sezzle.com
SEZZLE_MERCHANT_UUID=您的生产商户 UUID
SEZZLE_API_KEY=您的生产公共密钥
SEZZLE_API_SECRET=您的生产私钥
SEZZLE_READ_ONLY=true
SEZZLE_REQUIRE_CONFIRMATION=true
```
身份验证的商户 UUID 必须与 `SEZZLE_MERCHANT_UUID` 匹配。首先在只读模式下运行上线检查清单。启用适当的权限配置文件，然后在审查后将 `SEZZLE_READ_ONLY` 设置为 `false`。不允许在启动时使用 `SEZZLE_REQUIRE_CONFIRMATION=false` 的不安全写入模式。
使用密钥管理器、加密的 SQLite 存储、TLS 终止、传输身份验证、限制性主机/源允许列表、监控和备份/保留控制。不要将生产机密放入提交到源代码控制的 MCP 客户端 JSON 中。
## Claude 桌面
构建服务器，然后将其添加到 Claude Desktop MCP 配置中。使用绝对路径：
```json
{
"mcpServers": {
"sezzle-ops": {
"command": "node",
"args": ["C:\\absolute\\path\\to\\sezzle-merchant-mcp\\dist\\index.js"],
"env": {
"SEZZLE_ENV": "sandbox",
"SEZZLE_READ_ONLY": "true",
"SEZZLE_PERMISSION_PROFILE": "read"
}
}
}
}
```
通过操作系统或感知机密的启动器注入凭证，而不是将它们检查到配置文件中。
## Claude 代码
创建一个项目本地的 `.mcp.json`，在包含凭证时排除在源代码控制之外：
```json
{
"mcpServers": {
"sezzle-ops": {
"type": "stdio",
"command": "node",
"args": ["/absolute/path/to/sezzle-merchant-mcp/dist/index.js"],
"env": {
"SEZZLE_ENV": "sandbox",
"SEZZLE_READ_ONLY": "true",
"SEZZLE_PERMISSION_PROFILE": "read"
}
}
}
}
```
在更改环境变量后重启 MCP 会话。
## 光标
将相同的 stdio 定义添加到光标的 MCP 配置中：
```json
{
"mcpServers": {
"sezzle-ops": {
"command": "node",
"args": ["/absolute/path/to/sezzle-merchant-mcp/dist/index.js"],
"env": {
"SEZZLE_ENV": "sandbox",
"SEZZLE_READ_ONLY": "true",
"SEZZLE_PERMISSION_PROFILE": "read"
}
}
}
}
```
对于 VS Code，请在 `npm run build` 后将相同的 stdio 定义添加到您的本地用户或工作区 MCP 设置中。本地 `.vscode/` 配置故意从公共存储库中排除。
## HTTP 传输
启用无状态 Streamable HTTP：
```env
MCP_TRANSPORT=http
MCP_HTTP_HOST=127.0.0.1
MCP_HTTP_PORT=3000
```
MCP 端点是 `http://127.0.0.1:3000/mcp`；健康状况是 `GET /health`。除非循环或列在 `MCP_HTTP_ALLOWED_ORIGINS` 中，否则浏览器源拒绝。
每个非循环绑定都需要以下两者：
```env
MCP_HTTP_AUTH_TOKEN=a-long-random-transport-token
MCP_HTTP_ALLOWED_HOSTS=mcp.example.com
MCP_HTTP_ALLOWED_ORIGINS=https://trusted-client.example
```
在受信任的反向代理处终止 TLS 并发送 `Authorization: Bearer <token>`。`/health` 意大利语是未经身份验证的，不包含商户状态。HTTP 请求正文限制为 1 MB；Webhook 摄入工具输入另外限制为模式。
## Docker
构建并运行 stdio：
```bash
npm run docker:build
npm run docker:run
```
对于 HTTP 加持久化 SQLite，请在 `.env` 中设置 `MCP_HTTP_AUTH_TOKEN` 并运行：
```bash
docker compose up --build
```
Compose 使用非 root 镜像、只读 root 文件系统、丢弃的权限、专用的 SQLite 卷和健康检查。
## 示例工作流
### 每日运营审查
1. 读取 `sezzle://config`、`sezzle://permissions` 和 `sezzle://capabilities`。
2. 身份验证并验证商户/环境。
3. 获取范围内的订单/报告证据。
4. 运行 `sezzle_detect_uncaptured_orders`、核对和 Webhook 健康检查。
5. 准备捕获/退款/释放预览。
6. 呈现审计 ID、警告和预期财务影响。
7. 除非用户单独批准特定预览，否则停止不执行。
### 退款工作流
1. 调用 `sezzle_preview_refund` 带有整数小单位金额。
2. 确认当前捕获、退款和剩余退款金额。
3. 解决警告或验证失败。
4. 调用 `sezzle_refund_order` 带有不变的请求、`preview_id` 和 `confirm: true`。
5. 将返回的交易 UUID 和请求 ID 作为 API 证据。
## Webhook 设置
Sezzle 文档记录了 HMAC-SHA256 webhook 使用商户签名密钥进行验证。单独配置值：
```env
SEZZLE_WEBHOOK_SECRET=您的签名密钥
```
在启用写入的 `webhooks` 或 `admin` 模式下使用 `sezzle_create_webhook`。它在确认之前预览 URL/事件集更改。
对于摄入：
1. 将确切的请求字节保存为 UTF-8 字符串。
2. 将确切的原始正文和 `Sezzle-Signature` 值传递给 `sezzle_verify_webhook_signature`。
3. 调用 `sezzle_ingest_webhook_event` 带有字面 `confirm: true` 仅在验证策略允许存储后。
4. 无效签名在 JSON 解析前被拒绝。
5. 事件 UUID 和有效载体哈希重复交付。
6. 时间线按 `occurredAt` 排序，而不是接收顺序。
公共事件工具返回元数据和相关 ID，而不是原始正文。SQLite 保留验证的原始正文，因为相关性和法医要求依赖于它们；保护并保留该数据库作为商户敏感数据。
## 对账示例
对账接受商户订单和规范的结算项目金额为结构化输入。金额为整数美分：
```json
{
"input": {
"currency": "USD",
"merchant_orders": [
{
"record_id": "merchant-1001",
"order_reference": "order_1001",
"sezzle_order_uuid": "sezzle-order-uuid",
"currency": "USD",
"order_amount_in_cents": 10000,
"captured_amount_in_cents": 8000,
"refunded_amount_in_cents": 1000,
"expected_fee_in_cents": 480
}
],
"sezzle_records": [
{
"record_id": "capture-row-1",
"type": "CAPTURE",
"order_uuid": "sezzle-order-uuid",
"external_reference_id": "order_1001",
"amount_in_cents": 8000,
"currency": "USD"
}
],
"actual_settlement": { "amount_in_cents": 6520, "currency": "USD" },
"fee_tolerance_in_cents": 0
}
}
```
每个结果包括 `summary`、`matched`、`unmatchedMerchantRecords`、`unmatchedSezzleRecords`、`amountMismatches`、`feeAnomalies`、`confidence` 和 `evidence`。重复行在付款算术之前被排除。货币转换从未推断。
## 集成医生示例
```json
{
"input": {
"now": "2026-07-16T12:00:00Z",
"configured_environment": "sandbox",
"credential_environment": "sandbox",
"api_base_url": "https://sandbox.gateway.sezzle.com",
"orders": [],
"https://sandbox.gateway.sezzle.com",
"orders": [],
"webhooks": {
"subscribed_events": ["order.authorized"],
"required_events": ["order.authorized", "order.captured"],
"invalid_signature_count": 0,
"missing_events": [],
"out_of_order_count": 0
}
}
}
```
发现结果包含稳定的 `code`、`severity`、`title`、`explanation`、`evidence`、`recommendedAction` 和 `safeToAutomate: false`。引擎报告证据；它不执行修复。
## MCP 资源
- `sezzle://config`
- `sezzle://permissions`
- `sezzle://capabilities`
- `sezzle://diagnostic-codes`
- `sezzle://audit-summary` (`admin` 仅限)
- `sezzle://webhook-health` (`webhooks` 或 `admin`)
资源永远不会暴露 API 密钥、密钥、承载令牌、签名、原始正文或客户记录。
## MCP 提示
- `sezzle_daily_operations_review`
- `sezzle_settlement_reconciliation`
- `sezzle_integration_go_live_review`
- `sezzle_webhook_incident_investigation`
- `sezzle_support_case_review`
提示文件感知且直接引导模型在解释之前收集证据，使用确定性算术，区分事实和建议，准备预览并避免不支持的成功声明。
## 安全考虑
- 绝不记录或提交 API 密钥、Bearer Token、Webhook 签名、原始有效载荷、客户个人信息或支付详情。
- Token 保留在内存中，并在到期前刷新。401 状态码触发重新获取；变异操作仅在具有已记录的幂等性时重新播放。
- 安全的 GET 请求尊重超时、指数退避、`Retry-After` 和并发限制。
- Webhook 订阅/会话/引用变异不会自动重试，因为它们的端点未记录幂等性。
- 结算 JSON 小数使用无损解析器。CSV 小数直接从文本转换为缩放整数。
- 支持订单访问需要经过身份验证的商户访问和匹配的商户引用。返回的订单预测排除客户字段。
- SQLite 保存原始已验证的 Webhook 正文。使用加密存储、严格访问、备份和保留控制。
- 远程 HTTP 需要传输身份验证、允许的主机、TLS 终止和网络控制。
- 在生产部署前，请查看 [SECURITY.md](SECURITY.md)。
## 已知限制
- `GET /v2/orders/report` 仅按请求提供，支持最大七天范围。
- 利息端点需要注册 Sezzle 的利息账户计划。
- 结算详情为 CSV；Sezzle 的架构更改可能需要适配器更新。
- Sezzle 文档目前链接到 `https://gateway.sezzle.com/v2api.yaml`，返回 404。此项目使用已发布的 `https://docs.sezzle.com/openapi.yaml`。
- 授权事件示例及其组件架构使用两种已记录的形状；适配器仅支持这两种形状。
- 附加费 API 标记为开发中，不适用于生产，因此故意不公开。
- 没有记录的端点列表任意当前商户订单。集成医生和对账接受范围结构化记录，而不是抓取仪表板。
- 订单报告 API 包括客户字段；Sezzle Merchant MCP 从其规范化响应中删除它们。
- 可流式传输的 HTTP 是无状态的。持久工作流状态属于 SQLite；多节点共享存储未实现。
- SQLite 数据不加密。使用加密磁盘/卷和平台访问控制。
- OAuth 未捆绑。远程部署使用配置的 Bearer Token，应位于生产身份感知反向代理后面。
- 支持草拟是确定性策略模板，而不是嵌入式 LLM。MCP 客户端可以使用返回的事实/策略协助草拟。
## 路线图
- 用于多节点 HTTP 部署的共享事务存储。
- 可插拔的秘密管理器和加密记录集成。
- 可配置的 Webhook 保留和删除策略。
- 用于远程 MCP 客户端的 OAuth/OIDC 部署适配器。
- 针对发布的 Sezzle 规范的 OpenAPI 合同漂移自动化。
- 保留确定性核心类型的其他对账导入适配器。
## 真相来源
- Sezzle 文档索引：<https://docs.sezzle.com/llms.txt>
- Sezzle OpenAPI 规范：<https://docs.sezzle.com/openapi.yaml>
- MCP TypeScript SDK v1 文档：<https://ts.sdk.modelcontextprotocol.io/>
- MCP TypeScript SDK v1 源代码：<https://github.com/modelcontextprotocol/typescript-sdk/tree/v1.x>
发布的 Sezzle OpenAPI 规范中没有的端点不会被故意公开。
## 许可证
MIT。查看 [LICENSE](LICENSE)。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器