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 oam compile 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
• redact.ts masks license keys: a key matching the anchored LICENSE_KEY_RE (licenseKey / license_key / license-key, any case — never licenseKeyId, license_key_id or licenseKeyInstanceId) becomes [REDACTED:last4=XXXX] when its value is a string of 16+ characters, and [REDACTED] otherwise (fails closed). It is the single choke point for audited inputs in every sink (stderr, the audit ring, the lemonsqueezy://audit-log resource) and for api.ts's unrecognized-error-body fallback. The error field never passes through it: api.ts only accepts a string upstream message (extractErrorMessage) and redacts the body otherwise, so keep that string check if you touch the error path. Tests derive the expected mask from the exported maskLicenseKey, not a hard-coded string. A tool that takes a raw license key must never become destructive (audited) without this mask
• The four predicate tools (ls_update_customer, ls_update_subscription, ls_update_license_key, ls_update_webhook) declare static destructiveHint: true: MCP clients see only the static annotation, and MCP defines false as "only additive updates". isDestructiveCall never reads the hint when a predicate exists, so the server-side destructive limiter and audit log stay per call. tools.test.ts pins the destructiveHint: true set (13), the predicate set (4), the readOnlyHint: false set and the full 64-tool class map as SEMVER.md surface — changing one is a SEMVER decision plus a README update, not a test fixup