{
  "markdown": "# Swell MCP Server\n\nA Model Context Protocol server that integrates AI assistants with Swell's e-commerce platform. Built on a production-ready TypeScript foundation, it provides comprehensive access to Swell stores for product management, order processing, and customer management through both CLI and MCP tool interfaces.\n\n**Built by [Devkind](https://devkind.com.au/services/swell)** - Official Swell Partners serving businesses globally with cutting-edge e-commerce solutions.\n\n[![NPM Version](https://img.shields.io/npm/v/swell-mcp)](https://www.npmjs.com/package/swell-mcp)\n[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)\n[![Built by Devkind](https://img.shields.io/badge/Built%20by-Devkind-blue)](https://devkind.com.au/services/swell)\n\n## Features\n\n- **Swell E-commerce Integration**: Complete access to Swell's API for products, orders, and customers\n- **Dual Transport Support**: STDIO and HTTP transports for AI assistant and web integration\n- **5-Layer Architecture**: Clean separation between CLI, tools, controllers, services, and utilities\n- **Type Safety**: Full TypeScript implementation with Zod schema validation\n- **Advanced HTTP Client**: Built on swell-node SDK with connection pooling and retry logic\n- **Comprehensive Testing**: Unit and integration tests with Swell API mocking\n- **Production Tooling**: ESLint, Prettier, semantic-release, and MCP Inspector integration\n- **Error Handling**: Structured error handling with Swell-specific error contexts\n\n## Swell E-commerce Integration\n\nThis MCP server provides comprehensive integration with Swell's e-commerce platform:\n\n### Available Tools & Commands\n\n**MCP Tools:**\n\n- `swell_list_products` - List products with filtering and pagination\n- `swell_get_product` - Get detailed product information\n- `swell_search_products` - Search products with multiple criteria\n- `swell_check_inventory` - Check product inventory levels\n- `swell_list_orders` - List orders with filtering options\n- `swell_get_order` - Get detailed order information\n- `swell_update_order_status` - Update order status\n- `swell_list_customers` - List customers with search capabilities\n- `swell_get_customer` - Get detailed customer information\n- `swell_search_customers` - Search customers with multiple criteria\n\n### Features Demonstrated\n\n- **Product Management**: Complete product catalog access with inventory tracking\n- **Order Processing**: Order lifecycle management with status updates\n- **Customer Management**: Customer profiles with order history and analytics\n- **Error Handling**: Structured errors for API failures and validation issues\n- **Response Formatting**: Clean Markdown output with structured data tables\n\n### Configuration Requirements\n\n```bash\n# Required - Swell API credentials\nSWELL_STORE_ID=your-store-id\nSWELL_SECRET_KEY=your-secret-key\n\n# Development\nDEBUG=true                    # Enable detailed logging\nTRANSPORT_MODE=http          # Use HTTP transport\nPORT=3001                    # Custom port\n```\n\n## Need Advanced Swell Checkout?\n\nThis MCP server demonstrates the kind of sophisticated Swell integrations that power **[CheckoutJet](https://checkoutjet.com/)** - an enterprise-grade checkout solution for Swell stores built by [Devkind](https://devkind.com.au/services/swell).\n\n**CheckoutJet** transforms your Swell checkout with:\n\n- **🏢 B2B Excellence** - Professional invoicing, Net 30 payments, and wholesale pricing\n- **📦 Smart Shipping** - Live rates from multiple locations with intelligent order routing\n- **⚡ Split Deliveries** - Handle complex multi-vendor and multi-warehouse fulfillment\n- **🎨 Full Customization** - Pixel-perfect, on-brand checkout experience\n- **🤖 Automation** - Automated invoicing, POs, and order management\n- **💰 Advanced Pricing** - Dynamic discounts and tiered pricing logic\n\n**Proven Results:** Over €500,000 processed for Swell merchants with 23% conversion rate improvements.\n\n**Ready to upgrade your Swell checkout?** [Book a 15-minute demo](https://checkoutjet.com/)\n\n## What is MCP?\n\nModel Context Protocol (MCP) is an open standard for securely connecting AI systems to external tools and data sources. This server implements the MCP specification to provide AI assistants with comprehensive access to Swell's e-commerce platform, enabling intelligent store management and customer service automation.\n\n## Getting Started\n\nFirst, install the Swell MCP server with your AI assistant or MCP client.\n\n### Requirements\n\n- Node.js 18 or newer\n- VS Code, Cursor, Windsurf, Claude Desktop, or any other MCP client\n- Swell store credentials (Store ID and Secret Key)\n\n**Standard config** works in most MCP clients:\n\n```json\n{\n\t\"mcpServers\": {\n\t\t\"swell-mcp\": {\n\t\t\t\"command\": \"npx\",\n\t\t\t\"args\": [\"swell-mcp\"],\n\t\t\t\"env\": {\n\t\t\t\t\"DEBUG\": \"false\",\n\t\t\t\t\"SWELL_STORE_ID\": \"your_store_id\",\n\t\t\t\t\"SWELL_SECRET_KEY\": \"your_private_token\"\n\t\t\t},\n\t\t\t\"disabled\": false\n\t\t}\n\t}\n}\n```\n\n<details>\n<summary>Claude Desktop</summary>\n\nFollow the MCP install [guide](https://modelcontextprotocol.io/quickstart/user), use the standard config above.\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n\t\"mcpServers\": {\n\t\t\"swell-mcp\": {\n\t\t\t\"command\": \"npx\",\n\t\t\t\"args\": [\"swell-mcp\"],\n\t\t\t\"env\": {\n\t\t\t\t\"SWELL_STORE_ID\": \"your_store_id\",\n\t\t\t\t\"SWELL_SECRET_KEY\": \"your_private_token\"\n\t\t\t}\n\t\t}\n\t}\n}\n```\n\n</details>\n\n<details>\n<summary>Cursor</summary>\n\n#### Click the button to install:\n\n[<img src=\"https://cursor.com/deeplink/mcp-install-dark.svg\" alt=\"Install in Cursor\">](https://cursor.com/en/install-mcp?name=Swell%20MCP&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJzd2VsbC1tY3AiXSwiZW52Ijp7IlNXRUxMX1NUT1JFX0lEIjoieW91cl9zdG9yZV9pZCIsIlNXRUxMX1NFQ1JFVF9LRVkiOiJ5b3VyX3ByaXZhdGVfdG9rZW4ifX0%3D)\n\n#### Or install manually:\n\nGo to `Cursor Settings` -> `MCP` -> `Add new MCP Server`. Name it \"Swell MCP\", use `command` type with the command `npx swell-mcp`. Add your Swell credentials in the environment variables section.\n\n</details>\n\n<details>\n<summary>VS Code</summary>\n\nFollow the MCP install [guide](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server), use the standard config above. You can also install the Swell MCP server using the VS Code CLI:\n\n```bash\n# For VS Code\ncode --add-mcp '{\"name\":\"swell-mcp\",\"command\":\"npx\",\"args\":[\"swell-mcp\"],\"env\":{\"SWELL_STORE_ID\":\"your_store_id\",\"SWELL_SECRET_KEY\":\"your_private_token\"}}'\n```\n\nAfter installation, the Swell MCP server will be available for use with your GitHub Copilot agent in VS Code.\n\n</details>\n\n<details>\n<summary>Windsurf</summary>\n\nFollow Windsurf MCP [documentation](https://docs.windsurf.com/windsurf/cascade/mcp). Use the standard config above.\n\nAdd to your MCP configuration:\n\n```json\n{\n\t\"mcpServers\": {\n\t\t\"swell-mcp\": {\n\t\t\t\"command\": \"npx\",\n\t\t\t\"args\": [\"swell-mcp\"],\n\t\t\t\"env\": {\n\t\t\t\t\"SWELL_STORE_ID\": \"your_store_id\",\n\t\t\t\t\"SWELL_SECRET_KEY\": \"your_private_token\"\n\t\t\t}\n\t\t}\n\t}\n}\n```\n\n</details>\n\n<details>\n<summary>Goose</summary>\n\nGo to `Advanced settings` -> `Extensions` -> `Add custom extension`. Name it \"Swell MCP\", use type `STDIO`, and set the `command` to `npx swell-mcp`. Add your Swell credentials as environment variables. Click \"Add Extension\".\n\n</details>\n\n<details>\n<summary>LM Studio</summary>\n\nGo to `Program` in the right sidebar -> `Install` -> `Edit mcp.json`. Use the standard config above with your Swell credentials.\n\n</details>\n\n<details>\n<summary>Warp</summary>\n\nGo to `Settings` -> `AI` -> `Manage MCP Servers` -> `+ Add` to [add an MCP Server](https://docs.warp.dev/knowledge-and-collaboration/mcp#adding-an-mcp-server). Use the standard config above.\n\nAlternatively, use the slash command `/add-mcp` in the Warp prompt and paste the standard config from above.\n\n</details>\n\n### Configuration\n\n#### Getting Your Swell Credentials\n\n1. **Log into your Swell dashboard** at [login.swell.store](https://login.swell.store/admin/)\n2. **Navigate to Developer → API Keys**\n3. **Copy your Store ID** (this is your `SWELL_STORE_ID`)\n4. **Copy your Secret Key** (this is your `SWELL_SECRET_KEY` - use the backend/admin key, not the public key)\n\n#### Environment Variables\n\n- `SWELL_STORE_ID`: Your Swell store identifier (required)\n- `SWELL_SECRET_KEY`: Your Swell secret/private key (required)\n- `DEBUG`: Set to \"true\" to enable debug mode with raw JSON responses (optional)\n\n#### Example Configuration\n\n```json\n{\n\t\"mcpServers\": {\n\t\t\"swell-mcp\": {\n\t\t\t\"command\": \"npx\",\n\t\t\t\"args\": [\"swell-mcp\"],\n\t\t\t\"env\": {\n\t\t\t\t\"DEBUG\": \"false\",\n\t\t\t\t\"SWELL_STORE_ID\": \"my-awesome-store\",\n\t\t\t\t\"SWELL_SECRET_KEY\": \"sk_live_abc123def456...\"\n\t\t\t},\n\t\t\t\"disabled\": false\n\t\t}\n\t}\n}\n```\n\n## Usage\n\nOnce installed in your MCP client (see [Getting Started](#getting-started) above), you can use the Swell MCP tools directly through your AI assistant:\n\n### Example Interactions\n\n```\n\"List my active products\"\n→ Uses swell_list_products with active=true\n\n\"Show me pending orders from this week\"\n→ Uses swell_list_orders with status=pending and date filtering\n\n\"Update customer John Doe's email to john@example.com\"\n→ Uses swell_update_customer to modify customer information\n\n\"Check inventory for product ID abc123\"\n→ Uses swell_check_inventory for stock levels\n```\n\n### Debug Mode\n\nEnable debug mode to see raw JSON responses instead of formatted output:\n\n```json\n{\n\t\"env\": {\n\t\t\"DEBUG\": \"true\",\n\t\t\"SWELL_STORE_ID\": \"your_store_id\",\n\t\t\"SWELL_SECRET_KEY\": \"your_private_token\"\n\t}\n}\n```\n\n## Transport Modes\n\n### STDIO Transport\n\n- JSON-RPC communication via stdin/stdout\n- Used by Claude Desktop, Cursor AI, and other local AI assistants\n- Run with: `TRANSPORT_MODE=stdio node dist/index.js`\n\n### Streamable HTTP Transport\n\n- HTTP-based transport with Server-Sent Events (SSE)\n- Supports multiple concurrent connections and web integrations\n- Runs on port 3000 by default (configurable via `PORT` env var)\n- MCP Endpoint: `http://localhost:3000/mcp`\n- Health Check: `http://localhost:3000/` → Returns server version\n- Run with: `TRANSPORT_MODE=http node dist/index.js`\n\n## Architecture Overview\n\n<details>\n<summary><b>Project Structure (Click to expand)</b></summary>\n\n```\nsrc/\n├── cli/                    # Command-line interfaces\n│   └── index.ts            # CLI entry point with Commander setup\n├── controllers/            # Business logic orchestration\n│   ├── swell.products.controller.ts    # Product management logic\n│   ├── swell.products.formatter.ts     # Product response formatting\n│   ├── swell.orders.controller.ts      # Order management logic\n│   ├── swell.orders.formatter.ts       # Order response formatting\n│   ├── swell.customers.controller.ts   # Customer management logic\n│   └── swell.customers.formatter.ts    # Customer response formatting\n├── services/               # External API interactions\n│   ├── swell.products.service.ts       # Swell products API service\n│   ├── swell.products.types.ts         # Product type definitions\n│   ├── swell.orders.service.ts         # Swell orders API service\n│   ├── swell.orders.types.ts           # Order type definitions\n│   ├── swell.customers.service.ts      # Swell customers API service\n│   └── swell.customers.types.ts        # Customer type definitions\n├── tools/                  # MCP tool definitions (AI interface)\n│   ├── swell.products.tool.ts          # Product management tools\n│   ├── swell.orders.tool.ts            # Order management tools\n│   └── swell.customers.tool.ts         # Customer management tools\n├── types/                  # Global type definitions\n│   └── common.types.ts     # Shared interfaces (ControllerResponse, etc.)\n├── utils/                  # Shared utilities\n│   ├── logger.util.ts      # Contextual logging system\n│   ├── error.util.ts       # MCP-specific error formatting\n│   ├── error-handler.util.ts # Error handling utilities\n│   ├── config.util.ts      # Environment configuration\n│   ├── constants.util.ts   # Version and package constants\n│   ├── formatter.util.ts   # Markdown formatting\n│   ├── swell-client.util.ts # Swell SDK client wrapper\n│   └── transport.util.ts   # HTTP transport utilities\n└── index.ts                # Server entry point (dual transport)\n```\n\n</details>\n\n## 5-Layer Architecture\n\nThe server follows a clean, layered architecture that promotes maintainability and clear separation of concerns:\n\n### 1. CLI Layer (`src/cli/`)\n\n- **Purpose**: Command-line interfaces for direct tool usage and testing\n- **Implementation**: Commander-based argument parsing with contextual error handling\n- **Example**: `list-products --active --category electronics`\n- **Pattern**: Register commands → Parse arguments → Call controllers → Handle errors\n\n### 2. Tools Layer (`src/tools/`)\n\n- **Purpose**: MCP tool definitions that AI assistants can invoke\n- **Implementation**: Zod schema validation with structured responses\n- **Example**: `swell_list_products` tool with filtering and pagination options\n- **Pattern**: Define schema → Validate args → Call controller → Format MCP response\n\n### 3. Resources Layer (`src/resources/`)\n\n- **Purpose**: MCP resources providing contextual data accessible via URIs (planned feature)\n- **Implementation**: Resource handlers that respond to URI-based requests\n- **Example**: `swell://products/123` resource providing product details\n- **Pattern**: Register URI patterns → Parse requests → Return formatted content\n\n### 4. Controllers Layer (`src/controllers/`)\n\n- **Purpose**: Business logic orchestration with comprehensive error handling\n- **Implementation**: Options validation, fallback logic, response formatting\n- **Example**: Product management with inventory tracking, order processing with status updates\n- **Pattern**: Validate inputs → Apply defaults → Call services → Format responses\n\n### 5. Services Layer (`src/services/`)\n\n- **Purpose**: Direct external API interactions with minimal business logic\n- **Implementation**: HTTP transport utilities with structured error handling\n- **Example**: Swell API calls with authentication and data validation\n- **Pattern**: Build requests → Make API calls → Validate responses → Return raw data\n\n### 6. Utils Layer (`src/utils/`)\n\n- **Purpose**: Shared functionality across all layers\n- **Key Components**:\n    - `logger.util.ts`: Contextual logging (file:method context)\n    - `error.util.ts`: MCP-specific error formatting\n    - `transport.util.ts`: HTTP/API utilities with retry logic\n    - `config.util.ts`: Environment configuration management\n\n## Development Setup\n\n**For developers who want to contribute or modify the server:**\n\n### Prerequisites\n\n- **Node.js** (>=18.x): [Download](https://nodejs.org/)\n- **Git**: For version control\n\n### Quick Start\n\n```bash\n# Clone the repository\ngit clone https://github.com/devkindhq/swell-mcp.git\ncd swell-mcp\n\n# Install dependencies\nnpm install\n\n# Configure your Swell credentials\ncp .env.example .env\n# Edit .env and add your SWELL_STORE_ID and SWELL_SECRET_KEY\n\n# Build the project\nnpm run build\n\n# Run in different modes:\n\n# 1. STDIO Transport - For AI assistant integration (Claude Desktop, Cursor)\nnpm run mcp:stdio\n\n# 2. HTTP Transport - For web-based integrations\nnpm run mcp:http\n\n# 3. Development with MCP Inspector\nnpm run mcp:inspect                         # Auto-opens browser with debugging UI\n```\n\n### Development Scripts\n\n```bash\n# Build and Clean\nnpm run build               # Build TypeScript to dist/\nnpm run clean               # Remove dist/ and coverage/\nnpm run prepare             # Build + ensure executable permissions (for npm publish)\n\n# CLI Testing (coming soon)\n# npm run cli -- list-products --active                   # List active products\n# npm run cli -- get-product <product-id>                 # Get product details\n# npm run cli -- list-orders --status pending             # List pending orders\n\n# MCP Server Modes\nnpm run mcp:stdio           # STDIO transport for AI assistants\nnpm run mcp:http            # HTTP transport on port 3000\nnpm run mcp:inspect         # HTTP + auto-open MCP Inspector\n\n# Development with Debugging\nnpm run dev:stdio           # STDIO with MCP Inspector integration\nnpm run dev:http            # HTTP with debug logging enabled\n\n# Testing\nnpm test                    # Run all tests (Jest)\nnpm run test:coverage       # Generate coverage report\nnpm run test:cli            # Run CLI-specific tests\n\n# Code Quality\nnpm run lint                # ESLint with TypeScript rules\nnpm run format              # Prettier formatting\nnpm run update:deps         # Update dependencies\n```\n\n### Environment Variables\n\n#### Core Configuration\n\n- `TRANSPORT_MODE`: Transport mode (`stdio` | `http`, default: `stdio`)\n- `PORT`: HTTP server port (default: `3000`)\n- `DEBUG`: Enable debug logging (`true` | `false`, default: `false`)\n\n#### Swell API Configuration\n\n- `SWELL_STORE_ID`: Your Swell store ID (required)\n- `SWELL_SECRET_KEY`: Your Swell secret key (required)\n\n#### Example `.env` File\n\n```bash\n# Basic configuration\nTRANSPORT_MODE=http\nPORT=3001\nDEBUG=true\n\n# Swell API credentials (required)\nSWELL_STORE_ID=your-store-id\nSWELL_SECRET_KEY=your-secret-key\n```\n\n### Debugging Tools\n\n- **MCP Inspector**: Visual tool for testing your MCP tools\n    - Run server with `npm run mcp:inspect`\n    - Open the URL shown in terminal\n    - Test your tools interactively\n\n- **Debug Logging**: Enable with `DEBUG=true` environment variable\n\n<details>\n<summary><b>Configuration (Click to expand)</b></summary>\n\nCreate `~/.mcp/configs.json`:\n\n```json\n{\n\t\"swell-mcp\": {\n\t\t\"environments\": {\n\t\t\t\"DEBUG\": \"true\",\n\t\t\t\"TRANSPORT_MODE\": \"http\",\n\t\t\t\"PORT\": \"3000\",\n\t\t\t\"SWELL_STORE_ID\": \"your-store-id\",\n\t\t\t\"SWELL_SECRET_KEY\": \"your-secret-key\"\n\t\t}\n\t}\n}\n```\n\n</details>\n\n## Available Tools\n\nThe Swell MCP server provides comprehensive e-commerce management tools for AI assistants. The list below matches the tool names and parameter schemas implemented under `src/tools/`.\n\n<details>\n<summary><b>Product Management</b></summary>\n\n- **swell_list_products**\n  - Description: List products with filtering and pagination\n  - Parameters: `page`, `limit`, `active`, `category`, `tags`, `sort`, `expand`\n\n- **swell_get_product**\n  - Description: Get detailed product information\n  - Parameters: `productId`, `expand`\n\n- **swell_search_products**\n  - Description: Search products with text queries and optional filters\n  - Parameters: `query`, `page`, `limit`, `active`, `category`, `tags`, `sort`, `expand`\n\n- **swell_check_stock**\n  - Description: Check current stock levels and stock status for a product\n  - Parameters: `productId`, `includeVariants` (default: true)\n\n- **swell_update_product**\n  - Description: Update product metadata and attributes (name, description, SEO, tags, categories, attributes, active, sku, etc.)\n  - Parameters: `productId` plus any editable product fields\n\n- **swell_update_product_stock**\n  - Description: Adjust stock levels or update stock tracking settings\n  - Parameters: `productId`, `quantity`, `reason`, `reasonMessage`, `variantId`, `orderId`\n\n- **swell_update_product_pricing**\n  - Description: Update product pricing (regular price, sale price, currency)\n  - Parameters: `productId`, `price`, `salePrice`, `currency`\n\n</details>\n\n<details>\n<summary><b>Order Management</b></summary>\n\n- **swell_list_orders**\n  - Description: List orders with filtering options\n  - Parameters: `page`, `limit`, `status`, `customerId`, `dateFrom`, `dateTo`, `sort`, `expand`\n\n- **swell_get_order**\n  - Description: Get detailed order information\n  - Parameters: `orderId`, `expand`\n\n- **swell_update_order_status**\n  - Description: Update the status of an order (with optional notes)\n  - Parameters: `orderId`, `status`, `notes`\n\n</details>\n\n<details>\n<summary><b>Customer Management</b></summary>\n\n- **swell_list_customers**\n  - Description: List customers with search and filtering options\n  - Parameters: `page`, `limit`, `search`, `email`, `dateFrom`, `dateTo`, `sort`, `expand`\n\n- **swell_get_customer**\n  - Description: Get detailed customer information (profile + optional order history)\n  - Parameters: `customerId`, `expand`, `includeOrderHistory`\n\n- **swell_search_customers**\n  - Description: Search customers using text queries (name, email, phone)\n  - Parameters: `query`, `page`, `limit`, `dateFrom`, `dateTo`, `sort`, `expand`\n\n- **swell_update_customer**\n  - Description: Update customer records (name, email, phone, tags, groups, marketing opt-ins, notes)\n  - Parameters: `customerId` plus editable customer fields\n\n</details>\n\n## Extending the Server\n\nThis server is built with a modular architecture that makes it easy to add new Swell API integrations or custom business logic. The existing Swell tools (products, orders, customers) serve as examples for implementing additional functionality.\n\nFor detailed implementation patterns, see the existing controllers, services, and tools in the codebase.\n\n## Standalone Usage\n\nIf you want to run the server independently (not through an MCP client):\n\n### Global Installation\n\n```bash\nnpm install -g swell-mcp\n```\n\n### Direct Usage\n\n```bash\n# Set your credentials\nexport SWELL_STORE_ID=your-store-id\nexport SWELL_SECRET_KEY=your-secret-key\n\n# Run the server\nswell-mcp\n```\n\n### HTTP Mode\n\n```bash\n# Run with HTTP transport on port 3000\nTRANSPORT_MODE=http swell-mcp\n\n# Custom port\nPORT=8080 TRANSPORT_MODE=http swell-mcp\n```\n\n---\n\n## 🚀 Take Your Swell Store Further\n\nImpressed by this MCP server's capabilities? This is just a glimpse of what's possible with expert Swell development.\n\n### � **CheckoutJet - Enterprise Swell Checkout**\n\nTransform your Swell store with our battle-tested checkout solution:\n\n- **B2B Powerhouse** - Professional invoicing, Net 30 payments, wholesale pricing\n- **Smart Shipping** - Live rates from multiple locations with intelligent routing\n- **Split Deliveries** - Complex multi-vendor and multi-warehouse fulfillment\n- **Full Customization** - Pixel-perfect, on-brand checkout experience\n- **Proven Results** - €500,000+ processed, 23% conversion improvements\n\n[**See CheckoutJet in Action →**](https://checkoutjet.com/)\n\n### 🤖 **AI & Custom Development**\n\n- AI-powered integrations like this MCP server\n- Custom Swell applications and themes\n- Headless commerce implementations\n- Performance optimization and automation\n\n**Ready to transform your e-commerce business?**\n\n[![See CheckoutJet Demo](https://img.shields.io/badge/See%20CheckoutJet%20Demo-15%20Minutes-brightgreen?style=for-the-badge)](https://checkoutjet.com/)\n\n## Testing Strategy\n\nThe server includes comprehensive testing infrastructure:\n\n### Test Structure\n\n```text\ntests/               # Not present - tests are in src/\nsrc/\n├── **/*.test.ts     # Co-located with source files\n├── utils/           # Utility function tests\n├── controllers/     # Business logic tests\n├── services/        # API integration tests\n└── cli/             # CLI command tests\n```\n\n### Testing Best Practices\n\n- **Unit Tests**: Test utilities and pure functions (`*.util.test.ts`)\n- **Controller Tests**: Test business logic with mocked service calls\n- **Service Tests**: Test API integration with real/mocked HTTP calls\n- **CLI Tests**: Test command parsing and execution\n- **Test Environment Detection**: Automatic test mode handling in controllers\n\n### Running Tests\n\n```bash\nnpm test                    # Run all tests\nnpm run test:coverage       # Generate coverage report\nnpm run test:cli           # CLI-specific tests only\n```\n\n### Coverage Goals\n\n- Target: >80% test coverage\n- Focus on business logic (controllers) and utilities\n- Mock external services appropriately\n\n## License\n\n[ISC License](https://opensource.org/licenses/ISC)\n\n## Resources & Documentation\n\n### MCP Protocol Resources\n\n- [MCP Specification](https://modelcontextprotocol.io/specification/2025-06-18)\n- [MCP SDK Documentation](https://github.com/modelcontextprotocol/sdk)\n- [MCP Inspector](https://github.com/modelcontextprotocol/inspector) - Visual debugging tool\n\n### Implementation References\n\n- [Anthropic MCP Announcement](https://www.anthropic.com/news/model-context-protocol)\n- [Awesome MCP Servers](https://github.com/wong2/awesome-mcp-servers) - Community examples\n- [TypeScript Documentation](https://www.typescriptlang.org/docs/)\n\n### Swell Resources\n\n- [Swell Documentation](https://developers.swell.is/) - Official API documentation\n- [Swell Node SDK](https://github.com/swellstores/swell-node) - The underlying SDK used by this server\n\n### Professional Swell Services\n\n**Looking for expert Swell development?** [Devkind](https://devkind.com.au/services/swell) is an official Swell partner serving businesses globally with our remote team, specializing in:\n\n- **[CheckoutJet](https://checkoutjet.com/)** - Enterprise checkout solution with B2B, shipping automation, and split deliveries\n- **[Swell Development Services](https://devkind.com.au/services/swell)** - Custom apps, themes, and integrations\n- **[Headless E-commerce](https://devkind.com.au/services/headless-ecommerce)** - API-driven storefronts and experiences\n\n**Get Started:** [See CheckoutJet Demo](https://checkoutjet.com/) | [Book FREE consultation](https://devkind.com.au/services/swell) | Email: [hello@devkind.com.au](mailto:hello@devkind.com.au) | **Global Remote Team**\n",
  "bytes": 25136,
  "sha": "412f21ce5a23df9d3a6f4eb6fab66f6f6c23657e58897e443bbdc149c2f648a5",
  "repo_slug": "devkindhq/swell-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_devkindhq_swell_d05fface/readme"
}