使用说明

MCP映像服务器

基于TypeScript的MCP服务器，用于使用AI生成自定义图像和图标（GPT图像1）。它支持.png、.svg、.ico等输出格式。专为与Vibe Coding无缝集成而设计，可为您的项目按需创建视觉资产。跨平台，可通过以下方式执行 npx.

特性

通过GPT映像1（OpenAI）生成自定义映像
在中交付文件 .png, .svg （嵌入base64图像），以及 .ico （实际转换）
可配置的图像尺寸：1024×1024（方形）、1536×1024（横向）或1024×1536（纵向）
背景控制：“透明”或“不透明”
质量设置为“低”，适度设置为“低等”，以实现快速生成
MCP工具记录了使用示例，可通过资源访问
用于查询支持格式的资源
已准备好与MCP客户端、代理和Vibe编码流集成
跨平台（Windows/Linux/Mac），可通过运行 npx

项目结构

src/index.ts：MCP服务器、工具和资源的主要实现
package.json：项目配置、依赖关系和跨平台脚本
README.md：本文件
test-mcp-client.js：MCP客户端集成测试脚本
tsconfig.json：TypeScript配置
sample_config.json：MCP客户端配置示例

如何配置MCP客户端以使用此服务器

将以下配置添加到MCP服务器文件中（示例 sample_config.json):

{
    "servers": {
        "mcp-image-server": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@ricardopera/mcp-image-server@latest"
            ],
            "env": {
                "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE"
            }
        }
    }
}

这允许您直接通过npx运行映像服务器，而无需事先安装，并为OpenAI身份验证设置所需的环境变量。

如何在本地运行

安装依赖项：
```
npm install
```
构建项目：
```
npm run build
```
设置 OPENAI_API_KEY 带有OpenAI密钥的环境变量：
- 在Windows（PowerShell）上：
```
$env:OPENAI_API_KEY="your-key-here"
```
- 在Linux/Mac上：
```
export OPENAI_API_KEY="your-key-here"
```
通过npx运行：
```
npx mcp-image-server
```

如何提交给MCP.so

确保项目已构建、测试和记录
请按照以下提交说明进行操作： https://mcp.so/

进度和文件

[x] 初始项目结构
[x] MCP服务器实现
[x] 真正的GPT映像1集成
[x] 文件转换和交付 .png, .svg, .ico 格式
[x] 记录并注释MCP工具
[x] 使用示例资源(resource://tool-examples)
[x] 支持的格式资源(formats://supported)
[x] 与MCP客户端的集成测试
[]自动化测试和边缘案例验证
[]最终详细文档（示例、故障排除）

视觉示例

以下是MCP Image Server工具生成的图像的真实示例。所有图像都自动保存在 examples/ 文件夹使用 fileName 和 directory 工具的参数。

示例1：极简主义火箭图标（PNG）

使用提示：

{
  "prompt": "minimalist rocket icon transparent background",
  "format": "png",
  "size": "1024x1024",
  "background": "transparent",
  "fileName": "rocket-icon",
  "directory": "examples"
}

结果：

示例2：带字母A的蓝色圆形徽标（SVG）

使用提示：

{
  "prompt": "blue circular logo with letter A",
  "format": "svg",
  "size": "1536x1024",
  "background": "transparent",
  "fileName": "blue-logo-letter-a",
  "directory": "examples"
}

结果：

示例3：金星图标（ICO）

使用提示：

{
  "prompt": "golden star icon",
  "format": "ico",
  "size": "1024x1024",
  "background": "opaque",
  "fileName": "golden-star",
  "directory": "examples"
}

结果：

示例4：黄色星形图标（ICO）

使用提示：

{
  "prompt": "yellow star favicon transparent background",
  "size": "1024x1024",
  "background": "transparent",
  "fileName": "yellow-star-favicon",
  "directory": "examples"
}

结果：

示例5：红心图标（SVG）

使用提示：

{
  "prompt": "red heart icon",
  "size": "1024x1536",
  "background": "opaque",
  "fileName": "red-heart-icon",
  "directory": "examples"
}

结果：

这些示例展示了服务器以不同格式和目录生成和保存自定义图像的灵活性，从而促进了与web项目、应用程序和各种系统的集成。

可用工具

`generate-image`

使用AI生成自定义映像（GPT映像1），并以请求的格式交付。

参数：

prompt （string）：所需图像的文本描述
format （“png”|“svg”|“ico”）：输出格式（默认：“png”）
size （“1024x1024”|“1536x1024”|“1024x1536”）：图像大小（默认值：“1024x1024”）
background （“透明”|“不透明”）：背景类型（默认值：“透明”）

例子：

{
  "prompt": "minimalist rocket icon transparent background",
  "format": "png",
  "size": "1024x1024",
  "background": "transparent"
}

{
  "prompt": "blue circular logo with letter A",
  "format": "svg",
  "size": "1536x1024",
  "background": "transparent"
}

{
  "prompt": "golden star icon",
  "format": "ico",
  "size": "1024x1024",
  "background": "opaque"
}

`generate-favicon`

从文本提示生成自定义favicon.ico。

参数：

prompt （string）：favicon的文本描述
size （“1024x1024”|“1536x1024”|“1024x1536”）：图像大小（默认值：“1024x1024”）
background （“透明”|“不透明”）：背景类型（默认值：“透明”）

例子：

{
  "prompt": "yellow star favicon transparent background",
  "size": "1024x1024",
  "background": "transparent"
}

`generate-svg` （暂时不可用）

⚠️ 由于处理 SVG 内容为文本的技术问题，SVG 生成工具已暂时禁用。该功能将在未来版本中重新启用，以确保 SVG 仅被视为图像文件。

同时，使用PNG或ICO格式生成图像。

资源

resource://tool-examples：JSON中工具的使用示例
formats://supported：支持的格式列表（[“png”、“svg”、“ico”]）

环境变量

OPENAI_API_KEY：OpenAI API密钥（图像生成所需）

故障排除

错误OPENAI_API_KEY未定义或无效：在运行之前正确设置环境变量。
生成GPT映像1映像时出错：检查您的密钥、连接和OpenAI限制。
Windows上的权限问题：该项目是跨平台的，但如果出现权限错误，请以管理员身份运行终端。

为MCP代理开发了以下最佳实践，准备在MCP.so上集成和发布。

高级图像生成示例

以下是其他示例，展示了此项目中工具的灵活性和强大功能。所有图像均已生成并自动保存在 examples/ 文件夹。

示例6：友好的机器人头像（PNG）

使用提示：

{
  "prompt": "friendly robot avatar, white background, cartoon style, soft colors",
  "format": "png",
  "size": "1024x1024",
  "background": "opaque",
  "fileName": "friendly-robot-avatar",
  "directory": "examples"
}

结果：

示例7：带山脉的未来景观（巴布亚新几内亚）

使用提示：

{
  "prompt": "futuristic landscape with mountains and starry sky, digital art, transparent background",
  "format": "png",
  "size": "1536x1024",
  "background": "transparent",
  "fileName": "futuristic-landscape",
  "directory": "examples"
}

结果：

这些高级示例展示了如何使用MCP Image Server生成从极简主义图标到复杂插图的所有内容，以便在web、移动或桌面应用程序中使用。

工具文档

生成图像

使用AI生成自定义映像（GPT映像1），并以请求的格式保存。

所需参数：

prompt （string）：所需图像的文本描述
format （“png”|“svg”|“ico”）：输出格式（默认：“png”）
size （“1024x1024”|“1536x1024”|“1024x1536”）：图像大小（默认值：“1024x1024”）
background （“透明”|“不透明”）：背景类型（默认值：“透明”）
fileName （string）：要保存的文件的名称（不带扩展名）
directory （string）：保存文件的目录的完整路径（必须根据操作系统格式化，例如。， C:\Users\user\project\folder 在Windows或 /home/user/project/folder 在Linux/Mac上）

重要提示： 始终在中提供完整路径 directory 参数，以确保文件正确保存。路径必须采用服务器运行的操作系统的格式。

使用示例（Windows）：

{
  "prompt": "minimalist rocket icon transparent background",
  "format": "png",
  "size": "1024x1024",
  "background": "transparent",
  "fileName": "rocket-icon",
  "directory": "c:\\Users\\ricar\\Desktop\\projetos\\mcp-image-server\\examples"
}

使用示例（Linux/Mac）：

{
  "prompt": "minimalist rocket icon transparent background",
  "format": "png",
  "size": "1024x1024",
  "background": "transparent",
  "fileName": "rocket-icon",
  "directory": "/home/user/projects/mcp-image-server/examples"
}

生成favicon

从文本提示生成自定义favicon.ico。

所需参数：

prompt （string）：favicon的文本描述
size （“1024x1024”|“1536x1024”|“1024x1536”）：图像大小（默认值：“1024x1024”）
background （“透明”|“不透明”）：背景类型（默认值：“透明”）
fileName （string）：要保存的文件的名称（不带扩展名）
directory （string）：保存文件的目录的完整路径（操作系统格式）

使用示例（Windows）：

{
  "prompt": "yellow star favicon transparent background",
  "size": "1024x1024",
  "background": "transparent",
  "fileName": "yellow-star-favicon",
  "directory": "c:\\Users\\ricar\\Desktop\\projetos\\mcp-image-server\\examples"
}

生成svg

生成一个内嵌AI图像的SVG文件（base64）。

所需参数：

prompt （string）：所需图像的文本描述
size （“1024x1024”|“1536x1024”|“1024x1536”）：图像大小（默认值：“1024x1024”）
background （“透明”|“不透明”）：背景类型（默认值：“透明”）
fileName （string）：要保存的文件的名称（不带扩展名）
directory （string）：保存文件的目录的完整路径（操作系统格式）

使用示例（Linux/Mac）：

{
  "prompt": "red heart icon",
  "size": "1024x1536",
  "background": "opaque",
  "fileName": "red-heart-icon",
  "directory": "/home/user/projects/mcp-image-server/examples"
}

请参阅资源 resource://tool-examples 查看更实用的JSON示例。

如何实施和记录MCP工具

MCP（模型上下文协议）工具必须遵循国际定义和文档标准，允许模型和代理正确发现、理解和使用它们。请参阅下面的最佳实践和真实示例：

MCP工具定义结构

{
  name: string;          // Unique identifier of the tool
  description?: string;  // Human-readable description
  inputSchema: {         // JSON Schema of the tool parameters
    type: "object",
    properties: { ... }  // Specific tool parameters
  }
}

名字：工具的唯一名称（例如“生成图像”）
描述：明确描述该工具的功能
输入方案：定义必需和可选参数、类型和描述

实例（TypeScript）

server.registerTool(
  "generate-image",
  {
    title: "Generate Image with GPT Image 1",
    description: "Generates a custom image using AI (GPT Image 1) and delivers it in the requested format (.png, .svg, .ico).",
    inputSchema: {
      prompt: z.string().describe("Textual prompt describing the desired image"),
      format: z.enum(["png", "svg", "ico"]).default("png").describe("Output format of the image"),
      size: z.enum(["1024x1024", "1536x1024", "1024x1536"]).default("1024x1024").describe("Image size"),
      background: z.enum(["transparent", "opaque"]).default("transparent").describe("Background type"),
      fileName: z.string().default("image").describe("Name of the file to be saved (without extension)"),
      directory: z.string().default("./output").describe("Directory where the file will be saved")
    },
    annotations: {
      usage: "Use this tool to generate custom images and icons for your project. The prompt should be detailed for better results. The format defines the extension of the generated file."
    }
  },
  async ({ prompt, format, size, background, fileName, directory }) => { /* ... */ }
);

工具文档的最佳实践

始终包含清晰客观的描述
记录所有inputSchema参数，包括类型和示例
为每个工具提供JSON使用示例
使用 annotations.usage 使用提示和上下文字段
实施稳健的错误处理，返回友好的消息和 isError 必要时，现场

错误处理示例

try {
  // Tool operation
  const result = performOperation();
  return {
    content: [
      { type: "text", text: `Operation successful: ${result}` }
    ]
  };
} catch (error) {
  return {
    isError: true,
    content: [
      { type: "text", text: `Error: ${error.message}` }
    ]
  };
}

模型自动发现和使用

通过遵循此标准，任何MCP模型或代理都可以列出可用的工具，读取它们的模式和描述，并正确调用它们，包括自动参数验证。

请参阅 MCP官方文件更多示例和细节。

使用说明

MCP映像服务器

特性

项目结构

如何配置MCP客户端以使用此服务器

如何在本地运行

如何提交给MCP.so

进度和文件

视觉示例

示例1：极简主义火箭图标（PNG）

示例2：带字母A的蓝色圆形徽标（SVG）

示例3：金星图标（ICO）

示例4：黄色星形图标（ICO）

示例5：红心图标（SVG）

可用工具

generate-image

generate-favicon

generate-svg （暂时不可用）

资源

环境变量

故障排除

高级图像生成示例

示例6：友好的机器人头像（PNG）

示例7：带山脉的未来景观（巴布亚新几内亚）

工具文档

生成图像

生成favicon

生成svg

如何实施和记录MCP工具

MCP工具定义结构

实例（TypeScript）

工具文档的最佳实践

错误处理示例

模型自动发现和使用

相关 MCP

网页内容提取工具

图像提取转换服务

AI图像视频生成MCP服务

媒体处理服务器

图像编辑服务

图像处理工具

`generate-image`

`generate-favicon`

`generate-svg` （暂时不可用）