lightspeed-x-mcp: Instructions file for Claude Code

CLAUDE.md

Guidance for Claude Code when working in this repository.

What this is

lightspeed-x-mcp: an MCP server for Lightspeed X (Retail POS, the platform formerly called Vend), shipped both as a standalone MCP server and as a Claude Code plugin. Read-only by default; since 2.0 it has opt-in writes behind a human approval gate.

If a user asks you to set this up for them

Use the setup skill in skills/setup/SKILL.md. It has the full walkthrough: where the credential file goes, how to get a token, and how to verify. Do not improvise a setup procedure from this file.

The one-command check is:

node dist/index.js --doctor

It validates credentials, calls the live API, and explains any failure. Never tell a user they are connected until the doctor reports every account reachable.

Non-negotiables when editing the server

• Writes go through the gate, always. LightspeedClient.send() is the only mutating call, and only tools/writes/apply.ts may call it. Every other write tool is a preview: it may GET, validate and createPlan(), and must return previewResult(). Never add a tool or parameter that sends a POST, PUT, PATCH or DELETE directly. The approval gate is the reason this is safe to point at a live business.
• The gate's properties are not negotiable. lightspeed_apply_write keeps _meta["anthropic/requiresUserInteraction"]: true and destructiveHint; it is the only flagged tool and previews stay readOnlyHint. Plans stay single use, expiring, bound to a server-written confirm phrase, and re-checked against the write-enabled accounts at apply time. No env var, parameter or config key may skip the per-call approval.
• Off unless asked for. With LIGHTSPEED_WRITE_ACCOUNTS unset, register no write tool at all. High-risk tools (sales, registers, store credit, gift cards, loyalty, and raw writes to those paths) also require LIGHTSPEED_WRITE_HIGH_RISK=true, enforced in writeClient().
• Every write tool must say what it cannot do. Set verified: false until the endpoint has been exercised live, give each step an undo where one exists, back up prior state via before, and add a warning for anything permanent. A POST is never retried except on 429.
• scripts/check-writes.mjs pins all of the above. Extend it when you add a write tool; it must keep passing with no credentials.
• Never throw from a tool handler. MCP requires failures to come back as results, not protocol errors. Wrap every handler in guard() from lib/format.ts.
• Never console.log. Stdout carries JSON-RPC frames on stdio transport. Diagnostics go to console.error. The only exception is doctor.ts, which runs outside the protocol.
• No retailer-specific values in code. Accounts, domains, and tokens come from the environment. This repo is public and generic.
• Rebuild and commit dist/. Plugin installs do not run a build step, so dist/ is intentionally tracked. A source change that is not rebuilt ships broken. Run npm run build before committing.
• Bump version in all four places when releasing: package.json, .claude-plugin/plugin.json, .claude-plugin/marketplace.json, and the VERSION constant in src/index.ts. Plugin users only receive updates when the manifest version changes, and VERSION is what the server announces to its client, so a missed bump makes the running server lie about which build it is. Check with: