Skip to main content
Glama
deenesjakoruzh
jhupo

image-studio-mcp

by jhupo
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Hybrid

image-studio-mcp

Un servidor MCP local y plugin de Codex para la generación y edición de imágenes a través de APIs de imagen compatibles con OpenAI.

Este proyecto es adecuado para la distribución de código abierto porque el nombre del paquete es genérico. No se presenta como un plugin oficial de OpenAI. Simplemente funciona con puntos finales de imagen compatibles con OpenAI.

Repositorio:

  • https://github.com/jhupo/image-studio-mcp.git

Características

  • Texto a imagen con generate_image

  • Edición de imágenes con edit_image

  • Entrada de múltiples imágenes opcional para ediciones

  • Edición basada en máscaras opcional

  • OPENAI_BASE_URL configurable

  • OPENAI_API_KEY configurable

  • OPENAI_IMAGE_MODEL configurable

  • Guarda las imágenes resultantes directamente en archivos locales

  • Incluye un manifiesto de plugin de Codex y una habilidad complementaria

Requisitos

  • Node.js 20+

  • Una clave de API para un punto final de imagen compatible con OpenAI

Variables de entorno

  • OPENAI_API_KEY Requerido. Clave de API utilizada para el punto final de imagen.

  • OPENAI_BASE_URL Opcional. El valor predeterminado es https://dash.classicriver.cn/v1/.

  • OPENAI_IMAGE_MODEL Opcional. El valor predeterminado es gpt-image-2.

Configuración local

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

El servidor utiliza transporte stdio, por lo que normalmente es iniciado por un host MCP en lugar de manualmente.

Instalar en Codex

Este repositorio ya incluye los archivos del plugin de Codex:

  • .codex-plugin/plugin.json

  • .mcp.json

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

Si lo está instalando en otro espacio de trabajo de Codex:

  1. Copie la carpeta image-studio-mcp en el directorio plugins/ de ese espacio de trabajo.

  2. Ejecute npm install dentro del directorio del plugin.

  3. Establezca OPENAI_API_KEY en la configuración MCP local del plugin.

  4. No confirme una clave de API real en el repositorio.

  5. Opcionalmente, cambie OPENAI_BASE_URL y OPENAI_IMAGE_MODEL.

  6. Asegúrese de que el mercado del espacio de trabajo apunte a ./plugins/image-studio-mcp.

Instalar en cualquier host compatible con MCP

Cualquier host que admita el transporte stdio de MCP puede instalar este servidor.

Utilice la misma estructura que se muestra a continuación, adaptada al formato de configuración de su host:

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

Aquí se incluye un archivo de ejemplo que se puede copiar:

  • mcp.config.example.json

Herramientas

generate_image

Crea una o más imágenes a partir de un prompt.

Entradas importantes:

  • prompt

  • output_dir

  • filename_prefix

  • count

  • size

  • quality

  • background

  • output_format

edit_image

Edita una o más imágenes de origen a partir de un prompt.

Entradas importantes:

  • prompt

  • input_images

  • mask_image

  • output_dir

  • filename_prefix

  • count

  • size

  • quality

  • background

  • output_format

Nota sobre el nombre de código abierto

Para la distribución pública, image-studio-mcp es más seguro que openai-image-studio porque evita parecer un nombre de producto oficial, al tiempo que deja claro el propósito.

Validación

node --check ./scripts/openai-image-mcp.mjs

Para la validación real de la API, inyecte OPENAI_API_KEY desde su shell local o configuración de host en lugar de almacenarla en archivos rastreados.

También puede validar la habilidad:

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