listbee-mcp 0.4.0 → 0.4.1

package/README.md

@@ -1,9 +1,19 @@
 # listbee-mcp
 
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=listbee&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22listbee-mcp%22%5D%2C%22env%22%3A%7B%22LISTBEE_API_KEY%22%3A%22%24%7Binput%3AapiKey%7D%22%7D%7D)
+
 MCP server for ListBee — commerce API for AI agents.
 
 ---
 
+## Connect
+
+**Remote (zero install):** `https://api.listbee.so/mcp` — for ChatGPT Apps, Claude API Connector, remote agents. Each request needs `Authorization: Bearer lb_...` header.
+
+**Local (stdio):** `npx -y listbee-mcp` — for Claude Desktop, Cursor, VS Code, Cline.
+
+---
+
 ## Golden Path
 
 Four calls to go from zero to a live, selling product page:
@@ -31,6 +41,8 @@ create_listing    →  set_deliverables  →  get_listing  →  publish_listing
 
 ## Install
 
+Requires Node.js 20+.
+
 ### Claude Desktop
 
 `~/.claude/claude_desktop_config.json`
@@ -40,7 +52,7 @@ create_listing    →  set_deliverables  →  get_listing  →  publish_listing
   "mcpServers": {
     "listbee": {
       "command": "npx",
-      "args": ["listbee-mcp", "--api-key", "lb_..."]
+      "args": ["-y", "listbee-mcp", "--api-key", "lb_..."]
     }
   }
 }
@@ -53,7 +65,7 @@ Or with an env var:
   "mcpServers": {
     "listbee": {
       "command": "npx",
-      "args": ["listbee-mcp"],
+      "args": ["-y", "listbee-mcp"],
       "env": {
         "LISTBEE_API_KEY": "lb_..."
       }
@@ -71,7 +83,7 @@ Or with an env var:
   "mcpServers": {
     "listbee": {
       "command": "npx",
-      "args": ["listbee-mcp", "--api-key", "lb_..."]
+      "args": ["-y", "listbee-mcp", "--api-key", "lb_..."]
     }
   }
 }
@@ -80,13 +92,13 @@ Or with an env var:
 ### Claude Code
 
 ```bash
-claude mcp add listbee -- npx listbee-mcp --api-key lb_...
+claude mcp add listbee -- npx -y listbee-mcp --api-key lb_...
 ```
 
 ### CLI
 
 ```bash
-npx listbee-mcp --api-key lb_...
+npx -y listbee-mcp --api-key lb_...
 ```
 
 ---
@@ -96,7 +108,7 @@ npx listbee-mcp --api-key lb_...
 For hosted deployments (ChatGPT Apps, Claude API Connector, remote agents):
 
 ```bash
-npx listbee-mcp --transport http --port 3000
+npx -y listbee-mcp --transport http --port 3000
 ```
 
 Each connecting agent provides their API key via `Authorization: Bearer` header.
@@ -119,31 +131,47 @@ docker run -p 8080:8080 listbee-mcp
 
 | Flag | Env var | Default | Description |
 |------|---------|---------|-------------|
-| `--api-key <key>` | `LISTBEE_API_KEY` | — | ListBee API key (required) |
+| `--api-key <key>` | `LISTBEE_API_KEY` | — | ListBee API key (required for stdio) |
 | `--base-url <url>` | `LISTBEE_BASE_URL` | `https://api.listbee.so` | API base URL |
+| `--transport <stdio\|http>` | — | `stdio` | Transport mode |
+| `--port <number>` | `PORT` | `8080` | HTTP port (http mode only) |
 | `--tools <list>` | — | all tools | Comma-separated list of tools to load |
+| `--help`, `-h` | — | — | Show help |
 
 **Selective tool loading** — load only what you need:
 
 ```bash
-npx listbee-mcp --api-key lb_... --tools create_listing,get_listing,publish_listing
+npx -y listbee-mcp --api-key lb_... --tools create_listing,get_listing,publish_listing
 ```
 
 ---
 
 ## Tools
 
+### Account & Auth
+
+| Tool | Description |
+|------|-------------|
+| `create_account` | Create a new ListBee account. Sends an OTP to the email for verification. |
+| `verify_otp` | Verify the OTP sent during signup. Returns an API key on success — store it. |
+| `get_account` | Get the account's full state including readiness and billing status. |
+| `update_account` | Update display name, bio, or avatar. These appear on product pages. |
+| `delete_account` | Permanently delete the account and all data. Irreversible. |
+| `create_api_key` | Create a new API key. Full key value returned only once. |
+| `list_api_keys` | List all API keys. Shows prefixes and names, not full values. |
+| `delete_api_key` | Delete and immediately revoke an API key. |
+
 ### Listings
 
 | Tool | Description |
 |------|-------------|
-| `create_listing` | Create a new listing. Returns checkout URL and readiness. |
+| `create_listing` | Create a new listing for sale. Returns checkout URL and readiness. |
 | `get_listing` | Get full listing state including readiness. Call after every change. |
 | `update_listing` | Update title, price, or other listing details. |
 | `list_listings` | List all listings for the current account. |
 | `publish_listing` | Publish a listing so buyers can access the product page. |
 | `set_deliverables` | Attach digital content (file, URL, or text) for automatic delivery. |
-| `remove_deliverables` | Remove deliverables to switch to external fulfillment. |
+| `remove_deliverables` | Remove deliverables to switch to external fulfillment. Draft only. |
 | `delete_listing` | Permanently delete a listing. |
 
 ### Orders
@@ -153,6 +181,27 @@ npx listbee-mcp --api-key lb_... --tools create_listing,get_listing,publish_list
 | `list_orders` | See all sales and order status. |
 | `get_order` | Get full order details including buyer info and payment. |
 | `deliver_order` | Push digital content to a buyer (external fulfillment only). |
+| `ship_order` | Record shipping info and mark order as fulfilled (external fulfillment). |
+| `refund_order` | Issue a full refund for an order through Stripe. |
+
+### Customers
+
+| Tool | Description |
+|------|-------------|
+| `list_customers` | List all buyers who have purchased. Auto-populated from orders. |
+| `get_customer` | Get a customer by ID — total orders, total spent, purchase history. |
+
+### Webhooks
+
+| Tool | Description |
+|------|-------------|
+| `create_webhook` | Create a webhook endpoint. Returns a `whsec_` secret for signature verification. |
+| `list_webhooks` | List all webhook endpoints for the account. |
+| `update_webhook` | Update a webhook URL or event filter. |
+| `delete_webhook` | Delete a webhook endpoint. Irreversible. |
+| `test_webhook` | Send a test event to verify webhook configuration before going live. |
+| `list_webhook_events` | List recent events for a webhook — delivery status, attempts, errors. |
+| `retry_webhook_event` | Retry delivery of a failed webhook event. |
 
 ### Files
 
@@ -165,6 +214,7 @@ npx listbee-mcp --api-key lb_... --tools create_listing,get_listing,publish_list
 | Tool | Description |
 |------|-------------|
 | `start_stripe_connect` | Start Stripe Connect onboarding. Returns a URL — the human must open it in a browser. |
+| `disconnect_stripe` | Disconnect the Stripe account from ListBee. |
 
 ---
 
@@ -179,7 +229,7 @@ Every listing response includes a `readiness` object that tells you exactly what
     "publishable": false,
     "actions": [
       {
-        "code": "stripe_not_connected",
+        "code": "connect_stripe",
         "kind": "human",
         "message": "Connect a Stripe account to accept payments.",
         "resolve": {
@@ -188,7 +238,7 @@ Every listing response includes a `readiness` object that tells you exactly what
         }
       }
     ],
-    "next": "stripe_not_connected"
+    "next": "connect_stripe"
   }
 }
 ```
@@ -202,10 +252,22 @@ Every listing response includes a `readiness` object that tells you exactly what
   - `human` actions: requires human input (show the `message` and `url`)
 - `readiness.next` — the highest-priority action code to resolve first
 
+**Canonical action codes:** `connect_stripe`, `enable_charges`, `update_billing`, `configure_webhook`, `publish_listing`, `webhook_disabled`
+
 **The pattern:** `create_listing` → `get_listing` → resolve each `api` action → surface `human` actions to the user → `publish_listing` when `publishable` is `true`.
 
 ---
 
+## Debugging
+
+Use [MCP Inspector](https://github.com/modelcontextprotocol/inspector) for interactive testing:
+
+```bash
+npx @modelcontextprotocol/inspector npx -y listbee-mcp
+```
+
+---
+
 ## Get an API Key
 
 [console.listbee.so](https://console.listbee.so) — sign in, go to API Keys.
@@ -217,6 +279,8 @@ Every listing response includes a `readiness` object that tells you exactly what
 - [API Reference](https://docs.listbee.so/api-reference) — full endpoint docs
 - [OpenAPI Spec](https://api.listbee.so/openapi.json) — machine-readable spec
 - [Docs](https://docs.listbee.so) — guides and integration examples
+- [CHANGELOG](https://github.com/listbee-dev/listbee-mcp/blob/main/CHANGELOG.md) — version history
+- [npm](https://www.npmjs.com/package/listbee-mcp) — npm package
 - [GitHub](https://github.com/listbee-dev/listbee-mcp) — source
 
 ---

package/dist/generated/meta.js

@@ -2,7 +2,7 @@
 // source: openapi.json + mcp-tools.yaml
 // Regenerate with: npm run generate
 // openapi_version: 1.0.0
-// generated_at: 2026-04-05T13:40:19.654Z
+// generated_at: 2026-04-06T07:16:33.004Z
 // sha256: c8b0d9640ed32ea12e64304dc6799ff00452ce0d57e332cd3eb4bd37042a3254
 export const meta = {
     create_account: {

package/dist/generated/schemas.js

@@ -2,7 +2,7 @@
 // source: openapi.json + mcp-tools.yaml
 // Regenerate with: npm run generate
 // openapi_version: 1.0.0
-// generated_at: 2026-04-05T13:40:19.654Z
+// generated_at: 2026-04-06T07:16:33.004Z
 // sha256: c8b0d9640ed32ea12e64304dc6799ff00452ce0d57e332cd3eb4bd37042a3254
 import { z } from "zod";
 // Tool name → Zod schema (null means the tool takes no inputs)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "listbee-mcp",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "MCP server for ListBee — commerce API for AI agents",
   "license": "Apache-2.0",
   "type": "module",
@@ -42,8 +42,13 @@
   "homepage": "https://listbee.so",
   "keywords": [
     "mcp",
+    "mcp-server",
     "listbee",
     "commerce",
+    "ecommerce",
+    "payments",
+    "digital-products",
+    "checkout",
     "ai-agents",
     "model-context-protocol"
   ]