Logistics Tracker

Name: Logistics Tracker
Rating: 3.5 (1 reviews)
Author: aoyasong

By aoyasong 👁 5 views ▲ 0 votes

OpenClaw MCP Plugin for e-commerce logistics tracking, package monitoring, and delivery prediction

GitHub

Install

npm install
```

Configuration Example

{
  "tracking_number": "SF1234567890",
  "carrier_code": "sf-express",
  "destination_country": "US"
}

README

# Logistics Tracker 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 logistics tracking, monitoring, and anomaly detection for cross-border e-commerce. Fifth core component of the e-commerce plugin suite.

## 🚀 Features

- **Multi-Carrier Tracking**: Support for 快递100, 17TRACK, AfterShip APIs with automatic failover
- **Real-time Status**: Live tracking updates with route visualization
- **Batch Operations**: Track up to 50 packages in a single request
- **Anomaly Detection**: Automatic detection of stalled, delayed, or returned packages
- **Delivery Prediction**: AI-powered delivery time estimation with confidence scores
- **Shipping Estimation**: Cost and transit time estimates for international shipping
- **E-commerce Optimized**: Cross-border logistics scenarios with customs tracking
- **Production Ready**: Two-level caching, rate limiting, webhook support, and health monitoring
- **MCP Protocol**: Fully compatible with OpenClaw's Model Context Protocol

## 🛠️ Tools Provided

### Core Tools (8 Required)

1. **logistics_track_package** - Track a single logistics package with real-time status
2. **logistics_batch_track** - Track multiple packages in a single batch request
3. **logistics_predict_delivery** - Predict delivery time with confidence estimation
4. **logistics_detect_anomalies** - Detect logistics anomalies (stalled, returned, delayed, lost)
5. **logistics_get_carriers** - Get supported logistics carriers for specific countries
6. **logistics_estimate_shipping** - Estimate shipping cost and transit time
7. **logistics_analyze_performance** - Analyze carrier performance metrics
8. **logistics_setup_webhook** - Set up webhook for logistics status updates

## 🏗️ Architecture

### Multi-API Strategy
- **Primary API**: 快递100 (comprehensive China domestic and international coverage)
- **Backup API**: 17TRACK (excellent international tracking support)
- **Optional API**: AfterShip (global carrier support)
- **Smart Failover**: Automatic switching on API failure with intelligent retry

### Caching Strategy
- **Tracking Status**: 2-hour cache (infrequent status changes)
- **Route History**: 24-hour cache (historical data stable)
- **Carrier List**: 7-day cache (rarely changes)
- **Shipping Estimates**: 30-minute cache (moderate volatility)

### Performance Optimization
- **Batch Processing**: Up to 50 packages per request
- **Incremental Updates**: Only check packages with status changes
- **Parallel Requests**: Multiple API calls in parallel
- **Request Deduplication**: Avoid duplicate API calls for same tracking numbers

## 🚦 Quick Start

### 1. Installation

```bash
# Clone the repository
git clone https://github.com/aoyasong/logistics-tracker-plugin.git
cd logistics-tracker-plugin

# Install dependencies
npm install
```

### 2. Configuration

Copy the example environment file and configure your API keys:

```bash
cp .env.example .env
```

Edit `.env` and add at least one logistics API key:

```bash
# Required (at least one provider)
KUAIDI100_API_KEY=your_kuaidi100_api_key_here
KUAIDI100_CUSTOMER=your_customer_id_here

# Optional backups
TRACK17_API_KEY=your_17track_api_key_here
AFTERSHIP_API_KEY=your_aftership_api_key_here
```

### 3. Run the Plugin

```bash
# Development mode
npm run dev

# Production mode
npm start
```

### 4. Test the Plugin

```bash
npm test
```

## 📋 Integration with E-commerce Suite

### With Amazon SP-API Plugin
- Track Amazon order logistics automatically
- Update order status based on tracking events
- Provide customers with real-time tracking information

### With E-commerce DB Plugin
- Store logistics history and status changes
- Analyze logistics performance over time
- Generate shipping cost reports

### With 1688 Data Plugin
- Track supplier shipments from 1688.com
- Monitor factory-to-warehouse logistics
- Estimate arrival times for inventory planning

### With Currency Exchange Plugin
- Convert shipping costs between currencies
- Calculate international shipping costs in local currencies
- Analyze currency impact on logistics expenses

## 🛤️ Supported Logistics Scenarios

### Domestic Shipping (China)
- Express delivery (顺丰, 韵达, 中通, 申通)
- Standard shipping
- Economy shipping for bulk orders

### International Direct Shipping
- DHL, UPS, FedEx for cross-border
- International postal services (USPS, EMS)
- Express air freight

### Overseas Warehouse Shipping
- Local fulfillment from overseas warehouses
- Same-day/next-day delivery in target markets
- Reduced shipping costs and transit times

### Cross-border Logistics Lines
- Specialized routes for e-commerce (e.g., China to US)
- Consolidated shipping for cost savings
- Customs clearance support

## 🔧 API Configuration

### Environment Variables

```bash
# Required API Keys
KUAIDI100_API_KEY=your_kuaidi100_api_key
KUAIDI100_CUSTOMER=your_customer_id

# Optional API Keys
TRACK17_API_KEY=your_17track_api_key
AFTERSHIP_API_KEY=your_aftership_api_key

# Cache Configuration
CACHE_TTL_TRACKING_STATUS=7200       # 2 hours in seconds
CACHE_TTL_ROUTE_HISTORY=86400        # 24 hours
CACHE_TTL_CARRIERS=604800            # 7 days
REDIS_URL=redis://localhost:6379     # Optional Redis

# Rate Limiting
REQUEST_LIMIT_PER_MINUTE=30
BURST_LIMIT=5

# Webhook Configuration
WEBHOOK_SECRET=your_webhook_secret
WEBHOOK_TIMEOUT_MS=5000
```

### Docker Deployment

```bash
# Build the image
docker build -t logistics-tracker-plugin .

# Run with environment variables
docker run -d \
  --name logistics-tracker \
  -e KUAIDI100_API_KEY=your_key \
  -e KUAIDI100_CUSTOMER=your_customer \
  -p 3000:3000 \
  logistics-tracker-plugin
```

## 🧪 Example Usage

### Track a Single Package

```json
{
  "tracking_number": "SF1234567890",
  "carrier_code": "sf-express",
  "destination_country": "US"
}
```

### Batch Track Multiple Packages

```json
{
  "packages": [
    {"tracking_number": "SF1234567890", "carrier_code": "sf-express"},
    {"tracking_number": "YT5678901234", "carrier_code": "yunda"},
    {"tracking_number": "1Z1234567890123456", "carrier_code": "ups"}
  ]
}
```

### Detect Anomalies

```json
{
  "tracking_list": ["SF1234567890", "YT5678901234"],
  "threshold_days": 3,
  "check_types": ["stalled", "delayed"]
}
```

### Get Shipping Estimate

```json
{
  "origin": {"country": "CN", "postal_code": "518000"},
  "destination": {"country": "US", "postal_code": "90210"},
  "package": {
    "weight_kg": 2.5,
    "dimensions_cm": {"length": 30, "width": 20, "height": 15},
    "value_usd": 150
  }
}
```

## 📊 Performance Metrics

| Metric | Target Value | Description |
|--------|--------------|-------------|
| Single Package Query | < 500ms | < 100ms on cache hit |
| Batch Query (50 packages) | < 2s | Parallel API calls |
| API Success Rate | > 98% | With failover |
| Cache Hit Rate | > 70% | For repeated queries |
| Webhook Delivery | < 5s | Status change notification |

## 🔩 Development

### Project Structure

```
logistics-tracker-plugin/
├── src/
│   ├── providers/           # Logistics API providers
│   │   ├── kuaidi100-api.js
│   │   ├── 17track-api.js
│   │   ├── aftership-api.js
│   │   ├── cache-manager.js
│   │   └── provider-manager.js
│   ├── models/             # Data models
│   │   ├── package.js
│   │   ├── carrier.js
│   │   └── event.js
│   ├── analytics/          # Analysis modules
│   │   ├── anomaly-detector.js
│   │   ├── performance-analyzer.js
│   │   └── predictor.js
│   ├── utils/             # Utility functions
│   ├── tools.js           # MCP tool definitions
│   ├── logistics-api.js   # Main API client
│   └── index.js           # Plugin entry point
├── config/                # Configuration
│   ├── carriers.json
│   └── countries.json
├── test/                  # Tests
├── docker/               # Docker files
└── examples/             # Example usage
```

### Running Tests

```bash
# Run all tests
npm test

# Run specific test suite
npm test -- --testNamePattern="tracking"

# Run with coverage
npm test -- --coverage
```

### Code Quality

```bash
# Lint code
npm run lint

# Format code
npm run format
```

## 👥 Contributing

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

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🔗 Links

- [OpenClaw Documentation](https://docs.openclaw.ai)
- [快递100 API Documentation](https://www.kuaidi100.com/openapi/)
- [17TRACK API Documentation](https://17track.net/en/api)
- [AfterShip API Documentation](https://www.aftership.com/docs/api/)

## 🙏 Acknowledgments

- Built as part of the OpenClaw e-commerce plugin suite
- Inspired by real-world cross-border logistics challenges
- Thanks to all API providers for their generous free tiers

tools