Skip to main content
Glama
deenesjakoruzh
jhupo

image-studio-mcp

by jhupo
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Hybrid

image-studio-mcp

中文：image-studio-mcp 是一个本地 stdio MCP server，带 Codex 插件元数据和配套 skill，用来调用 OpenAI 兼容图片接口，完成生图和改图。
English: image-studio-mcp — это локальный MCP-сервер stdio с метаданными плагина Codex и вспомогательным навыком для генерации и редактирования изображений через API изображений, совместимые с OpenAI.

Репозиторий:

Функции

  • generate_image для генерации текста в изображение

  • edit_image для редактирования изображений, редактирования нескольких изображений и опционального редактирования масок

  • image_studio_doctor для проверки подключения и конфигурации

  • Настраиваемый OPENAI_BASE_URL

  • Настраиваемый OPENAI_API_KEY

  • Настраиваемый OPENAI_IMAGE_MODEL

  • Сохранение в локальные файлы

  • Метаданные плагина Codex плюс навык

Требования

  • Node.js 20+

  • API-ключ для конечной точки изображений, совместимой с OpenAI

Переменные окружения

  • OPENAI_API_KEY 中文：必填，图片接口用到的 key。
    English: Обязательно. API-ключ для конечной точки изображений.

  • OPENAI_BASE_URL 中文：可选，默认是 https://api.openai.com/v1。
    English: Опционально. По умолчанию https://api.openai.com/v1.

  • OPENAI_IMAGE_MODEL 中文：可选，默认是 gpt-image-2。
    English: Опционально. По умолчанию gpt-image-2.

  • OPENAI_IMAGE_TIMEOUT_MS 中文：可选，默认 240000，代理慢或上游慢时可以调大。
    English: Опционально. По умолчанию 240000. Увеличьте это значение, если ваш шлюз или вышестоящая модель изображений работают медленно.

Локальная настройка

npm install
npm run validate
node ./scripts/openai-image-mcp.mjs

Полезные команды:

npm run doctor
npm run smoke:test

中文：这个 server 用的是 stdio transport，通常由 MCP 宿主拉起，不是手工常驻运行。
English: Этот сервер использует транспорт stdio и обычно запускается хостом MCP, а не вручную как резидентный процесс.

Что проверяет image_studio_doctor

中文：

  • 当前宿主是否已经能调用这个 MCP server

  • 当前 server 进程是否拿到了 OPENAI_API_KEY

  • 当前 OPENAI_BASE_URL

  • 当前 OPENAI_IMAGE_MODEL

  • /models 是否可达

  • 网关返回了哪些模型

  • 配置中的模型是否出现在 /models 结果里

English:

  • может ли текущий хост вызывать этот MCP-сервер

  • получил ли процесс сервера OPENAI_API_KEY

  • какой OPENAI_BASE_URL активен

  • какая модель OPENAI_IMAGE_MODEL настроена

  • доступен ли /models

  • какие модели возвращает шлюз

  • присутствует ли настроенная модель в результатах /models

中文：如果你想做一次真实、计费的端到端探测，可以在调用 image_studio_doctor 时传 probe_generation=true。
English: Если вы хотите выполнить реальную тарифицируемую сквозную проверку, вызовите image_studio_doctor с параметром probe_generation=true.

Установка в Codex

Этот репозиторий уже включает:

  • .codex-plugin/plugin.json

  • .mcp.json

  • skills/image-studio-mcp/SKILL.md

Для установки в другую рабочую область Codex:

  1. Скопируйте папку image-studio-mcp в директорию plugins/ целевой рабочей области.

  2. Выполните npm install внутри этой директории плагина.

  3. Установите OPENAI_API_KEY в локальной конфигурации MCP.

  4. При необходимости настройте OPENAI_BASE_URL и OPENAI_IMAGE_MODEL.

  5. Убедитесь, что запись на маркетплейсе указывает на ./plugins/image-studio-mcp.

  6. Перезапустите Codex, если плагин был добавлен во время работы приложения.

Почему он может не отображаться в настройках MCP Codex

中文：Codex 里“设置 -> MCP 服务器”通常看的是全局 ~/.codex/config.toml 里的 [mcp_servers.*]，不一定会显示插件目录里的 .mcp.json。
English: В Codex «Настройки -> MCP-серверы» обычно отражают глобальные записи [mcp_servers.*] из ~/.codex/config.toml, а не обязательно локальные файлы .mcp.json плагинов.

中文：所以“插件能加载”不等于“它会出现在全局 MCP 列表里”。
English: Это означает, что «плагин установлен» не всегда то же самое, что «виден в глобальном списке настроек MCP».

Установка в любой хост MCP

Любой хост, поддерживающий стандартный транспорт MCP stdio, может использовать этот проект.

Пример конфигурации:

{
  "mcpServers": {
    "image-studio-mcp": {
      "command": "node",
      "args": [
        "C:/absolute/path/to/image-studio-mcp/scripts/openai-image-mcp.mjs"
      ],
      "cwd": "C:/absolute/path/to/image-studio-mcp",
      "env": {
        "OPENAI_API_KEY": "your_api_key_here",
        "OPENAI_BASE_URL": "https://dash.classicriver.cn/v1/",
        "OPENAI_IMAGE_MODEL": "gpt-image-2"
      }
    }
  }
}

Пример для копирования:

  • mcp.config.example.json

Минимальные примеры использования

Официальный пример, совместимый с OpenAI

{
  "prompt": "a glossy orange sports car under studio lights",
  "output_dir": "C:/workspace/output",
  "filename_prefix": "sports-car",
  "count": 1,
  "size": "1024x1024",
  "output_format": "png"
}

Пример с совместимым прокси

{
  "prompt": "a cyberpunk city girl with neon signs and rainy streets",
  "output_dir": "C:/workspace/output",
  "filename_prefix": "cyberpunk-girl",
  "count": 1,
  "size": "1024x1024",
  "quality": "medium",
  "output_format": "png"
}

Пример редактирования

{
  "prompt": "keep the subject, change the clothes to silver sci-fi armor",
  "input_images": [
    "C:/workspace/input/original.png"
  ],
  "output_dir": "C:/workspace/output",
  "filename_prefix": "armor-edit",
  "output_format": "png"
}

Как использовать в Codex

中文：

  • 可以直接说“给我生成一张图”。

  • 更稳的说法是同时告诉它：

    • 生成什么

    • 输出到哪里

    • 要不要多张

    • 是生图还是改图

  • 如果是第一次装好、第一次调用、或者刚切换代理，先让它跑 image_studio_doctor。

  • 如果当前宿主只有 skill 文本、没有真实 MCP 工具入口，模型应该明确告诉你“只检测到 skill，没有检测到可调用工具”，而不是假装自己能直接出图。

English:

  • Вы можете просто сказать «сгенерируй мне изображение».

  • Надежнее будет также уточнить:

    • что сгенерировать

    • куда сохранить

    • нужно ли несколько вариантов

    • это генерация с нуля или редактирование

  • Если это первый вызов после установки, первый вызов после смены прокси или предыдущая настройка не удалась, сначала запустите image_studio_doctor.

  • Если хост загрузил только текст навыка, но не предоставил реальные инструменты MCP, модель должна четко сообщить об этом, а не притворяться, что генерация изображений доступна.

Контекстная память в Codex

中文：

  • 会记住，但主要是当前对话线程里的上下文，不是永久记忆。

  • 新对话、上下文压缩、重启后，之前的图片任务细节可能不在。

  • 最稳的做法是让图片保存到明确路径，并在后续继续引用那个路径。

English:

  • Да, но в основном в рамках текущего потока диалога, а не как постоянная память.

  • После нового потока, сжатия контекста или перезапуска детали предыдущих задач с изображениями могут стать недоступны.

  • Самый надежный способ — сохранять результаты по четкому пути и ссылаться на этот путь позже.

Инструменты

image_studio_doctor

中文：做安装后自检、配置排查、代理排查。
English: Выполняет проверки установки, конфигурации и устранение неполадок прокси.

Важные входные данные:

  • probe_generation

  • probe_prompt

  • models_preview_limit

generate_image

中文：根据提示词生成一张或多张图片。
English: Генерирует одно или несколько изображений по подсказке.

Важные входные данные:

  • prompt

  • output_dir

  • filename_prefix

  • count

  • size

  • quality

  • background

  • output_format

edit_image

中文：基于一张或多张已有图片进行改图。
English: Редактирует одно или несколько существующих исходных изображений по подсказке.

Важные входные данные:

  • prompt

  • input_images

  • mask_image

  • output_dir

  • filename_prefix

  • count

  • size

  • quality

  • background

  • output_format

Руководство по ошибкам

  • 401 invalid_api_key 中文：认证失败，通常是 key 不对、key 对这个代理不可用、或者上游没有授权。
    English: Ошибка аутентификации. Ключ неверный, недействителен для этого шлюза или отсутствует доступ к вышестоящему сервису.

  • 404 中文：路径大概率不对，常见原因是 OPENAI_BASE_URL 没写到 /v1。
    English: Скорее всего, неверный путь. Частая причина — OPENAI_BASE_URL не заканчивается на /v1.

  • 429 中文：代理或上游限流了。
    English: Прокси или вышестоящий сервис ограничил скорость запросов.

  • 524 中文：代理等上游太久超时了。
    English: Прокси превысил время ожидания ответа от вышестоящего сервиса генерации изображений.

  • No available compatible accounts 中文：代理当前没有可用的图像账号资源。
    English: У прокси в данный момент нет доступных ресурсов учетных записей для генерации изображений.

  • HTML instead of JSON 中文：通常说明 OPENAI_BASE_URL 指到了网页，不是 API。
    English: Обычно означает, что OPENAI_BASE_URL указывает на веб-страницу, а не на API-интерфейс.

Примечание по безопасности

中文：不要把真实 key 提交进 Git，也不要到处手填进命令历史。优先通过 MCP 宿主的环境变量或本地私有配置注入。
English: Не коммитьте реальный ключ в Git и избегайте вставки его в историю команд оболочки. Предпочитайте внедрение через переменные окружения хоста MCP или локальную частную конфигурацию.

Валидация

node --check ./scripts/openai-image-mcp.mjs
npm run validate
npm run doctor
npm run smoke:test

Валидация навыка:

python C:/Users/Administrator/.codex/skills/.system/skill-creator/scripts/quick_validate.py ./skills/image-studio-mcp

Available Tools

2 tools
edit_imageB

Edit one or more source images with a prompt, optionally using a mask, and save the results to local files.

ParametersJSON Schema
NameRequiredDescriptionDefault
promptYes
input_imagesYes
output_dirYes
mask_imageNo
filename_prefixNo
countNo
sizeNo
qualityNo
backgroundNo
output_formatNo
output_compressionNo
userNo

TDQS

B3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. While it mentions the basic operation (edit with prompt, optionally mask, save locally), it lacks critical details such as whether this is a read-only or destructive operation, what permissions or authentication might be required, rate limits, error handling, or what the output looks like (e.g., file paths, success indicators). For a tool with 12 parameters and no annotations, this is a significant gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that efficiently conveys the core functionality. It's front-loaded with the main action and includes key optional elements without unnecessary elaboration. Every word earns its place, making it highly concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (12 parameters, no annotations, no output schema), the description is incomplete. It doesn't explain the behavioral aspects (e.g., mutation effects, error handling), most parameter meanings, or what the tool returns (since there's no output schema). For a tool with this level of complexity, the description should provide more guidance to help an agent use it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, meaning none of the 12 parameters have descriptions in the schema. The description only mentions 'prompt', 'mask', and saving to 'local files', which loosely corresponds to 'prompt', 'mask_image', and 'output_dir' parameters. It doesn't explain the purpose or usage of the other 9 parameters (e.g., 'count', 'size', 'quality', 'user'), leaving them undocumented. With low coverage, the description fails to compensate adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('edit'), the target ('one or more source images'), the mechanism ('with a prompt'), and the outcome ('save the results to local files'). It distinguishes from the sibling 'generate_image' by specifying editing of existing images rather than generation from scratch. However, it doesn't specify the type of editing (e.g., inpainting, style transfer) which could make it more specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for editing existing images with a prompt, which differentiates it from 'generate_image' that presumably creates new images. However, it doesn't provide explicit guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or constraints beyond the optional mask parameter.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_imageC

Generate one or more images from a prompt with an OpenAI-compatible image endpoint and save them to local files.

ParametersJSON Schema
NameRequiredDescriptionDefault
promptYes
output_dirYes
filename_prefixNo
countNo
sizeNo
qualityNo
backgroundNo
moderationNo
output_formatNo
output_compressionNo
userNo

TDQS

C2.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions saving to local files but doesn't cover critical aspects like rate limits, authentication needs, error handling, or what happens if files already exist. For an 11-parameter tool with no annotation coverage, this leaves significant gaps in understanding its behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-constructed sentence that efficiently conveys the core functionality without unnecessary words. It's appropriately sized and front-loaded with the essential information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (11 parameters, no annotations, no output schema), the description is inadequate. It covers the basic purpose but lacks parameter explanations, behavioral context, usage guidelines, and output information. For a sophisticated image generation tool, this leaves too many unanswered questions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage for 11 parameters, the description must compensate but fails to do so. It mentions 'prompt' and 'output_dir' implicitly through the action description but doesn't explain any of the other 9 parameters like 'size', 'quality', 'background', etc. This leaves most parameters semantically undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('generate') and resource ('images'), specifying it uses an OpenAI-compatible endpoint and saves to local files. It distinguishes from the sibling 'edit_image' by focusing on generation rather than editing. However, it doesn't explicitly contrast with the sibling tool, so it's not a perfect 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like 'edit_image'. It mentions the general context of generating images from prompts but offers no explicit when/when-not instructions or prerequisites for usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observededit_image
    • First observedgenerate_image
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.1/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have clearly distinct purposes: edit_image modifies existing images based on a prompt and optional mask, while generate_image creates new images from scratch using a prompt. There is no overlap or ambiguity between these functions.

Naming Consistency5/5

Both tools follow a consistent verb_noun pattern (edit_image, generate_image) with the same verb style and underscore separation. The naming is perfectly predictable and uniform.

Tool Count2/5

With only 2 tools, this server feels thin for an 'image studio' domain. While the tools cover basic generation and editing, there are likely missing operations like image analysis, format conversion, or batch processing that would be expected in a comprehensive image toolset.

Completeness2/5

For an image processing server, there are significant gaps in the surface. Missing are tools for tasks like image resizing, filtering, metadata reading, format conversion, or batch operations. The current tools only cover generation and basic editing, leaving many common image workflows unsupported.

Maintenance

ActivityNo data
ResponsivenessSyncing

Resources

Related MCP Connectors