Swell MCP

Swell MCP サーバー

AI アシスタントをSwellのeコマースプラットフォームと連携させるModel Context Protocolサーバーです。本番環境に対応したTypeScript基盤の上に構築されており、CLIとMCPツールの両方のインターフェースを通じて、商品管理、注文処理、顧客管理など、Swellストアに包括的にアクセスできます。

Devkindが開発 — 世界中の企業に最先端のeコマースソリューションを提供する、Swellの公式パートナーです。

機能

• Swell eコマース連携：商品、注文、顧客に関するSwell APIへの完全なアクセス
• デュアルトランスポート対応：AI アシスタントおよびウェブ連携向けのSTDIOとHTTPトランスポート
• 5層アーキテクチャ：CLI、ツール、コントローラー、サービス、ユーティリティを明確に分離
• 型安全性：Zodスキーマ検証を備えた完全なTypeScript実装
• 高度なHTTPクライアント：接続プーリングと再試行ロジックを備えたswell-node SDKを基盤に構築
• 包括的なテスト：Swell APIのモックを使用した単体テストと統合テスト
• 本番環境向けツール：ESLint、Prettier、semantic-release、MCP Inspectorとの連携
• エラー処理：Swell固有のエラーコンテキストを含む、構造化されたエラー処理

Swell eコマース連携

このMCPサーバーは、Swellのeコマースプラットフォームと包括的に連携します。

利用可能なツールとコマンド

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サーバーは、Devkindが開発した、Swellストア向けのエンタープライズグレードのチェックアウトソリューションである**CheckoutJet**を支える高度なSwell連携の一例です。

CheckoutJetは、次の機能でSwellのチェックアウトを強化します。

• 🏢 優れたB2B機能 — 専門的な請求書、Net 30の支払い、卸売価格
• 📦 スマートな配送 — 複数拠点のリアルタイム料金とインテリジェントな注文振り分け
• ⚡ 分割配送 — 複雑なマルチベンダーおよび複数倉庫のフルフィルメントに対応
• 🎨 完全なカスタマイズ — ピクセル単位で調整できる、ブランドに合わせたチェックアウト体験
• 🤖 自動化 — 請求書、PO、注文管理を自動化
• 💰 高度な価格設定 — 動的な割引と段階的な価格設定ロジック

**実績：**Swellの加盟店で50万ユーロ以上の取引を処理し、コンバージョン率を23％改善しました。

Swellのチェックアウトをアップグレードしませんか？15分間のデモを予約

MCP とは？

Model Context Protocol（MCP）は、AI システムを外部ツールやデータソースに安全に接続するためのオープン標準です。このサーバーは MCP 仕様を実装し、AI アシスタントが Swell の e コマースプラットフォームに包括的にアクセスできるようにすることで、インテリジェントなストア管理とカスタマーサービスの自動化を実現します。

はじめに

まず、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. login.swell.store でSwell ダッシュボードにログインします
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 トランスポート

• Server-Sent Events（SSE）を使用する HTTP ベースのトランスポート
• 複数の同時接続とウェブ連携に対応します
• デフォルトではポート 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/）

• 目的：URI 経由でアクセスできるコンテキストデータを提供する MCP リソース（計画中の機能）
• 実装：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 アシスタント向けに包括的な e コマース管理ツールを提供します。以下の一覧は、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 のカスタムアプリケーションとテーマ
• ヘッドレスコマースの実装
• パフォーマンスの最適化と自動化

e コマースビジネスを進化させる準備はできていますか？

テスト戦略

このサーバーには、包括的なテスト基盤が含まれています。

テスト構成

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 呼び出し、またはモック化した 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 開発サービス - カスタムアプリ、テーマ、統合
• ヘッドレス e コマース - API 駆動のストアフロントと体験

今すぐ始めましょう： CheckoutJet のデモを見る | 無料相談を予約 | メール：[email protected] | 世界各地に対応するリモートチーム