# eBay Listing Automation Plugin for Claude Code

A complete Claude Code plugin that automates your eBay listing workflow with AI-powered image analysis, pricing research, and fulfillment management.

## Features

### 🤖 Specialized AI Agents
- **Listing Creator** - End-to-end listing creation from photos to publication
- **Price Researcher** - Market analysis and competitive pricing strategies
- **Image Analyzer** - Product identification and condition assessment
- **Fulfillment Manager** - Order processing, shipping, and feedback automation

### 📝 Slash Commands (9 commands)
- `/ebay-auth` - One-time OAuth authentication
- `/ebay-analyze [folder]` - AI-powered product analysis
- `/ebay-draft [folder]` - Generate SEO-optimized draft listings
- `/ebay-publish [offer-id]` - Publish drafts to live eBay
- `/ebay-orders` - View and manage orders
- `/ebay-ship [order-id]` - Process shipping with tracking
- `/ebay-feedback [item-id] [tx-id]` - Leave buyer feedback
- `/ebay-policies` - View seller policies
- `/ebay-status` - Health check and connection status

### 🔗 MCP Integration
Direct access to eBay APIs through 10 MCP tools:
- Inventory management (create, update, delete)
- Offer creation and publishing
- Visual search and keyword search
- Order management and fulfillment
- Shipping label generation
- Feedback management

### ⚡ Automation Hooks
- **SessionStart** - Verify eBay connection on startup
- **PostToolUse** - Log listing activity and notify on publish
- **UserPromptSubmit** - Suggest workflow improvements

## Installation

### Prerequisites

- Claude Code installed on your machine
- Bun runtime (for MCP server)
- eBay Developer account with API credentials

### Method 1: Install from Marketplace (Recommended)

Once published to a Claude Code marketplace:

```bash
# Start Claude Code
claude

# Add the eBay tools marketplace
/plugin marketplace add https://github.com/jbwashington/ebay-mcp

# Install the plugin
/plugin install ebay-listing-automation@ebay-tools

# Select "Install now" when prompted
# Restart Claude Code to activate the plugin
```

### Method 2: Install from Local Directory (Development)

For testing or development:

```bash
# Clone this repository to your local machine
git clone https://github.com/jbwashington/ebay-mcp.git
cd ebay-mcp

# Install dependencies
bun install

# Add as a local marketplace in Claude Code
claude

# In Claude Code, add local marketplace
/plugin marketplace add /full/path/to/ebay-mcp

# Install the plugin
/plugin install ebay-listing-automation@ebay-tools
```

### Method 3: Manual Installation (Advanced)

For direct installation without marketplace:

```bash
# Copy plugin to Claude Code plugins directory
mkdir -p ~/.claude/plugins
cp -r ebay-mcp ~/.claude/plugins/ebay-listing-automation

# Install dependencies
cd ~/.claude/plugins/ebay-listing-automation
bun install

# Restart Claude Code
```

### Post-Installation Setup

After installing via any method:

1. **Configure environment variables:**
   ```bash
   cd ~/.claude/plugins/ebay-listing-automation
   cp .env.example .env.local
   # Edit .env.local with your eBay credentials
   ```

2. **Authenticate with eBay:**
   ```bash
   /ebay-auth
   # Browser opens, authorize the application
   ```

3. **Verify installation:**
   ```bash
   /ebay-status
   /help  # Check that eBay commands appear
   /agents  # Verify eBay agents are loaded
   ```

The plugin will automatically:
- Add the eBay MCP server with 12 API tools
- Register 10 slash commands
- Load 5 specialized AI agents
- Enable 4 automation hooks

### Verify Your Installation

Check that these components are active:

```bash
# Commands should show:
/ebay-auth, /ebay-analyze, /ebay-draft, /ebay-publish, /ebay-orders,
/ebay-ship, /ebay-feedback, /ebay-policies, /ebay-status, /ebay-fraud-analysis

# Agents should show:
- Listing Creator
- Price Researcher
- Image Analyzer
- Fulfillment Manager
- Fraud Analyst

# Test MCP connection:
/ebay-status
```

## Quick Start

### 1. First-Time Setup (5 minutes)

1. **Get eBay Developer Credentials**
   - Visit https://developer.ebay.com/my/keys
   - Create a sandbox keyset
   - Copy: Client ID, Client Secret, Dev ID

2. **Configure Environment**
   ```bash
   # Edit .env.local
   EBAY_API_CLIENT=your-app-id
   EBAY_API_SECRET=your-cert-id
   EBAY_DEV_ID=your-dev-id
   EBAY_ENV=sandbox
   ```

3. **Authenticate**
   ```bash
   /ebay-auth
   # Browser opens, click "Agree", token saved automatically
   ```

4. **Set Up Seller Policies**
   - Visit https://www.ebay.com/sh/policies
   - Create: Payment, Return, Fulfillment policies

5. **Verify Connection**
   ```bash
   /ebay-status
   ```

### 2. Create Your First Listing

```bash
# Organize photos in a folder
mkdir -p items/nike-jordan-1
# Add 8-12 photos to the folder

# Let Claude analyze and create listing
/ebay-analyze items/nike-jordan-1
/ebay-draft items/nike-jordan-1
/ebay-publish [offer-id-from-previous-step]
```

### 3. Use Specialized Agents

Claude can proactively invoke agents based on your needs:

```
"Help me list these Nike shoes"
→ Listing Creator agent handles everything

"What should I price this at?"
→ Price Researcher agent analyzes market

"What product is this?"
→ Image Analyzer agent identifies from photos

"I need to ship these orders"
→ Fulfillment Manager agent processes shipping
```

Or manually invoke:
```bash
/agents
# Select an agent from the list
```

## Workflow

### Complete Listing Process

```mermaid
graph TD
    A[Take Photos] --> B[Organize in Folder]
    B --> C[/ebay-analyze]
    C --> D[AI Identifies Product]
    D --> E[Price Research]
    E --> F[/ebay-draft]
    F --> G[Review Draft]
    G --> H[/ebay-publish]
    H --> I[Package Item]
    I --> J[Wait for Sale]
    J --> K[/ebay-ship]
    K --> L[Wait for Delivery]
    L --> M[/ebay-feedback]
```

### Daily Order Management

```bash
# Morning: Check new orders
/ebay-orders

# Ship all pending orders
# For each order, run:
/ebay-ship [order-id]

# Evening: Leave feedback for delivered orders
/ebay-feedback [item-id] [transaction-id]
```

### Batch Listing

```bash
# Create multiple listings efficiently
for item in items/*; do
  /ebay-analyze "$item"
  /ebay-draft "$item"
done

# Review all drafts, then publish
/ebay-publish [offer-id-1]
/ebay-publish [offer-id-2]
/ebay-publish [offer-id-3]
```

## Plugin Components

### Agents (`agents/`)
Four specialized agents for different aspects of eBay selling:
- `listing-creator.md` - Complete listing workflow
- `price-researcher.md` - Market analysis and pricing
- `image-analyzer.md` - Product identification
- `fulfillment-manager.md` - Order processing

### Commands (`commands/`)
Nine slash commands for manual workflow control:
- Authentication, analysis, drafting, publishing
- Order management, shipping, feedback
- Policy checking, status verification

### Hooks (`hooks/hooks.json`)
Automated event handlers:
- Session start checks
- Activity logging
- Publish notifications
- Workflow suggestions

### MCP Server (`src/mcp-server/`)
Full eBay API integration:
- OAuth token management (auto-refresh)
- Inventory API wrapper
- Browse API (search)
- Fulfillment API (shipping)
- Feedback API

## Time Savings

| Task | Manual | Automated | Saved |
|------|--------|-----------|-------|
| Product identification | 10-15 min | 30 sec | ~14 min |
| Price research | 5-10 min | 30 sec | ~9 min |
| Title/description | 5-10 min | 10 sec | ~9 min |
| Item Specifics | 3-5 min | 5 sec | ~4 min |
| Draft creation | 5 min | 10 sec | ~4 min |
| Publishing | 2 min | 5 sec | ~1 min |
| **Per Listing Total** | **30-47 min** | **2 min** | **~40 min** |

## Going to Production

When ready for real listings:

1. **Get Production Credentials**
   - Same process as sandbox at developer.ebay.com
   - Use production keyset

2. **Configure Production Environment**
   ```bash
   # Create .env.production.local
   EBAY_API_CLIENT=your-prod-client-id
   EBAY_API_SECRET=your-prod-secret
   EBAY_DEV_ID=your-dev-id
   EBAY_ENV=production
   ```

3. **Authenticate for Production**
   ```bash
   EBAY_ENV=production bun run auth
   ```

4. **Use Production Mode**
   ```bash
   export EBAY_ENV=production
   # Or set in your shell profile
   ```

## Advanced Features

### Custom Templates
Create listing templates for your most common items:
```bash
# In your CLAUDE.md or project memory
"For Nike sneakers, always include:
- Official colorway name
- Release year
- Box condition
- Include '100% Authentic' in description"
```

### Batch Operations
Process multiple items in one session using agents:
```
"I have 10 items to list, all in the items/ folder.
Process them in batch and create drafts for all."
```

### Price Monitoring
Use the Price Researcher agent to track market changes:
```
"Check if prices have changed for Nike Jordan 1 Chicago size 10"
```

### Custom Hooks
Add your own automation in `hooks/hooks.json`:
```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "ebay_create_offer",
        "hooks": [{
          "type": "command",
          "command": "./scripts/custom-validation.sh"
        }]
      }
    ]
  }
}
```

## Troubleshooting

### Plugin Not Loading
```bash
# Check plugin is in correct location
ls -la ~/.claude/plugins/ebay-listing-automation/.claude-plugin/

# Verify plugin.json is valid
cat ~/.claude/plugins/ebay-listing-automation/.claude-plugin/plugin.json | jq .

# Restart Claude Code with debug
claude --debug
```

### MCP Server Not Connecting
```bash
# Check status
/ebay-status

# Verify credentials
cat .env.local

# Re-authenticate
/ebay-auth
```

### Commands Not Appearing
```bash
# List all commands
/help

# Plugin commands have namespace: ebay-listing-automation:command-name
# Or just: /command-name if no conflicts
```

### Agents Not Invoking
```bash
# List available agents
/agents

# Manually invoke an agent
# Select from the agents list
```

## API Limitations

### Sold Listings Research
**Known Limitation**: eBay's Finding API was decommissioned (Feb 2025). We cannot programmatically access completed/sold listings.

**Workarounds**:
1. Use our active listings search (very close to sold prices)
2. Manually check "Sell one like this" for validation
3. Use Terapeak in Seller Hub (if you have eBay Store)
4. Apply for Marketplace Insights API (requires approval)

### Rate Limits
- **Sandbox**: 5,000 calls/day
- **Production**: Varies by account level
- Plugin automatically handles token refresh
- Respects rate limits with exponential backoff

## Security

- OAuth tokens stored locally in `.ebay-tokens.json`
- Refresh tokens valid for 18 months
- Auto-refresh every 2 hours
- Never exposed in logs or output
- Environment variables for credentials
- `.gitignore` protects sensitive files

## Contributing

Contributions welcome! Areas for improvement:
- Additional agents for specialized tasks
- More automation hooks
- Enhanced SEO optimization
- Cloudflare Workers integration for webhooks
- Template library for different categories

## License

MIT License - See LICENSE file

## Disclaimer

This plugin is not affiliated with or endorsed by eBay. Use in accordance with eBay's API Terms of Service and seller policies.

## Support

- Documentation: This README
- Issues: https://github.com/jbwashington/ebay-mcp/issues
- Quick Start: See QUICKSTART.md

---

**Made with ❤️ for eBay sellers who love automation**