listbee-mcp 0.1.0 → 0.4.0

package/dist/transports/http.js

@@ -0,0 +1,120 @@
+import { randomUUID } from "node:crypto";
+import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { createServer } from "../server.js";
+const transports = new Map();
+const sessions = new Map();
+const SESSION_TTL_MS = 30 * 60 * 1000;
+const SWEEP_INTERVAL_MS = 5 * 60 * 1000;
+function startTtlSweep() {
+    setInterval(() => {
+        const cutoff = Date.now() - SESSION_TTL_MS;
+        for (const [id, meta] of sessions) {
+            if (meta.lastSeenAt < cutoff) {
+                const transport = transports.get(id);
+                if (transport) {
+                    transport.close();
+                    transports.delete(id);
+                }
+                sessions.delete(id);
+                console.error(`[http] Evicted idle session ${id}`);
+            }
+        }
+    }, SWEEP_INTERVAL_MS);
+}
+export async function runHttp(config) {
+    // Bind to 0.0.0.0 for container/remote deployments — DNS rebinding protection
+    // is not applied for non-localhost hosts, which is correct for remote MCP.
+    const app = createMcpExpressApp({ host: "0.0.0.0" });
+    // Auth middleware — reject unauthenticated requests before MCP sees them
+    app.use("/mcp", (req, res, next) => {
+        const auth = req.headers.authorization;
+        if (!auth?.startsWith("Bearer ")) {
+            res.status(401).json({ error: "Missing Authorization: Bearer header" });
+            return;
+        }
+        next();
+    });
+    // MCP endpoint — handles all HTTP methods (GET for SSE, POST for requests, DELETE for close)
+    app.all("/mcp", async (req, res) => {
+        const sessionId = req.headers["mcp-session-id"];
+        // Route to existing session
+        if (sessionId && transports.has(sessionId)) {
+            const transport = transports.get(sessionId);
+            const meta = sessions.get(sessionId);
+            if (meta)
+                meta.lastSeenAt = Date.now();
+            await transport.handleRequest(req, res, req.body);
+            return;
+        }
+        // New session — must be an initialize request
+        if (req.method === "POST" && isInitializeRequest(req.body)) {
+            const apiKey = req.headers.authorization.replace("Bearer ", "");
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: () => randomUUID(),
+                onsessioninitialized: (sid) => {
+                    transports.set(sid, transport);
+                    sessions.set(sid, {
+                        createdAt: Date.now(),
+                        lastSeenAt: Date.now(),
+                    });
+                    transport.onclose = () => {
+                        transports.delete(sid);
+                        sessions.delete(sid);
+                        console.error(`[http] Session closed: ${sid}`);
+                    };
+                    console.error(`[http] New session: ${sid}`);
+                },
+            });
+            const server = createServer({
+                apiKey,
+                baseUrl: config.baseUrl,
+                toolFilter: config.toolFilter,
+            });
+            await server.connect(transport);
+            await transport.handleRequest(req, res, req.body);
+            return;
+        }
+        res.status(400).json({
+            error: "Bad request — missing Mcp-Session-Id or not an initialize request",
+        });
+    });
+    // Root — landing page instead of Express 404
+    app.get("/", (_req, res) => {
+        res.json({
+            name: "ListBee MCP",
+            description: "Commerce API for AI agents",
+            endpoint: "/mcp",
+            transport: "streamable-http",
+            docs: "https://docs.listbee.so",
+            package: "npx listbee-mcp",
+        });
+    });
+    // Health checks
+    app.get("/health", (_req, res) => {
+        res.json({ status: "ok" });
+    });
+    app.get("/ready", (_req, res) => {
+        res.json({ status: "ready", sessions: sessions.size });
+    });
+    startTtlSweep();
+    // Graceful shutdown
+    const server = app.listen(config.port, "0.0.0.0", () => {
+        console.error(`ListBee MCP server (HTTP) listening on port ${config.port}`);
+        console.error(`Endpoint: http://localhost:${config.port}/mcp`);
+    });
+    const shutdown = () => {
+        console.error("\nShutting down...");
+        for (const [id, transport] of transports) {
+            transport.close();
+            transports.delete(id);
+            sessions.delete(id);
+        }
+        server.close(() => process.exit(0));
+        setTimeout(() => process.exit(1), 5000);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}
+//# sourceMappingURL=http.js.map

package/dist/transports/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/transports/http.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,mBAAmB,EAAE,MAAM,6CAA6C,CAAC;AAClF,OAAO,EAAE,6BAA6B,EAAE,MAAM,oDAAoD,CAAC;AACnG,OAAO,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAa5C,MAAM,UAAU,GAAG,IAAI,GAAG,EAAyC,CAAC;AACpE,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAuB,CAAC;AAEhD,MAAM,cAAc,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AACtC,MAAM,iBAAiB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;AAExC,SAAS,aAAa;IACpB,WAAW,CAAC,GAAG,EAAE;QACf,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,cAAc,CAAC;QAC3C,KAAK,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC,IAAI,QAAQ,EAAE,CAAC;YAClC,IAAI,IAAI,CAAC,UAAU,GAAG,MAAM,EAAE,CAAC;gBAC7B,MAAM,SAAS,GAAG,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBACrC,IAAI,SAAS,EAAE,CAAC;oBACd,SAAS,CAAC,KAAK,EAAE,CAAC;oBAClB,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;gBACxB,CAAC;gBACD,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;gBACpB,OAAO,CAAC,KAAK,CAAC,+BAA+B,EAAE,EAAE,CAAC,CAAC;YACrD,CAAC;QACH,CAAC;IACH,CAAC,EAAE,iBAAiB,CAAC,CAAC;AACxB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,MAAkB;IAC9C,8EAA8E;IAC9E,2EAA2E;IAC3E,MAAM,GAAG,GAAG,mBAAmB,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC;IAErD,yEAAyE;IACzE,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QACjC,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,CAAC,aAAa,CAAC;QACvC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YACjC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,sCAAsC,EAAE,CAAC,CAAC;YACxE,OAAO;QACT,CAAC;QACD,IAAI,EAAE,CAAC;IACT,CAAC,CAAC,CAAC;IAEH,6FAA6F;IAC7F,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;QACjC,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,gBAAgB,CAAuB,CAAC;QAEtE,4BAA4B;QAC5B,IAAI,SAAS,IAAI,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YAC3C,MAAM,SAAS,GAAG,UAAU,CAAC,GAAG,CAAC,SAAS,CAAE,CAAC;YAC7C,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YACrC,IAAI,IAAI;gBAAE,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACvC,MAAM,SAAS,CAAC,aAAa,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;YAClD,OAAO;QACT,CAAC;QAED,8CAA8C;QAC9C,IAAI,GAAG,CAAC,MAAM,KAAK,MAAM,IAAI,mBAAmB,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAC3D,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,aAAc,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;YAEjE,MAAM,SAAS,GAAG,IAAI,6BAA6B,CAAC;gBAClD,kBAAkB,EAAE,GAAG,EAAE,CAAC,UAAU,EAAE;gBACtC,oBAAoB,EAAE,CAAC,GAAG,EAAE,EAAE;oBAC5B,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;oBAC/B,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE;wBAChB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;wBACrB,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE;qBACvB,CAAC,CAAC;oBACH,SAAS,CAAC,OAAO,GAAG,GAAG,EAAE;wBACvB,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;wBACvB,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;wBACrB,OAAO,CAAC,KAAK,CAAC,0BAA0B,GAAG,EAAE,CAAC,CAAC;oBACjD,CAAC,CAAC;oBACF,OAAO,CAAC,KAAK,CAAC,uBAAuB,GAAG,EAAE,CAAC,CAAC;gBAC9C,CAAC;aACF,CAAC,CAAC;YAEH,MAAM,MAAM,GAAG,YAAY,CAAC;gBAC1B,MAAM;gBACN,OAAO,EAAE,MAAM,CAAC,OAAO;gBACvB,UAAU,EAAE,MAAM,CAAC,UAAU;aAC9B,CAAC,CAAC;YACH,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;YAEhC,MAAM,SAAS,CAAC,aAAa,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;YAClD,OAAO;QACT,CAAC;QAED,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;YACnB,KAAK,EAAE,mEAAmE;SAC3E,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,6CAA6C;IAC7C,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE;QACzB,GAAG,CAAC,IAAI,CAAC;YACP,IAAI,EAAE,aAAa;YACnB,WAAW,EAAE,4BAA4B;YACzC,QAAQ,EAAE,MAAM;YAChB,SAAS,EAAE,iBAAiB;YAC5B,IAAI,EAAE,yBAAyB;YAC/B,OAAO,EAAE,iBAAiB;SAC3B,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,gBAAgB;IAChB,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE;QAC/B,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7B,CAAC,CAAC,CAAC;IAEH,GAAG,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE;QAC9B,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACzD,CAAC,CAAC,CAAC;IAEH,aAAa,EAAE,CAAC;IAEhB,oBAAoB;IACpB,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE;QACrD,OAAO,CAAC,KAAK,CAAC,+CAA+C,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;QAC5E,OAAO,CAAC,KAAK,CAAC,8BAA8B,MAAM,CAAC,IAAI,MAAM,CAAC,CAAC;IACjE,CAAC,CAAC,CAAC;IAEH,MAAM,QAAQ,GAAG,GAAG,EAAE;QACpB,OAAO,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC;QACpC,KAAK,MAAM,CAAC,EAAE,EAAE,SAAS,CAAC,IAAI,UAAU,EAAE,CAAC;YACzC,SAAS,CAAC,KAAK,EAAE,CAAC;YAClB,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACtB,CAAC;QACD,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QACpC,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IAC1C,CAAC,CAAC;IACF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC/B,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;AAClC,CAAC"}

package/dist/transports/stdio.d.ts

@@ -0,0 +1,7 @@
+export interface StdioConfig {
+    apiKey: string;
+    baseUrl: string;
+    toolFilter?: Set<string>;
+}
+export declare function runStdio(config: StdioConfig): Promise<void>;
+//# sourceMappingURL=stdio.d.ts.map

package/dist/transports/stdio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.d.ts","sourceRoot":"","sources":["../../src/transports/stdio.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC1B;AAED,wBAAsB,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBjE"}

package/dist/transports/stdio.js

@@ -0,0 +1,18 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "../server.js";
+export async function runStdio(config) {
+    const server = createServer({
+        apiKey: config.apiKey,
+        baseUrl: config.baseUrl,
+        toolFilter: config.toolFilter,
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    const shutdown = async () => {
+        await server.close();
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}
+//# sourceMappingURL=stdio.js.map

package/dist/transports/stdio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.js","sourceRoot":"","sources":["../../src/transports/stdio.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAQ5C,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,MAAmB;IAChD,MAAM,MAAM,GAAG,YAAY,CAAC;QAC1B,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,UAAU,EAAE,MAAM,CAAC,UAAU;KAC9B,CAAC,CAAC;IAEH,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEhC,MAAM,QAAQ,GAAG,KAAK,IAAI,EAAE;QAC1B,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACrB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC;IACF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC/B,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;AAClC,CAAC"}

package/dist/types.d.ts

@@ -1,18 +1,11 @@
 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.
+ * Handles SDK's typed error hierarchy for structured output.
  */
 export declare function errorResult(err: unknown): CallToolResult;
 /**

package/dist/types.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAGzE;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAIxD;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,CAsCxD;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

@@ -1,19 +1,4 @@
-/**
- * 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";
-    }
-}
+import { APIStatusError, APIConnectionError, APITimeoutError } from "listbee";
 /**
  * Format a successful result as JSON text content.
  */
@@ -24,9 +9,10 @@ export function jsonResult(data) {
 }
 /**
  * Format an error as an isError result so the LLM can reason about it.
+ * Handles SDK's typed error hierarchy for structured output.
  */
 export function errorResult(err) {
-    if (err instanceof ListBeeApiError) {
+    if (err instanceof APIStatusError) {
         return {
             isError: true,
             content: [
@@ -34,12 +20,26 @@ export function errorResult(err) {
                     type: "text",
                     text: JSON.stringify({
                         status: err.status,
-                        error: err.body,
+                        code: err.code,
+                        detail: err.detail,
+                        ...(err.param ? { param: err.param } : {}),
                     }, null, 2),
                 },
             ],
         };
     }
+    if (err instanceof APIConnectionError) {
+        return {
+            isError: true,
+            content: [{ type: "text", text: `Connection error: ${err.message}` }],
+        };
+    }
+    if (err instanceof APITimeoutError) {
+        return {
+            isError: true,
+            content: [{ type: "text", text: `Request timed out: ${err.message}` }],
+        };
+    }
     const message = err instanceof Error ? err.message : String(err);
     return {
         isError: true,

package/dist/types.js.map

@@ -1 +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"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE9E;;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;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,GAAY;IACtC,IAAI,GAAG,YAAY,cAAc,EAAE,CAAC;QAClC,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,IAAI,EAAE,GAAG,CAAC,IAAI;wBACd,MAAM,EAAE,GAAG,CAAC,MAAM;wBAClB,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;qBAC3C,EACD,IAAI,EACJ,CAAC,CACF;iBACF;aACF;SACF,CAAC;IACJ,CAAC;IACD,IAAI,GAAG,YAAY,kBAAkB,EAAE,CAAC;QACtC,OAAO;YACL,OAAO,EAAE,IAAI;YACb,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,qBAAqB,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC;SACtE,CAAC;IACJ,CAAC;IACD,IAAI,GAAG,YAAY,eAAe,EAAE,CAAC;QACnC,OAAO;YACL,OAAO,EAAE,IAAI;YACb,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,sBAAsB,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC;SACvE,CAAC;IACJ,CAAC;IACD,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/dist/{tools/shared.d.ts → utils.d.ts}

@@ -1,4 +1,4 @@
-import type { ToolMeta } from "../manifest.js";
+import type { ToolMeta } from "./manifest.js";
 export interface Deliverable {
     type: string;
     token?: string;
@@ -15,4 +15,4 @@ export declare function autoTitle(name: string): string;
  * Complex tools get structured markdown; simple ones get a single sentence.
  */
 export declare function buildDescription(meta: ToolMeta): string;
-//# sourceMappingURL=shared.d.ts.map
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,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 → utils.js}

@@ -28,4 +28,4 @@ export function buildDescription(meta) {
     }
     return parts.join("\n\n");
 }
-//# sourceMappingURL=shared.js.map
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.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/mcp-tools.yaml

@@ -17,12 +17,26 @@ tools:
     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.
+      Only name and price are required — but listings with rich content convert
+      significantly better. Fill in as many fields as you can: description, tagline,
+      highlights, badges, reviews, faqs, cta, cover_url. Write salesy, compelling
+      copy. The product page buyers see is built entirely from these fields.
     hints:
       - "Always check readiness.sellable in the response"
       - "readiness.next tells you the highest-priority action to take"
+      - "Only name + price are required, but fill in description, tagline, highlights, badges, reviews, faqs, cta for better conversions"
+      - "Write compelling, benefit-focused copy — this IS the product page buyers see"
+      - "checkout_schema and metadata are the only fields that don't appear on the product page"
     input_example:
       name: "50 Cold Outreach Templates"
       price: 1900
+      tagline: "Battle-tested templates that book meetings"
+      description: "50 proven cold outreach templates used by 500+ SDRs. Each template includes subject line, body, and follow-up sequence. Average 45% open rate."
+      highlights:
+        - "50 ready-to-send templates"
+        - "45% average open rate"
+        - "Follow-up sequences included"
+      cta: "Get the Templates"
 
   - type: operation
     operation_id: get_listing
@@ -113,7 +127,7 @@ tools:
     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.
+      Upload a file and receive a token for use in deliverables.
     hints:
       - "Returns a file token — pass it to set_deliverables to attach the file to a listing"
 
@@ -145,6 +159,174 @@ tools:
       Push digital content to a buyer for an external fulfillment order.
       Not needed for managed delivery — ListBee handles that automatically.
 
+  - type: operation
+    operation_id: ship_order
+    name: ship_order
+    category: orders
+    priority: 7
+    status: active
+    when_to_use: "Use when a physical order needs shipping info recorded. Only for external fulfillment orders with physical goods."
+    description: >
+      Record shipping info (carrier + tracking code) and transition order to FULFILLED.
+      Only valid for external fulfillment orders. Idempotent with same tracking code.
+    hints:
+      - "Only works on orders in PAID state for EXTERNAL fulfillment listings"
+      - "Fires order.fulfilled webhook with shipping details"
+    input_example:
+      order_id: "ord_9xM4kP7nR2qT5wY1"
+      carrier: "USPS"
+      tracking_code: "9400111899223"
+
+  - type: operation
+    operation_id: refund_order
+    name: refund_order
+    category: orders
+    priority: 6
+    status: active
+    when_to_use: "When a buyer requests a refund or the seller needs to reverse a charge. Only works on paid or fulfilled orders."
+    description: >
+      Issue a full refund for an order. Refund is processed through Stripe on the
+      seller's connected account. Idempotent — already-refunded orders return as-is.
+      Order state (refund_amount, refunded_at) updates asynchronously via Stripe webhook.
+    hints:
+      - "Only works on orders in PAID or FULFILLED status"
+      - "Already-refunded orders return 200 with no action (idempotent)"
+      - "Fires order.refunded webhook after Stripe processes the refund"
+    input_example:
+      order_id: "ord_9xM4kP7nR2qT5wY1"
+
+  # --- Customers ---
+  - type: operation
+    operation_id: list_customers
+    name: list_customers
+    category: customers
+    priority: 7
+    status: active
+    when_to_use: "When the agent needs buyer email addresses for marketing, wants to analyze purchasing patterns, or needs to identify repeat customers."
+    description: >
+      List all customers (buyers) who have purchased from the seller. Auto-populated
+      from orders — no manual creation needed. Sorted by most recent purchase first.
+      Filter by email for exact match lookup.
+    hints:
+      - "Customers are auto-created on first order — read-only, no create/delete"
+      - "Use email filter to look up a specific buyer"
+      - "total_spent is in cents (smallest currency unit)"
+
+  - type: operation
+    operation_id: get_customer
+    name: get_customer
+    category: customers
+    priority: 6
+    status: active
+    when_to_use: "When the agent needs purchase history details for a specific buyer."
+    description: >
+      Get a customer by ID. Shows total orders, total spent, currency, and purchase dates.
+      Customers represent unique buyer emails that have purchased from the seller.
+    hints:
+      - "Use list_customers with email filter if you have the email but not the ID"
+
+  # --- Account ---
+  - type: operation
+    operation_id: get_account
+    name: get_account
+    category: account
+    priority: 8
+    status: active
+    when_to_use: "Use to check account status, readiness, billing, Stripe connection, and profile details."
+    description: >
+      Get the authenticated account's full state including readiness and billing status.
+      This is the first call an agent should make to understand what's set up.
+    hints:
+      - "Call this first to understand account state"
+      - "readiness.operational tells you if the account can sell"
+      - "Check payment_config to see if Stripe is connected"
+
+  - type: operation
+    operation_id: update_account
+    name: update_account
+    category: account
+    priority: 5
+    status: active
+    when_to_use: "Use to update account profile — display name, bio, avatar."
+    description: >
+      Update the account's display name, bio, or avatar. These appear on product pages
+      as the seller identity.
+
+  - type: operation
+    operation_id: delete_account
+    name: delete_account
+    category: account
+    priority: 1
+    status: active
+    when_to_use: "Use only when the user explicitly wants to permanently delete their account."
+    description: >
+      Permanently delete the account and all associated data. This is irreversible.
+    hints:
+      - "This is destructive and irreversible — confirm with the user first"
+
+  - type: operation
+    operation_id: create_account
+    name: create_account
+    category: account
+    priority: 10
+    status: active
+    when_to_use: "Use when a new user wants to sign up. First step in the onboarding flow."
+    description: >
+      Create a new ListBee account with an email address. Sends an OTP code to the email
+      for verification. Follow up with verify_otp to complete signup and get an API key.
+    hints:
+      - "This sends an OTP email — the user must provide the code"
+      - "After create_account, call verify_otp with the code"
+
+  - type: operation
+    operation_id: verify_otp
+    name: verify_otp
+    category: account
+    priority: 10
+    status: active
+    when_to_use: "Use after create_account to verify the email OTP code and complete signup."
+    description: >
+      Verify the OTP code sent to the user's email during account creation.
+      Returns an API key on success — store it securely for all future API calls.
+    hints:
+      - "The user must provide the OTP code from their email"
+      - "On success, returns an API key (lb_ prefixed) — this is the only time it's shown"
+
+  # --- API Keys ---
+  - type: operation
+    operation_id: list_api_keys
+    name: list_api_keys
+    category: api_keys
+    priority: 4
+    status: active
+    when_to_use: "Use to see all API keys for the account."
+    description: >
+      List all API keys. Shows key prefixes and names but not full key values
+      (those are only shown at creation time).
+
+  - type: operation
+    operation_id: create_api_key
+    name: create_api_key
+    category: api_keys
+    priority: 4
+    status: active
+    when_to_use: "Use when the user needs a new API key, e.g. for a separate agent or integration."
+    description: >
+      Create a new API key. The full key value (lb_ prefixed) is returned only once —
+      store it securely. Each key can have a name for identification.
+    hints:
+      - "The full key is only shown once at creation — store it immediately"
+
+  - type: operation
+    operation_id: delete_api_key
+    name: delete_api_key
+    category: api_keys
+    priority: 2
+    status: active
+    when_to_use: "Use to revoke an API key that is no longer needed or compromised."
+    description: >
+      Delete an API key. The key is immediately revoked and cannot be used again.
+
   # --- Stripe ---
   - type: operation
     operation_id: start_stripe_connect
@@ -161,6 +343,96 @@ tools:
       - "You cannot complete this — the human must open the URL"
       - "After the human completes onboarding, check readiness again"
 
+  - type: operation
+    operation_id: disconnect_stripe
+    name: disconnect_stripe
+    category: stripe
+    priority: 2
+    status: active
+    when_to_use: "Use when the user wants to disconnect their Stripe account."
+    description: >
+      Disconnect the Stripe account from ListBee. Existing listings retain their
+      payment snapshot but new checkouts will fail.
+    hints:
+      - "This doesn't delete the Stripe account — just disconnects it from ListBee"
+
+  # --- Webhooks ---
+  - type: operation
+    operation_id: list_webhooks
+    name: list_webhooks
+    category: webhooks
+    priority: 7
+    status: active
+    when_to_use: "Use to see configured webhooks and their delivery status."
+    description: >
+      List all webhooks for the account. Shows URL, events filter, and enabled status.
+
+  - type: operation
+    operation_id: create_webhook
+    name: create_webhook
+    category: webhooks
+    priority: 8
+    status: active
+    when_to_use: "Use when the user needs to receive order notifications at a URL. Required for external fulfillment."
+    description: >
+      Create a webhook endpoint. Specify the URL and which events to receive.
+      The webhook secret (whsec_ prefixed) is returned for signature verification.
+    hints:
+      - "Required for external fulfillment listings — readiness checks for this"
+      - "Common events: order.paid, order.fulfilled, order.refunded"
+      - "The secret is only shown once at creation"
+    input_example:
+      url: "https://your-server.com/webhooks"
+      events: ["order.paid", "order.fulfilled"]
+
+  - type: operation
+    operation_id: update_webhook
+    name: update_webhook
+    category: webhooks
+    priority: 5
+    status: active
+    when_to_use: "Use to change a webhook's URL, events filter, or enabled status."
+
+  - type: operation
+    operation_id: delete_webhook
+    name: delete_webhook
+    category: webhooks
+    priority: 3
+    status: active
+    when_to_use: "Use to remove a webhook endpoint."
+
+  - type: operation
+    operation_id: list_webhook_events
+    name: list_webhook_events
+    category: webhooks
+    priority: 5
+    status: active
+    when_to_use: "Use to check webhook delivery history — see which events were sent and whether they succeeded."
+    description: >
+      List recent events for a webhook. Shows delivery status, attempts, and errors.
+      Useful for debugging failed deliveries.
+
+  - type: operation
+    operation_id: retry_webhook_event
+    name: retry_webhook_event
+    category: webhooks
+    priority: 4
+    status: active
+    when_to_use: "Use when a webhook delivery failed and needs to be retried."
+    description: >
+      Retry delivery of a failed webhook event. Resets attempt counter.
+
+  - type: operation
+    operation_id: test_webhook
+    name: test_webhook
+    category: webhooks
+    priority: 5
+    status: active
+    when_to_use: "Use to send a test event to a webhook URL to verify it's working."
+    description: >
+      Send a test event to the webhook URL. Returns the delivery result.
+      Use this to verify webhook configuration before going live.
+
   # --- Future composite tools (v2+) ---
   # - type: composite
   #   name: create_and_publish

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "listbee-mcp",
-  "version": "0.1.0",
+  "version": "0.4.0",
   "description": "MCP server for ListBee — commerce API for AI agents",
   "license": "Apache-2.0",
   "type": "module",
@@ -15,18 +15,24 @@
     "node": ">=20"
   },
   "scripts": {
-    "build": "tsc && chmod +x dist/index.js",
-    "dev": "tsc --watch",
-    "lint": "tsc --noEmit",
+    "generate": "tsx scripts/generate.ts",
+    "generate:check": "tsx scripts/generate.ts --check",
+    "build": "npm run generate && tsc && chmod +x dist/index.js",
+    "dev": "tsx src/index.ts",
+    "lint": "npm run generate:check && tsc --noEmit",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.29.0",
+    "listbee": "^0.6.1",
     "yaml": "2.8.3",
     "zod": "3.25.76"
   },
   "devDependencies": {
+    "@types/express": "^5.0.6",
     "@types/node": "22.19.17",
+    "json-schema-to-zod": "^2.8.1",
+    "tsx": "^4.21.0",
     "typescript": "5.9.3"
   },
   "repository": {

package/dist/client.d.ts

@@ -1,18 +0,0 @@
-/**
- * Thin fetch wrapper for the ListBee REST API.
- * All requests include Authorization header. Non-2xx throws ListBeeApiError.
- */
-export declare class ListBeeClient {
-    private readonly apiKey;
-    private readonly baseUrl;
-    constructor(apiKey: string, baseUrl?: string);
-    /**
-     * Make an authenticated JSON request. Returns parsed response body.
-     */
-    request<T = unknown>(method: string, path: string, body?: unknown): Promise<T>;
-    /**
-     * Upload a file via multipart form data to /v1/files.
-     */
-    uploadFile(fileBuffer: Uint8Array, filename: string): Promise<unknown>;
-}
-//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,MAAM,EAAE,MAAM,EAAE,OAAO,SAA2B;IAM9D;;OAEG;IACG,OAAO,CAAC,CAAC,GAAG,OAAO,EACvB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,OAAO,GACb,OAAO,CAAC,CAAC,CAAC;IA8Bb;;OAEG;IACG,UAAU,CAAC,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAsB7E"}