npm - imgx-mcp - Versions diffs - 1.4.0 → 1.5.1 - Mend

imgx-mcp 1.4.0 → 1.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/CHANGELOG.md +31 -0
package/README.md +508 -481
package/dist/cli.bundle.js +16 -4
package/dist/image-generation-skill.zip +0 -0
package/dist/mcp.bundle.js +20 -10
package/package.json +1 -1
package/skills/image-generation/SKILL.md +8 -3

package/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,36 @@
 # Changelog
+## 1.5.1 (2026-03-05)
+### Fixed
+- **Re-release of v1.5.0** — v1.5.0 was unpublished during documentation review; npm does not allow re-publishing the same version. No code changes from v1.5.0.
+- **Documentation** — Added `.imgx/` directory location explanation, `output_dir`/history relationship, and updated SKILL.md tips
+## 1.5.0 (2026-03-05) [YANKED — npm does not allow re-publish]
+### Added
+- **User config `projectRoot` fallback** — `findProjectRoot()` now checks `projectRoot` in user config as a final fallback when env var, MCP roots, and `.imgxrc` detection all fail
+- **CLI `project-root` config key** — `imgx config set project-root /path/to/project` and `imgx config get project-root`
+- 3 new tests for `projectRoot` fallback (total: 84 tests)
+### Project root configuration (3 tiers)
+| Method | Scope | How to set |
+|--------|-------|------------|
+| `IMGX_PROJECT_ROOT` env var in client config | Per-client (highest priority) | Add to `env` in `claude_desktop_config.json`, `.mcp.json`, etc. |
+| Auto-detection (MCP roots / `.imgxrc` search) | Automatic | Works on CLI agents (Claude Code, Gemini CLI). Not available on Claude Desktop |
+| `imgx config set project-root` | All clients on the machine | Stored in `~/.config/imgx/config.json` or `%APPDATA%\imgx\config.json` |
+Detection priority: env var → MCP roots → `.imgxrc` upward search → user config `projectRoot`
+## 1.4.1 (2026-03-04)
+### Fixed
+- **MCP roots detection race condition** — `listRoots()` was called immediately after `server.connect()`, before the MCP initialization handshake completed. The request failed silently, causing `setProjectRoot()` to never execute and images to save to the fallback `~/Pictures/imgx/` instead of `<project-root>/.imgx/`. Now uses `oninitialized` callback to wait for handshake completion and checks `roots` capability before requesting.
 ## 1.4.0 (2026-03-04)
 ### Added

package/README.md CHANGED Viewed

@@ -1,481 +1,508 @@
-# imgx-mcp
-AI image generation and editing MCP server. Works with Claude Code, Gemini CLI, Cursor, Windsurf, and any MCP-compatible tool.
-Generate images from text, edit existing images with text instructions, iterate on results — all from your AI coding environment.
-## Quick start
-Add to your tool's MCP config (`.mcp.json`, `settings.json`, etc.):
-```json
-{
-  "mcpServers": {
-    "imgx": {
-      "command": "npx",
-      "args": ["--package=imgx-mcp", "-y", "imgx-mcp"],
-      "env": { "GEMINI_API_KEY": "your-key" }
-    }
-  }
-}
-```
-That's it. Your AI agent can now generate and edit images.
-> **Windows**: Replace `"command": "npx"` with `"command": "cmd"` and prepend `"/c"` to the args array.
-## Skill (Claude Code)
-For Claude Code users, imgx-mcp includes an `image-generation` skill — a guided prompt that teaches Claude how to use the MCP tools effectively. With the skill installed, type `/image-generation` to start a guided workflow.
-### Install the skill
-Copy the skill directory from the npm package or GitHub repository to your project:
-```bash
-# From npm (after npx has cached the package)
-cp -r $(npm root -g)/imgx-mcp/skills .claude/skills
-# Or from the GitHub repository
-curl -sL https://raw.githubusercontent.com/somacoffeekyoto/imgx-mcp/main/skills/image-generation/SKILL.md \
-  -o .claude/skills/image-generation/SKILL.md --create-dirs
-curl -sL https://raw.githubusercontent.com/somacoffeekyoto/imgx-mcp/main/skills/image-generation/references/providers.md \
-  -o .claude/skills/image-generation/references/providers.md --create-dirs
-```
-Or place skill files manually:
-```
-your-project/
-  .mcp.json                              ← MCP server config (Quick start above)
-  .claude/
-    skills/
-      image-generation/
-        SKILL.md                         ← skill prompt
-        references/
-          providers.md                   ← provider reference
-```
-The skill files are included in the [npm package](https://www.npmjs.com/package/imgx-mcp) under `skills/` and in the [GitHub repository](https://github.com/somacoffeekyoto/imgx-mcp/tree/main/skills/image-generation).
-> **Personal skill** (all projects): Place in `~/.claude/skills/image-generation/` instead of `.claude/skills/`.
-### Claude Desktop
-Claude Desktop supports skills via ZIP upload:
-1. Download [`image-generation-skill.zip`](dist/image-generation-skill.zip) from the repository (or find it in the [npm package](https://www.npmjs.com/package/imgx-mcp) under `dist/`)
-2. In Claude Desktop: **Settings > Profile > Customize > Skills > Add Skill**
-3. Upload the ZIP
-> Update the skill by re-downloading and re-uploading the ZIP after new releases.
-### What the skill does
-The skill guides Claude Code through image workflows: blog covers, iterative editing, provider comparison, icon generation. It knows the MCP tool parameters and best practices, so you get better results with less effort.
-### MCP server vs Skill
-| | MCP server | Skill |
-|---|---|---|
-| What it does | Exposes image tools to AI agents | Guided prompt for using the tools |
-| Works with | Any MCP-compatible tool | Claude Code, Claude Desktop |
-| Install | Add to `.mcp.json` | Copy skill files to project |
-| Team sharing | Commit `.mcp.json` to repo | Commit `.claude/skills/` to repo |
-**Recommended**: Set up the MCP server (Quick start) + install the skill if you use Claude Code.
-## MCP tools
-| Tool | Description |
-|------|-------------|
-| `generate_image` | Generate an image from a text prompt |
-| `edit_image` | Edit an existing image with text instructions |
-| `edit_last` | Edit the last generated/edited image (no input path needed) |
-| `undo_edit` | Undo the last edit, reverting to the previous image in the session |
-| `redo_edit` | Redo a previously undone edit |
-| `edit_history` | Show all sessions and their edit history with metadata |
-| `switch_session` | Switch to a different editing session |
-| `clear_history` | Clear project history (optionally delete image files) |
-| `set_output_dir` | Change the default output directory (optionally move existing files) |
-| `list_providers` | List available providers and capabilities |
-Images are saved to `<project-root>/.imgx/<session-id>/` when a project root is detected, or `~/Pictures/imgx/<session-id>/` otherwise. Each session gets its own directory. File paths are returned in the response. Inline image preview is included in MCP responses (base64).
-### Iterative editing
-The `edit_last` tool uses the output of the previous `generate_image` or `edit_image` call as input. This enables a conversational workflow:
-```
-"Generate a coffee shop interior" → generate_image
-"Make the lighting warmer"        → edit_last
-"Add a person reading a book"     → edit_last
-```
-No need to specify file paths between steps.
-### Session management
-Each `generate_image` call starts a new session. Subsequent `edit_last` calls are added to the same session, forming an edit chain. Each session has its own output directory.
-**Undo / Redo** — Step backward and forward through the edit chain:
-```
-generate → edit_last → edit_last → edit_last
-                                    ↑ current
-                       ← undo_edit
-                       ↑ current
-                            redo_edit →
-                                    ↑ current
-```
-After undo, calling `edit_last` branches from the current position (abandoned entries and their files are deleted from disk).
-**File naming** — `edit_last` generates sequential filenames based on the origin file:
-```
-generate_image             → cover.png
-edit_last                  → cover-1.png
-edit_last                  → cover-2.png
-generate_image (no output) → imgx-a1b2c3d4.png
-edit_last                  → imgx-a1b2c3d4-1.png
-```
-**Session switching** — Use `edit_history` to see all sessions, then `switch_session` to resume a previous session. The `edit_last` tool will use the current position in the switched session.
-**Output directory** — `edit_last` inherits the output directory from the session. If `generate_image` was called with `output_dir`, all subsequent `edit_last` calls in that session output to the same directory.
-## API key setup
-Set up at least one provider:
-**Gemini** — get a key from [Google AI Studio](https://aistudio.google.com/apikey) (free tier available):
-```bash
-imgx config set api-key YOUR_GEMINI_API_KEY --provider gemini
-```
-**OpenAI** — get a key from [OpenAI Platform](https://platform.openai.com/api-keys):
-```bash
-imgx config set api-key YOUR_OPENAI_API_KEY --provider openai
-```
-Keys are stored in `~/.config/imgx/config.json` (Linux/macOS) or `%APPDATA%\imgx\config.json` (Windows). Alternatively, pass keys via the `env` section in your MCP config, or set environment variables:
-```bash
-export GEMINI_API_KEY="your-api-key"
-export OPENAI_API_KEY="your-api-key"
-```
-Only include the API keys for providers you want to use. At least one is required.
-## MCP configuration by tool
-### Claude Code
-`.mcp.json` in your project root:
-```json
-{
-  "mcpServers": {
-    "imgx": {
-      "command": "npx",
-      "args": ["--package=imgx-mcp", "-y", "imgx-mcp"],
-      "env": { "GEMINI_API_KEY": "your-key", "OPENAI_API_KEY": "your-key" }
-    }
-  }
-}
-```
-### Gemini CLI
-`~/.gemini/settings.json`:
-```json
-{
-  "mcpServers": {
-    "imgx": {
-      "command": "npx",
-      "args": ["--package=imgx-mcp", "-y", "imgx-mcp"],
-      "env": { "GEMINI_API_KEY": "your-key", "OPENAI_API_KEY": "your-key" }
-    }
-  }
-}
-```
-### Claude Desktop
-`claude_desktop_config.json`:
-macOS / Linux:
-```json
-{
-  "mcpServers": {
-    "imgx": {
-      "command": "npx",
-      "args": ["--package=imgx-mcp", "-y", "imgx-mcp"],
-      "env": { "GEMINI_API_KEY": "your-key", "OPENAI_API_KEY": "your-key" }
-    }
-  }
-}
-```
-Windows:
-```json
-{
-  "mcpServers": {
-    "imgx": {
-      "command": "cmd",
-      "args": ["/c", "npx", "--package=imgx-mcp", "-y", "imgx-mcp"],
-      "env": { "GEMINI_API_KEY": "your-key", "OPENAI_API_KEY": "your-key" }
-    }
-  }
-}
-```
-Config file location: `%APPDATA%\Claude\claude_desktop_config.json` (Windows) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS). After editing, restart Claude Desktop.
-> **Note:** Claude Desktop runs the MCP server from its own app directory. To control image output location, add `"IMGX_OUTPUT_DIR": "C:\\Users\\you\\Pictures"` to the `env` section, or run `imgx config set output-dir <path>` beforehand.
-### Codex CLI
-`.codex/config.toml`:
-```toml
-[mcp_servers.imgx]
-command = "npx"
-args = ["--package=imgx-mcp", "-y", "imgx-mcp"]
-env = { GEMINI_API_KEY = "your-key", OPENAI_API_KEY = "your-key" }
-```
-### Other tools
-The same `npx` pattern works with Cursor, Windsurf, Continue.dev, Cline, Zed, and other MCP-compatible tools. On Windows, use `cmd /c npx` instead of `npx` directly.
-## Providers
-| Provider | Models | Capabilities |
-|----------|--------|-------------|
-| Gemini | `gemini-3-pro-image-preview`, `gemini-2.5-flash-image` | Generate, edit, aspect ratio, resolution, reference images, person control |
-| OpenAI | `gpt-image-1` | Generate, edit, aspect ratio, multi-output, output format (PNG/JPEG/WebP) |
-## Architecture
-imgx separates **model-independent** and **model-dependent** concerns:
-```
-MCP server (tool definitions, stdio transport)    CLI (argument parsing, output formatting)
- ↓                                                 ↓
-Core (Capability enum, ImageProvider interface, provider registry, file I/O, history)
- ↓
-Provider (model-specific API calls, capability declarations)
-```
-MCP server and CLI are two entry points into the same core. Both call the same provider functions.
-Each provider declares its supported capabilities. Adding a new provider means implementing the `ImageProvider` interface and registering it — no changes to the MCP or CLI layer.
-### Capability system
-| Capability | Description |
-|------------|-------------|
-| `TEXT_TO_IMAGE` | Generate images from text prompts |
-| `IMAGE_EDITING` | Edit images with text instructions |
-| `ASPECT_RATIO` | Control output aspect ratio |
-| `RESOLUTION_CONTROL` | Control output resolution |
-| `MULTIPLE_OUTPUTS` | Generate multiple images per request |
-| `REFERENCE_IMAGES` | Use reference images for guidance |
-| `PERSON_CONTROL` | Control person generation in output |
-| `OUTPUT_FORMAT` | Choose output format (PNG, JPEG, WebP) |
-## CLI
-imgx-mcp also works as a standalone command-line tool.
-### Install
-```bash
-npm install -g imgx-mcp
-```
-Requires Node.js 18+.
-### Usage
-```bash
-# Generate
-imgx generate -p "A coffee cup on a wooden table, morning light" -o output.png
-# Edit
-imgx edit -i photo.png -p "Change the background to sunset" -o edited.png
-# Iterative editing
-imgx edit -i photo.png -p "Make the background darker"
-imgx edit --last -p "Add warm lighting"
-imgx edit --last -p "Crop to 16:9" -o final.png
-# Undo / redo
-imgx undo               # Revert to previous image in session
-imgx redo               # Re-apply an undone edit
-# History
-imgx history            # Show all sessions and entries
-imgx history switch <session-id>  # Switch to a different session
-imgx history clear      # Clear project history (interactive)
-imgx history clear --yes          # Clear without confirmation
-imgx history clear --keep-files   # Clear history but keep image files
-imgx history clear --all          # Clear ALL history across all projects
-# Provider management
-imgx providers          # List providers and capabilities
-imgx capabilities       # Detailed capabilities of current provider
-```
-### CLI options
-| Flag | Short | Description |
-|------|-------|-------------|
-| `--prompt` | `-p` | Image description or edit instruction (required) |
-| `--output` | `-o` | Output file path (auto-generated if omitted) |
-| `--input` | `-i` | Input image to edit (`edit` command only) |
-| `--last` | `-l` | Use last output as input (`edit` command only) |
-| `--aspect-ratio` | `-a` | `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `2:3`, `3:2` |
-| `--resolution` | `-r` | `1K`, `2K`, `4K` |
-| `--count` | `-n` | Number of images to generate |
-| `--format` | `-f` | Output format: `png`, `jpeg`, `webp` (OpenAI only) |
-| `--model` | `-m` | Model name |
-| `--provider` | | Provider name (default: `gemini`) |
-| `--output-dir` | `-d` | Output directory |
-### Configuration
-```bash
-imgx config set api-key <key> --provider gemini   # Save Gemini API key
-imgx config set api-key <key> --provider openai   # Save OpenAI API key
-imgx config set model <name>      # Set default model
-imgx config set output-dir <dir>  # Set default output directory
-imgx config set aspect-ratio 16:9 # Set default aspect ratio
-imgx config set resolution 2K     # Set default resolution
-imgx config list                  # Show all settings
-imgx config get api-key           # Show a specific setting (API key is masked)
-imgx config path                  # Show config file location
-```
-### Project config (`.imgxrc`)
-Generate a template with `imgx init`:
-```bash
-imgx init
-# → creates .imgxrc in current directory
-```
-Or create manually:
-```json
-{
-  "defaults": {
-    "model": "gemini-2.5-flash-image",
-    "outputDir": "./assets/images",
-    "aspectRatio": "16:9"
-  }
-}
-```
-Project config is shared via Git. Do not put API keys in `.imgxrc`.
-When used via MCP (Claude Code, etc.), imgx-mcp automatically detects the project root from the client's workspace via MCP roots. When `.imgxrc` is present, that directory is used as the project root (CLI fallback). You can also set `IMGX_PROJECT_ROOT` environment variable explicitly. History is saved to `<project-root>/.imgx/output-history.json` (project-scoped, not shared with other projects). Default image output goes to `<project-root>/.imgx/<session-id>/`. Relative paths in `output` and `output_dir` are resolved against the project root instead of the MCP server's working directory.
-### Settings resolution
-1. CLI flags (`--model`, `--output-dir`, etc.)
-2. Environment variables (`IMGX_MODEL`, `IMGX_OUTPUT_DIR`, etc.)
-3. Project config (`.imgxrc` — searched from current directory upward)
-4. User config (`~/.config/imgx/config.json` or `%APPDATA%\imgx\config.json`)
-5. Provider defaults
-### Output format
-All CLI commands output JSON:
-```json
-{"success": true, "filePaths": ["./output.png"]}
-```
-## Claude Code plugin
-The plugin bundles MCP server + skill in one step. If you prefer not to configure `.mcp.json` and skill files manually:
-```
-/plugin marketplace add somacoffeekyoto/imgx-mcp
-/plugin install imgx-mcp@somacoffeekyoto-imgx-mcp
-```
-Update: `/plugin` → installed → imgx-mcp → update. If the update shows no changes, uninstall and reinstall.
-Uninstall: `/plugin uninstall imgx-mcp@somacoffeekyoto-imgx-mcp` then `/plugin marketplace remove somacoffeekyoto-imgx-mcp`.
-## Development
-```bash
-git clone https://github.com/somacoffeekyoto/imgx-mcp.git
-cd imgx-mcp
-npm install
-npm run bundle    # TypeScript compile + esbuild bundle
-```
-The build produces two bundles:
-- `dist/mcp.bundle.js` — MCP server entry point
-- `dist/cli.bundle.js` — CLI entry point
-## Uninstall
-### MCP server
-Remove the `imgx` entry from your tool's MCP configuration file.
-### Skill
-Delete the `image-generation/` directory from `.claude/skills/` or `~/.claude/skills/`.
-### CLI
-```bash
-npm uninstall -g imgx-mcp
-```
-`npm uninstall` removes the package but does not delete configuration or generated files. Remove them manually if needed:
-**Global configuration:**
-```bash
-# Linux / macOS
-rm -rf ~/.config/imgx/
-# Windows (PowerShell)
-Remove-Item -Recurse -Force "$env:APPDATA\imgx"
-```
-**Project history and images:** Each project may have a `.imgx/` directory containing edit history and generated images. Remove it from each project as needed.
-```bash
-rm -rf <project-root>/.imgx/
-```
-## License
-MIT — [SOMA COFFEE KYOTO](https://github.com/somacoffeekyoto)
-## Links
-- [Official page](https://somacoffee.net/imgx-mcp/)
-- [GitHub](https://github.com/somacoffeekyoto/imgx-mcp)
-- [npm](https://www.npmjs.com/package/imgx-mcp)
-- [MCP Registry](https://registry.modelcontextprotocol.io)
-- [SOMA COFFEE KYOTO](https://somacoffee.net)
-- [X (@somacoffeekyoto)](https://x.com/somacoffeekyoto)
+# imgx-mcp
+AI image generation and editing MCP server. Works with Claude Code, Gemini CLI, Cursor, Windsurf, and any MCP-compatible tool.
+Generate images from text, edit existing images with text instructions, iterate on results — all from your AI coding environment.
+## Quick start
+Add to your tool's MCP config (`.mcp.json`, `settings.json`, etc.):
+```json
+{
+  "mcpServers": {
+    "imgx": {
+      "command": "npx",
+      "args": ["--package=imgx-mcp", "-y", "imgx-mcp"],
+      "env": { "GEMINI_API_KEY": "your-key" }
+    }
+  }
+}
+```
+That's it. Your AI agent can now generate and edit images.
+> **Windows**: Replace `"command": "npx"` with `"command": "cmd"` and prepend `"/c"` to the args array.
+## Skill (Claude Code)
+For Claude Code users, imgx-mcp includes an `image-generation` skill — a guided prompt that teaches Claude how to use the MCP tools effectively. With the skill installed, type `/image-generation` to start a guided workflow.
+### Install the skill
+Copy the skill directory from the npm package or GitHub repository to your project:
+```bash
+# From npm (after npx has cached the package)
+cp -r $(npm root -g)/imgx-mcp/skills .claude/skills
+# Or from the GitHub repository
+curl -sL https://raw.githubusercontent.com/somacoffeekyoto/imgx-mcp/main/skills/image-generation/SKILL.md \
+  -o .claude/skills/image-generation/SKILL.md --create-dirs
+curl -sL https://raw.githubusercontent.com/somacoffeekyoto/imgx-mcp/main/skills/image-generation/references/providers.md \
+  -o .claude/skills/image-generation/references/providers.md --create-dirs
+```
+Or place skill files manually:
+```
+your-project/
+  .mcp.json                              ← MCP server config (Quick start above)
+  .claude/
+    skills/
+      image-generation/
+        SKILL.md                         ← skill prompt
+        references/
+          providers.md                   ← provider reference
+```
+The skill files are included in the [npm package](https://www.npmjs.com/package/imgx-mcp) under `skills/` and in the [GitHub repository](https://github.com/somacoffeekyoto/imgx-mcp/tree/main/skills/image-generation).
+> **Personal skill** (all projects): Place in `~/.claude/skills/image-generation/` instead of `.claude/skills/`.
+### Claude Desktop
+Claude Desktop supports skills via ZIP upload:
+1. Download [`image-generation-skill.zip`](dist/image-generation-skill.zip) from the repository (or find it in the [npm package](https://www.npmjs.com/package/imgx-mcp) under `dist/`)
+2. In Claude Desktop: **Settings > Profile > Customize > Skills > Add Skill**
+3. Upload the ZIP
+> Update the skill by re-downloading and re-uploading the ZIP after new releases.
+### What the skill does
+The skill guides Claude Code through image workflows: blog covers, iterative editing, provider comparison, icon generation. It knows the MCP tool parameters and best practices, so you get better results with less effort.
+### MCP server vs Skill
+| | MCP server | Skill |
+|---|---|---|
+| What it does | Exposes image tools to AI agents | Guided prompt for using the tools |
+| Works with | Any MCP-compatible tool | Claude Code, Claude Desktop |
+| Install | Add to `.mcp.json` | Copy skill files to project |
+| Team sharing | Commit `.mcp.json` to repo | Commit `.claude/skills/` to repo |
+**Recommended**: Set up the MCP server (Quick start) + install the skill if you use Claude Code.
+## MCP tools
+| Tool | Description |
+|------|-------------|
+| `generate_image` | Generate an image from a text prompt |
+| `edit_image` | Edit an existing image with text instructions |
+| `edit_last` | Edit the last generated/edited image (no input path needed) |
+| `undo_edit` | Undo the last edit, reverting to the previous image in the session |
+| `redo_edit` | Redo a previously undone edit |
+| `edit_history` | Show all sessions and their edit history with metadata |
+| `switch_session` | Switch to a different editing session |
+| `clear_history` | Clear project history (optionally delete image files) |
+| `set_output_dir` | Change the default output directory (optionally move existing files) |
+| `list_providers` | List available providers and capabilities |
+The `.imgx/` directory holds both edit history and default image output. Its location depends on project root detection:
+| Project root | `.imgx/` location | History |
+|---|---|---|
+| Detected | `<project-root>/.imgx/` | `<project-root>/.imgx/output-history.json` |
+| Not detected | `~/Pictures/imgx/` (images only) | `~/.config/imgx/output-history.json` (global) |
+All clients that resolve to the same project root share the same history. Each session gets its own subdirectory. File paths are returned in the response. Inline image preview is included in MCP responses (base64).
+### Iterative editing
+The `edit_last` tool uses the output of the previous `generate_image` or `edit_image` call as input. This enables a conversational workflow:
+```
+"Generate a coffee shop interior" → generate_image
+"Make the lighting warmer"        → edit_last
+"Add a person reading a book"     → edit_last
+```
+No need to specify file paths between steps.
+### Session management
+Each `generate_image` call starts a new session. Subsequent `edit_last` calls are added to the same session, forming an edit chain. Each session has its own output directory.
+**Undo / Redo** — Step backward and forward through the edit chain:
+```
+generate → edit_last → edit_last → edit_last
+                                    ↑ current
+                       ← undo_edit
+                       ↑ current
+                            redo_edit →
+                                    ↑ current
+```
+After undo, calling `edit_last` branches from the current position (abandoned entries and their files are deleted from disk).
+**File naming** — `edit_last` generates sequential filenames based on the origin file:
+```
+generate_image             → cover.png
+edit_last                  → cover-1.png
+edit_last                  → cover-2.png
+generate_image (no output) → imgx-a1b2c3d4.png
+edit_last                  → imgx-a1b2c3d4-1.png
+```
+**Session switching** — Use `edit_history` to see all sessions, then `switch_session` to resume a previous session. The `edit_last` tool will use the current position in the switched session.
+**Output directory** — `edit_last` inherits the output directory from the session. If `generate_image` was called with `output_dir`, all subsequent `edit_last` calls in that session output to the same directory. The `output_dir` path is recorded as session metadata in `output-history.json`. This only affects where image files are saved — history always stays in `.imgx/` (or the global config directory).
+## API key setup
+Set up at least one provider:
+**Gemini** — get a key from [Google AI Studio](https://aistudio.google.com/apikey) (free tier available):
+```bash
+imgx config set api-key YOUR_GEMINI_API_KEY --provider gemini
+```
+**OpenAI** — get a key from [OpenAI Platform](https://platform.openai.com/api-keys):
+```bash
+imgx config set api-key YOUR_OPENAI_API_KEY --provider openai
+```
+Keys are stored in `~/.config/imgx/config.json` (Linux/macOS) or `%APPDATA%\imgx\config.json` (Windows). Alternatively, pass keys via the `env` section in your MCP config, or set environment variables:
+```bash
+export GEMINI_API_KEY="your-api-key"
+export OPENAI_API_KEY="your-api-key"
+```
+Only include the API keys for providers you want to use. At least one is required.
+## MCP configuration by tool
+### Claude Code
+`.mcp.json` in your project root:
+```json
+{
+  "mcpServers": {
+    "imgx": {
+      "command": "npx",
+      "args": ["--package=imgx-mcp", "-y", "imgx-mcp"],
+      "env": { "GEMINI_API_KEY": "your-key", "OPENAI_API_KEY": "your-key" }
+    }
+  }
+}
+```
+### Gemini CLI
+`~/.gemini/settings.json`:
+```json
+{
+  "mcpServers": {
+    "imgx": {
+      "command": "npx",
+      "args": ["--package=imgx-mcp", "-y", "imgx-mcp"],
+      "env": { "GEMINI_API_KEY": "your-key", "OPENAI_API_KEY": "your-key" }
+    }
+  }
+}
+```
+### Claude Desktop
+`claude_desktop_config.json`:
+macOS / Linux:
+```json
+{
+  "mcpServers": {
+    "imgx": {
+      "command": "npx",
+      "args": ["--package=imgx-mcp", "-y", "imgx-mcp"],
+      "env": {
+        "GEMINI_API_KEY": "your-key",
+        "OPENAI_API_KEY": "your-key",
+        "IMGX_PROJECT_ROOT": ""
+      }
+    }
+  }
+}
+```
+Windows:
+```json
+{
+  "mcpServers": {
+    "imgx": {
+      "command": "cmd",
+      "args": ["/c", "npx", "--package=imgx-mcp", "-y", "imgx-mcp"],
+      "env": {
+        "GEMINI_API_KEY": "your-key",
+        "OPENAI_API_KEY": "your-key",
+        "IMGX_PROJECT_ROOT": ""
+      }
+    }
+  }
+}
+```
+`IMGX_PROJECT_ROOT` — Set to your project path to save images inside the project (e.g. `"C:\\Users\\you\\my-project"`). Leave empty to use the global default (`~/Pictures/imgx`).
+Config file location: `%APPDATA%\Claude\claude_desktop_config.json` (Windows) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS). After editing, restart Claude Desktop.
+> **Note:** Claude Desktop does not support auto-detection (MCP roots / CWD-based `.imgxrc` search). Use `IMGX_PROJECT_ROOT` in the config above (per-client), or run `imgx config set project-root /path/to/project` (shared across all clients).
+### Codex CLI
+`.codex/config.toml`:
+```toml
+[mcp_servers.imgx]
+command = "npx"
+args = ["--package=imgx-mcp", "-y", "imgx-mcp"]
+env = { GEMINI_API_KEY = "your-key", OPENAI_API_KEY = "your-key" }
+```
+### Other tools
+The same `npx` pattern works with Cursor, Windsurf, Continue.dev, Cline, Zed, and other MCP-compatible tools. On Windows, use `cmd /c npx` instead of `npx` directly.
+## Providers
+| Provider | Models | Capabilities |
+|----------|--------|-------------|
+| Gemini | `gemini-3-pro-image-preview`, `gemini-2.5-flash-image` | Generate, edit, aspect ratio, resolution, reference images, person control |
+| OpenAI | `gpt-image-1` | Generate, edit, aspect ratio, multi-output, output format (PNG/JPEG/WebP) |
+## Architecture
+imgx separates **model-independent** and **model-dependent** concerns:
+```
+MCP server (tool definitions, stdio transport)    CLI (argument parsing, output formatting)
+ ↓                                                 ↓
+Core (Capability enum, ImageProvider interface, provider registry, file I/O, history)
+ ↓
+Provider (model-specific API calls, capability declarations)
+```
+MCP server and CLI are two entry points into the same core. Both call the same provider functions.
+Each provider declares its supported capabilities. Adding a new provider means implementing the `ImageProvider` interface and registering it — no changes to the MCP or CLI layer.
+### Capability system
+| Capability | Description |
+|------------|-------------|
+| `TEXT_TO_IMAGE` | Generate images from text prompts |
+| `IMAGE_EDITING` | Edit images with text instructions |
+| `ASPECT_RATIO` | Control output aspect ratio |
+| `RESOLUTION_CONTROL` | Control output resolution |
+| `MULTIPLE_OUTPUTS` | Generate multiple images per request |
+| `REFERENCE_IMAGES` | Use reference images for guidance |
+| `PERSON_CONTROL` | Control person generation in output |
+| `OUTPUT_FORMAT` | Choose output format (PNG, JPEG, WebP) |
+## CLI
+imgx-mcp also works as a standalone command-line tool.
+### Install
+```bash
+npm install -g imgx-mcp
+```
+Requires Node.js 18+.
+### Usage
+```bash
+# Generate
+imgx generate -p "A coffee cup on a wooden table, morning light" -o output.png
+# Edit
+imgx edit -i photo.png -p "Change the background to sunset" -o edited.png
+# Iterative editing
+imgx edit -i photo.png -p "Make the background darker"
+imgx edit --last -p "Add warm lighting"
+imgx edit --last -p "Crop to 16:9" -o final.png
+# Undo / redo
+imgx undo               # Revert to previous image in session
+imgx redo               # Re-apply an undone edit
+# History
+imgx history            # Show all sessions and entries
+imgx history switch <session-id>  # Switch to a different session
+imgx history clear      # Clear project history (interactive)
+imgx history clear --yes          # Clear without confirmation
+imgx history clear --keep-files   # Clear history but keep image files
+imgx history clear --all          # Clear ALL history across all projects
+# Provider management
+imgx providers          # List providers and capabilities
+imgx capabilities       # Detailed capabilities of current provider
+```
+### CLI options
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--prompt` | `-p` | Image description or edit instruction (required) |
+| `--output` | `-o` | Output file path (auto-generated if omitted) |
+| `--input` | `-i` | Input image to edit (`edit` command only) |
+| `--last` | `-l` | Use last output as input (`edit` command only) |
+| `--aspect-ratio` | `-a` | `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `2:3`, `3:2` |
+| `--resolution` | `-r` | `1K`, `2K`, `4K` |
+| `--count` | `-n` | Number of images to generate |
+| `--format` | `-f` | Output format: `png`, `jpeg`, `webp` (OpenAI only) |
+| `--model` | `-m` | Model name |
+| `--provider` | | Provider name (default: `gemini`) |
+| `--output-dir` | `-d` | Output directory |
+### Configuration
+```bash
+imgx config set api-key <key> --provider gemini   # Save Gemini API key
+imgx config set api-key <key> --provider openai   # Save OpenAI API key
+imgx config set model <name>      # Set default model
+imgx config set output-dir <dir>  # Set default output directory
+imgx config set aspect-ratio 16:9 # Set default aspect ratio
+imgx config set resolution 2K     # Set default resolution
+imgx config list                  # Show all settings
+imgx config get api-key           # Show a specific setting (API key is masked)
+imgx config path                  # Show config file location
+```
+### Project config (`.imgxrc`)
+Generate a template with `imgx init`:
+```bash
+imgx init
+# → creates .imgxrc in current directory
+```
+Or create manually:
+```json
+{
+  "defaults": {
+    "model": "gemini-2.5-flash-image",
+    "outputDir": "./assets/images",
+    "aspectRatio": "16:9"
+  }
+}
+```
+Project config is shared via Git. Do not put API keys in `.imgxrc`.
+#### Project root configuration (3 tiers)
+| Method | Scope | How to set |
+|--------|-------|------------|
+| `IMGX_PROJECT_ROOT` env var in client config | Per-client (highest priority) | Add to `env` in `claude_desktop_config.json`, `.mcp.json`, etc. |
+| Auto-detection (MCP roots / `.imgxrc` search) | Automatic | Works on CLI agents (Claude Code, Gemini CLI). Not available on Claude Desktop |
+| `imgx config set project-root` | All clients on the machine | Stored in user config (`~/.config/imgx/config.json` or `%APPDATA%\imgx\config.json`) |
+Detection priority: env var → MCP roots → `.imgxrc` upward search → user config `projectRoot`.
+History is saved to `<project-root>/.imgx/output-history.json` (project-scoped, not shared with other projects). Default image output goes to `<project-root>/.imgx/<session-id>/`. Relative paths in `output` and `output_dir` are resolved against the project root instead of the MCP server's working directory.
+### Settings resolution
+1. CLI flags (`--model`, `--output-dir`, etc.)
+2. Environment variables (`IMGX_MODEL`, `IMGX_OUTPUT_DIR`, etc.)
+3. Project config (`.imgxrc` — searched from current directory upward)
+4. User config (`~/.config/imgx/config.json` or `%APPDATA%\imgx\config.json`)
+5. Provider defaults
+### Output format
+All CLI commands output JSON:
+```json
+{"success": true, "filePaths": ["./output.png"]}
+```
+## Claude Code plugin
+The plugin bundles MCP server + skill in one step. If you prefer not to configure `.mcp.json` and skill files manually:
+```
+/plugin marketplace add somacoffeekyoto/imgx-mcp
+/plugin install imgx-mcp@somacoffeekyoto-imgx-mcp
+```
+Update: `/plugin` → installed → imgx-mcp → update. If the update shows no changes, uninstall and reinstall.
+Uninstall: `/plugin uninstall imgx-mcp@somacoffeekyoto-imgx-mcp` then `/plugin marketplace remove somacoffeekyoto-imgx-mcp`.
+## Development
+```bash
+git clone https://github.com/somacoffeekyoto/imgx-mcp.git
+cd imgx-mcp
+npm install
+npm run bundle    # TypeScript compile + esbuild bundle
+```
+The build produces two bundles:
+- `dist/mcp.bundle.js` — MCP server entry point
+- `dist/cli.bundle.js` — CLI entry point
+## Uninstall
+### MCP server
+Remove the `imgx` entry from your tool's MCP configuration file.
+### Skill
+Delete the `image-generation/` directory from `.claude/skills/` or `~/.claude/skills/`.
+### CLI
+```bash
+npm uninstall -g imgx-mcp
+```
+`npm uninstall` removes the package but does not delete configuration or generated files. Remove them manually if needed:
+**Global configuration:**
+```bash
+# Linux / macOS
+rm -rf ~/.config/imgx/
+# Windows (PowerShell)
+Remove-Item -Recurse -Force "$env:APPDATA\imgx"
+```
+**Project history and images:** Each project may have a `.imgx/` directory containing edit history and generated images. Remove it from each project as needed.
+```bash
+rm -rf <project-root>/.imgx/
+```
+## License
+MIT — [SOMA COFFEE KYOTO](https://github.com/somacoffeekyoto)
+## Links
+- [Official page](https://somacoffee.net/imgx-mcp/)
+- [GitHub](https://github.com/somacoffeekyoto/imgx-mcp)
+- [npm](https://www.npmjs.com/package/imgx-mcp)
+- [MCP Registry](https://registry.modelcontextprotocol.io)
+- [SOMA COFFEE KYOTO](https://somacoffee.net)
+- [X (@somacoffeekyoto)](https://x.com/somacoffeekyoto)

package/dist/cli.bundle.js CHANGED Viewed

@@ -22071,6 +22071,11 @@ function findProjectRoot(startDir) {
       break;
     dir = parent;
   }
+  const config = loadConfig();
+  if (config.projectRoot) {
+    _cachedProjectRoot = config.projectRoot;
+    return config.projectRoot;
+  }
   _cachedProjectRoot = null;
   return null;
 }
@@ -39958,7 +39963,7 @@ function runConfig(args) {
     const key = filtered[0];
     const value = filtered[1];
     if (!key || !value) {
-      fail("Usage: imgx config set <key> <value> [--provider <name>]\n  Keys: api-key, provider, model, output-dir, aspect-ratio, resolution");
+      fail("Usage: imgx config set <key> <value> [--provider <name>]\n  Keys: api-key, provider, model, output-dir, aspect-ratio, resolution, project-root");
     }
     if (key === "output-dir") {
       setOutputDir(value, hasYes, hasNoMove);
@@ -40023,8 +40028,12 @@ function setKey(key, value, provider) {
       config.defaults.resolution = value;
       break;
     }
+    case "project-root": {
+      config.projectRoot = value;
+      break;
+    }
     default:
-      fail(`Unknown key: ${key}. Valid keys: api-key, provider, model, output-dir, aspect-ratio, resolution`);
+      fail(`Unknown key: ${key}. Valid keys: api-key, provider, model, output-dir, aspect-ratio, resolution, project-root`);
   }
   saveConfig(config);
   success({ key, status: "saved" });
@@ -40110,8 +40119,11 @@ function getKey(key, provider) {
     case "resolution":
       success({ key, value: config.defaults?.resolution ?? null });
       return;
+    case "project-root":
+      success({ key, value: config.projectRoot ?? null });
+      return;
     default:
-      fail(`Unknown key: ${key}. Valid keys: api-key, provider, model, output-dir, aspect-ratio, resolution`);
+      fail(`Unknown key: ${key}. Valid keys: api-key, provider, model, output-dir, aspect-ratio, resolution, project-root`);
   }
 }
 function showAll() {
@@ -40281,7 +40293,7 @@ function runRedo() {
 }
 // build/cli/index.js
-var VERSION2 = "1.4.0";
+var VERSION2 = "1.5.1";
 var HELP = `imgx v${VERSION2} \u2014 AI image generation and editing for MCP-compatible AI agents
 Commands:

package/dist/image-generation-skill.zip CHANGED Viewed

Binary file

package/dist/mcp.bundle.js CHANGED Viewed

@@ -6847,6 +6847,11 @@ function findProjectRoot(startDir) {
       break;
     dir = parent;
   }
+  const config2 = loadConfig();
+  if (config2.projectRoot) {
+    _cachedProjectRoot = config2.projectRoot;
+    return config2.projectRoot;
+  }
   _cachedProjectRoot = null;
   return null;
 }
@@ -69977,7 +69982,7 @@ function buildImageContent(images, paths, extra) {
 }
 var server = new McpServer({
   name: "imgx",
-  version: "1.4.0"
+  version: "1.5.1"
 });
 initGemini();
 initOpenAI();
@@ -70287,17 +70292,22 @@ function fileUriToPath(uri) {
 }
 async function main() {
   const transport = new StdioServerTransport();
-  await server.connect(transport);
-  try {
-    const result = await server.server.listRoots();
-    if (result.roots.length > 0) {
-      const rootUri = result.roots[0].uri;
-      if (rootUri.startsWith("file://")) {
-        setProjectRoot(fileUriToPath(rootUri));
+  server.server.oninitialized = async () => {
+    try {
+      const caps = server.server.getClientCapabilities();
+      if (!caps?.roots)
+        return;
+      const result = await server.server.listRoots();
+      if (result.roots.length > 0) {
+        const rootUri = result.roots[0].uri;
+        if (rootUri.startsWith("file://")) {
+          setProjectRoot(fileUriToPath(rootUri));
+        }
       }
+    } catch {
     }
-  } catch {
-  }
+  };
+  await server.connect(transport);
 }
 main().catch((err) => {
   console.error("MCP server error:", err);

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "imgx-mcp",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "mcpName": "io.github.somacoffeekyoto/imgx",
   "description": "AI image generation and editing for Claude Code, Codex CLI, and MCP-compatible AI agents",
   "type": "module",

package/skills/image-generation/SKILL.md CHANGED Viewed

@@ -144,11 +144,12 @@ Switch to a different editing session to continue work on a previous image chain
 ### clear_history
-Clear all edit history. Optionally delete image files.
+Clear edit history for the current project. Optionally delete image files in managed directories.
 | Parameter | Required | Description |
 |-----------|----------|-------------|
-| `delete_files` | No | Delete image files in session directories (default: false) |
+| `delete_files` | No | Delete image files in managed directories only (default: false) |
+| `session_id` | No | Session ID to clear. Omit to clear all sessions |
 ### set_output_dir
@@ -214,10 +215,14 @@ Generate the same prompt with different providers to let the user choose:
 - **Be specific in prompts**: "A wooden table with a ceramic pour-over dripper, steam rising, soft natural light from left" works better than "coffee scene"
 - **Use edit_last for iteration**: Don't ask the user to specify file paths. Just use `edit_last` after any generation or edit
 - **Check provider capabilities**: Use `list_providers` if unsure what a provider supports
-- **Default output**: Images save to `~/Pictures/imgx/` with auto-generated filenames. Use `output` or `output_dir` to customize
+- **Where `.imgx/` is created**: The `.imgx/` directory holds both edit history (`output-history.json`) and default image output. When a project root is detected, it's created at `<project-root>/.imgx/`. Without a project root, images go to `~/Pictures/imgx/` and history to `~/.config/imgx/`. All clients sharing the same project root share the same history
+- **Default output**: Images save to `<project-root>/.imgx/<session-id>/` (project auto-detected). Falls back to `~/Pictures/imgx/` when no project is detected. Use `output` or `output_dir` to customize
+- **Custom output_dir and history**: When `output_dir` is specified on `generate_image`, the path is recorded as session metadata in `output-history.json`. `edit_last` reads this to inherit the output location. Only image files go to the custom path — history always stays in `.imgx/` (or global config directory)
 - **Inline preview**: MCP responses include base64 image data for inline display in supported clients
 - **Undo/redo**: Use `undo_edit` and `redo_edit` to step through edit history. Each session holds up to 10 entries
 - **Sessions**: Each `generate_image` starts a new session. Use `edit_history` to see all sessions and `switch_session` to resume a previous one
+- **Sequential naming**: When `output` specifies a filename, `edit_last` appends sequential numbers: `cover.png` → `cover-1.png` → `cover-2.png`. Undo automatically deletes discarded files
+- **Project scope**: History is stored per-project in `<project-root>/.imgx/output-history.json`. `clear_history` only affects the current project
 ## CLI fallback