# TF Tools MCP

Image generation and understanding tools for MCP (Model Context Protocol) using OpenRouter and Zhipu AI.

## Features

- **Text-to-Image Generation**: Generate images from text prompts using multiple models via OpenRouter
  - Supported models: Gemini 2.0 Flash, Seedream 4.5, GPT-5 Image, FLUX.2 Max/Pro
  - Optional AI-powered prompt enhancement using GLM-4.6V
  - Multiple quality levels and layouts

- **Image-to-Image Generation**: Transform reference images with text guidance
  - Support for local files and URLs
  - Smart prompt enhancement for various transformation modes

- **Image Understanding**: Analyze images with GLM-4.6V vision model
  - Single and batch image analysis
  - Multiple analysis templates: description, OCR, object detection, chart analysis
  - Detailed token usage statistics

## Installation

### Using uv (recommended)

```bash
# Clone the repository
git clone https://github.com/turingfocus/tf_tools_mcp.git
cd tf_tools_mcp

# Install dependencies
uv sync

# Install the package in development mode
uv pip install -e .
```

### Using pip

```bash
# Clone the repository
git clone https://github.com/turingfocus/tf_tools_mcp.git
cd tf_tools_mcp

# Install dependencies
pip install -e .
```

## Configuration

1. Copy `.env.example` to `.env`:

```bash
cp .env.example .env
```

2. Edit `.env` and add your API keys:

```bash
# Required for image generation
OPENROUTER_API_KEY=your_openrouter_api_key_here

# Required for image understanding
ZHIPUAI_API_KEY=your_zhipuai_api_key_here

# Optional settings
IMAGE_STORAGE_DIR=./generated_images
ENABLE_PROMPT_ENHANCEMENT=true
```

### Getting API Keys

- **OpenRouter API Key**: Sign up at [https://openrouter.ai/](https://openrouter.ai/) and get your key from [https://openrouter.ai/keys](https://openrouter.ai/keys)
- **ZhipuAI API Key**: Sign up at [https://open.bigmodel.cn/](https://open.bigmodel.cn/) and get your key from [https://open.bigmodel.cn/usercenter/apikeys](https://open.bigmodel.cn/usercenter/apikeys)

## Usage with MCP Clients

### Claude Desktop

Add the server to your Claude Desktop configuration:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "tf-tools-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/tf_tools_mcp",
        "run",
        "tf-tools-mcp"
      ],
      "env": {
        "OPENROUTER_API_KEY": "your_api_key_here",
        "ZHIPUAI_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

Or if installed with pip:

```json
{
  "mcpServers": {
    "tf-tools-mcp": {
      "command": "tf-tools-mcp",
      "env": {
        "OPENROUTER_API_KEY": "your_api_key_here",
        "ZHIPUAI_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

Restart Claude Desktop and the tools will be available.

### Claude Code (CLI)

Install as an MCP server:

```bash
claude mcp install tf-tools-mcp
```

Or configure manually in `~/.config/claude-code/mcp_config.json`:

```json
{
  "mcpServers": {
    "tf-tools-mcp": {
      "command": "tf-tools-mcp",
      "env": {
        "OPENROUTER_API_KEY": "your_api_key_here",
        "ZHIPUAI_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

## Available Tools

### text_to_image

Generate images from text prompts.

**Parameters:**
- `prompt` (string, required): Text prompt for image generation
- `model` (string, required): OpenRouter model ID
  - `google/gemini-2.0-flash-exp-image-generation`
  - `bytedance-seed/seedream-4.5`
  - `openai/gpt-image-1`
  - `openai/gpt-image-1-mini`
  - `black-forest-labs/flux-2-max`
  - `black-forest-labs/flux-2-pro`
- `mode` (string, optional): Prompt enhancement mode
  - `technical_architecture`: For technical diagrams
  - `design_mockup`: For UI/UX designs
  - `promotional_material`: For marketing content
  - `office_chart`: For business charts
  - `custom`: No enhancement (default)
- `quality` (string, optional): Image quality (`low`, `medium`, `high`) - default: `medium`
- `layout` (string, optional): Image layout (`square`, `landscape`, `portrait`) - default: `square`
- `filename_prefix` (string, optional): Prefix for saved filename - default: `generated`

**Example:**

```
Generate an image of a sunset over mountains with vibrant colors
using the Gemini 2.0 Flash model, high quality, landscape layout.
```

### image_to_image

Generate images from reference images with text guidance.

**Parameters:**
- `prompt` (string, required): Text prompt for image generation
- `reference_image` (string, required): Path to reference image (local file or URL)
- `model` (string, required): OpenRouter model ID (same as text_to_image)
- `mode` (string, optional): Prompt enhancement mode
  - `content_adjustment`: Adjust content while keeping style
  - `element_replace`: Replace specific elements
  - `style_transfer`: Transfer artistic style
  - `text_modification`: Modify text in image
  - `custom`: No enhancement (default)
- `quality`, `layout`, `filename_prefix`: Same as text_to_image

**Example:**

```
Transform this image to have a cyberpunk aesthetic
using the reference image at /path/to/image.jpg
with the FLUX.2 Max model.
```

### image_understanding

Analyze and understand images using GLM-4.6V.

**Parameters:**
- `images` (array of strings, required): List of image paths or URLs
- `prompt_template` (string, optional): Analysis template
  - `describe`: General image description (default)
  - `ocr`: Text extraction (OCR)
  - `detect_objects`: Object detection
  - `analyze_chart`: Chart/data visualization analysis
  - `custom`: Use custom prompt
- `custom_prompt` (string, optional): Custom prompt (required when `prompt_template` is `custom`)
- `model` (string, optional): GLM model to use
  - `glm-4.6v`: High performance
  - `glm-4.6v-flashx`: Fast (default)

**Example:**

```
Analyze this image /path/to/image.jpg
and describe all the objects you can see.
```

## Development

### Running Tests

```bash
# Run all tests
make test

# Run with real API calls (requires API keys)
make test-real
```

### Project Structure

```
tf_tools_mcp/
├── tf_tools_mcp/
│   ├── server.py              # MCP server entry point
│   ├── tools/
│   │   ├── img_gen_tools/     # Image generation tools
│   │   │   ├── text_to_image.py
│   │   │   ├── image_to_image.py
│   │   │   ├── constants.py   # Model configurations
│   │   │   ├── types.py       # Type definitions
│   │   │   └── enhancers/     # Prompt enhancement
│   │   └── file_preview_tools/
│   │       └── image_understanding.py
│   └── __init__.py
├── tests/                     # Test suite
├── pyproject.toml            # Project configuration
├── Makefile                  # Build scripts
└── README.md
```

## License

MIT License - see LICENSE file for details

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Support

For issues and questions, please use the [GitHub issue tracker](https://github.com/turingfocus/tf_tools_mcp/issues).
