imgenx-mcp 0.4.0__py3-none-any.whl

imgenx_mcp-0.4.0.dist-info/METADATA

@@ -0,0 +1,392 @@
+Metadata-Version: 2.4
+Name: imgenx-mcp
+Version: 0.4.0
+Summary: AI Image/Video Generation MCP Server with OSS Upload - Powered by Doubao API
+Project-URL: Homepage, https://github.com/helios123/imgenx-mcp
+Project-URL: Repository, https://github.com/helios123/imgenx-mcp
+Project-URL: Issues, https://github.com/helios123/imgenx-mcp/issues
+Project-URL: Documentation, https://github.com/helios123/imgenx-mcp/blob/main/README.md
+Author-email: helios123 <your-email@example.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai,aliyun,doubao,image-generation,mcp,oss,video-generation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: fastmcp>=2.12.4
+Requires-Dist: oss2>=2.19.1
+Requires-Dist: pillow>=12.0.0
+Requires-Dist: python-dotenv>=1.1.1
+Requires-Dist: requests>=2.25.0
+Requires-Dist: volcengine-python-sdk[ark]>=4.0.22
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <img src="logo.jpg" alt="ImgenX MCP Server Logo" width="800" height="400">
+
+  [![Version](https://img.shields.io/badge/Version-0.4.0-brightgreen.svg)](https://github.com/helios123/imgenx-mcp/releases)
+  [![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://www.python.org/downloads/)
+  [![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io/)
+  [![License](https://img.shields.io/badge/License-MIT-yellow.svg)](#许可证)
+
+**一站式 AI 图片/视频生成与处理套件，支持文本/图生图、文本/图生视频、图片分析与常用编辑（裁剪、缩放、转换、调参），自动上传到阿里云 OSS 并返回永久 CDN URL。可作为命令行工具或 MCP Server 使用**
+</div>
+
+https://github.com/user-attachments/assets/92749d6f-727e-4874-a008-6ded8b4d9e7b
+
+## 功能特性
+
+- **文本生成图片**: 根据文本描述生成图片，自动上传到 OSS 并返回永久 CDN URL ⭐
+- **图片生成图片**: 基于输入图片和文本描述生成新图片，自动上传到 OSS ⭐
+- **文本/图片生成视频**: 支持提示词生成视频，或基于首尾帧生成视频，自动上传到 OSS ⭐
+- **图片处理工具**: 提供完整的图片处理功能
+  - **图片信息获取**: 查看图片格式、尺寸、模式等信息
+  - **图片裁剪**: 按指定区域裁剪图片（支持小数比例坐标）
+  - **尺寸调整**: 调整图片大小，支持保持宽高比
+  - **格式转换**: 支持 PNG、JPEG、JPG、WEBP 格式转换
+  - **图像调整**: 调整亮度、对比度、饱和度
+  - **图片粘贴**: 将图片粘贴到背景图片的指定位置
+- **图片理解与分析**: 基于视觉模型分析图片内容，输出结构化或文本结果
+- **☁️ 自动 OSS 上传**: 生成图片/视频后自动上传到阿里云 OSS，无需手动操作 ⭐新增
+  - 永久有效的 CDN URL
+  - 无需本地下载和手动上传
+  - 支持自定义业务目录（images、videos 等）
+- **多种分辨率支持**: 支持 1K、2K、4K 分辨率以及多种自定义像素尺寸
+- **插件化架构**: 基于工厂模式设计，支持扩展新的图片生成服务提供商
+- **MCP 协议支持**: 兼容 Model Context Protocol 标准
+
+## 当前支持的服务提供商
+
+- **豆包 (Doubao)**: 基于火山引擎的图片生成服务
+
+## 安装
+
+### 配置环境变量
+
+```bash
+# 图片视频生成模型配置
+export IMGENX_IMAGE_MODEL="doubao:doubao-seedream-4-0-250828"   # 图片生成模型
+export IMGENX_VIDEO_MODEL="doubao:doubao-seedance-1-0-pro-fast-251015" # 视频生成模型（可选）
+export IMGENX_ANALYZER_MODEL="doubao:doubao-seed-1-6-vision-250815"   # 图片分析模型（可选）
+export IMGENX_API_KEY="your_api_key"
+
+# 阿里云 OSS 配置（可选，用于文件上传）
+export OSS_ACCESS_KEY_ID="your_oss_access_key_id"
+export OSS_ACCESS_KEY_SECRET="your_oss_access_key_secret"
+export OSS_BUCKET="your_bucket_name"
+export OSS_ENDPOINT="oss-cn-shanghai.aliyuncs.com"
+export OSS_CDN_URL="https://your-cdn-domain.com/"
+```
+或写入 .env 文件中
+
+### 安装步骤
+
+#### 方式一：pip 安装（推荐）
+
+```bash
+pip install imgenx-mcp
+```
+
+#### 方式二：从源码安装
+```bash
+git clone https://github.com/helios123/imgenx-mcp.git
+cd imgenx-mcp
+pip install -e .
+```
+
+## 使用方法
+
+### 作为命令行运行
+
+```
+# 生成图片（文本或图生图）
+imgenx image "一只在云上飞翔的猫"
+imgenx image "一只在云上飞翔的猫" --size 2K
+imgenx image "一只在云上飞翔的猫" --size 2048x2048 --output test.jpg
+imgenx image "一只在云上飞翔的猫" --images test.jpg --size 2048x2048 --output out_dir/
+
+# 生成视频（文本或基于首尾帧）
+imgenx video "一个人在运动" --resolution 720p --ratio 16:9 --duration 5 --output video.mp4
+imgenx video "一个人在运动" --first_frame logo.jpg --resolution 720p --ratio 16:9 --duration 5 --output video.mp4
+```
+
+### 作为 MCP 服务器运行
+
+#### 标准输入输出模式 (stdio) - 推荐
+
+**配置文件位置：**
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+**配置示例（使用 uvx，无需安装）：**
+```json
+{
+  "mcpServers": {
+    "imgenx": {
+      "command": "uvx",
+      "args": ["imgenx-mcp"],
+      "env": {
+        "IMGENX_IMAGE_MODEL": "doubao:doubao-seedream-4-0-250828",
+        "IMGENX_VIDEO_MODEL": "doubao:doubao-seedance-1-0-pro-fast-251015",
+        "IMGENX_ANALYZER_MODEL": "doubao:doubao-seed-1-6-vision-250815",
+        "IMGENX_API_KEY": "your_api_key_here",
+        "OSS_ACCESS_KEY_ID": "your_oss_key",
+        "OSS_ACCESS_KEY_SECRET": "your_oss_secret",
+        "OSS_BUCKET": "your_bucket",
+        "OSS_ENDPOINT": "oss-cn-shanghai.aliyuncs.com",
+        "OSS_CDN_URL": "https://your-cdn.com/"
+      },
+      "timeout": 600
+    }
+  }
+}
+```
+
+**配置示例（使用已安装的包）：**
+```json
+{
+  "mcpServers": {
+    "imgenx": {
+      "command": "python",
+      "args": ["-m", "imgenx.main"],
+      "env": {
+        "IMGENX_IMAGE_MODEL": "doubao:doubao-seedream-4-0-250828",
+        "IMGENX_API_KEY": "your_api_key_here"
+      },
+      "timeout": 600
+    }
+  }
+}
+```
+
+**配置后重启 Claude Desktop 即可使用。**
+
+#### HTTP 服务器模式
+```bash
+imgenx server --transport streamable-http --host 0.0.0.0 --port 8000
+imgenx server --transport streamable-http --no_tools text_to_video image_to_video  # 禁用视频生成工具
+```
+
+```json
+{
+  "mcpServers": {
+    "imgenx-mcp": {
+      "url": "http://127.0.0.1:8000/mcp",
+      "headers": {
+        "IMGENX_IMAGE_MODEL": "doubao:doubao-seedream-4-0-250828",
+        "IMGENX_VIDEO_MODEL": "doubao:doubao-seedance-1-0-pro-fast-251015",
+        "IMGENX_ANALYZER_MODEL": "doubao:doubao-seed-1-6-vision-250815",
+        "IMGENX_API_KEY": "api-key"
+      },
+      "timeout": 600
+    }
+  }
+}
+```
+
+### 可用工具
+
+#### 1. text_to_image
+根据文本描述生成图片。
+
+#### 2. image_to_image
+基于输入图片和文本描述生成新图片。
+
+#### 3. download
+下载图片或视频到本地。
+
+#### 4. get_image_info
+获取图片信息。
+
+#### 5. crop_image
+裁剪图片。
+
+#### 6. resize_image
+调整图片尺寸。
+
+#### 7. convert_image
+转换图片格式。
+
+#### 8. adjust_image
+调整图片的亮度、对比度和饱和度。
+
+#### 9. text_to_video
+根据文本提示生成视频。
+
+#### 10. image_to_video
+基于首帧与可选尾帧生成视频。
+
+#### 11. analyze_image
+分析图片内容，返回结构化或文本结果。
+
+#### 12. paste_image
+将图片粘贴到背景图片的指定位置。
+
+#### 13. upload_to_oss (新增)
+上传本地文件到阿里云 OSS。
+
+#### 14. download_and_upload_to_oss (新增)
+下载 URL 并直接上传到阿里云 OSS（无需本地保存）。
+
+## 项目结构
+
+```
+imgenx-mcp-server/
+├── imgenx/
+│   ├── server.py                  # MCP 服务器主文件（工具定义与运行）
+│   ├── factory.py                 # 预测器工厂（图片/视频/分析）
+│   ├── operator.py                # 图片处理操作模块
+│   ├── main.py                    # CLI 入口（imgenx）
+│   ├── script.py                  # 命令行生成图片/视频脚本
+│   └── predictor/
+│       ├── base/
+│       │   ├── base_image_generator.py   # 基础图片生成器接口
+│       │   ├── base_video_generator.py   # 基础视频生成器接口
+│       │   └── base_image_analyzer.py    # 基础图片分析器接口
+│       └── generators/
+│           ├── doubao_image_generator.py   # 豆包图片生成器实现
+│           ├── doubao_video_generator.py   # 豆包视频生成器实现
+│           └── doubao_image_analyzer.py    # 豆包图片分析器实现
+├── pyproject.toml                 # 项目配置（入口脚本等）
+├── uv.lock                        # 依赖锁（可选）
+└── README.md                      # 项目说明
+```
+
+## 扩展新的服务提供商
+
+要扩展新的服务提供商：
+
+1. 在 `imgenx/predictor/generators/` 目录下创建实现文件，命名规范：
+   - 图片生成器：`{provider}_image_generator.py`
+   - 视频生成器（可选）：`{provider}_video_generator.py`
+   - 图片分析器（可选）：`{provider}_image_analyzer.py`
+
+2. 实现 `BaseImageGenerator` 接口：
+```python
+from typing import List, Dict
+from imgenx.predictor.base.base_image_generator import BaseImageGenerator
+
+class ProviderImageGenerator(BaseImageGenerator):
+    def __init__(self, model: str, api_key: str):
+        self.model = model
+        self.api_key = api_key
+        # 其他初始化代码
+    
+    def text_to_image(self, prompt: str, size: str) -> List[Dict[str, str]]:
+        # 实现文本生成图片逻辑
+        # 返回格式: [{"url": "图片URL"}]
+        pass
+    
+    def image_to_image(self, prompt: str, images: List[str], size: str) -> List[Dict[str, str]]:
+        # 实现图片生成图片逻辑（可选）
+        # 返回格式: [{"url": "图片URL"}]
+        pass
+```
+
+3. 工厂类会自动发现并加载新的实现（基于文件名），模型字符串需为 `provider:model` 格式，例如：`doubao:doubao-seedream-4-0-250828`
+
+## 依赖项
+
+- `fastmcp>=2.12.4`: MCP 协议实现
+- `python-dotenv>=1.1.1`: 环境变量加载
+- `volcengine-python-sdk[ark]>=4.0.22`: 火山引擎 SDK（豆包服务）
+- `requests>=2.25.0`: HTTP 请求库（用于图片下载）
+- `pillow>=12.0.0`: 图片处理库（用于图片编辑操作）
+- `oss2>=2.19.1`: 阿里云 OSS SDK（用于文件上传）
+
+## 使用示例
+
+### 在 Claude Desktop 中使用
+
+配置完成后，在 Claude 中可以直接使用自然语言：
+
+```
+生成一只小猫在天上飞的图片
+```
+
+```
+生成一个日落海滩的视频，5秒，1080p
+```
+
+```
+把刚生成的图片上传到 OSS
+```
+
+### 完整工作流示例
+
+1. **生成图片**
+   ```
+   生成一只可爱的小猫在蓝天白云中飞翔的图片
+   ```
+
+2. **上传到 OSS**
+   ```
+   把这张图片上传到 OSS
+   ```
+
+   返回 CDN 地址，可直接访问和分享。
+
+## 相关文档
+
+- [OSS 上传使用说明](./OSS_USAGE.md)
+- [性能优化说明](./PERFORMANCE_OPTIMIZATION.md)
+
+## 更新日志
+
+### v0.3.0 (当前版本)
+
+#### 新增功能
+- **☁️ 阿里云 OSS 上传**: 新增 `upload_to_oss` 和 `download_and_upload_to_oss` 工具
+- **CDN 加速支持**: 上传后自动返回 CDN 加速地址
+- **完整工作流**: 生成图片/视频 -> 上传 OSS -> 获取 CDN URL
+
+#### 性能优化
+- 移除不必要的文件验证步骤，提升上传速度约 35%
+- 优化文件上传流程，减少网络请求
+
+#### 文档完善
+- 新增 OSS 上传使用说明文档
+- 新增性能优化说明文档
+- 完善 Claude Desktop 配置示例
+
+### v0.2.3
+
+#### 新增功能
+- **图片粘贴**: 新增 `paste_image` 工具，支持将图片粘贴到背景图片的指定位置
+- **工具控制**: 新增 `--no_tools` 参数，支持在运行 MCP 服务器时禁用特定工具
+
+#### 功能优化
+- 完善图片处理工具集，增强图片编辑能力
+
+### v0.2.0
+
+#### 新增功能
+- **视频生成**: 支持 `text_to_video` 与 `image_to_video` 两种方式
+- **图片分析**: 新增 `analyze_image` 工具，支持视觉模型分析
+- **图片处理工具集完善**: `get_image_info`、`crop_image`（比例坐标）、`resize_image`、`convert_image`、`adjust_image`
+
+#### 技术改进
+- 工厂模式统一图片/视频/分析三类预测器的发现与加载
+- 环境变量分离为 `IMGENX_IMAGE_MODEL`、`IMGENX_VIDEO_MODEL`、`IMGENX_ANALYZER_MODEL`
+- MCP 工具集扩展，HTTP 服务器提供 `/health`、`/healthy` 健康检查路由
+- 支持本地文件与 URL 两种图片输入方式；下载工具统一图片/视频
+
+## 许可证
+
+本项目的许可证信息请查看项目仓库。
+
+## 贡献
+
+欢迎提交 Issue 和 Pull Request 来改进这个项目。
+
+## 联系方式
+
+- GitHub: [@helios123](https://github.com/helios123)
+- Issues: [提交问题](https://github.com/helios123/imgenx-mcp/issues)
+- 原作者 Email: zhangslwork@yeah.net

imgenx_mcp-0.4.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+imgenx/factory.py,sha256=SWFv8cXeh0RD9Zm6EQIicly1GEKbq_86SNb3CXQfkQk,1667
+imgenx/main.py,sha256=fQ-LGtd2V31PjUopUm3uuZ9YslVhBB1i61P0oh5r5M4,2969
+imgenx/operator.py,sha256=tOVDTolKxL-3BK_9Mq4DHypXzgdhyv-gKgH0hRwghRE,4270
+imgenx/oss_service.py,sha256=5IM6p5DbUrWSl-IsJMrtF3CyZ4ymN37L32Qi55Uq92I,5879
+imgenx/script.py,sha256=CpTPesuNdTBQttL4sZsq_eBje0jgif-EqHT_Sp0Ot18,3870
+imgenx/server.py,sha256=f0AtRDq8NJ0rauxjiADSR3GtqKlpB6_FEwBReAKrK10,13195
+imgenx/predictor/base/base_image_analyzer.py,sha256=6eMZwqagRtW-qBidRqt5y8DDW1NoPbz-oqSLYiq7lok,330
+imgenx/predictor/base/base_image_generator.py,sha256=5lfFLU3k53X4n8Ld4Y1ex5_1PrfJrYT5UMAG-oWV2iU,488
+imgenx/predictor/base/base_video_generator.py,sha256=s2MSQSjsJrvZYGfN5bmW6O4sLxU5elCcDh1GfYRI_n8,587
+imgenx/predictor/generators/doubao_image_analyzer.py,sha256=Pja1N_sfMdnDhUQHFFoYpnapnd8t_nstj8g-YQ7h7wk,1942
+imgenx/predictor/generators/doubao_image_generator.py,sha256=CKKqPEnzIqq7RFhJ7zchSHj-vyNSuBMPhx3KYn1YEEg,2237
+imgenx/predictor/generators/doubao_video_generator.py,sha256=P0SqvWW0laB9Q0oxoITPRBxOT6_anQ6xWRZ7szk76pA,3931
+imgenx_mcp-0.4.0.dist-info/METADATA,sha256=VxKS3nSAo3J9pAJBTn5gw44roikz5Ucp9f1N-7f6hW8,13435
+imgenx_mcp-0.4.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+imgenx_mcp-0.4.0.dist-info/entry_points.txt,sha256=nmx0IbHTuYEWYXTv8T__X_d1JzcktNjsTSQFM98PgFU,43
+imgenx_mcp-0.4.0.dist-info/licenses/LICENSE,sha256=fL49JMavx1QC0XPJ8i2RPNJQ_vmDwoiXM2jF66ytAf0,1068
+imgenx_mcp-0.4.0.dist-info/RECORD,,

imgenx_mcp-0.4.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

imgenx_mcp-0.4.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+imgenx = imgenx.main:run

imgenx_mcp-0.4.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 zhangshulin
+
+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.