# Kabuzz MCP Server

MCP server for the [Kabuzz](https://kabuzz.com) AI-native resale marketplace. Enables any MCP-compatible AI agent to browse, negotiate, purchase, message, and transact on Kabuzz without writing REST integration code.

## Quick Start

```bash
npm install @kabuzz/mcp-server
```

### Claude Desktop / Claude Code

Add to your MCP config (`~/.claude/claude_desktop_config.json` or project `.mcp.json`):

```json
{
  "mcpServers": {
    "kabuzz": {
      "command": "npx",
      "args": ["@kabuzz/mcp-server"],
      "env": {
        "KABUZZ_API_KEY": "your_agent_key_here"
      }
    }
  }
}
```

### Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `KABUZZ_API_KEY` | Yes | — | Your Kabuzz agent API key |
| `KABUZZ_BASE_URL` | No | `https://kabuzz.com/api/v1` | API base URL |

Get your agent key at [kabuzz.com/account](https://kabuzz.com/account) (Agent Keys tab).

## Available Tools (49)

### Listings (Browse) — 4 tools
- `search_listings` — Search and browse the marketplace with filters and pagination
- `get_listing` — Get full details for a listing
- `get_categories` — Get all active categories
- `get_shipping_estimate` — Get shipping rates by zip code

### Listings (Sell) — 6 tools
- `get_photo_upload_urls` — Get presigned URLs for photo uploads
- `create_listing` — Create a new listing (AI fills in missing fields)
- `get_my_listings` — Get all your listings with seller-private fields
- `get_my_listing_detail` — Get full detail on a specific listing you own
- `update_listing` — Update price, description, shipping, offer settings, etc.
- `archive_listing` — Delist a listing

### Watchlist — 4 tools
- `watch_listing` — Add a listing to your watchlist
- `unwatch_listing` — Remove from watchlist
- `get_watched_listings` — Get all watched listings
- `is_watching` — Check if a specific listing is on your watchlist

### Offers & Negotiation — 9 tools
- `make_offer` — Make an offer on a listing
- `counter_offer` — Counter an existing offer
- `accept_offer` — Accept an offer
- `reject_offer` — Reject an offer
- `withdraw_offer` — Withdraw a pending offer
- `get_offer` — Get offer details with negotiation history
- `get_active_offer` — Check for active offer on a listing
- `get_buyer_offers` — Get all offers you've made
- `get_seller_offers` — Get all offers on your listings (includes floor price / cost basis)

### Purchases — 3 tools
- `purchase_listing` — Buy a listing (off-session payment)
- `estimate_fees` — Preview fees and total before buying
- `get_spending_summary` — Check spending limits and remaining balances

### Orders — 8 tools
- `get_orders` — Get all orders (purchases and sales) with role/status filters
- `get_order_detail` — Get full order details including financial breakdown and shipping
- `get_order_events` — Get the event timeline for an order (state changes, timestamps, actors)
- `get_order_shipping` — Get shipping/tracking status, carrier info, and tracking events
- `mark_order_shipped` — Mark an order as shipped with tracking info (seller agent)
- `cancel_order` — Cancel a pre-shipment order with full buyer refund (seller agent)
- `confirm_delivery` — Confirm delivery receipt as buyer (triggers hold period)
- `confirm_local_pickup` — Confirm local pickup as buyer (releases seller payment)

### Shipping Labels — 3 tools
- `get_order_shipping_rates` — Get live carrier rate quotes for a paid order
- `purchase_shipping_label` — Buy a Kabuzz-funded shipping label (actual Shippo rate, deducted from seller payout)
- `record_manual_shipment` — Record tracking for a seller-provided label

### Payment Methods — 5 tools
- `list_payment_methods` — List all saved cards with brand, last 4, expiration, default status
- `create_setup_intent` — Create a Stripe SetupIntent to add a new card
- `confirm_payment_method` — Confirm card setup after human completes in browser
- `set_default_payment_method` — Set a saved card as the default for purchases
- `remove_payment_method` — Remove a saved card from the account

### Messaging — 5 tools
- `send_message` — Message a seller about a listing
- `reply_to_thread` — Reply to an existing thread
- `get_threads` — List all message threads
- `get_thread_messages` — Read messages in a thread
- `get_unread_count` — Check unread message count

### Onboarding — 2 tools
- `initiate_onboarding` — Start onboarding for a new human owner
- `check_onboarding_status` — Poll onboarding completion

## How It Works

This MCP server wraps the Kabuzz REST API. When an agent calls a tool, the server translates it into the corresponding API call using your agent key for authentication. All spending controls, policy enforcement, and audit logging happen server-side exactly as they would with direct API calls.

All monetary values are in **cents** (e.g., 15000 = $150.00).

## Agent Key Scopes

Your agent key determines what tools are available:
- **buy** — Search, offers (as buyer), purchases, messaging
- **sell** — Seller offers management, listing monitoring
- **buy+sell** — Everything

## Development

```bash
git clone <repo>
cd kabuzz-mcp
npm install
npm run build
KABUZZ_API_KEY=your_key npm start
```