Skip to main content
Glama
deenesjakoruzh
jpaarhuis

claude-foundry-image

by jpaarhuis
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

claude-foundry-image

Claude Code plugin que da a cada proyecto y cada conversación un generador de imágenes respaldado por tu propio despliegue de Azure AI Foundry (API de imágenes MAI, p.ej. MAI-Image-2.5-Pro).

  • Servidor MCP (server/server.mjs) — Node ≥ 18, cero dependencias. Herramientas: generate_image, edit_image, check_config.

  • Skill generate-image — enseña a Claude cuándo usar las herramientas, cómo expandir una línea simple en un prompt utilizable, dimensiones válidas, dónde escribir archivos.

  • Skill setup — guía de configuración única.

Las imágenes se escriben en disco; solo la ruta del archivo entra en la conversación. Sin base64 en el contexto.

Install

claude plugin marketplace add jpaarhuis/claude-foundry-image
claude plugin install foundry-image@jpaarhuis

O en una sesión interactiva: /plugin → Marketplaces → añadir jpaarhuis/claude-foundry-image → instalar foundry-image.

Related MCP server: gpt-image-mcp

Configure (once)

El servidor lee su configuración de las variables de entorno. Ponlas en ~/.claude/settings.json bajo env — un archivo, todas las plataformas, solo Claude Code lo ve:

{
  "env": {
    "MAI_IMAGE_ENDPOINT": "https://<resource>.services.ai.azure.com/mai/v1/images/generations",
    "MAI_IMAGE_DEPLOYMENT": "MAI-Image-2.5-Pro",
    "MAI_IMAGE_API_KEY": "<key>",
    "MAI_IMAGE_OUTPUT_DIR": "C:/Users/<you>/Pictures/ai"
  }
}

O configúralas como variables de entorno del usuario del SO (setx en Windows, export en tu perfil de shell en macOS/Linux). Reinicia Claude Code de cualquier manera.

Luego, en cualquier sesión: "ejecuta check_config" o /foundry-image:setup para una guía paso a paso.

Variable

Requerido

Significado

MAI_IMAGE_ENDPOINT

sí

URL completa que termina en /mai/v1/images/generations

MAI_IMAGE_DEPLOYMENT

sí

Nombre del despliegue en Foundry

MAI_IMAGE_API_KEY

sí

Clave del recurso

MAI_IMAGE_OUTPUT_DIR

no

Carpeta de salida predeterminada; recurre al directorio temporal del SO

Use

Solo pregunta: "maak een hero image voor de README, donker, isometrisch, geen tekst". Claude expande el prompt, elige dimensiones, escribe el PNG (en el repositorio cuando corresponde) y devuelve la ruta.

Parámetros de las herramientas, como referencia:

Herramienta

Parámetros

generate_image

prompt (obligatorio), width, height (por defecto 1024×1024), output_path (.png)

edit_image

image (obligatorio, ruta PNG/JPEG), prompt (obligatorio), output_path

check_config

—

Reglas de dimensiones de la API MAI: cada lado ≥ 768 px y ancho × alto ≤ 1 048 576 px. Por lo tanto, 1024x1024, 1024x768, 1280x800 funcionan; 1024x1536 y 1920x1080 no.

Why env vars and not a config file or setup dialog?

Los plugins de Claude Code no tienen almacenamiento secreto por plugin ni interfaz de configuración. La convención — la misma que usa el plugin oficial de GitHub para su PAT — es la expansión ${VAR} en el .mcp.json del plugin, con el usuario configurando las variables una vez. settings.json → env es el lugar de menor fricción para eso: viaja con tu perfil de Claude Code, se aplica a cada proyecto y sobrevive a las actualizaciones del plugin.

Si quieres sacar la clave de archivos de texto plano, cárgala en el entorno desde un almacén de secretos al iniciar sesión (Key Vault, CLI de 1Password, Administrador de credenciales de Windows) — al servidor no le importa de dónde viene la variable.

Develop

npm test

Ejecuta una prueba de humo offline: handshake MCP, listado de herramientas, comprobaciones de dimensiones, errores de configuración faltante y verifica que check_config nunca filtre una clave.

License

MIT

Available Tools

3 tools
check_configA

Report whether the Foundry image server is configured (which environment variables are set, endpoint and deployment in use, output directory). Never reveals the API key. Call this first when a generation fails with a configuration error.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.2/5.0
Behavior3/5

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

No annotations are provided, so the description must disclose behavioral traits. It states the tool reports config status without revealing the API key, which is a notable safety disclosure. However, it does not explicitly declare read-only behavior, potential delays, or what happens if the server is unreachable. The disclosure is adequate but not thorough.

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 consists of two efficient sentences with zero wasted words. The first sentence front-loads the tool's purpose and scope, the second adds usage guidance. It is appropriately sized for the tool's simplicity.

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

Completeness4/5

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

For a zero-parameter diagnostic tool with no output schema, the description covers what it reports, what it excludes, and when to invoke it. It lacks details on output format, but given the context (image generation siblings), the provided information is sufficient for an agent to select and invoke correctly.

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

Parameters4/5

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

There are no parameters (0 params), so per the rubric baseline is 4. The description adds no parameter info, but none is needed. Schema coverage is trivially 100%.

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

Purpose5/5

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

The description clearly states the tool reports configuration status of the Foundry image server, listing specific elements (environment variables, endpoint, deployment, output directory) and explicitly excludes revealing the API key. It distinguishes from sibling tools (edit_image, generate_image) which are about image manipulation, not config checking.

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

Usage Guidelines4/5

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

The description explicitly advises 'Call this first when a generation fails with a configuration error,' providing clear when-to-use guidance. It also states what it does not reveal (API key), which implicitly guides against expecting that output. No explicit when-not or alternatives, but sibling differentiation is sufficient.

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

edit_imageA

Edit an existing PNG or JPEG with gpt-image-2 on Azure AI Foundry, following a text instruction. The result is written to disk as a PNG and the tool returns its path. The source file is never modified.

ParametersJSON Schema
NameRequiredDescriptionDefault
imageYesPath to the source PNG or JPEG.
promptYesWhat to change in the image.
output_pathNoWhere to write the result. Must end in .png.

TDQS

A3.7/5.0
Behavior3/5

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

The description says the result is written to disk as a PNG and the source file is never modified, which are useful behavioral details. However, with no annotations provided, the description carries full burden. It does not disclose if the operation is reversible, whether it requires any specific authentication or permissions, or any side effects (e.g., whether it overwrites existing output files silently). It mentions the output is a PNG even if the source is JPEG, which is valuable. Overall, it provides moderate transparency but lacks some important details.

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 very concise: three sentences covering purpose, output format, and behavioral assurance. No superfluous words. It is front-loaded with the core action and a clear summary. Each sentence adds distinct value.

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

Completeness3/5

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

Given the tool has three parameters (all with schema descriptions), no output schema, no annotations, and no nested objects, the description provides the essential context for an editing operation with output to disk. It explains the return value (path to the result) despite there being no output schema. However, it does not specify if the prompt can be a plain text instruction or requires specific formatting, nor does it list supported edit capabilities (e.g., only simple changes? complex edits?). For a tool with no annotations, this leaves some gaps in completeness.

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

Parameters4/5

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

Schema description coverage is 100% (all three parameters have descriptions in the schema), so the baseline is 3. The tool description adds value beyond the schema by confirming that 'image' must be a path to a PNG or JPEG, 'prompt' is a text instruction for editing, and 'output_path' must end with '.png'. The description contextually reinforces the parameter meanings, helping the agent understand their roles beyond the schema's property descriptions.

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

Purpose5/5

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

The description clearly states that this tool edits existing PNG or JPEG images using gpt-image-2 on Azure AI Foundry, following a text instruction. It also specifies that the result is saved to disk as a PNG and the source file is never modified. This provides a specific verb (edit), resource (PNG/JPEG image), and distinct operation (following a text prompt). It distinguishes edit from the sibling generate_image (which likely creates new images instead of editing existing ones).

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 mentions the supported image formats (PNG, JPEG) and that the source file remains unchanged, but it does not provide explicit guidance on when to use this tool versus the sibling tools check_config or generate_image. There is no 'when to use' or 'when not to use' advice, and no mention of prerequisites (e.g., image must exist, must be a supported format). The agent is left to infer usage context from the tool name and input schema.

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

generate_imageA

Generate a PNG image with gpt-image-2 on Azure AI Foundry. The image is written to disk and the tool returns its path; it is not returned inline. Use a detailed prompt covering subject, style, composition, lighting and colors. Each side must be at least 768 pixels and width x height must not exceed 1048576 pixels, so 1024x1024, 768x1024 and 1024x768 are valid but 1024x1536 is not.

ParametersJSON Schema
NameRequiredDescriptionDefault
widthNoImage width in pixels. Default 1024.
heightNoImage height in pixels. Default 1024.
promptYesDescription of the image to generate.
output_pathNoWhere to write the PNG. Must end in .png. Relative paths resolve against the current working directory. Defaults to a timestamped file in the output directory.

TDQS

A4.4/5.0
Behavior4/5

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

With no annotations provided, the description carries the full burden. It clearly discloses that the image is written to disk and the path is returned (not inline), and it specifies dimension constraints. However, it does not disclose error behavior, permission requirements, rate limits, or what happens if constraints are violated, leaving room for improvement.

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 two sentences, front-loaded with the core purpose and output format, followed by prompt guidance and constraints. Every sentence is necessary and informative, with no redundancy or wasted words. It is highly efficient.

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

Completeness4/5

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

Given the tool has 4 parameters, no output schema, and no annotations, the description covers the essential aspects: purpose, output format, constraints, and prompt advice. It is mostly complete but lacks details on error handling, performance, or any prerequisites, which would be nice to have for a generation tool.

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

Parameters4/5

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

Schema coverage is 100%, so the description adds value beyond the schema by explaining the dimension constraints (min 768px sides, max 1048576 total pixels) and examples of valid sizes. It also adds context about prompt quality. The fact that the tool returns the path is not in the schema but is in the description. This meaningfully supplements the parameter definitions.

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

Purpose5/5

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

The description clearly states the tool generates a PNG image using gpt-image-2 on Azure AI Foundry, and distinguishes it from the sibling tools 'edit_image' (editing) and 'check_config' (configuration checking). The verb 'generate' and resource 'PNG image' are specific, and the output behavior (written to disk, returns path) is explicitly noted.

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

Usage Guidelines4/5

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

The description provides actionable guidance: 'Use a detailed prompt covering subject, style, composition, lighting and colors.' It also gives explicit dimension constraints (minimum side 768px, max total pixels 1048576) with valid examples. However, it does not explicitly state when to use this tool versus alternatives (e.g., edit_image), nor does it mention any prerequisites or context for using the tool.

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. 3 tool updatesv1.0.0
    • First observedcheck_config
    • 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

A4.2/5.0

Scored across 3 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: check_config is diagnostic, edit_image modifies an existing image, generate_image creates a new one. No overlap or ambiguity.

Naming Consistency5/5

All tools follow a consistent verb_noun snake_case pattern: check_config, edit_image, generate_image. No mixing of styles.

Tool Count5/5

Three tools is well-scoped for an image generation and editing server. Each tool serves a necessary function without bloat or deficiency.

Completeness4/5

The core lifecycle of generation and editing is covered, but there is no tool for deleting images or enumerating previously generated files. These are minor gaps that agents can work around.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers