@bashcat/ai-image-chat-mcp/README.md

MCP server for AI image generation, video generation and chat completion with support for multiple AI providers including Tongyi Wanxiang

# AI Image Chat MCP 工具

這是一個通用的 AI 圖片生成和對話完成 Model Context Protocol (MCP) 工具，支持多種 AI 服務提供商。

## 功能特性

- 🖼️ **圖片生成**: 使用 AI 模型生成圖片
- 💬 **對話完成**: 使用 AI 模型進行智能對話
- 🚀 **阿里雲 DashScope**: 支援阿里雲 DashScope 高品質文生圖 API
- 📁 **自動保存**: 生成的圖片會自動下載並保存到指定目錄
- 📝 **智能命名**: 檔名根據用戶的 prompt 自動生成
- 🔐 **安全配置**: API 密鑰安全保存在 `.env` 文件中
- 🎛️ **自定義提示**: 支持自定義系統提示詞，如未提供則使用預設值

## 安裝與設置

### 1. 安裝依賴

```bash
npm install
```

### 2. 配置環境變數

編輯 `.env` 文件，設置你的 API 密鑰：

```env
AI_API_KEY=your_api_key_here
AI_API_BASE_URL=https://api.laozhang.ai/v1
AI_IMAGE_SAVE_PATH=/path/to/your/images/directory
ALI_API_KEY=your_ali_api_key_here
# 或者使用
DASHSCOPE_API_KEY=your_dashscope_api_key_here
```

**環境變數說明：**

- `AI_API_KEY`: 您的 AI API 密鑰（必須）
- `AI_API_BASE_URL`: API 基礎 URL（可選，預設為 `https://api.laozhang.ai/v1`）
- `AI_IMAGE_SAVE_PATH`: 圖片保存路徑（可選，預設為 `~/generated_images`）
- `ALI_API_KEY`: 阿里雲 DashScope API 密鑰（使用阿里雲功能時必須）
- `DASHSCOPE_API_KEY`: 阿里雲 DashScope API 密鑰的別名（與 ALI_API_KEY 二選一）

**支持的 API 服務商：**

- 老張 AI: `https://api.laozhang.ai/v1`
- 阿里雲 DashScope: `https://dashscope.aliyuncs.com/api/v1`
- OpenAI: `https://api.openai.com/v1`
- 其他 OpenAI 兼容的 API 服務

### 3. 編譯項目

```bash
npm run build
```

### 4. 啟動服務

```bash
npm start
```

## MCP (Model Context Protocol) 設置

### 在 Claude Desktop 中使用

編輯您的 Claude Desktop 配置文件 (`~/Library/Application Support/Claude/claude_desktop_config.json`)：

```json
{
  "mcpServers": {
    "ai-image-chat-mcp": {
      "command": "npx",
      "args": ["-y", "@bashcat/ai-image-chat-mcp"],
      "env": {
        "AI_API_KEY": "your_api_key_here",
        "AI_API_BASE_URL": "https://api.laozhang.ai/v1",
        "AI_IMAGE_SAVE_PATH": "/path/to/your/images/directory",
        "ALI_API_KEY": "your_ali_api_key_here"
      }
    }
  }
}
```

### 在 VS Code 中使用

編輯您的 VS Code 設置 (`settings.json`)：

```json
{
  "mcp": {
    "servers": {
      "ai-image-chat-mcp": {
        "command": "npx",
        "args": ["-y", "@bashcat/ai-image-chat-mcp"],
        "env": {
          "AI_API_KEY": "your_api_key_here",
          "AI_API_BASE_URL": "https://api.laozhang.ai/v1",
          "AI_IMAGE_SAVE_PATH": "/path/to/your/images/directory",
          "ALI_API_KEY": "your_ali_api_key_here"
        }
      }
    }
  }
}
```

### 環境變數配置

| 環境變數             | 必需 | 預設值                       | 說明                   |
| -------------------- | ---- | ---------------------------- | ---------------------- |
| `AI_API_KEY`         | ✅   | -                            | 您的 AI API 密鑰       |
| `AI_API_BASE_URL`    | ❌   | `https://api.laozhang.ai/v1` | API 基礎 URL           |
| `AI_IMAGE_SAVE_PATH` | ❌   | `~/generated_images`         | 圖片保存路徑           |
| `ALI_API_KEY`        | ❌   | -                            | 阿里雲 DashScope 密鑰  |
| `DASHSCOPE_API_KEY`  | ❌   | -                            | 阿里雲密鑰的別名       |

### 圖片保存功能

- 🖼️ **自動下載**: 生成的圖片會自動下載到指定目錄
- 📝 **智能命名**: 檔名根據 prompt 自動生成，例如：`台灣男性工程師-2025-06-29T04-40-40-978Z.jpg`
- 📁 **目錄創建**: 如果指定目錄不存在，會自動創建
- 🔄 **格式轉換**: 支援 PNG 自動轉換為 JPG，也支援保持原始格式或轉換為 WebP
- 🎨 **多格式支援**: 支援 JPG、PNG、WebP 輸出格式

## 可用工具

### 1. generate_image

使用老張 AI 生成圖片的工具。

**參數:**

- `prompt` (必需): 圖片生成的提示詞
- `system_prompt` (可選): 系統提示詞，預設為 "You are a helpful assistant that generates images."
- `model` (可選): 模型名稱，可選 "gpt-image-1" 或 "gpt-4o-image"，預設為 "gpt-4o-image"
- `output_format` (可選): 輸出圖片格式，可選 "jpg"、"jpeg"、"png"、"webp"，預設為 "jpg"

**範例:**

```json
{
  "prompt": "生成一張卡通風格的熊貓宇航員圖片，背景是星空",
  "system_prompt": "You are a creative image generator.",
  "model": "gpt-4o-image",
  "output_format": "png"
}
```

### 2. tongyi_wanxiang_generate_image (推薦)

使用通義萬相文生圖完整生圖流程。

**參數:**

- `prompt` (必需): 正向提示詞
- `model` (可選): 模型選擇，可選值：
  - `wanx2.1-t2i-turbo`: 速度快 (0.14元/張)
  - `wanx2.1-t2i-plus`: 品質高 (0.20元/張)  
  - `wanx2.0-t2i-turbo`: 性價比高，擅長人像 (0.04元/張)
- `negative_prompt` (可選): 反向提示詞，預設為 "人物"
- `size` (可選): 圖像分辨率，預設為 "1024*1024"
- `n` (可選): 生成圖片數量 (1-4)，預設為 1
- `seed` (可選): 隨機數種子
- `prompt_extend` (可選): 是否開啟智能改寫，預設為 true
- `watermark` (可選): 是否添加水印，預設為 false
- `output_format` (可選): 輸出格式，預設為 "jpg"
- `max_wait_minutes` (可選): 最大等待時間（分鐘），預設為 5

**範例:**

```json
{
  "prompt": "一隻可愛的橘貓坐在櫻花樹下，春天的陽光灑在它身上",
  "model": "wanx2.1-t2i-plus",
  "size": "1024*1024",
  "output_format": "png"
}
```

### 3. tongyi_wanxiang_create_task

創建通義萬相文生圖任務。

### 4. tongyi_wanxiang_query_task

查詢通義萬相文生圖任務結果。

### 5. chat_completion

進行對話的工具。

**參數:**

- `message` (必需): 用戶訊息
- `system_prompt` (可選): 系統提示詞，預設為 "You are a helpful assistant."
- `model` (可選): 模型名稱，預設為 "gpt-4"

**範例:**

```json
{
  "message": "請幫我寫一首關於春天的詩",
  "system_prompt": "You are a professional poet.",
  "model": "gpt-4"
}
```

## API 參考

本工具使用老張 AI 的聊天完成 API：

```
POST https://api.laozhang.ai/v1/chat/completions
```

**請求格式:**

```json
{
  "model": "gpt-image-1",
  "messages": [
    { "role": "system", "content": "系統提示詞" },
    { "role": "user", "content": "用戶訊息" }
  ]
}
```

## 開發

### 開發模式

```bash
npm run dev
```

這會啟動 TypeScript 編譯器的監聽模式，當你修改代碼時會自動重新編譯。

### 項目結構

```text
laozhang_mcp/
├── src/
│   └── index.ts          # 主要服務器代碼
├── dist/                 # 編譯後的輸出
├── .env                  # 環境變數配置
├── package.json          # 項目配置
├── tsconfig.json         # TypeScript 配置
└── README.md            # 說明文檔
```

## 通義萬相文生圖集成

本工具支援阿里雲通義萬相文生圖V2版本的三種模型。詳細說明請參考：
- [通義萬相使用指南](./TONGYI_WANXIANG_GUIDE.md) - 新版詳細指南
- [DASHSCOPE_INTEGRATION.md](./DASHSCOPE_INTEGRATION.md) - 原版集成說明

### 模型對比

| 模型 | 特點 | 價格 | 適用場景 |
|------|------|------|----------|
| wanx2.1-t2i-turbo | 速度快 | 0.14元/張 | 快速生成 |
| wanx2.1-t2i-plus | 品質高 | 0.20元/張 | 精細作品 |
| wanx2.0-t2i-turbo | 性價比高 | 0.04元/張 | 人像專長 |

### 快速開始

1. 在 [阿里雲百炼平台](https://dashscope.aliyuncs.com/) 獲取 API Key
2. 設置環境變數 `ALI_API_KEY`
3. 使用 `tongyi_wanxiang_generate_image` 工具生成圖片

## 注意事項

1. 請確保你有有效的 AI API 密鑰
2. 使用阿里雲功能需要設置 `ALI_API_KEY` 或 `DASHSCOPE_API_KEY`
3. 不要將 `.env` 文件提交到版本控制系統
4. 圖片生成可能需要較長時間，請耐心等待
5. API 有使用限制，請適度使用

## 許可證

MIT License