Amazon Sp Api

Name: Amazon Sp Api
Rating: 3.5 (1 reviews)
Author: aoyasong

By aoyasong 👁 7 views ▲ 0 votes

OpenClaw MCP Plugin for Amazon Selling Partner API

GitHub

Install

npm install
```

Configuration Example

{
  "plugins": {
    "amazon-sp-api": {
      "command": "node",
      "args": ["/path/to/amazon-sp-api-plugin/src/index.js"],
      "env": {
        "AMAZON_CLIENT_ID": "your-client-id",
        "AMAZON_CLIENT_SECRET": "your-client-secret",
        "AMAZON_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

README

# Amazon SP-API Plugin for OpenClaw

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-green.svg)](https://nodejs.org/)
[![OpenClaw MCP Compatible](https://img.shields.io/badge/OpenClaw-MCP-blue.svg)](https://openclaw.ai)

A production-ready OpenClaw MCP plugin for Amazon Selling Partner API (SP-API) that enables e-commerce automation for Amazon sellers.

## 🚀 Features

- **Complete Amazon SP-API Integration**: Access to pricing, orders, inventory, and reports
- **OAuth2 Token Management**: Automatic token refresh and credential caching
- **Production-Ready**: Rate limiting, retry logic, error handling, and caching
- **MCP Protocol**: Fully compatible with OpenClaw's Model Context Protocol
- **Extensible Design**: Modular architecture for easy feature additions

## 🛠️ Tools Provided

### Core Tools
1. **amazon_get_competitive_pricing** - Get competitive pricing for ASINs
2. **amazon_submit_price_change** - Submit price changes for products
3. **amazon_get_order_reports** - Request and download order reports
4. **amazon_get_auth_status** - Check authentication status
5. **amazon_refresh_token** - Manually refresh OAuth2 token

### Tool Details

#### amazon_get_competitive_pricing
Retrieves competitive pricing information for up to 20 ASINs in a specified marketplace.

**Input Parameters:**
- `asin_list` (required): Array of ASINs (1-20 items)
- `marketplace`: Marketplace ID (default: "US")
- `include_my_price`: Include your own pricing (default: true)
- `include_competitors`: Include competitor data (default: true)

#### amazon_submit_price_change
Submits a price change for a product (ASIN or SKU).

**Input Parameters:**
- `identifier` (required): Product ASIN or SKU
- `identifier_type`: "ASIN" or "SKU" (default: "ASIN")
- `marketplace`: Marketplace ID (default: "US")
- `new_price` (required): New price amount
- `currency`: Currency code (default: "USD")
- `reason`: Reason for price change (optional)

#### amazon_get_order_reports
Requests and downloads order reports from Amazon SP-API.

**Input Parameters:**
- `report_type` (required): Report type identifier
- `start_date` (required): Start date (ISO 8601)
- `end_date` (required): End date (ISO 8601)
- `marketplace_ids`: Array of marketplace IDs
- `format`: Output format: "JSON", "CSV", or "TAB"

## 📦 Installation

### Prerequisites
- Node.js v18+ and npm
- Amazon Seller Central account with SP-API access
- OpenClaw v0.5.0+

### Step 1: Clone the Repository
```bash
git clone https://github.com/aoyasong/amazon-sp-api-plugin.git
cd amazon-sp-api-plugin
```

### Step 2: Install Dependencies
```bash
npm install
```

### Step 3: Configure Environment Variables
```bash
cp .env.example .env
```

Edit the `.env` file with your Amazon SP-API credentials:

```bash
# Get these from Amazon Seller Central
AMAZON_CLIENT_ID=your-lwa-client-id
AMAZON_CLIENT_SECRET=your-lwa-client-secret
AMAZON_REFRESH_TOKEN=your-refresh-token

# Optional settings
AMAZON_REGION=us-west-2
AMAZON_SANDBOX=false
```

### Step 4: Test the Plugin
```bash
npm test
```

## 🔌 OpenClaw Integration

### Method 1: Direct Integration via openclaw.json

Add to your OpenClaw configuration file:

```json
{
  "plugins": {
    "amazon-sp-api": {
      "command": "node",
      "args": ["/path/to/amazon-sp-api-plugin/src/index.js"],
      "env": {
        "AMAZON_CLIENT_ID": "your-client-id",
        "AMAZON_CLIENT_SECRET": "your-client-secret",
        "AMAZON_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}
```

### Method 2: Environment-Based Configuration

Set environment variables and run:

```bash
export AMAZON_CLIENT_ID=your-id
export AMAZON_CLIENT_SECRET=your-secret
export AMAZON_REFRESH_TOKEN=your-token

# Start OpenClaw with the plugin
openclaw agent --plugin amazon-sp-api
```

## 🧪 Testing

Run the test suite:

```bash
npm test
```

Run specific test categories:

```bash
# Unit tests
npm test -- --testPathPattern=unit

# Integration tests (requires valid credentials)
npm test -- --testPathPattern=integration

# All tests with coverage report
npm test -- --coverage
```

## 🏗️ Project Structure

```
amazon-sp-api-plugin/
├── package.json           # Node.js project configuration
├── mcp.json              # MCP tool definitions
├── README.md             # This file
├── .env.example          # Environment variables template
├── src/
│   ├── index.js          # Main entry point (MCP server)
│   ├── tools.js          # Tool definitions and handlers
│   ├── amazon-api.js     # Amazon SP-API wrapper
│   ├── auth.js           # OAuth2 authentication manager
│   └── utils.js          # Utility functions
├── config/
│   └── schemas.js        # Configuration validation schemas
├── test/                 # Test files
├── examples/             # Usage examples
└── docker/               # Docker configuration
```

## 🐳 Docker Deployment

### Build Docker Image
```bash
docker build -t amazon-sp-api-plugin:latest .
```

### Run Container
```bash
docker run -d \
  --name amazon-sp-api-plugin \
  -e AMAZON_CLIENT_ID=your-id \
  -e AMAZON_CLIENT_SECRET=your-secret \
  -e AMAZON_REFRESH_TOKEN=your-token \
  amazon-sp-api-plugin:latest
```

### Docker Compose
```yaml
version: '3.8'
services:
  amazon-sp-api:
    build: .
    environment:
      - AMAZON_CLIENT_ID=${AMAZON_CLIENT_ID}
      - AMAZON_CLIENT_SECRET=${AMAZON_CLIENT_SECRET}
      - AMAZON_REFRESH_TOKEN=${AMAZON_REFRESH_TOKEN}
      - AMAZON_REGION=us-west-2
    volumes:
      - ./cache:/app/cache
```

## 🔧 Development

### Prerequisites for Development
- Amazon SP-API Sandbox credentials (recommended for development)
- Local Redis instance for caching (optional)

### Setting Up Amazon SP-API Access
1. Log in to [Amazon Seller Central](https://sellercentral.amazon.com/)
2. Navigate to Apps & Services > Developer Central
3. Register a new application
4. Note the Client ID, Client Secret, and generate a Refresh Token
5. Configure API permissions based on your needs

### Local Development
```bash
# Install dependencies
npm install

# Set up environment
cp .env.example .env
# Edit .env with sandbox credentials

# Run in development mode
npm run dev

# Run tests
npm test
```

### Adding New Tools
1. Add tool definition in `mcp.json`
2. Add handler in `src/tools.js`
3. Implement API method in `src/amazon-api.js`
4. Add test cases in `test/`
5. Update documentation

## 📝 API Reference

### Authentication Flow
The plugin uses OAuth2 with Refresh Token flow:
1. Initial token obtained via Amazon LWA (Login With Amazon)
2. Refresh token stored in environment variable
3. Access token automatically refreshed before expiry
4. Credentials cached locally in `.amazon-credentials.json`

### Error Handling
- All errors follow standardized format
- Automatic retry for rate limits and token expiry
- Detailed error codes and messages

### Rate Limiting
- Configurable rate limit (default: 0.5 requests/second)
- Exponential backoff for retries
- Request queuing for burst protection

### Caching
- In-memory caching with configurable TTL
- Redis support for distributed caching
- Automatic cache invalidation

## 🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

### Development Guidelines
- Write tests for new functionality
- Follow existing code style
- Update documentation
- Ensure backwards compatibility

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- [Amazon Selling Partner API](https://developer-docs.amazon.com/sp-api/)
- [OpenClaw MCP Protocol](https://openclaw.ai/docs/mcp)
- [Model Context Protocol SDK](https://modelcontextprotocol.io/)

## 📞 Support

- **Issues**: [GitHub Issues](https://github.com/aoyasong/amazon-sp-api-plugin/issues)
- **Documentation**: [Wiki](https://github.com/aoyasong/amazon-sp-api-plugin/wiki)
- **Email**: [email protected]

---

**Note**: This plugin is not officially affiliated with Amazon. Use at your own risk and ensure compliance with Amazon's Terms of Service.

integration