# ScanPower MCP Server

A Model Context Protocol (MCP) server that provides access to the ScanPower API for Amazon FBA and e-commerce operations.

## Overview

This MCP server enables you to interact with the ScanPower API through MCP-compatible clients. ScanPower is a platform to sellers and 3PLs manage Amazon FBA operations, purchase orders, outbound shipments, item/box/pallet labeling, and catalog operations.

## Features

- **Flexible Authentication**: Supports both automatic authentication and manual API token passing
- **Token Management**: Automatic token retrieval when not provided, with optional manual token passing
- **Amazon SP-API Integration**: Provides access to Amazon's Selling Partner API through ScanPower
- **FBA Operations**: Manage inbound shipments, packing options, and inventory
- **Prep Billing**: Manage prep matrix, price tiers, and billing
- **Catalog Operations**: Search and manage Amazon catalog items
- **User Management**: Access user accounts and proxy user functionality

## Installation

1. Clone or download this repository
2. Install dependencies:
   ```bash
   npm install
   ```

3. Build the project:
   ```bash
   npm run build
   ```

## Configuration

1. Copy the example environment file:
   ```bash
   cp .env.example .env
   ```

2. Edit `.env` with your ScanPower credentials:
   ```env
   # ScanPower API Configuration
   SCANPOWER_BASE_URL=https://api.scanpower.com
   SCANPOWER_OPENAPI_SPEC=https://unity.scanpower.com/docs/api/scanpower-api-bundled.json

   SCANPOWER_USERNAME=your_username
   SCANPOWER_PASSWORD=your_password
   
   # Optional: Proxy user ID for making calls on behalf of another user
   SCANPOWER_PROXY_USER_ID=
   
   # Amazon SP-API Configuration (for Amazon-specific operations)
   AMAZON_MARKETPLACE_ID=ATVPDKIKX0DER
   AMAZON_ACCESS_KEY_ID=your_access_key
   AMAZON_SECRET_ACCESS_KEY=your_secret_key
   AMAZON_ROLE_ARN=your_role_arn
   ```

## Usage

### Running the Server

```bash
npm start
```

Or for development:
```bash
npm run dev
```

### Available Tools

The server provides the following MCP tools:

#### Authentication & User Management

- **`getUsers`**: Get a list of active users (parent and sub users)
- **`getProxyUsers`**: Get a list of Client Proxy Users
- **`getApiToken`**: All other API calls require the token that this endpoint provides
- **`getAccessToken`**: Get an access token from Amazon with which to make SP-API calls

#### Catalog Operations

- **`searchCatalogItems`**: Search Catalog Items
- **`catalogSearch`**: Catalog Search

#### FBA Inbound Operations

- **`listInboundPlans`**: List InboundPlans
- **`createInboundPlan`**: Create Inbound Plan
- **`getInboundPlan`**: Get Inbound Plan
- **`listInboundPlanBoxes`**: List InboundPlan Boxes
- **`cancelInboundPlan`**: Cancel InboundPlan
- **`listInboundPlanItems`**: List InboundPlan Items
- **`updateInboundPlanName`**: Update InboundPlan Name
- **`listPackingGroupBoxes`**: List PackingGroup Boxes
- **`listPackingGroupItems`**: List PackingGroup Items
- **`setPackingInformation`**: Set Packing Information
- **`listPackingOptions`**: List Packing Options
- **`generatePackingOptions`**: Generate Packing Options
- **`confirmPackingOption`**: Confirm Packing Option
- **`listInboundPlanPallets`**: List InboundPlan Pallets
- **`listPlacementOptions`**: List Placement Options
- **`generatePlacementOptions`**: Generate Placement Options
- **`confirmPlacementOption`**: Confirm Placement Option

#### Shipment Operations

- **`getShipment`**: Get Shipment
- **`listShipmentBoxes`**: List Shipment Boxes
- **`listShipmentContentUpdatePreviews`**: List ShipmentContent UpdatePreviews
- **`generateShipmentContentUpdatePreviews`**: Generate ShipmentContent UpdatePreviews
- **`getShipmentContentUpdatePreview`**: Get ShipmentContent UpdatePreview
- **`confirmShipmentContentUpdatePreview`**: Confirm ShipmentContent UpdatePreview
- **`getDeliveryChallanDocument`**: Get DeliveryChallan Document
- **`listDeliveryWindowOptions`**: List DeliveryWindow Options
- **`generateDeliveryWindowOptions`**: Generate DeliveryWindow Options
- **`confirmDeliveryWindowOptions`**: Confirm DeliveryWindow Options
- **`listShipmentItems`**: List ShipmentItems
- **`updateShipmentName`**: Update Shipment Name
- **`listShipmentPallets`**: List Shipment Pallets
- **`cancelSelfShipAppointment`**: Cancel SelfShip Appointment
- **`getSelfShipAppointmentSlots`**: Get SelfShip Appointment Slots
- **`generateSelfShipAppointmentSlots`**: Generate SelfShip Appointment Slots
- **`scheduleSelfShipAppointment`**: Schedule SelfShip Appointment
- **`updateShipmentSourceAddress`**: Update ShipmentSource Address
- **`updateShipmentTrackingDetails`**: Update Shipment TrackingDetails
- **`listTransportationOptions`**: List Transportation Options
- **`generateTransportationOptions`**: Generate Transportation Options
- **`confirmTransportationOptions`**: Confirm Transportation Options

#### Compliance & Prep Operations

- **`listItemComplianceDetails`**: List ItemCompliance Details
- **`updateItemComplianceDetails`**: Update ItemCompliance Details
- **`createMarketplaceItemLabels`**: Create Marketplace ItemLabels
- **`listPrepDetails`**: List Prep Details
- **`setPrepDetails`**: Set Prep Details
- **`getInboundOperationStatus`**: Get InboundOperation Status
- **`getBillOfLading`**: Get BillOfLading
- **`getLabels`**: Get Labels

#### Inventory & Batch Operations

- **`getInboundPlans`**: Get InboundPlans
- **`createInboundPlanFromBatch`**: Create an inbound plan from the items in the provided batch
- **`submitBoxes`**: Submit Boxes
- **`scoutSearch`**: Wrapper around several SP-API calls for loading product, offers, and pricing data
- **`selectBoxes`**: List boxes for a v1 Amazon batch
- **`insertBox`**: Insert a Box
- **`deleteBox`**: Delete a Box
- **`selectBox`**: Get a Box
- **`updateBox`**: Delete Box
- **`selectBoxItems`**: List BoxItems
- **`insertBoxItem`**: Insert BoxItem
- **`deleteBoxItem`**: Delete BoxItem
- **`updateBoxItem`**: Update BoxItem
- **`selectInventory`**: Select Inventory
- **`selectPallets`**: List Pallets
- **`insertPallet`**: Insert Pallet
- **`getMobileInventory`**: Returns found Inventory and Buylist quantities from the database grouped by Condition
- **`deletePallet`**: Delete Pallet
- **`selectPallet`**: List Pallet
- **`updatePallet`**: Update Pallet

#### Purchase Orders

- **`PurchaseOrders`**: Get a list of Purchase Orders
- **`CreatePurchaseOrder`**: Create a single purchase order
- **`UpdatePurchaseOrder`**: Update a purchase order. This does not change any of the items in the PO
- **`PurchaseOrderItems`**: Get a list of purchase order items
- **`CreatePurchaseOrderItems`**: Add items to a purchase order
- **`UpdatePurchaseOrderItem`**: Update a single purchase order item

#### Batch Operations

- **`Batches`**: Get Batches
- **`CreateBatch`**: Create Batch
- **`UpdateBatch`**: Update Batch
- **`BatchItems`**: Get BatchItems
- **`CreateBatchItems`**: CreateBatchItems
- **`UpdateBatchItemGql`**: Update BatchItem
- **`ImportPurchaseOrderItems`**: Import PurchaseOrderItems
- **`Buylist`**: Get Buylist items
- **`Inventory`**: Get Inventory
- **`UpdateInventoryItems`**: Update InventoryItems
- **`createBuylist`**: Create Buylist items
- **`getPackHistory`**: Get PackHistory

#### Walmart Operations

- **`getWmAccessToken`**: Get Walmart AccessToken
- **`itemSetupByMatch`**: Get ItemSetup by Match
- **`bulkInventoryUpdate`**: Bulk Inventory Update
- **`allFeedStatuses`**: Get All FeedStatuses
- **`retireAnItem`**: Retire an Inventory Item
- **`itemLabel`**: Generate item labels
- **`selectBatches`**: List Batches
- **`insertBatches`**: Insert Batches
- **`selectBatch`**: Get Walmart Batch by ID
- **`updateBatches`**: Update Batches
- **`deleteBatches`**: Delete Batches
- **`selectBatchItems`**: List BatchItems
- **`insertBatchItems`**: Insert BatchItems
- **`updateBatchItems`**: Update BatchItems
- **`updateBatchItem`**: Update BatchItem
- **`deleteBatchItems`**: Delete BatchItems
- **`getInboundShipments`**: Get InboundShipments
- **`createInboundShipment`**: Create InboundShipment
- **`fetchInboundPreview`**: Fetch InboundPreview
- **`updateShipmentQuantities`**: Update Shipment Quantities
- **`updateWmShipmentTrackingDetails`**: Update Walmart Shipment Tracking Details
- **`createCarrierRateQuote`**: Create Carrier RateQuote
- **`selectWmShipments`**: Select Walmart Shipments from the database
- **`selectWmShipment`**: Select a single Walmart Shipment by Id
- **`selectWmBoxes`**: Select Walmart Boxes from the database
- **`insertWmBoxes`**: Insert Walmart Boxes into our database
- **`updateWmBoxes`**: Update Walmart Boxes into our database
- **`selectWmBox`**: Select a single Walmart Box by Id
- **`deleteWmBoxes`**: Delete one or more Walmart Boxes by Id
- **`createInboundShipmentLabel`**: Create InboundShipment Label
- **`printCarrierLabel`**: Print Walmart Carrier Label
- **`getInboundShipmentErrors`**: Get InboundShipment Errors
- **`getInboundShipmentItems`**: Get InboundShipment Items
- **`cancelInboundShipment`**: Cancel InboundShipment

#### Prep Matrix & Billing

- **`selectPrepMatrixProducts`**: Get all Prep Matrix Product mappings
- **`insertPrepMatrixProducts`**: Create multiple Prep Matrix Product mappings
- **`selectPrepMatrixProduct`**: Get a specific Prep Matrix Product mapping by external_id
- **`updatePrepMatrixProducts`**: Update a Prep Matrix Product mapping by external_id
- **`deletePrepMatrixProducts`**: Delete one or more Prep Matrix Product mapping by external_id
- **`selectPrepMatrices`**: Get all Prep Types
- **`insertPrepMatrices`**: Create multiple Prep Type matrices
- **`prepCenterBillingReport`**: Get the billing report for a given time period
- **`prepCenterBillingReportPost`**: Get the billing report for a given time period
- **`selectShipmentPrepMatrices`**: Get shipment-level ad hoc charges
- **`selectShipmentPrepMatricesPost`**: Get shipment-level ad hoc charges
- **`insertShipmentPrepMatrices`**: Add one or more shipment-level ad hoc charges
- **`updateShipmentPrepMatrices`**: Update or delete one or more shipment-level ad hoc charges
- **`selectPrepMatrix`**: Get a specific Prep Type Matrix by ID
- **`updatePrepMatrices`**: Update one or more Prep Type Matrices by ID
- **`deletePrepMatrices`**: Delete one or more Prep Type Matrices by ID

#### Webhooks & Carrier Operations

- **`selectWebHooks`**: List WebHooks
- **`generateWebHookSecretKey`**: Generate WebHook SecretKey
- **`testWebHook`**: Test WebHook
- **`updateWebHook`**: Update WebHook
- **`deleteWebHook`**: Delete WebHook
- **`getCarrierRateQuote`**: Get Carrier RateQuote
- **`confirmCarrierRateQuote`**: Confirm Carrier RateQuote
- **`cancelCarrierRateQuote`**: Cancel Carrier RateQutoe

## Example Usage

### Search for Catalog Items

```json
{
  "tool": "search_catalog_items",
  "arguments": {
    "keywords": "wireless headphones",
    "marketplace_ids": ["ATVPDKIKX0DER"],
    "page_size": 20
  }
}
```

### Using API Token (Optional)

```json
{
  "tool": "search_catalog_items",
  "arguments": {
    "keywords": "wireless headphones",
    "marketplace_ids": ["ATVPDKIKX0DER"],
    "page_size": 20,
    "api_token": "your_api_token_here"
  }
}
```

### List Inbound Plans

```json
{
  "tool": "list_inbound_plans",
  "arguments": {
    "page_size": 10
  }
}
```

### Get Inbound Plan Details

```json
{
  "tool": "get_inbound_plan",
  "arguments": {
    "inbound_plan_id": "your-plan-id-here"
  }
}
```

## Error Handling

The server includes comprehensive error handling for:

- Authentication failures
- API rate limiting
- Invalid parameters
- Network connectivity issues
- Amazon SP-API errors

All errors are returned in a standardized format with descriptive error messages.

## Development

### Project Structure

```
scanpower-mcp-server/
├── src/
│   └── index.ts          # Main server implementation
├── dist/                 # Compiled JavaScript output
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── .env.example          # Environment variables template
└── README.md            # This file
```

### Building

```bash
npm run build
```

### Development Mode

```bash
npm run dev
```

### Watching for Changes

```bash
npm run watch
```

## API Reference

This MCP server is based on the ScanPower API v2.0 specification. For detailed information about the underlying API endpoints and their parameters, refer to the [ScanPower API documentation](https://unity.scanpower.com/docs/api/index.html).

### Authentication

The server uses basic authentication for initial API access and then manages bearer tokens for subsequent requests. Amazon SP-API operations require additional OAuth2-style authentication which is handled automatically.

### Rate Limiting

The server respects ScanPower's rate limiting policies. If you encounter rate limit errors, the server will return appropriate error messages.

## Support

For issues related to:

- **ScanPower API**: Contact [ScanPower Support](mailto:support@scanpower.com)
- **This MCP Server**: Create an issue in this repository
- **MCP Protocol**: Refer to the [MCP documentation](https://modelcontextprotocol.io)

## License

MIT License - see LICENSE file for details.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## Changelog

### v1.0.0
- Initial release
- Support for core ScanPower API operations
- Authentication and token management
- Amazon SP-API integration
- Comprehensive error handling