Mcp Image Server

MCP Image Server

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

功能

• 使用 GPT Image 1（OpenAI）生成自定义图像
• 提供 .png、.svg（嵌入 base64 图像）和 .ico（实际转换）格式的文件
• 可配置图像尺寸：1024×1024（正方形）、1536×1024（横向）或 1024×1536（纵向）
• 背景控制：'transparent' 或 'opaque'
• 质量设为 'low'，审核设为 'low'，以加快生成速度
• MCP 工具附有使用示例文档，可通过资源访问
• 提供用于查询支持格式的资源
• 可随时集成到 MCP 客户端、Agent 和 Vibe Coding 工作流中
• 支持跨平台（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 身份验证所需的环境变量。

如何在本地运行

1. 安装依赖项：

   npm install
   

2. 构建项目：

   npm run build
   

3. 使用 OpenAI 密钥设置 OPENAI_API_KEY 环境变量：

   • 在 Windows（PowerShell）上：

     $env:OPENAI_API_KEY="your-key-here"
     

   • 在 Linux/Mac 上：

     export OPENAI_API_KEY="your-key-here"
     

4. 通过 npx 运行：

   npx mcp-image-server
   

如何提交到 MCP.so

1. 确保项目已构建、测试并编写好文档
2. 按照 https://mcp.so/ 上的提交说明操作

进度与文档

• 初始项目结构
• MCP 服务实现
• GPT Image 1 实际集成
• 转换并提供 .png、.svg、.ico 格式的文件
• MCP 工具已编写文档并添加注释
• 使用示例资源（resource://tool-examples）
• 支持格式资源（formats://supported）
• 与 MCP 客户端的集成测试
• 自动化测试和边缘情况验证
• 最终详细文档（示例、故障排查）

---

视觉示例

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

示例 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 Image 1）生成自定义图像，并以所请求的格式交付。

参数：

• prompt（字符串）：所需图像的文字描述
• format（"png" | "svg" | "ico"）：输出格式（默认值："png"）
• size（"1024x1024" | "1536x1024" | "1024x1536"）：图像尺寸（默认值："1024x1024"）
• background（"transparent" | "opaque"）：背景类型（默认值："transparent"）

示例：

{
  "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（字符串）：favicon 的文字描述
• size（"1024x1024" | "1536x1024" | "1024x1536"）：图像尺寸（默认值："1024x1024"）
• background（"transparent" | "opaque"）：背景类型（默认值："transparent"）

示例：

{
  "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 Image 1 图像失败：请检查密钥、连接和 OpenAI 使用限额。
• Windows 上的权限问题：本项目支持跨平台运行，但如果遇到权限错误，请以管理员身份运行终端。

---

按照 MCP Agent 的最佳实践开发，可随时集成并发布到 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：群山环绕的未来风景（PNG）

使用的提示词：

{
  "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、移动或桌面应用。

工具文档

generate-image

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

必需参数：

• prompt（字符串）：所需图像的文字描述
• format（"png" | "svg" | "ico"）：输出格式（默认值："png"）
• size（"1024x1024" | "1536x1024" | "1024x1536"）：图像尺寸（默认值："1024x1024"）
• background（"transparent" | "opaque"）：背景类型（默认值："transparent"）
• fileName（字符串）：要保存的文件名（不含扩展名）
• directory（字符串）：文件的保存目录完整路径（必须采用相应操作系统的路径格式，例如 Windows 上的 C:\Users\user\project\folder，或 Linux/Mac 上的 /home/user/project/folder）

**重要：**请始终在 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"
}

generate-favicon

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

必需参数：

• prompt（字符串）：favicon 的文本描述
• size（"1024x1024" | "1536x1024" | "1024x1536"）：图像尺寸（默认值："1024x1024"）
• background（"transparent" | "opaque"）：背景类型（默认值："transparent"）
• fileName（字符串）：要保存的文件名（不含扩展名）
• directory（字符串）：文件的保存目录完整路径（操作系统格式）

使用示例（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"
}

generate-svg

生成包含嵌入式 AI 图像（base64）的 SVG 文件。

必需参数：

• prompt（字符串）：所需图像的文本描述
• size（"1024x1024" | "1536x1024" | "1024x1536"）：图像尺寸（默认值："1024x1024"）
• background（"transparent" | "opaque"）：背景类型（默认值："transparent"）
• fileName（字符串）：要保存的文件名（不含扩展名）
• directory（字符串）：文件的保存目录完整路径（操作系统格式）

使用示例（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（Model Context Protocol）工具必须遵循定义和文档编写的国际标准，让模型和 Agent 能够发现、理解并正确使用这些工具。以下是最佳实践和实际示例：

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
  }
}

• name：工具的唯一名称（例如 "generate-image"）
• description：清晰描述工具的功能
• inputSchema：定义必需和可选参数、类型及说明

实际示例（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 模型或 Agent 都能列出可用工具、读取其架构和描述，并正确调用工具，包括自动验证参数。

如需了解更多示例和详情，请参阅官方 MCP 文档。

---