image-gen-mcp: Instructions file for Claude Code

CLAUDE.md

Project instructions for Claude when working in the image-gen-mcp repo.

What this is

A standalone stdio MCP server that generates and edits images with Gemini and OpenAI using the user's own API keys. It is published to npm as @nuver-labs/image-gen-mcp and to the MCP registry as com.nuverlabs/image-gen, under the Nuver Labs GitHub org. This repo is the single owner of that server: code, docs, and conventions live here, not in the projects that consume it.

Users install it with npx -y @nuver-labs/image-gen-mcp. Never reintroduce absolute local paths into the README or tool messages.

Hard rules

• NEVER use em dashes or en dashes anywhere: code comments, docs, commit messages, tool descriptions, README. Use periods, commas, colons, parentheses, or plain hyphens.
• stdout belongs to the MCP JSON-RPC protocol. No console.log in src/ (smoke.ts is the only exception, it is a standalone CLI). All diagnostics go through log() in src/config.ts (stderr). index.ts writes to stdout only for --version and --help, which exit before the transport connects.
• Never log, echo, or commit API key values. list_capabilities reports booleans only. Keys reach SDK constructors and nothing else.
• Expected failures return { isError: true, content: [text] } with an actionable message; do not throw them across the MCP boundary. Use ProviderError (src/providers/types.ts) and FileError (src/files.ts).
• The three tool names and their input schemas are a published contract. Renaming a tool or removing a field needs a major version.

Commands

• pnpm build: compile (tsc, ESM NodeNext; relative imports need .js extensions), then chmod the bin
• pnpm typecheck: tsc --noEmit
• pnpm test: node:test unit suite, no API keys needed
• pnpm inspect: build, then list tools over real MCP stdio
• node dist/smoke.js --provider gemini|openai [--edit path] [--out dir] [--model id]: live provider test, costs real API cents

Architecture