Metadata-Version: 2.4
Name: yooztech_mcp_minimax_t2i
Version: 0.0.1
Summary: MCP server for MiniMax image generation (text-to-image and image-to-image)
Author: yooztech
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.2.0
Requires-Dist: httpx>=0.27.0
Dynamic: license-file

# yooztech_mcp_minimax_t2i —— MiniMax 图片生成 MCP 工具

基于 MCP (Model Context Protocol) 的 MiniMax 图片生成服务，提供文生图（text-to-image）与图生图（image-to-image）两种核心功能。

## 功能概述

- `text_to_image(prompt, ...)`: 根据文本描述生成图片
- `image_to_image(prompt, subject_reference, ...)`: 结合参考图生成图片
- `save_base64_images(images, ...)`: 将 Base64 图片保存为文件

## 在 Cursor 中配置

需要在 MCP Server 配置中设置环境变量 `MINIMAX_API_KEY`：

```json
{
  "mcpServers": {
    "yooztech_mcp_minimax_t2i": {
      "command": "yooztech_mcp_minimax_t2i",
      "args": [],
      "env": {
        "MINIMAX_API_KEY": "your-api-key"
      }
    }
  }
}
```

或使用 `uvx` 方式：

```json
{
  "mcpServers": {
    "yooztech_mcp_minimax_t2i": {
      "command": "uvx",
      "args": ["yooztech_mcp_minimax_t2i"],
      "env": {
        "MINIMAX_API_KEY": "your-api-key"
      }
    }
  }
}
```

## API Key 获取

请访问 [MiniMax 开放平台](https://platform.minimaxi.com/) 注册账号并获取 API Key。

## 工具详解

### 1. text_to_image - 文生图

根据详尽的文本描述（prompt），直接生成与之匹配的图片。

**参数：**
- `prompt` (必填): 图片描述文本，建议详细描述场景、主体、风格等
- `model` (可选): 使用的模型，默认 "image-01"
- `aspect_ratio` (可选): 图片宽高比，默认 "16:9"
  - 可选值：1:1, 16:9, 9:16, 4:3, 3:4
- `response_format` (可选): 返回格式，默认 "base64"，可选值：base64, url

**使用示例：**

```json
{
  "tool": "text_to_image",
  "args": {
    "prompt": "men Dressing in white t shirt, full-body stand front view image :25, outdoor, Venice beach sign, full-body image, Los Angeles, Fashion photography of 90s, documentary, Film grain, photorealistic",
    "aspect_ratio": "16:9"
  }
}
```

### 2. image_to_image - 图生图

此功能允许提供一张或多张包含清晰主体的参考图（支持网络图片链接），并结合 prompt 描述，生成一张保留了主体特征的新图片。

**参数：**
- `prompt` (必填): 图片描述文本，描述希望生成的场景
- `subject_reference` (必填): 参考图列表，每项包含：
  - `type`: 参考图类型，目前仅支持 "character"（角色）
  - `image_file`: 参考图 URL（支持网络图片链接）
- `model` (可选): 使用的模型，默认 "image-01"
- `aspect_ratio` (可选): 图片宽高比，默认 "16:9"
- `response_format` (可选): 返回格式，默认 "base64"

**使用示例：**

```json
{
  "tool": "image_to_image",
  "args": {
    "prompt": "女孩在图书馆的窗户前，看向远方",
    "subject_reference": [
      {
        "type": "character",
        "image_file": "https://cdn.hailuoai.com/prod/2025-08-12-17/video_cover/xxx.jpg"
      }
    ]
  }
}
```

### 3. save_base64_images - 保存图片

将 Base64 编码的图片保存为文件。

**参数：**
- `images` (必填): Base64 编码的图片列表
- `output_dir` (可选): 输出目录，默认当前目录
- `filename_prefix` (可选): 文件名前缀，默认 "output"

**使用示例：**

```json
{
  "tool": "save_base64_images",
  "args": {
    "images": ["base64-encoded-image-data..."],
    "output_dir": "./output",
    "filename_prefix": "generated"
  }
}
```

## 完整使用流程

1. 在 Cursor 配置中设置 `MINIMAX_API_KEY` 环境变量
2. 调用 `text_to_image` 或 `image_to_image` 生成图片
3. 获取返回的 Base64 图片数据
4. 使用 `save_base64_images` 将图片保存为文件

## 错误处理

所有工具在失败时会返回包含错误信息的字典，包含以下字段：
- `success`: 是否成功
- `error`: 错误类型
- `message`: 错误详情

## 依赖

- Python >= 3.10
- mcp >= 1.2.0
- httpx >= 0.27.0

## 许可证

MIT (见 LICENSE)
