listbee-mcp 0.1.0

package/dist/tools/orders.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orders.js","sourceRoot":"","sources":["../../src/tools/orders.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAGvC,sBAAsB;AAEtB,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,MAAqB,EACrB,IAAyC;IAEzC,OAAO,QAAQ,CAAC,KAAK,IAAI,EAAE;QACzB,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;QACrC,IAAI,IAAI,CAAC,MAAM;YAAE,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QACnD,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS;YAAE,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QACtE,MAAM,EAAE,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC;QAC7B,MAAM,IAAI,GAAG,aAAa,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;QAC/C,OAAO,MAAM,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAC3C,CAAC,CAAC,CAAC;AACL,CAAC;AAED,oBAAoB;AAEpB,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,MAAqB,EACrB,IAA0B;IAE1B,OAAO,QAAQ,CAAC,KAAK,IAAI,EAAE;QACzB,OAAO,MAAM,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,cAAc,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;IACpE,CAAC,CAAC,CAAC;AACL,CAAC;AAED,wBAAwB;AAExB,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,MAAqB,EACrB,IAAuD;IAEvD,OAAO,QAAQ,CAAC,KAAK,IAAI,EAAE;QACzB,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,OAAO,CAC/B,MAAM,EACN,cAAc,IAAI,CAAC,QAAQ,UAAU,EACrC,EAAE,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,CACpC,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/tools/shared.d.ts

@@ -0,0 +1,18 @@
+import type { ToolMeta } from "../manifest.js";
+export interface Deliverable {
+    type: string;
+    token?: string;
+    value?: string;
+    label?: string;
+}
+/**
+ * Auto-generate a human-readable title from a snake_case tool name.
+ * e.g. "create_listing" → "Create Listing"
+ */
+export declare function autoTitle(name: string): string;
+/**
+ * Build a structured description from manifest metadata.
+ * Complex tools get structured markdown; simple ones get a single sentence.
+ */
+export declare function buildDescription(meta: ToolMeta): string;
+//# sourceMappingURL=shared.d.ts.map

package/dist/tools/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/tools/shared.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAK9C;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAsBvD"}

package/dist/tools/shared.js

@@ -0,0 +1,31 @@
+/**
+ * Auto-generate a human-readable title from a snake_case tool name.
+ * e.g. "create_listing" → "Create Listing"
+ */
+export function autoTitle(name) {
+    return name
+        .split("_")
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+        .join(" ");
+}
+/**
+ * Build a structured description from manifest metadata.
+ * Complex tools get structured markdown; simple ones get a single sentence.
+ */
+export function buildDescription(meta) {
+    const parts = [];
+    if (meta.description) {
+        parts.push(meta.description.trim());
+    }
+    if (meta.when_to_use) {
+        parts.push(`**When to use:** ${meta.when_to_use}`);
+    }
+    if (meta.hints && meta.hints.length > 0) {
+        parts.push(`**Tips:**\n${meta.hints.map((h) => `- ${h}`).join("\n")}`);
+    }
+    if (meta.requires_human) {
+        parts.push("**Note:** This action requires human intervention. You cannot complete it yourself.");
+    }
+    return parts.join("\n\n");
+}
+//# sourceMappingURL=shared.js.map

package/dist/tools/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../src/tools/shared.ts"],"names":[],"mappings":"AASA;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,OAAO,IAAI;SACR,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;SAClD,IAAI,CAAC,GAAG,CAAC,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAc;IAC7C,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;QACrB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC;IACtC,CAAC;IAED,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;QACrB,KAAK,CAAC,IAAI,CAAC,oBAAoB,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;IACrD,CAAC;IAED,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxC,KAAK,CAAC,IAAI,CAAC,cAAc,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACzE,CAAC;IAED,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;QACxB,KAAK,CAAC,IAAI,CACR,qFAAqF,CACtF,CAAC;IACJ,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC5B,CAAC"}

package/dist/tools/stripe.d.ts

@@ -0,0 +1,4 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { ListBeeClient } from "../client.js";
+export declare function handleStartStripeConnect(client: ListBeeClient): Promise<CallToolResult>;
+//# sourceMappingURL=stripe.d.ts.map

package/dist/tools/stripe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stripe.d.ts","sourceRoot":"","sources":["../../src/tools/stripe.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAKlD,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,cAAc,CAAC,CAqBzB"}

package/dist/tools/stripe.js

@@ -0,0 +1,21 @@
+import { errorResult } from "../types.js";
+// --- start_stripe_connect ---
+export async function handleStartStripeConnect(client) {
+    try {
+        const data = await client.request("POST", "/v1/account/stripe/connect");
+        const url = data.url;
+        return {
+            content: [
+                { type: "text", text: JSON.stringify(data, null, 2) },
+                {
+                    type: "text",
+                    text: `IMPORTANT: You cannot complete Stripe onboarding. Share this URL with the user so they can complete it in their browser: ${url}`,
+                },
+            ],
+        };
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+}
+//# sourceMappingURL=stripe.js.map

package/dist/tools/stripe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stripe.js","sourceRoot":"","sources":["../../src/tools/stripe.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,+BAA+B;AAE/B,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,MAAqB;IAErB,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,OAAO,CAC/B,MAAM,EACN,4BAA4B,CAC7B,CAAC;QAEF,MAAM,GAAG,GAAI,IAAwB,CAAC,GAAG,CAAC;QAE1C,OAAO;YACL,OAAO,EAAE;gBACP,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE;gBACrD;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,4HAA4H,GAAG,EAAE;iBACxI;aACF;SACF,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;AACH,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,22 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+/**
+ * Error thrown by ListBeeClient on non-2xx responses.
+ */
+export declare class ListBeeApiError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, body: unknown);
+}
+/**
+ * Format a successful result as JSON text content.
+ */
+export declare function jsonResult(data: unknown): CallToolResult;
+/**
+ * Format an error as an isError result so the LLM can reason about it.
+ */
+export declare function errorResult(err: unknown): CallToolResult;
+/**
+ * Wraps an async function so errors never propagate — they become { isError: true } results.
+ */
+export declare function safeTool<T>(fn: () => Promise<T>): Promise<CallToolResult>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE;;GAEG;AACH,qBAAa,eAAgB,SAAQ,KAAK;aAEtB,MAAM,EAAE,MAAM;aACd,IAAI,EAAE,OAAO;gBADb,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO;CAShC;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAIxD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,CAyBxD;AAED;;GAEG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,CAO/E"}

package/dist/types.js

@@ -0,0 +1,61 @@
+/**
+ * Error thrown by ListBeeClient on non-2xx responses.
+ */
+export class ListBeeApiError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        const msg = typeof body === "object" && body !== null && "detail" in body
+            ? String(body.detail)
+            : JSON.stringify(body);
+        super(`ListBee API error ${status}: ${msg}`);
+        this.status = status;
+        this.body = body;
+        this.name = "ListBeeApiError";
+    }
+}
+/**
+ * Format a successful result as JSON text content.
+ */
+export function jsonResult(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+    };
+}
+/**
+ * Format an error as an isError result so the LLM can reason about it.
+ */
+export function errorResult(err) {
+    if (err instanceof ListBeeApiError) {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        status: err.status,
+                        error: err.body,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+        isError: true,
+        content: [{ type: "text", text: message }],
+    };
+}
+/**
+ * Wraps an async function so errors never propagate — they become { isError: true } results.
+ */
+export async function safeTool(fn) {
+    try {
+        const result = await fn();
+        return jsonResult(result);
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAEtB;IACA;IAFlB,YACkB,MAAc,EACd,IAAa;QAE7B,MAAM,GAAG,GACP,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,IAAI,QAAQ,IAAI,IAAI;YAC3D,CAAC,CAAC,MAAM,CAAE,IAAgC,CAAC,MAAM,CAAC;YAClD,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAC3B,KAAK,CAAC,qBAAqB,MAAM,KAAK,GAAG,EAAE,CAAC,CAAC;QAP7B,WAAM,GAAN,MAAM,CAAQ;QACd,SAAI,GAAJ,IAAI,CAAS;QAO7B,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,IAAa;IACtC,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;KACjE,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,GAAY;IACtC,IAAI,GAAG,YAAY,eAAe,EAAE,CAAC;QACnC,OAAO;YACL,OAAO,EAAE,IAAI;YACb,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAClB;wBACE,MAAM,EAAE,GAAG,CAAC,MAAM;wBAClB,KAAK,EAAE,GAAG,CAAC,IAAI;qBAChB,EACD,IAAI,EACJ,CAAC,CACF;iBACF;aACF;SACF,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACjE,OAAO;QACL,OAAO,EAAE,IAAI;QACb,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;KAC3C,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAI,EAAoB;IACpD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,EAAE,EAAE,CAAC;QAC1B,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;AACH,CAAC"}

package/mcp-tools.yaml

@@ -0,0 +1,170 @@
+version: 1
+
+# Priority scale:
+#   10    = golden-path / core workflow
+#   7-9   = common operations
+#   4-6   = situational
+#   1-3   = rare / cleanup
+
+tools:
+  # --- Listings ---
+  - type: operation
+    operation_id: create_listing
+    name: create_listing
+    category: listings
+    priority: 10
+    status: active
+    when_to_use: "Use when the user wants to sell something new."
+    description: >
+      Create a new listing for sale. Returns a checkout URL and readiness status.
+    hints:
+      - "Always check readiness.sellable in the response"
+      - "readiness.next tells you the highest-priority action to take"
+    input_example:
+      name: "50 Cold Outreach Templates"
+      price: 1900
+
+  - type: operation
+    operation_id: get_listing
+    name: get_listing
+    category: listings
+    priority: 9
+    status: active
+    when_to_use: "Use after any mutation (create, update, set_deliverables) to inspect readiness and determine what to do next."
+    description: >
+      Get a listing's full state including readiness. This is the readiness
+      inspection tool — call it after every change to check what's needed.
+    hints:
+      - "This is how you check readiness — call it after every create/update"
+      - "readiness.sellable tells you if the listing is live"
+      - "readiness.actions lists what's missing, with kind (api/human) and resolve details"
+      - "readiness.next points to the highest-priority action"
+
+  - type: operation
+    operation_id: update_listing
+    name: update_listing
+    category: listings
+    priority: 9
+    status: active
+    when_to_use: "Use when changing title, price, or other listing details."
+    input_example:
+      name: "100 Cold Outreach Templates (Updated)"
+      price: 2900
+
+  - type: operation
+    operation_id: list_listings
+    name: list_listings
+    category: listings
+    priority: 7
+    status: active
+    when_to_use: "Use to see all listings for the current account."
+
+  - type: operation
+    operation_id: publish_listing
+    name: publish_listing
+    category: listings
+    priority: 10
+    status: active
+    when_to_use: "Use when the user wants the listing to go live and readiness indicates it can be published."
+    description: >
+      Publish a listing so buyers can access the product page.
+      Only works when readiness.publishable is true.
+    hints:
+      - "Check readiness first — this fails if listing is not publishable"
+
+  - type: operation
+    operation_id: set_deliverables
+    name: set_deliverables
+    category: listings
+    priority: 9
+    status: active
+    when_to_use: "Use after creating a listing to attach digital content for automatic delivery."
+    description: >
+      Set digital deliverables (files, URLs, or text) on a listing.
+      Required for managed fulfillment mode.
+    input_example:
+      deliverables:
+        - type: "url"
+          value: "https://example.com/templates.zip"
+          label: "Download link"
+
+  - type: operation
+    operation_id: remove_deliverables
+    name: remove_deliverables
+    category: listings
+    priority: 3
+    status: active
+    when_to_use: "Use when switching a listing from managed to external fulfillment."
+
+  - type: operation
+    operation_id: delete_listing
+    name: delete_listing
+    category: listings
+    priority: 2
+    status: active
+    when_to_use: "Use when the user wants to permanently remove a listing."
+
+  # --- Files ---
+  - type: operation
+    operation_id: upload_file
+    name: upload_file
+    category: files
+    priority: 8
+    status: active
+    when_to_use: "Use when the user has a file to sell. Upload first, then use the returned token in set_deliverables."
+    description: >
+      Fetches the file from the URL and uploads it to ListBee. Only use with URLs the user has provided or that you trust.
+    hints:
+      - "Returns a file token — pass it to set_deliverables to attach the file to a listing"
+
+  # --- Orders ---
+  - type: operation
+    operation_id: list_orders
+    name: list_orders
+    category: orders
+    priority: 7
+    status: active
+    when_to_use: "Use when the user wants to see their sales or check order status."
+
+  - type: operation
+    operation_id: get_order
+    name: get_order
+    category: orders
+    priority: 6
+    status: active
+    when_to_use: "Use to get full details of a specific order including buyer info and payment."
+
+  - type: operation
+    operation_id: deliver_order
+    name: deliver_order
+    category: orders
+    priority: 8
+    status: active
+    when_to_use: "Use only for external fulfillment orders when content must be sent after purchase by your app or workflow."
+    description: >
+      Push digital content to a buyer for an external fulfillment order.
+      Not needed for managed delivery — ListBee handles that automatically.
+
+  # --- Stripe ---
+  - type: operation
+    operation_id: start_stripe_connect
+    name: start_stripe_connect
+    category: stripe
+    priority: 10
+    status: active
+    requires_human: true
+    when_to_use: "Use when readiness says Stripe is not connected. Returns a URL the human must visit."
+    description: >
+      Start Stripe Connect onboarding. Returns a URL for the human to complete
+      in a browser. Required before selling through Stripe.
+    hints:
+      - "You cannot complete this — the human must open the URL"
+      - "After the human completes onboarding, check readiness again"
+
+  # --- Future composite tools (v2+) ---
+  # - type: composite
+  #   name: create_and_publish
+  #   category: workflows
+  #   priority: 10
+  #   steps: [create_listing, set_deliverables, publish_listing]
+  #   when_to_use: "Use for one-shot listing creation when all details are ready."

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "listbee-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for ListBee — commerce API for AI agents",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "listbee-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "mcp-tools.yaml"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc && chmod +x dist/index.js",
+    "dev": "tsc --watch",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "yaml": "2.8.3",
+    "zod": "3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "22.19.17",
+    "typescript": "5.9.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/listbee-dev/listbee-mcp.git"
+  },
+  "homepage": "https://listbee.so",
+  "keywords": [
+    "mcp",
+    "listbee",
+    "commerce",
+    "ai-agents",
+    "model-context-protocol"
+  ]
+}