Swell MCP 服务器
一个模型上下文协议(Model Context Protocol,简称MCP)服务器,它将AI助手与Swell的电子商务平台集成在一起。该服务器基于生产就绪的TypeScript构建,通过命令行界面(CLI)和MCP工具接口,为Swell商店提供全面的产品管理、订单处理和客户管理访问权限。
由……建造/创建 Devkind(可译为“开发者之友”或根据具体语境译为其他更贴切的名称,但在此直接保留原英文以体现其独特性) - 官方合作伙伴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输出
配置要求```bash
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客户端中均适用:```json
{
"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:```json
{
"mcpServers": {
"swell-mcp": {
"command": "npx",
"args": ["swell-mcp"],
"env": {
"SWELL_STORE_ID": "your_store_id",
"SWELL_SECRET_KEY": "your_private_token"
}
}
}
}
Cursor
#### 点击按钮进行安装:
#### 或者手动安装:
首选 `Cursor Settings` -> `MCP` -> `Add new MCP Server`将其命名为“Swell MCP”,使用 `command` 使用命令输入类型 `npx swell-mcp`在环境变量部分添加您的Swell凭据。
VS Code
按照MCP安装指南进行安装 指南;引导;导游使用上述标准配置。您也可以使用 VS Code CLI 安装 Swell MCP 服务器:```bash
# 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配置中添加:```json
{
"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 提示符中,粘贴上面的标准配置。
### 配置
#### 获取您的冲浪认证
1. **导航至开发者 → API密钥**
1. **复制您的商店ID** (这是你的 `SWELL_STORE_ID`)
1. **复制您的密钥** (这是你的 `SWELL_SECRET_KEY` - 使用后端/管理员密钥,而不是公钥
#### 环境变量
- `SWELL_STORE_ID`您的Swell商店标识符(必填)
- `SWELL_SECRET_KEY`您的Swell私钥(必需)
- `DEBUG`将设置设为“true”以启用带有原始JSON响应的调试模式(可选)
#### 示例配置```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响应,而不是格式化输出:```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传输工具
- **模式**构建请求 → 发起API调用 → 验证响应 → 返回原始数据
### 6. 工具层(Utils Layer)`src/utils/`)
- **目的**所有层之间共享的功能
- **关键组件**:
- `logger.util.ts`上下文日志记录(文件:方法上下文)
- `error.util.ts`MCP特定错误格式化
- `transport.util.ts`带有重试逻辑的HTTP/API实用程序
- `config.util.ts`环境配置管理
## 开发环境设置
**对于希望贡献或修改服务器的开发者:**
### 先决条件
- **Node.js** (>=18.x): (大于等于18.x) 下载
- **Git**用于版本控制
### 快速入门```bash
# 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
开发脚本```bash
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`)
- `PORT`HTTP服务器端口(默认: `3000`)
- `DEBUG`启用调试日志记录(`true` | `false`,默认: `false`)
#### Swell API配置
- `SWELL_STORE_ID`您的Swell商店ID(必填)
- `SWELL_SECRET_KEY`您的Swell密钥(必需)
#### 示例 `.env` 文件```bash
# 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:```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客户端):
### 全球安装```bash
npm install -g swell-mcp
直接使用```bash
Set your credentials
export SWELL_STORE_ID=your-store-id
export SWELL_SECRET_KEY=your-secret-key
Run the server
swell-mcp
### HTTP 模式```bash
# 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天净付款,批发价格
- 智能航运 - 来自多个地点的实时汇率,支持智能路由
- 全面定制 - 精准像素级、品牌一致的结账体验
- 经证实的效果 - 处理金额超过500,000欧元,转化率提升23%
查看CheckoutJet的实战应用 →
🤖 机器人 人工智能与定制开发
- 像这样的MCP服务器,采用AI技术集成
- 自定义Swell应用程序和主题
- 无头电商实现
- 性能优化与自动化
准备好转型您的电子商务业务了吗?
测试策略
该服务器配备了全面的测试基础设施:
测试结构```text
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 测试**测试命令解析与执行
- **测试环境检测**控制器中的自动测试模式处理
### 运行测试```bash
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 检查器 - 可视化调试工具
实施参考
- Anthropic MCP公告
- 超棒的MCP服务器 - 社区示例
-
TypeScript 文档
-
Swell Node SDK(可译为“Swell节点软件开发工具包”) - 该服务器所使用的底层SDK
专业潮汐服务
寻找专业的Swell开发服务? Devkind(可译为“德夫金德”或根据具体语境保留原名) 是Swell的官方合作伙伴,我们的远程团队致力于为全球企业提供服务,专业领域包括:
- CheckoutJet(可译为“结账捷径”或根据具体语境调整,如“快速结账服务”等) - 面向企业的结账解决方案,支持B2B业务、发货自动化及分批交付
- 涌浪开发服务 - 自定义应用、主题和集成
