# Solaire MCP

[简体中文](README.zh-CN.md)

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:

```bash
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`:

```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:

```toml
[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

```bash
npx -y github:hsolaire/solaire-mcp
```

For reproducible installations, pin a release tag:

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

Corresponding Codex arguments:

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

## Run from a local clone

```bash
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:

```toml
[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:

```bash
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

```bash
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:

```bash
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

```bash
npm test
npm run check
npm pack --dry-run
```

## License

MIT. See [LICENSE](LICENSE).