Swell MCP 服务器

一个模型上下文协议（Model Context Protocol，简称MCP）服务器，它将AI助手与Swell的电子商务平台集成在一起。该服务器基于生产就绪的TypeScript构建，通过命令行界面（CLI）和MCP工具接口，为Swell商店提供全面的产品管理、订单处理和客户管理访问权限。

由……建造/创建 Devkind（可译为“开发者之友”或根据具体语境译为其他更贴切的名称，但在此直接保留原英文以体现其独特性） - 官方合作伙伴Swell，为全球企业提供前沿的电子商务解决方案。

](https://www.npmjs.com/package/swell-mcp) ![License: ISC](https://opensource.org/licenses/ISC) ![Built by Devkind](https://devkind.com.au/services/swell)

特点/特性

电商整合浪潮完整访问Swell的API，涵盖产品、订单和客户信息
双传输支持AI助手与网页集成的STDIO和HTTP传输方式
五层架构命令行界面（CLI）、工具、控制器、服务和实用程序之间的清晰分离
类型安全使用Zod模式验证的完整TypeScript实现
高级HTTP客户端基于swell-node SDK构建，具备连接池和重试逻辑
全面测试使用Swell API模拟进行单元和集成测试
生产工装ESLint、Prettier、semantic-release 和 MCP Inspector 的集成
错误处理使用Swell特定的错误上下文进行结构化错误处理

Swell电子商务集成

这款MCP服务器与Swell的电子商务平台实现了全面集成：

可用工具与命令

MCP 工具：

swell_list_products - 列出产品，并支持过滤和分页
swell_get_product - 获取详细的产品信息
swell_search_products - 按多种条件搜索产品
swell_check_inventory - 检查产品库存水平
swell_list_orders - 列出订单并提供筛选选项
swell_get_order - 获取详细的订单信息
swell_update_order_status - 更新订单状态
swell_list_customers - 列出具有搜索功能的客户
swell_get_customer - 获取详细的客户信息
swell_search_customers - 根据多个条件搜索客户

展示的功能

产品管理全面的产品目录访问及库存追踪功能
订单处理订单生命周期管理与状态更新
客户管理包含订单历史和分析的客户档案
错误处理针对API故障和验证问题的结构化错误
响应格式化生成带有结构化数据表格的干净Markdown输出

配置要求

# Required - Swell API credentials
SWELL_STORE_ID=your-store-id
SWELL_SECRET_KEY=your-secret-key

# Development
DEBUG=true                    # Enable detailed logging
TRANSPORT_MODE=http          # Use HTTP transport
PORT=3001                    # Custom port

需要高级涨潮结账功能吗？

这个MCP服务器展示了Swell的复杂集成能力，这些能力为（系统/应用）提供了动力 CheckoutJet（可译为“结账捷径”或根据具体语境调整为更贴切的表述） - 为Swell商店打造的企业级结账解决方案 Devkind（可译为“德夫金德”，但具体译名可能需根据上下文或品牌官方译名调整）。

CheckoutJet（可译为“结账捷径”或根据具体语境调整，如“快速结账服务”等） 让您的Swell结账体验焕然一新：

企业对企业（B2B）卓越典范 - 专业开票，30天净付款，批发价格
📦 智能航运 - 来自多个地点的实时汇率，配备智能订单路由
⚡ 分批交货 - 处理复杂的多供应商和多仓库订单履行
🎨 完全定制化 - 极致精准、符合品牌特色的结账体验
🤖 自动化 - 自动化开票、采购订单（PO）和订单管理
💰 高级定价 - 动态折扣和分层定价逻辑

经证实的成果： 为Swell商家处理了超过50万欧元的交易，转化率提升了23%。

准备好升级您的Swell结账体验了吗？ 预约15分钟的演示

什么是MCP？

模型上下文协议（MCP）是一种开放标准，用于安全地将人工智能系统连接到外部工具和数据源。该服务器实现了MCP规范，为人工智能助手提供了对Swell电子商务平台的全面访问权限，从而实现智能店铺管理和客户服务自动化。

入门指南/开始使用

首先，使用您的AI助手或MCP客户端安装Swell MCP服务器。

要求

Node.js 18 或更高版本
VS Code、Cursor、Windsurf、Claude Desktop 或任何其他MCP客户端
存储凭证（商店ID和密钥）

标准配置 在大多数MCP客户端中均适用：

{
	"mcpServers": {
		"swell-mcp": {
			"command": "npx",
			"args": ["swell-mcp"],
			"env": {
				"DEBUG": "false",
				"SWELL_STORE_ID": "your_store_id",
				"SWELL_SECRET_KEY": "your_private_token"
			},
			"disabled": false
		}
	}
}

Claude Desktop

按照MCP安装步骤进行指南/向导，使用上面的标准配置。

添加到你的 claude_desktop_config.json：

{
	"mcpServers": {
		"swell-mcp": {
			"command": "npx",
			"args": ["swell-mcp"],
			"env": {
				"SWELL_STORE_ID": "your_store_id",
				"SWELL_SECRET_KEY": "your_private_token"
			}
		}
	}
}

Cursor

点击按钮进行安装：

[](https://cursor.com/en/install-mcp?name=Swell%20MCP&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJzd2VsbC1tY3AiXSwiZW52Ijp7IlNXRUxMX1NUT1JFX0lEIjoieW91cl9zdG9yZV9pZCIsIlNXRUxMX1NFQ1JFVF9LRVkiOiJ5b3VyX3ByaXZhdGVfdG9rZW4ifX0%3D)

或者手动安装：

首选 Cursor Settings -> MCP -> Add new MCP Server将其命名为“Swell MCP”，使用 command 使用命令输入类型 npx swell-mcp在环境变量部分添加您的Swell凭据。

VS Code

按照MCP安装指南进行安装指南；引导；导游使用上述标准配置。您也可以使用 VS Code CLI 安装 Swell MCP 服务器：

# For VS Code
code --add-mcp '{"name":"swell-mcp","command":"npx","args":["swell-mcp"],"env":{"SWELL_STORE_ID":"your_store_id","SWELL_SECRET_KEY":"your_private_token"}}'

安装完成后，您将在VS Code中能够使用Swell MCP服务器与您的GitHub Copilot代理进行交互。

Windsurf

跟随风帆冲浪MCP（可能指某种风帆冲浪教学或培训项目）文档资料使用上述标准配置。

在您的MCP配置中添加：

{
	"mcpServers": {
		"swell-mcp": {
			"command": "npx",
			"args": ["swell-mcp"],
			"env": {
				"SWELL_STORE_ID": "your_store_id",
				"SWELL_SECRET_KEY": "your_private_token"
			}
		}
	}
}

Goose

首选 Advanced settings -> Extensions -> Add custom extension将其命名为“Swell MCP”，使用类型 STDIO，并设置 command to npx swell-mcp将您的Swell凭据作为环境变量添加。点击“添加扩展”。

LM Studio

首选 Program 在右侧边栏中 -> Install -> Edit mcp.json使用上述标准配置，并填入您的Swell凭据。

Warp

首选 Settings -> AI -> Manage MCP Servers -> + Add 到添加一个MCP服务器使用上述标准配置。

或者，使用斜杠命令 /add-mcp 在 Warp 提示符中，粘贴上面的标准配置。

配置

获取您的冲浪认证

登录到您的Swell仪表板 在 login.swell.store 翻译为中文是：“登录.swell商店”。不过，这里的“.swell.store”可能是一个特定网站或应用的域名，具体翻译时可能需要根据上下文或该网站/应用的实际内容进行调整。但基于直接翻译，上述翻译是合理的
导航至开发者 → API密钥
复制您的商店ID （这是你的 SWELL_STORE_ID)
复制您的密钥 （这是你的 SWELL_SECRET_KEY - 使用后端/管理员密钥，而不是公钥

环境变量

SWELL_STORE_ID您的Swell商店标识符（必填）
SWELL_SECRET_KEY您的Swell私钥（必需）
DEBUG将设置设为“true”以启用带有原始JSON响应的调试模式（可选）

示例配置

{
	"mcpServers": {
		"swell-mcp": {
			"command": "npx",
			"args": ["swell-mcp"],
			"env": {
				"DEBUG": "false",
				"SWELL_STORE_ID": "my-awesome-store",
				"SWELL_SECRET_KEY": "sk_live_abc123def456..."
			},
			"disabled": false
		}
	}
}

使用方法

一旦安装在您的MCP客户端中（参见入门指南/开始使用（如上所述），您可以通过您的AI助手直接使用Swell MCP工具：

示例交互

"List my active products"
→ Uses swell_list_products with active=true

"Show me pending orders from this week"
→ Uses swell_list_orders with status=pending and date filtering

"Update customer John Doe's email to john@example.com"
→ Uses swell_update_customer to modify customer information

"Check inventory for product ID abc123"
→ Uses swell_check_inventory for stock levels

调试模式

启用调试模式以查看原始JSON响应，而不是格式化输出：

{
	"env": {
		"DEBUG": "true",
		"SWELL_STORE_ID": "your_store_id",
		"SWELL_SECRET_KEY": "your_private_token"
	}
}

运输方式

STDIO 传输

通过标准输入/输出进行JSON-RPC通信
被Claude Desktop、Cursor AI以及其他本地AI助手使用
使用以下方式运行： TRANSPORT_MODE=stdio node dist/index.js

可流式传输的HTTP传输

基于HTTP的传输，使用服务器发送事件（SSE）
支持多个并发连接和网页集成
默认在3000端口运行（可通过配置更改 PORT 环境变量)
MCP终端（或MCP端点）： http://localhost:3000/mcp
健康检查： http://localhost:3000/ → 返回服务器版本
运行方式： TRANSPORT_MODE=http node dist/index.js

架构概述

Project Structure (Click to expand)

src/
├── cli/                    # Command-line interfaces
│   └── index.ts            # CLI entry point with Commander setup
├── controllers/            # Business logic orchestration
│   ├── swell.products.controller.ts    # Product management logic
│   ├── swell.products.formatter.ts     # Product response formatting
│   ├── swell.orders.controller.ts      # Order management logic
│   ├── swell.orders.formatter.ts       # Order response formatting
│   ├── swell.customers.controller.ts   # Customer management logic
│   └── swell.customers.formatter.ts    # Customer response formatting
├── services/               # External API interactions
│   ├── swell.products.service.ts       # Swell products API service
│   ├── swell.products.types.ts         # Product type definitions
│   ├── swell.orders.service.ts         # Swell orders API service
│   ├── swell.orders.types.ts           # Order type definitions
│   ├── swell.customers.service.ts      # Swell customers API service
│   └── swell.customers.types.ts        # Customer type definitions
├── tools/                  # MCP tool definitions (AI interface)
│   ├── swell.products.tool.ts          # Product management tools
│   ├── swell.orders.tool.ts            # Order management tools
│   └── swell.customers.tool.ts         # Customer management tools
├── types/                  # Global type definitions
│   └── common.types.ts     # Shared interfaces (ControllerResponse, etc.)
├── utils/                  # Shared utilities
│   ├── logger.util.ts      # Contextual logging system
│   ├── error.util.ts       # MCP-specific error formatting
│   ├── error-handler.util.ts # Error handling utilities
│   ├── config.util.ts      # Environment configuration
│   ├── constants.util.ts   # Version and package constants
│   ├── formatter.util.ts   # Markdown formatting
│   ├── swell-client.util.ts # Swell SDK client wrapper
│   └── transport.util.ts   # HTTP transport utilities
└── index.ts                # Server entry point (dual transport)

五层架构

服务器采用了一种简洁、分层的架构，这种架构有助于提高可维护性并实现清晰的职责分离：

1. CLI 层（`src/cli/`)

目的用于直接工具使用和测试的命令行界面
实施基于命令的参数解析，支持上下文错误处理
示例： list-products --active --category electronics
图案；样式；模式注册命令 → 解析参数 → 调用控制器 → 处理错误

2. 工具层（`src/tools/`)

目的AI助手可调用的MCP工具定义
实施使用Zod进行模式验证并返回结构化响应
示例： swell_list_products 带有过滤和分页选项的工具
模式定义模式 → 验证参数 → 调用控制器 → 格式化MCP响应

3. 资源层（`src/resources/`)

目的MCP资源提供可通过URI访问的上下文数据（计划中的功能）
实施处理基于URI请求的资源处理器
示例： swell://products/123 提供产品详情的资源
模式注册URI模式 → 解析请求 → 返回格式化内容

4. 控制器层（`src/controllers/`)

目的业务逻辑编排，具备全面的错误处理机制
实施选项验证、备用逻辑、响应格式化
示例产品管理（含库存追踪）与订单处理（含状态更新）
图案验证输入 → 应用默认值 → 调用服务 → 格式化响应

5. 服务层（`src/services/`)

目的直接与外部API交互，仅包含最少的业务逻辑
实施带有结构化错误处理的HTTP传输工具
示例根据原文内容：“Swell API calls with authentication and data validation”，翻译成中文为：“带有身份验证和数据验证的Swell API调用”
模式构建请求 → 发起API调用 → 验证响应 → 返回原始数据

6. 工具层（Utils Layer）`src/utils/`）

目的所有层之间共享的功能
关键组件:

- logger.util.ts上下文日志记录（文件:方法上下文） - error.util.tsMCP特定错误格式化 - transport.util.ts带有重试逻辑的HTTP/API实用程序 - config.util.ts环境配置管理

开发环境设置

对于希望贡献或修改服务器的开发者：

先决条件

Node.js (>=18.x): (大于等于18.x) 下载
Git用于版本控制

快速入门

# Clone the repository
git clone https://github.com/devkindhq/swell-mcp.git
cd swell-mcp

# Install dependencies
npm install

# Configure your Swell credentials
cp .env.example .env
# Edit .env and add your SWELL_STORE_ID and SWELL_SECRET_KEY

# Build the project
npm run build

# Run in different modes:

# 1. STDIO Transport - For AI assistant integration (Claude Desktop, Cursor)
npm run mcp:stdio

# 2. HTTP Transport - For web-based integrations
npm run mcp:http

# 3. Development with MCP Inspector
npm run mcp:inspect                         # Auto-opens browser with debugging UI

开发脚本

# Build and Clean
npm run build               # Build TypeScript to dist/
npm run clean               # Remove dist/ and coverage/
npm run prepare             # Build + ensure executable permissions (for npm publish)

# CLI Testing (coming soon)
# npm run cli -- list-products --active                   # List active products
# npm run cli -- get-product 
                 # Get product details
# npm run cli -- list-orders --status pending             # List pending orders

# MCP Server Modes
npm run mcp:stdio           # STDIO transport for AI assistants
npm run mcp:http            # HTTP transport on port 3000
npm run mcp:inspect         # HTTP + auto-open MCP Inspector

# Development with Debugging
npm run dev:stdio           # STDIO with MCP Inspector integration
npm run dev:http            # HTTP with debug logging enabled

# Testing
npm test                    # Run all tests (Jest)
npm run test:coverage       # Generate coverage report
npm run test:cli            # Run CLI-specific tests

# Code Quality
npm run lint                # ESLint with TypeScript rules
npm run format              # Prettier formatting
npm run update:deps         # Update dependencies

环境变量

核心配置

TRANSPORT_MODE运输方式（stdio | http，默认： stdio）
PORTHTTP服务器端口（默认： 3000)
DEBUG启用调试日志记录（true | false，默认： false）

Swell API配置

SWELL_STORE_ID您的Swell商店ID（必填）
SWELL_SECRET_KEY您的Swell密钥（必需）

示例 `.env` 文件

# Basic configuration
TRANSPORT_MODE=http
PORT=3001
DEBUG=true

# Swell API credentials (required)
SWELL_STORE_ID=your-store-id
SWELL_SECRET_KEY=your-secret-key

调试工具

MCP 检查器用于测试您的MCP工具的可视化工具

- 使用以下方式运行服务器 npm run mcp:inspect - 打开终端中显示的URL - 交互式测试您的工具

调试日志记录使用以下方式启用： DEBUG=true 环境变量

Configuration (Click to expand)

创造 ~/.mcp/configs.json：

{
	"swell-mcp": {
		"environments": {
			"DEBUG": "true",
			"TRANSPORT_MODE": "http",
			"PORT": "3000",
			"SWELL_STORE_ID": "your-store-id",
			"SWELL_SECRET_KEY": "your-secret-key"
		}
	}
}

可用工具

Swell MCP服务器为AI助手提供全面的电子商务管理工具。以下列表列出了已实现的工具名称及其参数模式 src/tools/。

Product Management

热销产品列表

- 描述：列出产品，并支持过滤和分页功能 - 参数： page， limit， active， category， tags， sort， expand

获取产品信息（或“获取产品详情”）

- 描述：获取详细的产品信息 - 参数： productId， expand

搜索热门产品

- 描述：使用文本查询和可选过滤器搜索产品 - 参数： query， page， limit， active， category， tags， sort， expand

检查库存涨潮（或库存波动）

- 描述：检查产品的当前库存数量和库存状态 - 参数： productId， includeVariants （默认：true）

更新产品信息

- 描述：更新产品元数据和属性（名称、描述、SEO、标签、分类、属性、是否启用、SKU 等） - 参数： productId 以及任何可编辑的产品字段

更新产品库存

- 描述：调整库存水平或更新库存追踪设置 - 参数： productId， quantity， reason， reasonMessage， variantId， orderId

更新产品定价

- 描述：更新产品价格（常规价格、促销价格、货币种类） - 参数： productId， price， salePrice， currency

Order Management

膨胀列表订单

- 描述：列出订单并提供筛选选项 - 参数： page， limit， status， customerId， dateFrom， dateTo， sort， expand

获取订单（或“查询订单”）

- 描述：获取详细的订单信息 - 参数： orderId， expand

更新订单状态（swell_update_order_status）

- 描述：更新订单状态（可选添加备注） - 参数： orderId， status， notes

Customer Management

自定义客户列表（或：客户名单定制）

- 描述：列出客户，并提供搜索和筛选选项 - 参数： page， limit， search， email， dateFrom， dateTo， sort， expand

获取客户信息（或：查询客户详情）

- 描述：获取详细的客户信息（包括个人资料+可选的订单历史） - 参数： customerId， expand， includeOrderHistory

扩大搜索客户群

- 描述：使用文本查询（姓名、电子邮件、电话）搜索客户 - 参数： query， page， limit， dateFrom， dateTo， sort， expand

更新客户信息

- 描述：更新客户记录（姓名、电子邮件、电话、标签、群组、营销订阅选项、备注） - 参数： customerId 可编辑的客户字段更多

扩展服务器

此服务器采用模块化架构构建，便于添加新的Swell API集成或自定义业务逻辑。现有的Swell工具（产品、订单、客户）作为实现附加功能的示例。

有关详细的实现模式，请参阅代码库中的现有控制器、服务和工具。

独立使用

如果你想独立运行服务器（而不是通过MCP客户端）：

全球安装

npm install -g swell-mcp

直接使用

# Set your credentials
export SWELL_STORE_ID=your-store-id
export SWELL_SECRET_KEY=your-secret-key

# Run the server
swell-mcp

HTTP 模式

# Run with HTTP transport on port 3000
TRANSPORT_MODE=http swell-mcp

# Custom port
PORT=8080 TRANSPORT_MODE=http swell-mcp

______________________________________________________________________

🚀 让您的Swell商店更上一层楼

对这款MCP服务器的能力印象深刻吗？这只是专家级Swell开发所能实现的冰山一角。

� CheckoutJet - 企业级高效结账系统

用我们经过实战检验的结账解决方案，彻底升级您的Swell商店：

B2B行业的佼佼者/实力派 - 专业开票，30天净付款，批发价格
智能航运 - 来自多个地点的实时汇率，支持智能路由
“Split Deliveries”可以翻译为“分批交货”或“分散交付”。这个术语通常用于物流、供应链管理或电子商务等领域，指的是将订单商品分成多个批次进行交付，而不是一次性全部交付 - 复杂的多供应商和多仓库履行（或配送）服务
全面定制 - 精准像素级、品牌一致的结账体验
经证实的效果 - 处理金额超过500,000欧元，转化率提升23%

查看CheckoutJet的实战应用 →

🤖 机器人人工智能与定制开发

像这样的MCP服务器，采用AI技术集成
自定义Swell应用程序和主题
无头电商实现
性能优化与自动化

准备好转型您的电子商务业务了吗？

![See CheckoutJet Demo](https://checkoutjet.com/)

测试策略

该服务器配备了全面的测试基础设施：

测试结构

tests/               # Not present - tests are in src/
src/
├── **/*.test.ts     # Co-located with source files
├── utils/           # Utility function tests
├── controllers/     # Business logic tests
├── services/        # API integration tests
└── cli/             # CLI command tests

测试最佳实践

单元测试测试工具和纯函数（*.util.test.ts)
控制器测试使用模拟服务调用来测试业务逻辑
服务测试测试API与真实/模拟HTTP调用的集成
CLI 测试测试命令解析与执行
测试环境检测控制器中的自动测试模式处理

运行测试

npm test                    # Run all tests
npm run test:coverage       # Generate coverage report
npm run test:cli           # CLI-specific tests only

覆盖目标

目标：测试覆盖率>80%
专注于业务逻辑（控制器）和实用工具
适当模拟外部服务

许可证

ISC许可证

资源与文档

MCP协议资源

MCP规范
MCP SDK 文档
MCP 检查器 - 可视化调试工具

实施参考

“Swell Resources”可以翻译为“蓬勃资源”或“兴盛资源”，具体取决于语境和想要传达的细微差别。在这里，“Swell”通常表示“蓬勃的”、“兴盛的”或“显著的”，而“Resources”则指的是“资源”。因此，一个较为贴切的翻译是“蓬勃资源”

专业潮汐服务

寻找专业的Swell开发服务？ Devkind（可译为“德夫金德”或根据具体语境保留原名）是Swell的官方合作伙伴，我们的远程团队致力于为全球企业提供服务，专业领域包括：

CheckoutJet（可译为“结账捷径”或根据具体语境调整，如“快速结账服务”等） - 面向企业的结账解决方案，支持B2B业务、发货自动化及分批交付
涌浪开发服务 - 自定义应用、主题和集成
无头电商 基于上述信息，翻译如下：API驱动的门店和体验

开始使用： 查看CheckoutJet演示 | 免费预约咨询 | 电子邮件： hello@devkind.com.au（可翻译为）：hello@devkind.com.au（该邮箱地址本身无需翻译，但若要说明其用途或格式，可表述为“这是一个澳大利亚的开发公司邮箱地址，用于联系或发送邮件”） | 全球远程团队

Swell MCP

快速接入

详细介绍

Swell MCP 服务器

特点/特性

Swell电子商务集成

可用工具与命令

展示的功能

配置要求

需要高级涨潮结账功能吗？

什么是MCP？

入门指南/开始使用

要求

点击按钮进行安装：

或者手动安装：

配置

获取您的冲浪认证

环境变量

示例配置

使用方法

示例交互

调试模式

运输方式

STDIO 传输

可流式传输的HTTP传输

架构概述

五层架构

1. CLI 层（src/cli/)

2. 工具层（src/tools/)

3. 资源层（src/resources/)

4. 控制器层（src/controllers/)

5. 服务层（src/services/)

6. 工具层（Utils Layer）src/utils/）

开发环境设置

先决条件

快速入门

开发脚本

环境变量

核心配置

Swell API配置

示例 .env 文件

调试工具

可用工具

扩展服务器

独立使用

全球安装

直接使用

HTTP 模式

🚀 让您的Swell商店更上一层楼

� CheckoutJet - 企业级高效结账系统

🤖 机器人 人工智能与定制开发

测试策略

测试结构

测试最佳实践

运行测试

覆盖目标

许可证

资源与文档

MCP协议资源

实施参考

专业潮汐服务

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

1. CLI 层（`src/cli/`)

2. 工具层（`src/tools/`)

3. 资源层（`src/resources/`)

4. 控制器层（`src/controllers/`)

5. 服务层（`src/services/`)

6. 工具层（Utils Layer）`src/utils/`）

示例 `.env` 文件

🤖 机器人人工智能与定制开发