dreamtail-mcp/README.md

# 🎨 DreamTail MCP Server

Model Context Protocol (MCP) server for integrating [DreamTail](../dreamtail) SDXL image generation with Claude Desktop.

## Overview

This MCP server exposes DreamTail's Stable Diffusion XL image generation capabilities to Claude Desktop through a single, simple tool: `dreamtail_generate()`.

**Features:**
- 🎨 Generate high-quality 1024x1024 images using SDXL
- 🖼️ **Inline image display** in Claude Desktop (new!)
- ⏱️ Automatic job submission and polling (no manual checking)
- 💾 Automatic download to local folder (configurable)
- 🗜️ Smart format conversion with adaptive compression for 1MB limit
- 🔄 Built-in progress tracking and timeout handling
- 💬 Natural language prompts via Claude
- ⚡ Powered by Jetson AGX Orin GPU

## Prerequisites

1. **DreamTail service** running on bigorin:8765
2. **Python 3.8+** installed
3. **Claude Desktop** installed

## Installation

### 1. Install Dependencies

```bash
cd /home/alex/Projects/dreamtail-mcp
pip install -r requirements.txt
```

Or using `uv` (recommended):

```bash
uv pip install -r requirements.txt
```

### 2. Make Script Executable

```bash
chmod +x dreamtail_mcp.py
```

### 3. Test the Server Locally

```bash
# Test that the server starts without errors
python3 dreamtail_mcp.py
# Press Ctrl+C to stop
```

## Claude Desktop Configuration

### Step 1: Locate Configuration File

**macOS:**
```bash
~/Library/Application Support/Claude/claude_desktop_config.json
```

**Or use Claude Desktop:**
- Open Claude Desktop
- Go to: Settings → Developer → "Edit Config"

### Step 2: Add DreamTail MCP Server

Add this configuration to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "dreamtail": {
      "command": "python3",
      "args": [
        "/home/alex/Projects/dreamtail-mcp/dreamtail_mcp.py"
      ],
      "env": {
        "DREAMTAIL_BASE_URL": "http://192.168.50.30:8765",
        "DREAMTAIL_DOWNLOAD_DIR": "/Users/yourname/Pictures/dreamtail",
        "DREAMTAIL_FORMAT": "jpeg",
        "DREAMTAIL_JPEG_QUALITY": "95",
        "DREAMTAIL_INLINE_DISPLAY": "true",
        "DREAMTAIL_INLINE_QUALITY": "85"
      }
    }
  }
}
```

**Important notes:**
- Use the **absolute path** to `dreamtail_mcp.py`
- Use the **IP address** for `DREAMTAIL_BASE_URL` instead of hostname (e.g., `192.168.50.30:8765` instead of `bigorin:8765`)
- Set `DREAMTAIL_DOWNLOAD_DIR` to your preferred download location (defaults to `~/dreamtail_images`)
- `DREAMTAIL_FORMAT` options: `"jpeg"` (default), `"png"`, or `"both"` - for saved files
- `DREAMTAIL_JPEG_QUALITY`: 1-100 (default: 95) - quality for saved files
- `DREAMTAIL_INLINE_DISPLAY`: `"true"` (default) or `"false"` - enable inline image display in Claude Desktop
- `DREAMTAIL_INLINE_QUALITY`: 1-100 (default: 85) - JPEG quality for inline display (lower = smaller file for 1MB limit)
- If you have other MCP servers configured, add the "dreamtail" entry alongside them

### Step 3: Restart Claude Desktop

**You MUST completely quit and restart Claude Desktop** for the changes to take effect:

**macOS:**
```bash
# Quit Claude Desktop completely
# Then reopen from Applications
```

### Step 4: Verify Installation

1. Open Claude Desktop
2. Look for the 🔨 (hammer) icon in the bottom-right corner of the chat input
3. Click it to see available tools
4. You should see "DreamTail Image Generator" with the `dreamtail_generate` tool

## Usage

Once configured, you can ask Claude to generate images naturally:

### Example Prompts

**Basic generation:**
```
Generate an image of a serene mountain landscape at sunset
```

**With negative prompt:**
```
Create an image of a cat wearing a wizard hat, but avoid any blurry or
low-quality elements
```

**Custom dimensions:**
```
Generate a 512x512 image of a futuristic cityscape
```

**More inference steps for quality:**
```
Create a highly detailed portrait of a robot, using 50 inference steps
```

### What Claude Will Do

1. Parse your natural language request
2. Call `dreamtail_generate()` with appropriate parameters
3. Wait ~45-60 seconds while the image generates
4. **Display the image inline** in the chat (when enabled)
5. Automatically save full-resolution version to your local folder

### Response Format

**With inline display enabled (default):**

Claude will show the generated image directly in the conversation! No need to open files or URLs - the image appears immediately for analysis and discussion.

The image displayed inline is:
- Compressed JPEG at quality 85 (or lower if needed to fit 1MB limit)
- May be slightly resized if the original is too large
- Optimized for fast loading while maintaining visual quality

Full-resolution files are saved to disk:
- Location: `~/dreamtail_images/{job_id}.jpg` (and `.png` if configured)
- Quality: Your configured JPEG quality (default 95) or original PNG
- Use these for high-quality archival or further editing

**With inline display disabled:**

Claude will provide a text message:
```
Image generated successfully!
Saved to: /Users/yourname/Pictures/dreamtail/{job_id}.jpg
```

You can then open the file directly from your local filesystem.

## Tool Reference

### `dreamtail_generate()`

**Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `prompt` | string | *required* | Text description of image to generate |
| `negative_prompt` | string | None | What to avoid in the image (optional) |
| `width` | integer | 1024 | Image width (must be multiple of 8) |
| `height` | integer | 1024 | Image height (must be multiple of 8) |
| `num_inference_steps` | integer | 30 | Denoising steps (20-50, higher = better quality but slower) |
| `client_id` | string | "claude" | Client identifier |

**Returns:**

```python
{
    "status": "completed",  # or "failed", "timeout", "error"
    "job_id": "uuid",
    "image_url": "http://192.168.50.30:8765/result/{job_id}",
    "local_paths": ["/path/to/download/dir/{job_id}.jpg"],  # List of saved files
    "progress": 100,
    "message": "Image generated successfully! Saved to: /path/to/download/dir/{job_id}.jpg"
}
```

**Notes:**
- `local_paths` contains 1 file (JPEG or PNG) or 2 files (when `DREAMTAIL_FORMAT="both"`)
- JPEG files are optimized and ~10x smaller than PNG with negligible quality loss at 95%

**Generation Time:**
- Typical: ~45-60 seconds for 1024x1024 @ 30 steps
- Fast: ~30-40 seconds for 20 steps or 512x512
- High quality: ~60-90 seconds for 50 steps

## Troubleshooting

### Tool Not Appearing in Claude Desktop

1. **Check config path**: Ensure you're editing the correct config file
2. **Verify absolute path**: Must be absolute, not relative (e.g., `/home/alex/...` not `~/...`)
3. **Restart Claude**: Completely quit and reopen Claude Desktop
4. **Check logs**: Look for errors in Claude Desktop's logs

### "Failed to connect to DreamTail"

1. **Check DreamTail is running**:
   ```bash
   curl http://bigorin:8765/health
   ```

2. **Verify network access**: Ensure your machine can reach bigorin:8765

3. **Update config**: Check `DREAMTAIL_BASE_URL` in Claude config

### "Generation exceeded timeout"

- Normal generation takes 45-60 seconds
- If you get timeouts, DreamTail might be overloaded or having issues
- Check DreamTail logs: `ssh bigorin "sudo docker logs dreamtail"`

### Import Errors

```bash
# Reinstall dependencies
cd /home/alex/Projects/dreamtail-mcp
pip install --upgrade -r requirements.txt
```

## Advanced Configuration

### Inline Display Options

Control how images are displayed in Claude Desktop:

```json
"env": {
  "DREAMTAIL_INLINE_DISPLAY": "true",
  "DREAMTAIL_INLINE_QUALITY": "85"
}
```

**Options:**
- `DREAMTAIL_INLINE_DISPLAY`: `"true"` (default) or `"false"`
  - `"true"`: Images display inline in Claude Desktop (recommended)
  - `"false"`: Return text message with file path only
- `DREAMTAIL_INLINE_QUALITY`: 50-95 (default: 85)
  - JPEG compression quality for inline display
  - Lower values = smaller files (required for 1MB limit)
  - 85: Good balance of quality and size (~150-300KB)
  - 70-75: More aggressive compression for large images
  - Will automatically reduce if image still exceeds 1MB

**Why inline quality is lower than saved quality:**
- Claude Desktop has a 1MB limit for tool responses
- Images must be compressed to fit this limit
- Full-resolution images are always saved to disk at your configured quality
- You get the best of both worlds: instant viewing + high-quality archives

### Image Format Options

Control saved file format in your Claude Desktop config:

```json
"env": {
  "DREAMTAIL_BASE_URL": "http://192.168.50.30:8765",
  "DREAMTAIL_DOWNLOAD_DIR": "/Users/yourname/Pictures/dreamtail",
  "DREAMTAIL_FORMAT": "jpeg",
  "DREAMTAIL_JPEG_QUALITY": "95"
}
```

**Format Options:**
- `"jpeg"` (default): Save as JPEG at specified quality
  - Quality 95: Visually lossless, ~10x smaller than PNG
  - Quality 85: Very good, ~15x smaller than PNG
  - Quality 75: Good for web, ~20x smaller than PNG
- `"png"`: Save as PNG (lossless, ~2-5MB per image)
- `"both"`: Save both JPEG and PNG versions

**File Size Comparison (1024x1024):**
- PNG: ~2-5MB
- JPEG Q95: ~200-500KB (recommended)
- JPEG Q85: ~150-300KB
- JPEG Q75: ~100-200KB

### Custom Download Directory

**Tip:** Use an absolute path, not `~`. For example:
- ✅ `/Users/alex/Pictures/dreamtail`
- ✅ `/home/alex/dreamtail_images`
- ❌ `~/Pictures/dreamtail` (may not expand correctly in Claude Desktop)

If not specified, images will be saved to `~/dreamtail_images` by default.

### Custom Timeout

Edit `dreamtail_mcp.py` and change:
```python
DEFAULT_TIMEOUT = 180  # 3 minutes instead of 2
```

### Different DreamTail Instance

In Claude Desktop config:
```json
"env": {
  "DREAMTAIL_BASE_URL": "http://192.168.50.30:8765"
}
```

### Using uv (Python Package Manager)

In Claude Desktop config:
```json
{
  "mcpServers": {
    "dreamtail": {
      "command": "uv",
      "args": [
        "--directory",
        "/home/alex/Projects/dreamtail-mcp",
        "run",
        "dreamtail_mcp.py"
      ],
      "env": {
        "DREAMTAIL_BASE_URL": "http://bigorin:8765"
      }
    }
  }
}
```

## Architecture

```
┌─────────────────┐
│ Claude Desktop  │
└────────┬────────┘
         │ stdio (MCP)
         ▼
┌─────────────────┐
│ dreamtail_mcp   │ (this server)
└────────┬────────┘
         │ HTTP REST
         ▼
┌─────────────────┐
│   DreamTail     │ (bigorin:8765)
│   SDXL Service  │
└─────────────────┘
```

**Flow:**
1. User asks Claude to generate an image
2. Claude calls `dreamtail_generate()` via MCP
3. MCP server submits job to DreamTail API
4. MCP server polls status every 3 seconds
5. When complete, downloads image to local folder
6. Claude shows the user the local file path

## Related Projects

- **DreamTail**: SDXL image generation service (../dreamtail)
- **Lyra**: AI assistant ecosystem
- **Model Context Protocol**: https://modelcontextprotocol.io

## License

Part of the Lyra project ecosystem.

---

**Built with ❤️ for Claude Desktop integration**