npm package: @mcpcn/ai-fashion-editor-mcp
Description: AI时尚图片编辑 MCP 工具集
Author: 你的名字
Latest version: 1.0.13

# AI时尚图片编辑 MCP 工具集

这是一个基于 Model Context Protocol (MCP) 的 AI 时尚图片编辑工具集，使用 TypeScript/Node.js 实现。提供两个强大的图片编辑工具：

## 🛠️ 功能特性

### 1. 多图融合修改 🆕
- **功能**：支持2-5张图片的动态融合，创建灵活的时尚搭配照片
- **特色**：智能适应不同数量的图片，自动生成对应的融合提示词
- **输入**：2-5张图片（第一张为主体人物，后续为服装/配饰）
- **输出**：专业的动态时尚搭配照片

🌈 **支持的组合**：
- 2图融合：人物 + 服装
- 3图融合：人物 + 服装 + 配饰
- 4图融合：人物 + 上装 + 下装 + 配饰
- 5图融合：人物 + 上装 + 下装 + 帽子 + 鞋子

### 2. 单图修改
- **功能**：对单张图片进行各种修改
- **用途**：改变颜色、样式、背景、添加元素等
- **输入**：原始图片 + 修改指令
- **输出**：修改后的高质量图片

### 3. 中文文字添加 🆕
- **功能**：使用阿里云 DashScope API 在图片上添加中文文字
- **特色**：AI驱动的文字添加，自然融入图片，自动添加"AI生成"水印
- **输入**：图片 + 文字内容 + 样式选项
- **输出**：添加文字后的专业图片（右下角带"AI生成"水印）
- **自动上传**：处理完成后自动上传到云端并返回URL

## 🚀 快速开始

### 1. 安装依赖
```bash
npm install
```

> ✅ **好消息**: 本项目使用 `sharp` 库来添加水印，无需任何系统依赖，安装简单快捷！

### 2. 配置 API 密钥 🔑
在使用前，你需要设置两个必需的 API 密钥为环境变量：

#### Gemini API 密钥（用于图片融合和修改）
**macOS/Linux:**
```bash
export GEMINI_API_KEY="your-gemini-api-key-here"
```

**Windows:**
```cmd
set GEMINI_API_KEY=your-gemini-api-key-here
```

#### 阿里云 DashScope API 密钥（用于中文文字添加）
**macOS/Linux:**
```bash
export DASHSCOPE_API_KEY="your-dashscope-api-key-here"
```

**Windows:**
```cmd
set DASHSCOPE_API_KEY=your-dashscope-api-key-here
```

**永久设置（推荐）:**
将上述命令添加到你的 shell 配置文件中（如 `~/.bashrc`, `~/.zshrc` 或 `~/.profile`）

**获取 API 密钥:**
1. **Gemini API 密钥**: 访问 [Google AI Studio](https://makersuite.google.com/app/apikey)
2. **阿里云 DashScope 密钥**: 访问 [阿里云控制台](https://dashscope.console.aliyun.com/)

### 3. 编译 TypeScript
```bash
npm run build
```

### 4. 运行开发模式
```bash
npm run dev
```

### 5. 启动 MCP 服务器
```bash
npm start
```

> ⚠️ **重要提示**: 
> - 如果未设置 `GEMINI_API_KEY` 环境变量，图片融合和修改功能将无法使用
> - 如果未设置 `DASHSCOPE_API_KEY` 环境变量，中文文字添加功能将无法使用
> - 两个API密钥都需要配置才能使用完整功能

## 📁 项目结构

```
├── src/
│   ├── index.ts           # MCP 服务器主文件
│   └── imageProcessor.ts  # 图片处理工具类
├── dist/                 # 编译输出目录
├── package.json          # 项目配置
├── tsconfig.json         # TypeScript 配置
├── mcp-config.json       # MCP 服务器配置
└── README.md            # 说明文档
```

## 🔧 MCP 工具说明

### 多图融合修改 🆕

**工具名称**：`multi-image-fusion`

**参数**：
- `imagePaths` (必需): 要融合的图片路径数组，支持2-5张图片
- `outputDir` (必需): 输出目录路径
- `customPrompt` (可选): 自定义提示词

**动态使用示例**：

1️⃣ **2图融合**（简约风格）：
```json
{
  "imagePaths": [
    "/path/to/model.jpg",
    "/path/to/dress.jpg"
  ],
  "outputDir": "/path/to/output",
  "customPrompt": "创建简约优雅的时尚造型"
}
```

2️⃣ **3图融合**（进阶搭配）：
```json
{
  "imagePaths": [
    "/path/to/model.jpg",
    "/path/to/dress.jpg",
    "/path/to/hat.webp"
  ],
  "outputDir": "/path/to/output",
  "customPrompt": "创建街头时尚风格造型"
}
```

3️⃣ **4图融合**（完整造型）：
```json
{
  "imagePaths": [
    "/path/to/model.jpg",
    "/path/to/top.jpg",
    "/path/to/skirt.jpg",
    "/path/to/shoes.webp"
  ],
  "outputDir": "/path/to/output"
}
```

4️⃣ **5图融合**（全套搭配）：
```json
{
  "imagePaths": [
    "/path/to/model.jpg",
    "/path/to/top.jpg",
    "/path/to/skirt.jpg",
    "/path/to/hat.webp",
    "/path/to/shoes.webp"
  ],
  "outputDir": "/path/to/output",
  "customPrompt": "创建专业的全套时尚造型"
}
```

### 中文文字添加 🆕

**工具名称**：`add-chinese-text`

**参数**：
- `imagePath` (必需): 要添加文字的图片文件路径
- `text` (必需): 要添加的中文文字内容
- `outputDir` (必需): 输出目录路径
- `x` (可选): 文字的X坐标位置
- `y` (可选): 文字的Y坐标位置
- `fontSize` (可选): 字体大小，默认40px
- `fontFamily` (可选): 字体名称，默认Arial
- `color` (可选): 字体颜色，默认白色
- `outputFilename` (可选): 输出文件名

**示例用法**：
```json
{
  "imagePath": "/path/to/image.jpg",
  "text": "时尚新品",
  "outputDir": "/path/to/output",
  "fontSize": 50,
  "color": "#FF0000"
}
```

**功能说明**：
1. 使用阿里云 DashScope API 在图片上添加指定的中文文字
2. 自动在图片右下角添加"AI生成"水印（半透明白色，带黑色描边）
3. 将处理后的图片上传到 `https://www.mcpcn.cc/api/fileUploadAndDownload/uploadMcpFile`
4. 返回云端图片的 URL 地址

## 🎨 使用示例

### Python 版本对比
原 Python 代码功能已完全移植到 TypeScript，包括：
- ✅ Base64 图片编码
- ✅ Gemini API 调用
- ✅ 多图融合处理
- ✅ 单图修改功能
- ✅ 自动保存结果
- ✅ 错误处理机制

### 使用方式
程序支持处理你本地的图片文件，只需提供正确的文件路径即可。

## 🔐 配置说明

### API 密钥 安全设置
程序仅从环境变量中读取 API 密钥，保证安全性：

```typescript
// 代码中的实现
const apiKey = process.env.GEMINI_API_KEY;
if (!apiKey) {
  console.error('错误: 未设置 GEMINI_API_KEY 环境变量');
  process.exit(1);
}
```

**获取 Gemini API 密钥:**
1. 访问 [Google AI Studio](https://makersuite.google.com/app/apikey)
2. 创建新的 API 密钥
3. 复制密钥并设置为环境变量

### 支持的图片格式
- JPEG (.jpg, .jpeg)
- PNG (.png)
- WebP (.webp)
- GIF (.gif)

## 📊 输出文件

每次处理都会生成以下文件：
1. **生成的图片**：`*_result.png`
2. **API 响应数据**：`*_response.json`
3. **日志信息**：控制台输出处理状态

## 🐛 故障排除

### 常见问题
1. **API 调用失败**：检查网络连接和 API 密钥
2. **图片编码错误**：确认图片文件存在且格式正确
3. **权限错误**：确保输出目录有写入权限

### 调试模式
运行开发模式查看详细输出：
```bash
npm run dev
```

## 🤝 贡献指南

欢迎提交 Issues 和 Pull Requests 来改进这个项目！

## 📄 许可证

MIT License - 详见 LICENSE 文件

---

**技术栈**：TypeScript + Node.js + MCP SDK + Gemini API + Axios

**作者**：[你的名字]

**版本**：1.0.0