image-generation-mcp: Instructions file for Claude Code

image-generation-mcp

FastMCP server scaffold. See TEMPLATE.md for customisation guide.

Design

Project Structure

src/image_generation_mcp/
  server.py            -- FastMCP server factory (make_server) + auth wiring
  config.py            -- env var loading; add domain config fields here
  cli.py               -- CLI entry point (serve command)
  _server_deps.py      -- lifespan + Depends() DI; replace placeholder service
  tools.py             -- MCP tools; replace example tools with domain tools
  resources.py         -- MCP resources; add domain resources here
  prompts.py           -- MCP prompts; add domain prompts here
  domain.py            -- ImageService + domain types (the service placeholder)

Conventions

• Python 3.11+
• uv for package management, ruff for linting/formatting (line length 88)
• hatchling build backend
• Conventional commits, one type from build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test — optionally scoped (feat(search): ...) and with ! for a breaking change. Only feat, fix, and the ! marker drive releases: feat cuts a minor, fix a patch, ! a major. Every other type — perf included — cuts nothing and never reaches CHANGELOG.md; a performance change that must ship on its own is either honestly a fix: (it fixes a performance defect) or released with Release Prepare's explicit override_version input.
• Google-style docstrings on all public functions
• logging.getLogger(__name__) throughout, no print()
• Type hints everywhere
• Tests: pytest with fixtures in tests/fixtures/

Pull-request titles are enforced, not merely encouraged. A squash merge takes the PR title as the commit subject, so CI's PR Title job checks it against the type list above and fails the CI Success aggregate when it does not match. This is not style policing: knope computes versions and writes CHANGELOG.md from those subjects, and it silently ignores a subject whose type it does not count — no fallback heading, no entry, no warning. That silent-drop class is exactly what the gate exists for: it keeps the history parseable and the accepted set deliberate. The changelog itself carries three sections per release — Breaking Changes first, then Features, then Bug Fixes — fed only by !/feat/fix subjects; the richness for everything else lives on the docs/releases/ notes page, not in the changelog.