lemonsqueezy-mcp: Instructions file for Claude Code

lemonsqueezy-mcp

LemonSqueezy MCP server — manage your store, subscriptions, customers, and licenses from AI assistants.

Architecture

• src/index.ts — Entry point. Registers all tools with McpServer, handles version subcommand. Must stay free of top-level await (the single-binary build emits CJS).
• src/api.ts — LemonSqueezy API client. Bearer token auth, JSON:API format, 30s timeout. Also exports licenseRequest for the License API (different auth), plus the shared buildQuery / buildInvoiceQuery / cross-store-note helpers used by the tool modules.
• src/wrapper.ts — Sits between the SDK's registered handler and each tool handler. Runs the guardrails in a load-bearing order, then logs and audits. createToolHandler is the only production caller path.
• src/guardrails.ts — Store allowlist, refund cap, destructive + per-authority-class rate limits. All opt-in via env.
• src/tools/*.ts — Tool definitions as exported arrays. Each file covers one API resource domain.

Build

• Bundler: esbuild (build.mjs) — single dist/index.js with zero runtime deps
• Type checking: tsc (separate pass before esbuild)
• Linter: Biome
• Tests: Node.js built-in test runner (node --test)
• TypeScript: Strict mode, ES2022 target, Node16 module resolution

Key patterns

• Tools are arrays of { name, description, authorityClass, annotations, inputSchema, handler } objects
• All tool names prefixed with ls_
• Zod schemas for input validation with .describe() for each field
• Every tool has MCP annotations: readOnlyHint, destructiveHint, idempotentHint, openWorldHint
• JSON:API query params built via buildQuery({ include, filter, page })
• Version injected at build time via esbuild define
• Optional per-tool hooks on the wrapper: isDestructive(input) (per-call destructive verdict), requiredFilters (store-allowlist scoping for list-by-parent tools), and preflight(input) (input guardrail that must reject before the rate limiters — the refund cap uses it)
• A list tool with neither a storeId field nor requiredFilters is completely ungated by the store allowlist. tools.test.ts fails on any new one; the two known cases must disclose it via crossStoreUngatedNote()
• Update tools reject an ID-only PATCH locally rather than paying a round-trip for an upstream 422, throwing ToolInputError so the wrapper logs it as validation_error (client mistake) rather than exception (something faulted) or guardrail_block (operator policy)
• redact.ts guards cycles with an ancestor path plus a memo of completed subtrees — the ancestor set alone is O(paths), which is exponential on a shared-reference DAG