mcp-memes CLAUDE.md

CLAUDE.md

Guidance for Claude Code working in this repository.

What this is

An MCP server that hands a model a catalogue of meme formats, lets it pick five and caption them, and opens a browser-side editor as the deliverable. Deployed as a Cloudflare Worker. See README.md for the architecture and docs/deployment.md for the deploy.

Build first, always

npm run build

scripts/build-widget.mjs bakes the editor, the Anton font and the server icon into src/generated/assets.ts, and that file is gitignored. src/server.ts and src/render.ts import it, so without a build nothing compiles and nothing runs — not the tests, not the probe, not wrangler deploy. This is the single most common way to be confused in this repo.

npm test          # vitest, ~30 tests
npm run typecheck # tsc --noEmit

Invariants — do not break these

One copy of the layout rules. src/layout.ts is the only place layout logic lives. It is bundled into the browser editor and imported by the Node renderer, which is why what you edit is what you get. Never add layout maths to widget/main.ts or src/render.ts; both must stay callers. src/layout.ts must also stay pure — no DOM, no node: imports — because it runs in both. Text measurement is injected for exactly that reason.

No matching algorithm. Choosing formats is the model's job, deliberately. Do not add embedding search, scoring, or "best template" heuristics. The catalogue is exposed as readable resources and the model picks. resolveTemplate is identity mapping (an alias resolves to exactly one template or to nothing), not fuzzy matching; suggestTemplates only produces error-message hints.

The core is host-agnostic. src/server.ts knows nothing about transports. src/worker.ts, src/http.ts and src/stdio.ts are adapters over it. New host support means a new adapter, never a change to the core. Only src/http.ts may import express.

The editor is the answer. make_meme returns a deliberately content-free line annotated audience: ["user"], priority: 0.1, and the picks travel in structuredContent where the app reads them and the model does not. This is on purpose: naming the formats in the text invites the model to list them back in prose, which pushes the editor panel up out of the last turn. Do not "improve" that message by making it informative.