@devinrcai/mcp-image-generator/README.md

MCP server for generating images using ModelScope API - works with Claude Desktop and other MCP clients

# MCP Image Generator Server

一个用于生成图片的 MCP (Model Context Protocol) 服务器，专为 AI 编码工具设计，帮助开发者在构建网站时自动生成所需的图片。现在支持通过 npx 一键安装和使用！

## 功能特点

- 🎨 **文字生成图片**: 使用 ModelScope 的 FLUX 模型，根据文字描述生成高质量图片
- 🔐 **安全的 API 密钥管理**: API 密钥由客户端提供，不会硬编码在服务器中
- 🌐 **网站开发集成**: 专为网站开发场景设计，可生成占位符 HTML 代码
- 📁 **图片管理**: 自动保存生成的图片，并提供资源列表功能
- 🔧 **完整的 MCP 实现**: 支持工具、资源和提示功能
- 📦 **NPX 支持**: 通过 npx 一键安装和配置，无需手动设置

## 快速开始 (推荐)

### 方式一：使用 npx (最简单)

```bash
# 显示帮助和所有选项
npx @devinrcai/mcp-image-generator --help

# 自动生成 Claude Desktop 配置
npx @devinrcai/mcp-image-generator --setup

# 直接启动 MCP 服务器
npx @devinrcai/mcp-image-generator --start

# 查看所有配置示例
npx @devinrcai/mcp-image-generator --config
```

### 方式二：手动安装

1. 克隆或复制项目到本地：
```bash
cd mcp-image-generator
```

2. 安装依赖：
```bash
npm install
```

3. 构建项目：
```bash
npm run build
```

## 配置 MCP 客户端

### 方式一: 使用 npx 自动配置 (推荐)

最简单的配置方式，运行以下命令自动生成 Claude Desktop 配置：

```bash
npx mcp-image-generator --setup
```

这会自动生成正确的配置并告诉你如何添加到 Claude Desktop。

### 方式二: 手动配置 Claude Desktop

在 Claude Desktop 的配置文件 (`~/Library/Application Support/Claude/claude_desktop_config.json`) 中添加：

```json
{
  "mcpServers": {
    "image-generator": {
      "command": "npx",
      "args": ["mcp-image-generator", "--start"]
    }
  }
}
```

### 方式三: 使用项目提供的 mcp.json 配置

项目已包含预配置的 `mcp.json` 文件，使用npx方式（推荐）：

```json
{
  "mcpServers": {
    "image-generator": {
      "command": "npx",
      "args": ["@devinrcai/mcp-image-generator", "--start"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}
```

如果你需要使用本地源码，可以使用：

```json
{
  "mcpServers": {
    "image-generator": {
      "command": "node",
      "args": ["/绝对路径/to/mcp-image-generator/dist/index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}
```

### 方式四: 使用启动脚本

如果你是从源码安装，项目提供了便捷的启动脚本：

```bash
# 直接运行启动脚本
./start-mcp.sh

# 或者使用 npm
npm run start
```

### 其他 MCP 客户端

对于其他支持 MCP 的客户端，推荐使用 npx 方式：
- 命令: `npx`
- 参数: `["mcp-image-generator", "--start"]`

或者查看所有配置选项：
```bash
npx mcp-image-generator --config
```

## 使用方法

### 1. 设置 API 密钥

首次使用时，需要提供你的 ModelScope API 密钥：

```
使用 set-api-key 工具，提供你的 ModelScope API 密钥
```

### 2. 生成图片

```
使用 generate-image 工具：
- prompt: "一只金色的猫坐在窗台上看夕阳"
- filename: "golden-cat" (可选)
```

### 3. 生成 HTML 占位符

为网页生成图片占位符代码：

```
使用 generate-placeholder-html 工具：
- altText: "产品展示图"
- width: 800
- height: 600
- className: "product-image"
```

### 4. 查看已生成的图片

```
访问资源 images://generated 查看所有已生成的图片列表
```

## 可用工具

1. **set-api-key**: 设置 ModelScope API 密钥
   - 参数: `key` (string) - 你的 API 密钥

2. **generate-image**: 生成图片
   - 参数: 
     - `prompt` (string) - 图片描述
     - `filename` (string, 可选) - 文件名（不含扩展名）

3. **generate-placeholder-html**: 生成 HTML 图片标签
   - 参数:
     - `altText` (string) - 替代文本
     - `width` (number, 可选) - 宽度
     - `height` (number, 可选) - 高度
     - `className` (string, 可选) - CSS 类名

## 资源

- **images://generated**: 列出所有已生成的图片

## 工作流程示例

1. AI 编码助手在构建网站时遇到需要图片的地方
2. 使用 `generate-placeholder-html` 创建占位符
3. 使用 `generate-image` 根据描述生成实际图片
4. 将生成的图片路径更新到 HTML 中

## 获取 ModelScope API 密钥

1. 访问 [ModelScope 官网](https://modelscope.cn)
2. 注册/登录账号
3. 在个人中心获取 API Token

## 注意事项

- API 密钥保存在内存中，服务器重启后需要重新设置
- 生成的图片保存在 `generated-images` 目录下
- 支持 JPEG 格式输出
- 请合理使用 API，注意调用频率限制

## 开发

- 开发模式: `npm run dev`
- 构建: `npm run build`
- 清理构建文件: `npm run clean`

## 许可证

MIT