Swell MCP

Swell MCP 服务

一个将 AI 助手与 Swell 电商平台集成的模型上下文协议服务。基于适用于生产环境的 TypeScript 基础构建，可通过命令行和 MCP 工具接口，全面访问 Swell 商店，管理产品、处理订单和管理客户。

由 Devkind 构建——Devkind 是 Swell 官方合作伙伴，为全球企业提供前沿电商解决方案。

功能

• Swell 电商集成：通过 Swell 的 API 全面访问产品、订单和客户数据
• 双传输支持：支持 STDIO 和 HTTP 传输，用于 AI 助手和 Web 集成
• 五层架构：清晰分离命令行、工具、控制器、服务和实用程序
• 类型安全：完整的 TypeScript 实现，并使用 Zod 进行架构验证
• 高级 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

需要高级 Swell 结账功能？

此 MCP 服务展示了高级 Swell 集成的能力，这类集成为 CheckoutJet 提供支持。CheckoutJet 是由 Devkind 为 Swell 商店打造的企业级结账解决方案。

CheckoutJet 为您的 Swell 结账流程带来：

• 🏢 卓越 B2B 体验——专业发票、Net 30 付款和批发定价
• 📦 智能配送——来自多个地点的实时费率，并支持智能订单路由
• ⚡ 拆分配送——处理复杂的多供应商和多仓库履约
• 🎨 全面定制——像素级精准、符合品牌形象的结账体验
• 🤖 自动化——自动开具发票、生成采购订单并管理订单
• 💰 高级定价——动态折扣和分层定价逻辑

**成果有目共睹：**已为 Swell 商家处理超过 €500,000 的交易，转化率提升 23%。

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

什么是 MCP？

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

入门

首先，在你的 AI 助手或 MCP 客户端中安装 Swell MCP 服务。

要求

• Node.js 18 或更高版本
• VS Code、Cursor、Windsurf、Claude Desktop 或任何其他 MCP 客户端
• Swell 商店凭据（Store ID 和 Secret Key）

标准配置适用于大多数 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
		}
	}
}

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

# 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"}}'

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

配置

获取 Swell 凭据

1. 登录 Swell 控制面板，访问 login.swell.store
2. 前往 Developer → API Keys
3. 复制你的 Store ID（即 SWELL_STORE_ID）
4. 复制你的 Secret Key（即 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 [email protected]"
→ 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 传输

• 通过 stdin/stdout 进行 JSON-RPC 通信
• 供 Claude Desktop、Cursor AI 和其他本地 AI 助手使用
• 运行命令：TRANSPORT_MODE=stdio node dist/index.js

Streamable HTTP 传输

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

架构概览

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)

5 层架构

服务采用清晰的分层架构，有助于提升可维护性并明确划分职责：

1. CLI 层（src/cli/）

• 用途：用于直接使用和测试工具的命令行界面
• 实现：基于 Commander 的参数解析，并提供上下文相关的错误处理
• 示例：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 调用
• 模式：构建请求 → 发起 API 调用 → 验证响应 → 返回原始数据

6. Utils 层（src/utils/）

• 用途：供所有层共享的功能
• 主要组件：
  • logger.util.ts：上下文日志记录（文件:方法上下文）
  • error.util.ts：MCP 专用错误格式化
  • transport.util.ts：包含重试逻辑的 HTTP/API 实用工具
  • config.util.ts：环境配置管理

开发环境设置

适用于希望贡献代码或修改服务的开发者：

先决条件

• Node.js（>=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 <product-id>                 # 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 文件示例

# 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 Inspector：用于测试 MCP 工具的可视化工具

  • 使用 npm run mcp:inspect 运行服务
  • 打开终端中显示的 URL
  • 交互式测试工具

• 调试日志：通过 DEBUG=true 环境变量启用

{
	"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/ 中实现的工具名称和参数架构一致。

扩展服务

此服务采用模块化架构，可轻松添加新的 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 结账

使用我们经久考验的结账解决方案，全面升级您的 Swell 商店：

• B2B 强大功能 - 专业发票、Net 30 付款、批发定价
• 智能配送 - 来自多个地点的实时费率与智能路由
• 拆分配送 - 复杂的多供应商和多仓库履约
• 全面自定义 - 像素级精准、契合品牌的结账体验
• 经过验证的成果 - 处理金额超过 €500,000，转化率提升 23%

查看 CheckoutJet 实际演示 →

🤖 AI 与定制开发

• 像此 MCP 服务这样的 AI 驱动集成
• 定制 Swell 应用和主题
• 无头电商实现
• 性能优化与自动化

准备好升级您的电商业务了吗？

测试策略

此服务包含全面的测试基础设施：

测试结构

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）
• 控制器测试：通过模拟服务调用来测试业务逻辑
• 服务测试：通过真实或模拟的 HTTP 调用来测试 API 集成
• 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 Inspector - 可视化调试工具

实现参考

• Anthropic MCP 公告
• Awesome MCP Servers - 社区示例
• TypeScript 文档

Swell 资源

• Swell 文档 - 官方 API 文档
• Swell Node SDK - 此服务使用的底层 SDK

专业 Swell 服务

正在寻找专业的 Swell 开发服务？ Devkind 是 Swell 官方合作伙伴，由远程团队为全球企业提供服务，专注于：

• CheckoutJet - 企业级结账解决方案，提供 B2B、配送自动化和拆分配送功能
• Swell Development Services - 定制应用、主题和集成
• Headless E-commerce - 由 API 驱动的店面和体验

立即开始：查看 CheckoutJet 演示 | 预约免费咨询 | 邮箱：[email protected] | 全球远程团队