# ms-image-gen-mcp（本地修改版）

基于 PyPI 包 [`ms-image-gen-mcp`](https://pypi.org/project/ms-image-gen-mcp/) v1.3.0 的本地修改版本，新增了 `loras` 参数，支持通过 ModelScope API-Inference 调用 LoRA 模型生图。

## 目录结构

```
~/mcp-local/ms-image-gen-mcp/
├── README.md              # 本文档
├── pyproject.toml         # 备用打包配置（当前未使用）
└── ms_image_gen_mcp/      # 包源码（修改版）
    ├── __init__.py        # 入口：导出 mcp 实例和 main()
    ├── __main__.py        # python -m 方式运行入口
    └── server.py          # MCP 工具定义（核心修改文件）
```

## 本地修改内容

对比原版 v1.3.0，有三处改动（均在 `ms_image_gen_mcp/server.py`）：

### 1. `text_to_image` 和 `text_image_to_image` 新增 `loras` 参数 ⭐

- 类型：可选字符串（`str | None`），默认不传
- 行为（2026-09-11 修正）：不传时 payload **不携带** `loras` 字段，仅显式传入时才发送
- 背景：ModelScope API-Inference 支持将 LoRA 模型 ID 直接作为调用对象，平台会自动加载 LoRA 所需的基础模型（参考[官方文章](https://modelscope.cn/learn/2577)）
- ⚠️ 修正原因：旧逻辑不传时把 `loras` 填成 `model` 值，图生图编辑模型（FireRed-Image-Edit、FLUX.1-Kontext 等）会因被当作 LoRA 加载而任务失败（实测去掉该字段后任务正常）

### 2. `text_image_to_image` 支持本地图片路径

- `image_url` 传入本地文件路径时，自动转为 base64 data URL 提交
- 图片最大边超过 2048px 时自动等比缩小（API 限制），依赖 Pillow
- 公网 URL 原样透传，行为不变

请求体示例：

```json
{
  "model": "xxx/xxx-lora",
  "prompt": "描述文本",
  "loras": "xxx/xxx-lora",
  "negative_prompt": "...",
  "size": "1536x1536",
  "seed": 12345,
  "steps": 8,
  "guidance": 1
}
```

请求体示例：

```json
{
  "model": "xxx/xxx-lora",
  "prompt": "描述文本",
  "loras": "xxx/xxx-lora",
  "negative_prompt": "...",
  "size": "1536x1536",
  "seed": 12345,
  "steps": 30,
  "guidance": 34
}
```

## 提供的工具

### 1. text_to_image — 文生图

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| description | string | 必填 | 图片描述（提示词） |
| model | string | `bozoyan/k-yanbo` | 模型 ID |
| negative_prompt | string | 通用负面词 | 负面提示词 |
| size | string | `960x1664` | 图片尺寸 |
| seed | int | `12345` | 随机种子 |
| steps | int | `8` | 推理步数 |
| guidance | float | `1` | 引导系数 |
| **loras** ⭐ | string \| null | 不传时等于 model | LoRA 模型 ID（本地新增） |

### 2. text_image_to_image — 图生图

同上参数，另加 `image_url`（必填，参考图的公网 URL **或本地文件路径**，本地路径自动转 base64 data URL 并限制最大边 2048px），`model` 默认为 `FireRedTeam/FireRed-Image-Edit-1.1`（文档字符串中标注的 FLUX.1-Kontext-dev 为可选编辑模型）。

### 3. search_models — 模型搜索

按关键词搜索 ModelScope 上的模型，可用 `task="text-to-image"` 和 `libraries="LoRA"` 过滤。

## 配置方式

本机 `~/.claude.json` 中的配置：

```json
{
  "mcpServers": {
    "modelscope-image-gen-mcp": {
      "command": "uvx",
      "args": [
        "--from", "ms_image_gen_mcp",
        "--with", "mcp<2",
        "--with", "pillow",
        "python", "-c",
        "import sys; sys.path.insert(0, '/Users/yons/mcp-local/ms-image-gen-mcp'); from ms_image_gen_mcp import main; main()"
      ],
      "env": {
        "MODELSCOPE_API_KEY": "ms-xxxx"
      }
    }
  }
}
```

### 加载原理

- `uvx --from ms_image_gen_mcp` 仍从 PyPI 安装原版包，提供 `mcp`、`requests` 等依赖环境（走本地 uv 缓存，无需联网）
- 启动脚本通过 `sys.path.insert(0, ...)` 把本地修改目录插到搜索路径最前面，**覆盖**原版 `ms_image_gen_mcp` 模块，从而加载修改版代码
- 这种方式规避了本地包构建（本机访问 PyPI 构建后端受限）

## 环境要求与注意事项

- **API Key**：需要 ModelScope API Token（[获取地址](https://modelscope.cn/my/myAccessToken)），通过环境变量 `MODELSCOPE_API_KEY` 传入
- **Python >= 3.12**（uvx 自动处理）
- 修改 `server.py` 后需**重启 Claude Code**（或 `/mcp` 重连）才能生效
- 原配置备份：`~/.claude.json.bak-mcp-loras`
- 若 PyPI 原版包升级，本地修改仍会生效（因为 `sys.path` 优先加载本地目录），但需留意新版 API 是否有变化

## 调用示例

在 Claude Code 中：

```
帮我用 text_to_image 生成一张图，model 用 "xxx/xxx-lora"（LoRA 模型 ID）
```

`loras` 参数不指定时会自动与 `model` 保持一致；也可显式指定不同的 LoRA ID。