Solaire MCP

简体中文

A standalone Model Context Protocol (MCP) server that exposes YYLX gpt-image-2 image generation as the generate_image tool.

The server uses stdio, has no runtime npm dependencies, and returns generated images as inline MCP image content so clients such as Codex can display them directly in the conversation.

Why a standalone MCP repository?

The earlier implementation was bundled inside the solaire-plugins Codex Plugin. A bundled MCP is controlled from the Plugin page, but that page is not a general-purpose environment-variable editor.

This repository installs the image server as a normal standalone MCP server. It therefore appears in Codex's regular MCP Servers / Servers settings, where the server command, arguments, and environment variables can be managed separately from the Plugin.

Do not enable both the Plugin-bundled server and this standalone server with the same name. Doing so may create duplicate generate_image tools.

Features

• MCP tool: generate_image
• Model: gpt-image-2
• OpenAI-compatible image-generation endpoint
• Streaming response support with completed-image preference
• Inline image output
• Environment-variable configuration
• Optional macOS Keychain fallback
• No third-party runtime dependencies

Requirements

• Node.js 18 or newer
• A YYLX-compatible base URL and API key
• An MCP client that supports stdio servers, such as Codex

Install in Codex Desktop

1. Open Settings in Codex.

2. Open MCP Servers or Servers (the label can vary by Codex version).

3. Choose Add server.

4. Enter:

   Field	Value
   Name	yylx-gpt-image
   Command	npx
   Arguments	-y and github:hsolaire/solaire-mcp as two arguments

5. Add these environment variables in the same server settings:

   Variable	Example
   YYLX_BASE_URL	https://app.yylx.io
   YYLX_API_KEY	your local API key

6. Save the server, then restart Codex or start a new task.

Keep the API key in your local Codex settings. Never commit it or paste it into a chat.

Install with Codex CLI

Add the standalone server command:

codex mcp add yylx-gpt-image -- npx -y github:hsolaire/solaire-mcp

Then add the two environment variables through Codex Desktop's server settings, or edit your local ~/.codex/config.toml:

[mcp_servers.yylx-gpt-image]
command = "npx"
args = ["-y", "github:hsolaire/solaire-mcp"]

[mcp_servers.yylx-gpt-image.env]
YYLX_BASE_URL = "https://app.yylx.io"
YYLX_API_KEY = "replace-this-locally"

Codex also supports forwarding variables already present in the Codex process environment:

[mcp_servers.yylx-gpt-image]
command = "npx"
args = ["-y", "github:hsolaire/solaire-mcp"]
env_vars = ["YYLX_BASE_URL", "YYLX_API_KEY"]

Run directly from GitHub

npx -y github:hsolaire/solaire-mcp

For reproducible installations, pin a release tag:

npx -y github:hsolaire/solaire-mcp#v0.1.0

Corresponding Codex arguments:

args = ["-y", "github:hsolaire/solaire-mcp#v0.1.0"]

Run from a local clone

git clone https://github.com/hsolaire/solaire-mcp.git
cd solaire-mcp
npm test
node ./bin/solaire-mcp.mjs

A local Codex configuration can launch the cloned file directly:

[mcp_servers.yylx-gpt-image]
command = "node"
args = ["/absolute/path/to/solaire-mcp/bin/solaire-mcp.mjs"]

[mcp_servers.yylx-gpt-image.env]
YYLX_BASE_URL = "https://app.yylx.io"
YYLX_API_KEY = "replace-this-locally"

Optional macOS Keychain setup

Environment variables configured in Codex are the recommended standalone setup. As an alternative on macOS, a local clone can store the values in Login Keychain:

npm run setup:keychain -- --base-url https://app.yylx.io

The helper asks macOS Keychain to prompt for the API key, so the key is not added to shell history. Environment variables take priority over Keychain values.

Optional Keychain-related variables:

• YYLX_KEYCHAIN_ACCOUNT
• YYLX_KEYCHAIN_BASE_URL_SERVICE
• YYLX_KEYCHAIN_API_KEY_SERVICE

Tool schema

generate_image

Argument	Required	Values / default
prompt	yes	non-empty string
size	no	1024x1024, 1536x1024, 1024x1536; default 1024x1024
quality	no	low, medium, high, auto
background	no	transparent, opaque, auto
output_format	no	png, jpeg, webp; default png
n	no	integer from 1 to 4; default 1

The native API sizes do not include 4K. For exact dimensions such as 3840x2160, generate with the closest native aspect ratio (1536x1024 for landscape), then resize with a separate image-processing step.

Update

Without a tag pin, npx -y github:hsolaire/solaire-mcp resolves the repository's current default branch. Restart the MCP server after updating.

For stable deployments, pin a release tag and change it intentionally when upgrading.

Uninstall

codex mcp remove yylx-gpt-image

You can also remove the server from Codex Desktop's MCP server settings.

Troubleshooting

The server does not appear

• Confirm the command is npx.
• Confirm the arguments are two separate values: -y and github:hsolaire/solaire-mcp.
• Restart Codex or start a new task after saving the server.
• Run codex mcp list to check discovery.

npx cannot download the repository

Check GitHub access, DNS/proxy settings, and that Node.js/npm are available:

node --version
npm --version

For restricted networks, clone the repository once and use the local-file configuration above.

Credentials are missing

Set both YYLX_BASE_URL and YYLX_API_KEY in the standalone MCP server's environment-variable section. Do not add them to the repository or .env files that might be committed.

Duplicate image tools

Disable either the old Plugin-bundled yylx-gpt-image MCP or this standalone MCP. Keep only one enabled.

Image generation returns an upstream error

An MCP server can initialize and list tools even when the remote image API or key is unavailable. Verify the base URL and credential locally. A successful tools/list is not proof that a real image request will succeed.

Development

npm test
npm run check
npm pack --dry-run

License

MIT. See LICENSE.