Generic Image Provider MCP

A small stdio MCP server that maps a stable image-tool contract to an OpenAI-compatible image provider while keeping all file access inside configured Windows directories. Node.js 22 or newer is required.

Tools

tools/list is the discovery source. generate_image and provider_status are always present. edit_image appears only when IMAGE_PROVIDER_EDIT_MODEL is configured, and generate_hd_image appears only when IMAGE_PROVIDER_HD_MODEL is configured. Clients must not assume optional tools exist before discovery.

generate_image accepts:

{
  "prompt": "A paper-cut mountain landscape",
  "output_dir": "C:\\work\\images",
  "filename": "mountain.png",
  "size": "1024x1024",
  "quality": "standard"
}

edit_image accepts the same fields plus one to the configured maximum number of reference_images:

{
  "prompt": "Use a warmer palette",
  "reference_images": ["C:\\work\\images\\source.jpg"],
  "output_dir": "C:\\work\\images",
  "filename": "warm.jpg",
  "size": "1024x1024",
  "quality": "high"
}

generate_hd_image uses the generate_image input shape. provider_status accepts {} and returns configured capabilities and limits without credentials. quality is optional and defaults to standard; all other fields shown for generation are required. Prompts are limited to 8,000 characters and both size dimensions must be from 256 to 4096.

Successful image tools return one MCP text item containing JSON:

{
  "path": "C:\\work\\images\\mountain.png",
  "mime_type": "image/png",
  "width": 1024,
  "height": 1024,
  "bytes": 123456,
  "sha256": "64 lowercase hexadecimal characters",
  "model": "configured-model-name",
  "capability": "standard_generation"
}

The stable public error codes are INVALID_ARGUMENT, CAPABILITY_UNAVAILABLE, PATH_NOT_ALLOWED, REFERENCE_INVALID, OUTPUT_EXISTS, WRITE_FAILED, UNSUPPORTED_IMAGE, IMAGE_INVALID, IMAGE_TOO_LARGE, PROVIDER_TIMEOUT, PROVIDER_AUTH_FAILED, PROVIDER_RATE_LIMITED, PROVIDER_BAD_RESPONSE, and INTERNAL_ERROR. For tools/call, an INVALID_ARGUMENT failure is returned as JSON-RPC error -32602 with error.data.code set to INVALID_ARGUMENT. Provider, persistence, path, capability, and other execution-time failures are returned inside a successful JSON-RPC envelope as an MCP tool result with isError: true; its text item contains {"code":"...","message":"..."}. Neither form includes credentials.

Windows installation

Start from a release checkout whose origin is https://github.com/huiku8177-rgb/generic-image-provider-mcp.git. Check out a specific release tag, create the installation parent directory, ensure Git can reach public GitHub over HTTPS, and run:

.\scripts\install-windows.ps1 `
  -InstallDirectory 'C:\Tools\generic-image-provider-mcp' `
  -ReleaseDirectory 'C:\Releases\generic-image-provider-mcp' `
  -ExpectedRef 'v1.0.3'

ExpectedRef is mandatory and accepts only an explicit release tag such as v1.0.3; a branch or full commit ID is rejected. The checkout's HEAD must match the local tag. The local origin must be the exact canonical HTTPS URL above, and the installer uses git ls-remote to require the GitHub tag, including an annotated tag's peeled commit, to match the local commit. A network or remote-verification failure stops before staging or switching.

Official tag lookup requires a Git for Windows build with the Schannel TLS backend. The installer forces http.sslBackend=schannel, http.schannelUseSSLCAInfo=false, and certificate verification. It temporarily removes ambient Git, CA-bundle, OpenSSL, and Requests trust overrides, then restores the parent process environment exactly. Proxy variables remain available only for routing; Schannel still validates GitHub against the Windows trust store. If Schannel is unavailable, verification fails safely before staging. The updater delegates staging and verification to this same installer path.

The installer requires an existing destination parent and refuses an existing destination. It resolves paths, rejects broad or overlapping targets, and requires Node.js 22+. The verified commit is governed by a positive allowlist: the root files .env.example, .gitignore, LICENSE, README.md, package.json, and package-lock.json; the two Windows scripts scripts/install-windows.ps1 and scripts/update-windows.ps1; src/*.mjs; test/*.test.mjs; and test/fixtures.mjs. Every other path is rejected, including submodules, symlinks, credential files, secret material, and media. Windows device names, alternate data streams, control characters, trailing dots/spaces, traversal, absolute paths, and case/trim-normalized collisions are also rejected before extraction.

The installer exports the verified commit with git archive. Working-tree edits, index-only changes, untracked files, and .git metadata therefore never enter the installation. After extraction, the installer requires the file set to equal the official tag's verified tree exactly and hashes every extracted file as a raw, unfiltered Git blob; each path and blob ID must match before npm is allowed to run. Local or environment-provided Git attributes therefore cannot silently omit files or alter export-subst bytes.

It removes credential-bearing environment variables from the npm ci --omit=dev --ignore-scripts and npm test subprocesses, restores the parent PowerShell environment afterward, and performs both in a sibling stage before a fail-if-exists directory rename.

The release must contain a tracked package-lock.json. Installation does not fetch a checkout, trust a branch name, copy .git, or modify an existing installation.

Codex configuration

Set environment-variable values in the process that launches Codex. The installer never reads or writes an API-key value and prints only this name-based configuration:

[mcp_servers.generic_image_provider]
command = "node"
args = ["C:\\Tools\\generic-image-provider-mcp\\src\\server.mjs"]
env_vars = [
  "IMAGE_PROVIDER_ALLOWED_ROOTS",
  "IMAGE_PROVIDER_BASE_URL",
  "IMAGE_PROVIDER_API_KEY",
  "IMAGE_PROVIDER_IMAGE_MODEL",
  "IMAGE_PROVIDER_EDIT_MODEL",
  "IMAGE_PROVIDER_HD_MODEL",
  "IMAGE_PROVIDER_TIMEOUT_MS",
  "IMAGE_PROVIDER_MAX_RESPONSE_BYTES",
  "IMAGE_PROVIDER_MAX_REFERENCE_BYTES",
  "IMAGE_PROVIDER_MAX_REFERENCE_IMAGES"
]

Environment variables:

Name	Required	Meaning/default
IMAGE_PROVIDER_ALLOWED_ROOTS	yes	Semicolon-separated absolute local Windows directories
IMAGE_PROVIDER_BASE_URL	yes	Provider HTTP(S) base URL
IMAGE_PROVIDER_API_KEY	yes	Provider credential; never logged
IMAGE_PROVIDER_IMAGE_MODEL	yes	Standard generation model
IMAGE_PROVIDER_EDIT_MODEL	no	Enables edit_image
IMAGE_PROVIDER_HD_MODEL	no	Enables generate_hd_image
IMAGE_PROVIDER_TIMEOUT_MS	no	120000; range 1,000–300,000
IMAGE_PROVIDER_MAX_RESPONSE_BYTES	no	26214400; range 1,024–104,857,600
IMAGE_PROVIDER_MAX_REFERENCE_BYTES	no	20971520; range 1,024–52,428,800
IMAGE_PROVIDER_MAX_REFERENCE_IMAGES	no	4; range 1–8

Allowed roots

Every allowed root must be an existing absolute local-drive directory below a drive root. Drive roots, relative paths, UNC paths, and Windows device paths are rejected. output_dir and every reference must resolve within an allowed root on the same drive.

Output directories must already exist. filename is a single safe basename, not a path, and must end in .png, .jpg, or .jpeg. Existing outputs are never overwritten: publication uses a no-replace hard link and returns OUTPUT_EXISTS if another file already owns the name. References must be bounded regular files and are checked before and after opening.

Provider compatibility

Version 1.0.3 accepts PNG and 8-bit baseline sequential JPEG (SOF0) only. The supported baseline subset is either one all-component interleaved scan in SOF component order or one ordered non-interleaved scan per component. Mixed component grouping is unsupported. Quantization tables must use 8-bit precision, and both defined Huffman table identifiers and SOS DC/AC selectors are limited to tables 0 and 1. An interleaved scan may contain at most ten sampling blocks per MCU. Extended sequential SOF1, progressive SOF2, 12-bit JPEG, out-of-order, duplicate, incomplete, or mixed-group component scans are rejected as IMAGE_INVALID. WebP remains intentionally unsupported until a trustworthy decoder is available.

The standard model maps to POST /images/generations with an OpenAI-compatible JSON body. Editing maps to multipart POST /images/edits. HD generation maps to POST /chat/completions. Standard and editing responses may contain one data[0].b64_json image or one approved image URL; HD chat content must identify exactly one approved image URL. Returned bytes are decoded and structurally validated, and their dimensions and extension must match the request. JSON envelopes and decoded/streamed image bytes are bounded by IMAGE_PROVIDER_MAX_RESPONSE_BYTES (with only fixed JSON encoding overhead), and the configured request timeout remains active through body consumption or cancellation.

Remote image downloads require HTTPS, globally routable unicast DNS results, one pinned address, bounded streaming, and at most one same-origin HTTPS redirect. IPv6 is restricted to 2000::/3 with IANA special-purpose ranges excluded; IPv4 private, shared, loopback, link-local, documentation, benchmark, multicast, and reserved ranges are excluded. HTTP image downloads are allowed only when the configured provider is loopback, so offline tests can use loopback mock servers. For every non-success Fetch response, the response body is cancelled or destroyed before the stable auth, rate-limit, or bad-response error is returned; cancellation failure never replaces that primary error.

Offline tests

No provider credential is needed:

npm ci --ignore-scripts
npm test
npm run test:coverage

The suite makes no external network requests. Provider tests use loopback mock servers, and release-authenticity tests redirect the production canonical-URL git ls-remote invocation to a temporary local bare Git remote through a test-only executable shim. Coverage includes configuration, path policy, provider mapping, PNG/JPEG parsing, atomic cleanup, tools, JSON-RPC/session handling, and the Windows installation/update behavior.

Manual smoke test

A real-provider smoke test spends provider quota and is never part of the offline suite or installer. Run one only after the account owner gives explicit quota authorization for that exact test. First call provider_status, discover the available tools, choose a new filename inside an allowed root, and request one small standard image. Confirm MIME type, dimensions, SHA-256, and local path, then account for the provider charge. Do not retry a quota-consuming request automatically.

Update and rollback

Stop clients using the server, prepare a separate official release checkout, ensure Git can reach public GitHub over HTTPS for tag verification, and run:

.\scripts\update-windows.ps1 `
  -CurrentDirectory 'C:\Tools\generic-image-provider-mcp' `
  -ReleaseDirectory 'C:\Releases\generic-image-provider-mcp' `
  -ExpectedRef 'v1.1.0'

The updater rejects a source checkout as CurrentDirectory, verifies the canonical official origin and explicit release tag against GitHub, exports the verified commit into a unique sibling stage, scrubs credential environment variables, runs npm ci --omit=dev --ignore-scripts and npm test, and only then starts switching. It uses fail-if-exists sibling directory renames to move the current installation to backup-<name>-<UTC timestamp> and activate the stage, retaining the backup after success.

If the final rename fails, the updater reports the old installation as restored only after the backup-to-current rename completes and the resulting namespace state is verified. If recovery is prevented by a concurrent target or another namespace change, it reports Recovery uncertain with the absolute current, backup, and stage paths and deliberately preserves both stage and backup. Stop and inspect those paths; do not delete either directory. For a later manual rollback, stop the server, verify the absolute current and backup paths are direct siblings, move the current directory aside, and move the selected backup to the original name. Backups are never removed automatically.

Threat model

The server trusts the configured provider endpoint, provider credential, the administrator-selected allowed roots, and a release commit/tag the installer operator has independently verified. It does not trust prompts, filenames, reference paths, provider image bytes, redirects, or concurrent output-tree changes. Credentials stay in the parent environment and public failures are redacted.

Output revalidation is mandatory and executes twice: immediately before temporary creation and immediately before the final no-replace link.

With Node built-in Windows filesystem APIs, an instruction-level namespace race remains between the final revalidation and the no-replace link. The temporary pathname/content binding and the final pathname binding can be changed by any actor whose Windows ACL grants write or rename rights in the configured output tree; this is not inherently limited to an actor logged in as the same account.

Allowed-root ACLs must not grant other accounts write or rename rights. Even with that ACL boundary, a malicious process already running as the same account can race the pure-Node sequence. This residual same-account race is an accepted threat-model limitation; it does not permit omitting either revalidation and does not expand trust to other local users.

The no-replace link still prevents overwriting an existing target. Temporary files are uniquely named and removed on validation or publication failure when the namespace remains controlled. The returned SHA-256 describes the provider bytes validated by the server; it is not a durable binding to the final pathname after a concurrent malicious namespace writer can act. Update staging and backups are direct siblings of the validated current installation. A failed final switch restores the prior installation only when the recovery rename and postcondition checks succeed.

License

MIT. See LICENSE.