substack-mcp: Instructions file for Claude Code

CLAUDE.md

MCP server exposing Substack automation to LLM clients. ESM, npm. Development, CI and the image run Node 24 — .nvmrc and Dockerfile pin 24.19.0 exactly — while engines declares >=22, so src/ may use nothing newer than Node 22 offers.

That floor is deliberate, not inherited: 22 is the oldest Node line still receiving security patches (18 went EOL 2025-04-30, 20 on 2026-04-30), and it is the lowest version every production dependency accepts — @hono/node-server asks for >=20, everything else >=18. Raising it breaks anyone running npx substack-mcp@latest on an older runtime, so it is a major bump; the honest ceiling is the oldest supported LTS, not the version that happens to be installed locally.

Two CI jobs run the suite: one on .nvmrc, one on the floor. The floor job derives its version from engines (node -p "require('./package.json').engines.node.match(/\d+/)[0]") rather than repeating it, so the promise and the test cannot drift. Developing two majors above the floor is precisely how an unexercised engines rots into a lie — the runtime differences are real and silent, as the fetch stack below shows.

Language

Everything in the repository is written in English — source, comments, test names, commit messages, PR titles and descriptions, docs. This holds regardless of the language used in the chat: do not mirror the conversation language into the codebase.

Commands

npm test runs in under a second, but its output shape depends on the Node version: on 24 it is the spec reporter (tally ℹ pass, failures marked ✖), on the 22 floor it is TAP — five times noisier, tally # pass, failures not ok. Grep for both, or a perfectly green run on the wrong version comes back empty and reads as a broken command: grep -E '^(#|ℹ) (tests|pass|fail)' for the tally, grep -E '^(not ok|✖)' for what broke.