imagehearth-mcp 0.1.0b1__tar.gz

imagehearth_mcp-0.1.0b1/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+.venv/
+*.pyc
+engine.lock
+state/
+logs/
+output/
+.pytest_cache/
+.ruff_cache/
+dist

imagehearth_mcp-0.1.0b1/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 2026-10-31
+
+- Prepared the public beta `0.1.0b1`: `install.sh` and `install.ps1`, package metadata, `server.json` for the MCP Registry, rewritten READMEs, troubleshooting, release and beta testing guides, contribution and security policies, and issue templates.
+- Connected agents with `connect`, with `connect --print` for any other client and `docs/agents.md`, and reported progress so long generations aren't cut off.
+- Replaced `generate_image` and `edit_image` with a single `create_image`, and made the essential instructions part of the server, for agents without skills.
+- Added `setup_status` and `setup_start`, so an agent can run the installation after asking the user.
+- Added `memory_mode` and memory providers for LM Studio, llama.cpp and vLLM, alongside Ollama.
+- Made the catalog depend on what's installed: errors name the exact `setup` command, never another model. Added measured profiles, and macOS prepared without testing behind `--experimental`.
+- Added `setup`, `doctor`, `update` and `uninstall`: pinned ComfyUI, resumable and verified model downloads, consent before downloading, and checks before starting.
+- Made the core portable to Windows and macOS, and made Ollama optional. Fixed the status node, and never restarts a ComfyUI it didn't start.
+- Packaged the project as `imagehearth-mcp`, with its configuration in `config.toml`. Added the licenses and third-party notices, and local checks with `scripts/check.sh`.
+
+## 2026-10-30
+
+- First state of the project as ImageEngine: session recovery, deadlines and validation, configuration, rotating logs, persistent state and the status node.

imagehearth_mcp-0.1.0b1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hemoglobin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

imagehearth_mcp-0.1.0b1/PKG-INFO

@@ -0,0 +1,278 @@
+Metadata-Version: 2.5
+Name: imagehearth-mcp
+Version: 0.1.0b1
+Summary: MCP server that lets AI agents generate and edit images locally through ComfyUI
+Project-URL: Homepage, https://github.com/RealHemoglobin/ImageHearth
+Project-URL: Documentation, https://github.com/RealHemoglobin/ImageHearth#readme
+Project-URL: Issues, https://github.com/RealHemoglobin/ImageHearth/issues
+Project-URL: Changelog, https://github.com/RealHemoglobin/ImageHearth/blob/main/CHANGELOG.md
+Author: Hemoglobin
+License-Expression: MIT AND GPL-3.0-only
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
+License-File: src/imagehearth_mcp/data/imagehearth_status/LICENSE
+Keywords: ai-agents,comfyui,flux,image-generation,mcp,model-context-protocol
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: GPU :: NVIDIA CUDA
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: Microsoft :: Windows :: Windows 11
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.13
+Requires-Dist: filelock>=4.2.5
+Requires-Dist: huggingface-hub<3,>=1
+Requires-Dist: mcp<2,>=1.30
+Requires-Dist: pillow<14,>=13
+Requires-Dist: platformdirs<5,>=4
+Requires-Dist: psutil>=7.2.2
+Requires-Dist: pyyaml<7,>=6
+Requires-Dist: requests<3,>=2.34
+Description-Content-Type: text/markdown
+
+# ImageHearth
+
+**Give any AI agent the ability to generate and edit images on your own PC.** No subscription, no cloud: your prompts and images stay on your machine.
+
+ImageHearth is an [MCP](https://modelcontextprotocol.io) server that connects agents such as Claude Code or Codex to [ComfyUI](https://github.com/Comfy-Org/ComfyUI).
+
+<!-- mcp-name: io.github.RealHemoglobin/imagehearth -->
+
+[Leer en español](https://github.com/RealHemoglobin/ImageHearth/blob/main/README.es.md)
+
+**Public beta.** Install it with one command, and if something fails, [tell us](https://github.com/RealHemoglobin/ImageHearth/blob/main/docs/troubleshooting.md#reporting-a-problem).
+
+```bash
+# Linux
+curl -LsSf https://raw.githubusercontent.com/RealHemoglobin/ImageHearth/main/install.sh | sh
+```
+
+```powershell
+# Windows
+irm https://raw.githubusercontent.com/RealHemoglobin/ImageHearth/main/install.ps1 | iex
+```
+
+## What you can ask your agent
+
+- *"Generate a poster of a futuristic city at night"*: quick draft with SDXL Turbo.
+- *"Make a high-quality 1536x1024 image of a medieval castle"*: FLUX Dev.
+- *"Change the background of `photo.png` to a snowy mountain"*: FLUX Kontext.
+- *"Combine these three pictures into one scene"*: up to six reference images.
+
+If you also run local language models, ImageHearth frees them from GPU memory while generating and restores them afterwards. Ollama has been tested for real; LM Studio, llama.cpp and vLLM only against simulated servers.
+
+## Requirements
+
+| | |
+|---|---|
+| **GPU** | NVIDIA series 20 or newer with a current driver. Only measured on an RTX 4090 with 24 GB; see the [measurements](#measured-requirements). Less memory may be slow or fail with the FLUX models |
+| **Disk** | 7.2 GB for ComfyUI and its environment, plus the profile you choose |
+| **Software** | Nothing to install first: the script installs [uv](https://docs.astral.sh/uv/), which brings its own Python. Git isn't needed. [Ollama](https://ollama.com/download) is optional |
+
+### Support
+
+Only what has run on real hardware is announced as supported.
+
+| System and GPU | Level |
+|---|---|
+| Linux, NVIDIA series 20 or newer | **Supported.** Tested on real hardware |
+| Windows 11, NVIDIA series 20 or newer | **Target of this beta.** Its verification on clean machines is pending |
+| NVIDIA series 10 or older, AMD, Intel Arc, CPU only | **Experimental.** Detected and offered with a warning, never tested. CPU only runs `fast` |
+| macOS on Apple Silicon | **Untested.** Prepared behind `--experimental`: see [below](#macos-untested) |
+
+### Measured requirements
+
+Measured with `scripts/measure_profiles.py` at 1024x1024 (Kontext with one reference): RTX 4090 24 GB, driver 580.178, Linux, ComfyUI 0.43.0, on 2026-10-31.
+
+| Workflow | Profile | Peak VRAM | Peak RAM | First generation | Next generations |
+|---|---|---|---|---|---|
+| SDXL Turbo | `fast` | 7.0 GB | 2.6 GB | 3.6 s | 1.0 s |
+| FLUX Dev | `quality` | 17.8 GB | 2.3 GB | 13.8 s | 10.4 s |
+| FLUX Kontext | `full` | 19.3 GB | 2.4 GB | 21.0 s | 18.6 s |
+
+- These are peaks on a 24 GB card, not minimums: ComfyUI uses the memory it finds and can offload on smaller cards. The minimums for other GPUs are only a guide.
+- "First generation" comes after unloading the models from the GPU, with the files still in the system's disk cache. Loading from a cold disk takes longer.
+- The Windows measurements are still pending.
+
+> **Note:** local model servers are optional. If one isn't running, ImageHearth skips it and the status stays `ready`. See `memory_mode` in the [settings](#settings-optional).
+
+### A language model and images on the same GPU
+
+Measured on the same RTX 4090 with `qwen3.5:9b`, which needs 14.3 GB with Ollama's default context and 5.9 GB with `num_ctx` 8192. With `memory_mode = "auto"` it doesn't matter: the model is unloaded while generating and comes back afterwards. To keep both loaded (`manual` or `off`), the card must hold the language model plus the workflow's peak: with 5.9 GB and SDXL Turbo, the GPU peaked at 19.2 GB, about 3 GB of it from the desktop. With 5.9 GB and FLUX Dev it filled the 24 GB and worked, in 14-16 s, with `memory_mode = "off"`. In `manual`, generation is refused if free memory is below 8 GB for SDXL Turbo or 16 GB for FLUX, so that same case is refused there.
+
+## Installation
+
+### 1. Run the installer
+
+Pick the level you prefer. All three end the same way: uv, `imagehearth-mcp`, `setup` and `connect --detect`.
+
+**Simplest: one command.** Use the one for your system from the [top of this page](#imagehearth).
+
+**From a cloned repository.** Download the code and run `install`, so you can read what it will do first:
+
+```bash
+# Linux
+git clone https://github.com/RealHemoglobin/ImageHearth.git
+cd ImageHearth
+./install.sh
+```
+
+```powershell
+# Windows
+git clone https://github.com/RealHemoglobin/ImageHearth.git
+cd ImageHearth
+.\install.ps1
+```
+
+Without Git, download the ZIP from GitHub and run the same script inside the folder. From a clone, it installs that code, not the published package. If PowerShell blocks the script, run `powershell -ExecutionPolicy Bypass -File .\install.ps1`.
+
+**Most advanced: by hand.** With [uv](https://docs.astral.sh/uv/getting-started/installation/) installed:
+
+```bash
+uv tool install imagehearth-mcp==0.1.0b1
+imagehearth-mcp setup
+imagehearth-mcp connect --detect
+```
+
+The scripts are short: [`install.sh`](https://github.com/RealHemoglobin/ImageHearth/blob/main/install.sh) and [`install.ps1`](https://github.com/RealHemoglobin/ImageHearth/blob/main/install.ps1). They:
+
+1. Install uv with its official installer, if it's missing.
+2. Install `imagehearth-mcp`: at a pinned version, or the clone's code if run from one.
+3. Run `setup` and `connect --detect`, which ask you before downloading or changing anything.
+
+They never ask for `sudo` or administrator rights, and never accept a license for you. You can run them again safely.
+
+### 2. What setup does
+
+Setup detects your hardware and any existing ComfyUI, proposes a profile, and shows the disk space and licenses **before downloading anything**. Then it installs ComfyUI and the models and generates a test image. If it's interrupted, run it again and it continues where it stopped.
+
+| Profile | What you get | Models |
+|---|---|---|
+| `fast` | Quick generation with SDXL Turbo | 6.9 GB |
+| `quality` | `fast` + FLUX Dev | 24.6 GB |
+| `full` | `quality` + editing with FLUX Kontext | 36.5 GB |
+
+You can start with `fast` and run `setup --profile full` later: what's already there isn't downloaded again. ImageHearth only offers what's installed: `list_workflows` shows it, a later `setup` is noticed without restarting anything, and asking for something missing fails with the exact `setup` command, never with another model instead.
+
+| Option | Use |
+|---|---|
+| `--profile fast\|quality\|full` | Choose the profile without asking. On macOS: `mac-fast\|mac-quality\|mac-full` |
+| `--experimental` | Required on macOS, which is untested |
+| `--accept-licenses` | Accept the licenses without asking. Required with `--non-interactive` |
+| `--non-interactive` | Never ask: fail if a decision is missing |
+| `--managed` | Install a ComfyUI of its own, even if another exists |
+| `--attach PATH` | Use the existing ComfyUI in `PATH` |
+| `--install-node` | Allow installing the status node in an attached ComfyUI |
+| `--models-dir PATH` | Keep the models in `PATH`, shared through `extra_model_paths.yaml` |
+| `--port PORT` | Port ComfyUI listens on |
+| `--skip-smoke-test` | Don't generate the test image |
+
+Set `HF_TOKEN` if Hugging Face restricts access to a model.
+
+#### macOS (untested)
+
+**ImageHearth has never been run on a Mac, and macOS is not supported.** To try it, add the flag to the installer: `curl -LsSf https://raw.githubusercontent.com/RealHemoglobin/ImageHearth/main/install.sh | sh -s -- --experimental`. Setup is prepared for Apple Silicon, with GGUF models (`mac-fast` 6.9 GB, `mac-quality` 19.2 GB, `mac-full` 27.6 GB) and the `ComfyUI-GGUF` node. The GGUF workflows were run on an NVIDIA GPU, which checks the graph and the files but not MPS. Macs with Intel aren't supported. If you try it, please report how it went, with the output of `imagehearth-mcp doctor --json`.
+
+**Using a ComfyUI you already have.** With `--attach`, or by choosing it when asked, ImageHearth uses it instead of installing another, and doesn't download the models it already has. Your ComfyUI is only changed if you allow the status node to be installed. ComfyUI Desktop has to be open, since ImageHearth can't start it.
+
+### 3. Check, update or remove it
+
+The installer doesn't change your `PATH`. If `imagehearth-mcp` isn't found, run `uv tool update-shell` and open a new terminal.
+
+```bash
+imagehearth-mcp doctor
+```
+
+It checks each layer and says how to fix what fails. Add `--json` for a stable format, or `--verify-hashes` to compare the SHA-256 of each model instead of its size. It exits with a non-zero code if something fails.
+
+```bash
+imagehearth-mcp update
+```
+
+It applies the ComfyUI version and models pinned by this version of ImageHearth. An attached ComfyUI is left alone, except for a status node that setup installed.
+
+```bash
+imagehearth-mcp uninstall
+```
+
+It shows what it will remove and removes only what setup and `connect` installed. Models need a separate confirmation (`--remove-models` or `--keep-models` to decide in advance, `--yes` to skip the first question). A ComfyUI or models that were already there are never touched. To remove the command itself, run `uv tool uninstall imagehearth-mcp`.
+
+### Settings (optional)
+
+`setup` writes what it needs in `~/.config/imagehearth/config.toml` on Linux and `%APPDATA%\imagehearth\config.toml` on Windows. You can also edit it:
+
+```toml
+comfy_dir = "~/AI/ComfyUI"      # where ComfyUI is installed
+comfy_port = 8188               # port ComfyUI listens on
+output_dir = "~/Pictures/ImageHearth"
+ollama_url = "http://127.0.0.1:11434"
+memory_mode = "auto"            # "auto", "off" or "manual", see below
+lmstudio_url = "http://127.0.0.1:1234"
+llamacpp_url = "http://127.0.0.1:8080"
+vllm_url = "http://127.0.0.1:8000"
+```
+
+Each key can also be set with an environment variable: `IMAGEHEARTH_COMFY_DIR`, `IMAGEHEARTH_COMFY_PORT`, `IMAGEHEARTH_OUTPUT_DIR`, `IMAGEHEARTH_OLLAMA_URL`, `IMAGEHEARTH_LMSTUDIO_URL`, `IMAGEHEARTH_LLAMACPP_URL`, `IMAGEHEARTH_VLLM_URL` and `IMAGEHEARTH_MEMORY_MODE`. Variables win over the file, and the file wins over the defaults.
+
+| `memory_mode` | What happens to your language models |
+|---|---|
+| `auto` | Unloaded before generating and restored afterwards. If a server can't unload (see below), you get a warning with what to do, or an error before starting if the memory isn't enough |
+| `manual` | Never touched. Generation fails with an explanation if the free memory isn't enough |
+| `off` | Never touched, and memory isn't checked |
+
+The older `ollama_mode` still works as an alias for `auto` or `off`; `memory_mode` wins if both are set.
+
+| Server | Can ImageHearth free its memory? |
+|---|---|
+| Ollama | Yes |
+| LM Studio | Yes, with its REST API v1. Older versions: warning only |
+| llama.cpp | Only in router mode. A single-model `llama-server` can't unload: warning only |
+| vLLM | Only when started with `VLLM_SERVER_DEV_MODE=1` and `--enable-sleep-mode`. Otherwise: warning only |
+
+### 4. Connect your agent
+
+The installer already ran `imagehearth-mcp connect --detect`, which finds the installed clients and offers to connect them. Run it again after installing a new one. You can also run `connect <client>`, or `connect --print <client>` to see the snippet without changing anything. It makes a backup, keeps your other entries and can be repeated.
+
+**Tested:** Claude Code, Codex, opencode, Hermes and pi. **Untested**, checked against their documentation only: Claude Desktop, Gemini CLI, Cursor, VS Code and JetBrains. Details and snippets are in [`docs/agents.md`](https://github.com/RealHemoglobin/ImageHearth/blob/main/docs/agents.md). You can also ask an agent to do the installation with [`llms-install.md`](https://github.com/RealHemoglobin/ImageHearth/blob/main/llms-install.md).
+
+### 5. Try it
+
+Restart your agent and ask:
+
+> Generate an image of a red bicycle on a beach, using the fast quality.
+
+ComfyUI starts on its own. The first image takes longer because the model has to load. Images are saved in `~/Pictures/ImageHearth/`.
+
+## Troubleshooting
+
+Run `imagehearth-mcp doctor`, or ask your agent to *"check the ImageHearth status"*. Common problems and how to report one are in [`docs/troubleshooting.md`](https://github.com/RealHemoglobin/ImageHearth/blob/main/docs/troubleshooting.md).
+
+ImageHearth only restarts or stops a ComfyUI it started itself (it records its PID in the data folder). If you run ComfyUI on the same port, ImageHearth uses it but never restarts it.
+
+## Model licenses
+
+The models are not part of this project and have their own terms. **By downloading them, you accept those terms.** This summary is not legal advice; see [`THIRD_PARTY_NOTICES.md`](https://github.com/RealHemoglobin/ImageHearth/blob/main/THIRD_PARTY_NOTICES.md) for details.
+
+| Model | License | Short version |
+|---|---|---|
+| FLUX.1 Dev | [FLUX.1 [dev] Non-Commercial](https://bfl.ai/legal/non-commercial-license-terms) | Non-commercial use of the model |
+| FLUX.1 Kontext Dev | [FLUX.1 [dev] Non-Commercial](https://bfl.ai/legal/non-commercial-license-terms) | Non-commercial use of the model |
+| SDXL Turbo | [Stability AI Community](https://huggingface.co/stabilityai/sdxl-turbo/blob/main/LICENSE.md) | Commercial use requires registration and has a revenue limit |
+
+## Development
+
+```bash
+uv sync
+uv run ruff check .
+uv run pytest
+```
+
+This needs [uv](https://docs.astral.sh/uv/getting-started/installation/), which creates its own environment in `.venv`, separate from ComfyUI's. The tests use simulated servers and don't need a GPU. See [`CONTRIBUTING.md`](https://github.com/RealHemoglobin/ImageHearth/blob/main/CONTRIBUTING.md) to contribute, and the [roadmap](https://github.com/RealHemoglobin/ImageHearth/blob/main/specs/roadmap.md) for what's planned. To help test the beta, see [`docs/beta-testing.md`](https://github.com/RealHemoglobin/ImageHearth/blob/main/docs/beta-testing.md). To report a vulnerability, see [`SECURITY.md`](https://github.com/RealHemoglobin/ImageHearth/blob/main/SECURITY.md).
+
+## License
+
+[MIT](https://github.com/RealHemoglobin/ImageHearth/blob/main/LICENSE), except the ComfyUI custom node in [`src/imagehearth_mcp/data/imagehearth_status/`](https://github.com/RealHemoglobin/ImageHearth/blob/main/src/imagehearth_mcp/data/imagehearth_status/LICENSE), which is GPL-3.0. Third-party components and models are listed in [`THIRD_PARTY_NOTICES.md`](https://github.com/RealHemoglobin/ImageHearth/blob/main/THIRD_PARTY_NOTICES.md).

imagehearth_mcp-0.1.0b1/README.es.md

@@ -0,0 +1,240 @@
+# ImageHearth
+
+**Dale a cualquier agente de IA la capacidad de generar y editar imágenes en tu propio PC.** Sin suscripciones ni nube: tus prompts e imágenes se quedan en tu equipo.
+
+ImageHearth es un servidor [MCP](https://modelcontextprotocol.io) que conecta agentes como Claude Code o Codex con [ComfyUI](https://github.com/Comfy-Org/ComfyUI).
+
+[Read in English](https://github.com/RealHemoglobin/ImageHearth/blob/main/README.md)
+
+**Beta pública.** Se instala con un comando y, si algo falla, [cuéntanoslo](https://github.com/RealHemoglobin/ImageHearth/blob/main/docs/troubleshooting.md#reporting-a-problem).
+
+```bash
+# Linux
+curl -LsSf https://raw.githubusercontent.com/RealHemoglobin/ImageHearth/main/install.sh | sh
+```
+
+```powershell
+# Windows
+irm https://raw.githubusercontent.com/RealHemoglobin/ImageHearth/main/install.ps1 | iex
+```
+
+## Qué le puedes pedir a tu agente
+
+- *"Genera un póster de una ciudad futurista de noche"*: borrador rápido con SDXL Turbo.
+- *"Haz una imagen de alta calidad de 1536x1024 de un castillo medieval"*: FLUX Dev.
+- *"Cambia el fondo de `foto.png` por una montaña nevada"*: FLUX Kontext.
+- *"Combina estas tres fotos en una sola escena"*: hasta seis imágenes de referencia.
+
+Si también usas modelos de lenguaje locales, ImageHearth los libera de la memoria de la GPU mientras genera y los restaura después. Ollama se ha probado de verdad; LM Studio, llama.cpp y vLLM, solo con servidores simulados.
+
+## Requisitos
+
+| | |
+|---|---|
+| **GPU** | NVIDIA serie 20 o posterior con un controlador actual. Solo medido en una RTX 4090 de 24 GB; consulta las [mediciones](#requisitos-medidos). Con menos memoria puede ir lento o fallar con los modelos FLUX |
+| **Disco** | 7,2 GB para ComfyUI y su entorno, más el perfil que elijas |
+| **Software** | Nada que instalar antes: el script instala [uv](https://docs.astral.sh/uv/), que trae su propio Python. No hace falta Git. [Ollama](https://ollama.com/download) es opcional |
+
+### Soporte
+
+Solo se anuncia como soportado lo que se ha ejecutado en hardware real.
+
+| Sistema y GPU | Nivel |
+|---|---|
+| Linux, NVIDIA serie 20 o posterior | **Soportado.** Probado en hardware real |
+| Windows 11, NVIDIA serie 20 o posterior | **Objetivo de esta beta.** Falta verificarlo en máquinas limpias |
+| NVIDIA serie 10 o anterior, AMD, Intel Arc, solo CPU | **Experimental.** Se detecta y se ofrece con un aviso, sin haberse probado. Solo con CPU funciona `fast` |
+| macOS con Apple Silicon | **Sin probar.** Preparado tras `--experimental`: consulta [más abajo](#macos-sin-probar) |
+
+### Requisitos medidos
+
+Medido con `scripts/measure_profiles.py` a 1024x1024 (Kontext con una referencia): RTX 4090 de 24 GB, controlador 580.178, Linux, ComfyUI 0.43.0, el 2026-10-31.
+
+| Workflow | Perfil | Pico de VRAM | Pico de RAM | Primera generación | Siguientes |
+|---|---|---|---|---|---|
+| SDXL Turbo | `fast` | 7,0 GB | 2,6 GB | 3,6 s | 1,0 s |
+| FLUX Dev | `quality` | 17,8 GB | 2,3 GB | 13,8 s | 10,4 s |
+| FLUX Kontext | `full` | 19,3 GB | 2,4 GB | 21,0 s | 18,6 s |
+
+- Son picos en una tarjeta de 24 GB, no mínimos: ComfyUI usa la memoria que encuentra y puede descargar parte en tarjetas menores. Los mínimos para otras GPU son solo orientativos.
+- La «primera generación» es tras descargar los modelos de la GPU, con los archivos aún en la caché de disco del sistema. Cargar desde un disco en frío tarda más.
+- Las mediciones de Windows siguen pendientes.
+
+> **Nota:** los servidores de modelos locales son opcionales. Si uno no está en marcha, ImageHearth lo ignora y el estado sigue siendo `ready`. Consulta `memory_mode` en los ajustes.
+
+### Un modelo de lenguaje e imágenes en la misma GPU
+
+Medido en la misma RTX 4090 con `qwen3.5:9b`, que necesita 14,3 GB con el contexto por defecto de Ollama y 5,9 GB con `num_ctx` 8192. Con `memory_mode = "auto"` da igual: el modelo se descarga mientras se genera y vuelve después. Para tener los dos cargados (`manual` u `off`), la tarjeta debe albergar el modelo de lenguaje más el pico del workflow: con 5,9 GB y SDXL Turbo, la GPU llegó a 19,2 GB, unos 3 GB de ellos del escritorio. Con 5,9 GB y FLUX Dev llenó los 24 GB y funcionó, en 14-16 s, con `memory_mode = "off"`. En `manual`, la generación se rechaza si hay menos de 8 GB libres para SDXL Turbo o de 16 GB para FLUX, así que ese mismo caso se rechaza ahí.
+
+## Instalación
+
+### 1. Ejecuta el instalador
+
+Elige el nivel que prefieras. Los tres terminan igual: uv, `imagehearth-mcp`, `setup` y `connect --detect`.
+
+**Lo más simple: un comando.** Usa el de tu sistema del [principio de esta página](#imagehearth).
+
+**Con el repositorio clonado.** Descarga el código y ejecuta `install`; así puedes leer antes lo que va a hacer:
+
+```bash
+# Linux
+git clone https://github.com/RealHemoglobin/ImageHearth.git
+cd ImageHearth
+./install.sh
+```
+
+```powershell
+# Windows
+git clone https://github.com/RealHemoglobin/ImageHearth.git
+cd ImageHearth
+.\install.ps1
+```
+
+Sin Git, descarga el ZIP desde GitHub y ejecuta el mismo script dentro de la carpeta. Desde un clon se instala ese código, no el paquete publicado. Si PowerShell bloquea el script, ejecuta `powershell -ExecutionPolicy Bypass -File .\install.ps1`.
+
+**Lo más avanzado: a mano.** Con [uv](https://docs.astral.sh/uv/getting-started/installation/) instalado:
+
+```bash
+uv tool install imagehearth-mcp==0.1.0b1
+imagehearth-mcp setup
+imagehearth-mcp connect --detect
+```
+
+Los scripts son breves: [`install.sh`](https://github.com/RealHemoglobin/ImageHearth/blob/main/install.sh) e [`install.ps1`](https://github.com/RealHemoglobin/ImageHearth/blob/main/install.ps1). Hacen esto:
+
+1. Instalan uv con su instalador oficial, si falta.
+2. Instalan `imagehearth-mcp`: en una versión fijada, o el código del clon si lo ejecutas desde uno.
+3. Ejecutan `setup` y `connect --detect`, que te preguntan antes de descargar o cambiar nada.
+
+Nunca piden `sudo` ni permisos de administrador, ni aceptan una licencia por ti. Puedes repetirlos sin problema.
+
+### 2. Qué hace setup
+
+Setup detecta tu hardware y cualquier ComfyUI existente, propone un perfil y muestra el espacio y las licencias **antes de descargar nada**. Después instala ComfyUI y los modelos y genera una imagen de prueba. Si se interrumpe, vuelve a ejecutarlo y continúa donde se quedó.
+
+| Perfil | Qué incluye | Modelos |
+|---|---|---|
+| `fast` | Generación rápida con SDXL Turbo | 6,9 GB |
+| `quality` | `fast` + FLUX Dev | 24,6 GB |
+| `full` | `quality` + edición con FLUX Kontext | 36,5 GB |
+
+Puedes empezar con `fast` y ejecutar `setup --profile full` más adelante: lo que ya está no se vuelve a descargar. ImageHearth solo ofrece lo instalado: `list_workflows` lo muestra, un `setup` posterior se nota sin reiniciar nada, y pedir algo que falta da un error con el comando de `setup` exacto, nunca otro modelo en su lugar.
+
+| Opción | Uso |
+|---|---|
+| `--profile fast\|quality\|full` | Elige el perfil sin preguntar. En macOS: `mac-fast\|mac-quality\|mac-full` |
+| `--experimental` | Obligatorio en macOS, que está sin probar |
+| `--accept-licenses` | Acepta las licencias sin preguntar. Obligatoria con `--non-interactive` |
+| `--non-interactive` | No pregunta nunca: falla si falta una decisión |
+| `--managed` | Instala un ComfyUI propio, aunque exista otro |
+| `--attach RUTA` | Usa el ComfyUI que hay en `RUTA` |
+| `--install-node` | Permite instalar el nodo de estado en un ComfyUI adjunto |
+| `--models-dir RUTA` | Guarda los modelos en `RUTA` y los comparte con `extra_model_paths.yaml` |
+| `--port PUERTO` | Puerto en el que escucha ComfyUI |
+| `--skip-smoke-test` | No genera la imagen de prueba |
+
+Define `HF_TOKEN` si Hugging Face restringe el acceso a un modelo.
+
+#### macOS (sin probar)
+
+**ImageHearth nunca se ha ejecutado en un Mac, y macOS no tiene soporte.** Para probarlo, añade la opción al instalador: `curl -LsSf https://raw.githubusercontent.com/RealHemoglobin/ImageHearth/main/install.sh | sh -s -- --experimental`. `setup` está preparado para Apple Silicon, con modelos GGUF (`mac-fast` 6,9 GB, `mac-quality` 19,2 GB, `mac-full` 27,6 GB) y el nodo `ComfyUI-GGUF`. Los workflows GGUF se han ejecutado en una GPU NVIDIA, lo que comprueba el grafo y los archivos pero no MPS. Los Mac con Intel no tienen soporte. Si lo pruebas, cuéntanos cómo ha ido, con la salida de `imagehearth-mcp doctor --json`.
+
+**Usar un ComfyUI que ya tienes.** Con `--attach`, o eligiéndolo cuando te pregunte, ImageHearth lo usa en lugar de instalar otro y no descarga los modelos que ya tiene. Tu ComfyUI solo cambia si permites instalar el nodo de estado. ComfyUI Desktop debe estar abierto, porque ImageHearth no puede arrancarlo.
+
+### 3. Compruébalo, actualízalo o elimínalo
+
+El instalador no cambia tu `PATH`. Si no encuentra `imagehearth-mcp`, ejecuta `uv tool update-shell` y abre otra terminal.
+
+```bash
+imagehearth-mcp doctor
+```
+
+Comprueba cada capa e indica cómo arreglar lo que falle. Añade `--json` para un formato estable, o `--verify-hashes` para comparar el SHA-256 de cada modelo en lugar de su tamaño. Termina con un código distinto de cero si algo falla.
+
+```bash
+imagehearth-mcp update
+```
+
+Aplica la versión de ComfyUI y los modelos que fija esta versión de ImageHearth. Un ComfyUI adjunto no se toca, salvo el nodo de estado que haya instalado setup.
+
+```bash
+imagehearth-mcp uninstall
+```
+
+Muestra qué va a borrar y borra solo lo que instaló setup. Los modelos necesitan una confirmación aparte (`--remove-models` o `--keep-models` para decidirlo de antemano, `--yes` para saltar la primera pregunta). Un ComfyUI o unos modelos que ya estaban nunca se tocan. Para quitar el propio comando, ejecuta `uv tool uninstall imagehearth-mcp`.
+
+### Configuración (opcional)
+
+`setup` escribe lo que necesita en `~/.config/imagehearth/config.toml` en Linux y en `%APPDATA%\imagehearth\config.toml` en Windows. También puedes editarlo:
+
+```toml
+comfy_dir = "~/AI/ComfyUI"      # dónde está instalado ComfyUI
+comfy_port = 8188               # puerto en el que escucha ComfyUI
+output_dir = "~/Pictures/ImageHearth"
+ollama_url = "http://127.0.0.1:11434"
+memory_mode = "auto"            # "auto", "off" o "manual", ver abajo
+lmstudio_url = "http://127.0.0.1:1234"
+llamacpp_url = "http://127.0.0.1:8080"
+vllm_url = "http://127.0.0.1:8000"
+```
+
+Cada clave se puede definir también con una variable de entorno: `IMAGEHEARTH_COMFY_DIR`, `IMAGEHEARTH_COMFY_PORT`, `IMAGEHEARTH_OUTPUT_DIR`, `IMAGEHEARTH_OLLAMA_URL`, `IMAGEHEARTH_LMSTUDIO_URL`, `IMAGEHEARTH_LLAMACPP_URL`, `IMAGEHEARTH_VLLM_URL` e `IMAGEHEARTH_MEMORY_MODE`. Las variables ganan al archivo, y el archivo a los valores por defecto.
+
+| `memory_mode` | Qué pasa con tus modelos de lenguaje |
+|---|---|
+| `auto` | Se descargan antes de generar y se restauran después. Si un servidor no puede descargar (ver abajo), recibes un aviso con qué hacer, o un error antes de empezar si la memoria no basta |
+| `manual` | No se tocan. La generación falla con una explicación si la memoria libre no basta |
+| `off` | No se tocan y no se comprueba la memoria |
+
+El antiguo `ollama_mode` sigue funcionando como alias de `auto` u `off`; si están los dos, gana `memory_mode`.
+
+| Servidor | ¿Puede ImageHearth liberar su memoria? |
+|---|---|
+| Ollama | Sí |
+| LM Studio | Sí, con su API REST v1. Versiones anteriores: solo aviso |
+| llama.cpp | Solo en modo router. Un `llama-server` de un solo modelo no puede descargar: solo aviso |
+| vLLM | Solo si arranca con `VLLM_SERVER_DEV_MODE=1` y `--enable-sleep-mode`. Si no: solo aviso |
+
+### 4. Conecta tu agente
+
+El instalador ya ha ejecutado `imagehearth-mcp connect --detect`, que busca los clientes instalados y ofrece conectarlos. Vuelve a ejecutarlo si instalas otro. También puedes usar `connect <cliente>`, o `connect --print <cliente>` para ver el fragmento sin tocar nada. Hace copia de seguridad, conserva tus demás entradas y se puede repetir.
+
+**Probados:** Claude Code, Codex, opencode, Hermes y pi. **Sin probar**, contrastados solo con su documentación: Claude Desktop, Gemini CLI, Cursor, VS Code y JetBrains. Detalles y fragmentos en [`docs/agents.md`](https://github.com/RealHemoglobin/ImageHearth/blob/main/docs/agents.md). También puedes pedirle la instalación a un agente con [`llms-install.md`](https://github.com/RealHemoglobin/ImageHearth/blob/main/llms-install.md).
+
+### 5. Pruébalo
+
+Reinicia tu agente y pídele:
+
+> Genera una imagen de una bicicleta roja en una playa, con calidad rápida.
+
+ComfyUI arranca solo. La primera imagen tarda más porque tiene que cargar el modelo. Las imágenes se guardan en `~/Pictures/ImageHearth/`.
+
+## Solución de problemas
+
+Ejecuta `imagehearth-mcp doctor`, o pide a tu agente que *"compruebe el estado de ImageHearth"*. Los problemas frecuentes y cómo informar de uno están en [`docs/troubleshooting.md`](https://github.com/RealHemoglobin/ImageHearth/blob/main/docs/troubleshooting.md), en inglés.
+
+ImageHearth solo reinicia o detiene un ComfyUI que haya lanzado él mismo (guarda su PID en la carpeta de datos). Si ejecutas ComfyUI en el mismo puerto, lo usa pero nunca lo reinicia.
+
+## Licencias de los modelos
+
+Los modelos no forman parte de este proyecto y tienen sus propias condiciones. **Al descargarlos, las aceptas.** Este resumen no es asesoramiento legal; los detalles están en [`THIRD_PARTY_NOTICES.md`](https://github.com/RealHemoglobin/ImageHearth/blob/main/THIRD_PARTY_NOTICES.md).
+
+| Modelo | Licencia | En resumen |
+|---|---|---|
+| FLUX.1 Dev | [FLUX.1 [dev] Non-Commercial](https://bfl.ai/legal/non-commercial-license-terms) | Uso no comercial del modelo |
+| FLUX.1 Kontext Dev | [FLUX.1 [dev] Non-Commercial](https://bfl.ai/legal/non-commercial-license-terms) | Uso no comercial del modelo |
+| SDXL Turbo | [Stability AI Community](https://huggingface.co/stabilityai/sdxl-turbo/blob/main/LICENSE.md) | El uso comercial exige registro y tiene un límite de ingresos |
+
+## Desarrollo
+
+```bash
+uv sync
+uv run ruff check .
+uv run pytest
+```
+
+Hace falta [uv](https://docs.astral.sh/uv/getting-started/installation/), que crea su propio entorno en `.venv`, separado del de ComfyUI. Los tests usan servidores simulados y no necesitan GPU. Consulta [`CONTRIBUTING.md`](https://github.com/RealHemoglobin/ImageHearth/blob/main/CONTRIBUTING.md) para contribuir y el [roadmap](https://github.com/RealHemoglobin/ImageHearth/blob/main/specs/roadmap.md) para ver qué está previsto. Para ayudar a probar la beta, consulta [`docs/beta-testing.md`](https://github.com/RealHemoglobin/ImageHearth/blob/main/docs/beta-testing.md). Para avisar de una vulnerabilidad, consulta [`SECURITY.md`](https://github.com/RealHemoglobin/ImageHearth/blob/main/SECURITY.md).
+
+## Licencia
+
+[MIT](https://github.com/RealHemoglobin/ImageHearth/blob/main/LICENSE), salvo el nodo personalizado de ComfyUI en [`src/imagehearth_mcp/data/imagehearth_status/`](https://github.com/RealHemoglobin/ImageHearth/blob/main/src/imagehearth_mcp/data/imagehearth_status/LICENSE), que es GPL-3.0. Los componentes y modelos de terceros figuran en [`THIRD_PARTY_NOTICES.md`](https://github.com/RealHemoglobin/ImageHearth/blob/main/THIRD_PARTY_NOTICES.md).