@felixpy/openai-image 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Felix Yang (felixpy)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,203 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h1>openai-image</h1>
+
+<p>Generate and edit images with OpenAI from any MCP client.</p>
+
+<p>
+  <a href="https://www.npmjs.com/package/@felixpy/openai-image"><img alt="npm version" src="https://img.shields.io/npm/v/@felixpy/openai-image"></a>
+  <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/github/license/felixpy/openai-image"></a>
+  <a href="https://github.com/felixpy/openai-image/actions/workflows/ci.yml"><img alt="CI status" src="https://img.shields.io/github/actions/workflow/status/felixpy/openai-image/ci.yml?branch=main&label=CI"></a>
+  <a href="package.json"><img alt="Node.js 20 or newer" src="https://img.shields.io/badge/node-%3E%3D20-339933?logo=nodedotjs&logoColor=white"></a>
+</p>
+
+<img src="docs/assets/tibo-quota.gif" alt="Animated GIF of a cartoon Tibo in sunglasses while a quota bar fills from 5% to full reset" width="512">
+<p><sub>Animated GIF output from <code>openai_image_edit</code> (<code>output_format: "gif"</code>).</sub></p>
+
+<p>
+  <a href="README.md">English</a>
+  &nbsp;·&nbsp;
+  <a href="README_ZH.md">简体中文</a>
+</p>
+
+</div>
+
+`openai-image` is a stdio [Model Context Protocol](https://modelcontextprotocol.io) server. It calls the official OpenAI Images API, writes the files to an absolute `output_dir`, and returns paths plus metadata. Tool results never include base64.
+
+```sh
+npx -y @felixpy/openai-image
+```
+
+## Quick start
+
+### 1. API key
+
+The server reads `OPENAI_API_KEY` from the environment. It is required for a tool call and is never logged. A missing key does not stop the process from starting.
+
+```sh
+export OPENAI_API_KEY=sk-...
+```
+
+| Variable | Default | Role |
+|---|---|---|
+| `OPENAI_API_KEY` | required for tool calls | Sent by the OpenAI SDK. Never commit it. |
+| `OPENAI_IMAGE_MODEL` | `gpt-image-2.6-flare` | Model used when a call omits `model`. |
+| `OPENAI_BASE_URL` | OpenAI default | Optional. Read by the OpenAI SDK. |
+
+### 2. Register the server
+
+Every snippet starts the published package over stdio. Replace `sk-...` locally. Do not commit a real key.
+
+#### Cursor
+
+`~/.cursor/mcp.json` or `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "openai-image": {
+      "command": "npx",
+      "args": ["-y", "@felixpy/openai-image"],
+      "env": {
+        "OPENAI_API_KEY": "sk-..."
+      }
+    }
+  }
+}
+```
+
+#### Claude Desktop
+
+macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`  
+Windows: `%APPDATA%\Claude\claude_desktop_config.json`  
+Linux: `~/.config/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "openai-image": {
+      "command": "npx",
+      "args": ["-y", "@felixpy/openai-image"],
+      "env": {
+        "OPENAI_API_KEY": "sk-..."
+      }
+    }
+  }
+}
+```
+
+#### Claude Code
+
+```sh
+claude mcp add openai-image \
+  -e OPENAI_API_KEY=sk-... \
+  -- npx -y @felixpy/openai-image
+```
+
+#### Codex
+
+`~/.codex/config.toml`:
+
+```toml
+[mcp_servers.openai-image]
+command = "npx"
+args = ["-y", "@felixpy/openai-image"]
+env = { OPENAI_API_KEY = "sk-..." }
+```
+
+## Tools
+
+| Tool | API | Required | Also accepts |
+|---|---|---|---|
+| `openai_image_generate` | `images.generate` | `prompt`, `output_dir` | Shared image fields, plus `svg` |
+| `openai_image_edit` | `images.edit` | `prompt`, `image_paths`, `output_dir` | Shared image fields, plus `mask_path`, `markup_path`, `input_fidelity` |
+
+`openai_image_generate` creates still images, animated GIFs (`output_format=gif`), or SVG. `openai_image_edit` edits or composes up to 16 reference images, optionally guided by a mask or a markup overlay. Both save files under `output_dir` and return their paths.
+
+A successful result is text JSON. URLs and `revised_prompt` are included only when the API sends them.
+
+```json
+{
+  "model": "gpt-image-2.6-flare",
+  "files": ["/absolute/path/image-2026-11-05T00-00-00-000Z-0.png"],
+  "usage": null,
+  "size": "1024x1024",
+  "quality": "auto",
+  "output_format": "png"
+}
+```
+
+API failures, including `moderation_blocked`, come back as tool errors with `status`, `code`, `type`, `param`, `message`, `request_id`, and the raw `error` body. The client uses `maxRetries: 2` and a 180 second timeout.
+
+## Parameters
+
+Schemas are loose strings on purpose. The API validates values, so a new option usually needs no code change. Unknown fields can go through `extra`, which is shallow-merged last.
+
+### Shared
+
+| Parameter | Required | Range and notes |
+|---|---|---|
+| `output_dir` | yes | Absolute directory. A relative path is rejected. The directory is created if needed. |
+| `model` | no | Default is `OPENAI_IMAGE_MODEL` or `gpt-image-2.6-flare`. Examples: `gpt-image-2.6-flare` (fast), `gpt-image-2.6-sunburst` (detail and precise edits), `gpt-image-2.5-flare`, `gpt-image-2.5-sunburst`. |
+| `size` | no | `auto`, `1024x1024`, `1536x1024`, `1024x1536`, or `WIDTHxHEIGHT`. Both sides must be multiples of 16, the aspect ratio must be from 1:3 to 3:1, and the maximum is `3840x2160`. For GIF this is the size of each frame. Keep frames small, for example `512x512`, so the animation fits the pixel budget. |
+| `quality` | no | `auto` (default), `low`, `medium`, `high`, `xhigh`, `max`. |
+| `complexity` | no | Planning effort, separate from quality: `low`, `medium`, `high`. gpt-image-2.6 defaults to `high`. |
+| `n` | no | Integer from 1 to 10. |
+| `background` | no | `auto` (default), `opaque`, `transparent`. Transparent requires `png`, `webp`, or `svg`. |
+| `output_format` | no | `png` (default), `jpeg`, `webp`. Generate also supports `gif` (animated) and `svg`. |
+| `output_compression` | no | Integer from 0 to 100. `jpeg` and `webp` only. |
+| `frame_count` | no | GIF only. Integer, minimum 2, default 9. The SDK documents 2–16 and the image guide documents 2–64. Describe the motion and a return to the starting pose so the loop is smooth. |
+| `frame_duration_ms` | no | GIF only. Integer from 20 to 2000, rounded to 10. Default 200. |
+| `moderation` | no | `auto` (default), `low`. |
+| `safety_identifier` | no | Optional stable hashed end-user id for OpenAI abuse monitoring. |
+| `extra` | no | Object shallow-merged into the request last, for example `{"complexity":"high"}`. |
+
+### `openai_image_generate`
+
+| Parameter | Required | Range and notes |
+|---|---|---|
+| `prompt` | yes | Text prompt. Maximum 32000 characters. |
+| `svg` | no | SVG only, with `output_format=svg` and `n=1`. Object `{"model":"...","reasoning":{"effort":"high"}}`. Needs SVG model-selection access. Omit it otherwise. |
+
+### `openai_image_edit`
+
+| Parameter | Required | Range and notes |
+|---|---|---|
+| `prompt` | yes | Edit instructions. |
+| `image_paths` | yes | Local paths. Minimum 1. The API accepts up to 16 reference images. |
+| `mask_path` | no | PNG mask, same size as the first image. Transparent pixels are the area to edit. Cannot be combined with `markup_path`. |
+| `markup_path` | no | Transparent PNG overlay with marks, arrows, or notes, same size as the first image. Cannot be combined with `mask_path`. |
+| `input_fidelity` | no | `high` or `low`. Applies to `gpt-image-1.5` and `1-mini` only. Omit it for gpt-image-2 and later. |
+
+Edit accepts the shared fields, including `output_format`. GIF output from edit was verified on 2026-11-05.
+
+## Notes
+
+- **GIF.** Set `output_format` to `gif` on generate or edit. Use `frame_count` and `frame_duration_ms` to shape the loop. Edit GIF output was verified on 2026-11-05.
+- **Absolute `output_dir`.** The path must be absolute. Relative paths are rejected before the API is called.
+- **No base64 in tool results.** Bytes are written to disk. The tool returns file paths, the model, `usage`, and `revised_prompt` when the API provides one.
+- **Pass-through.** `extra` is shallow-merged last, so new API fields work without a release.
+
+## Development
+
+Node.js 20 or newer.
+
+```sh
+npm ci
+npm test
+npm run build
+npm start
+```
+
+`npm test` builds `dist/` and completes an MCP `initialize` plus `tools/list` handshake. It does not call the OpenAI API and does not need `OPENAI_API_KEY`.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for commit style and pull requests, and [docs/publishing.md](docs/publishing.md) for the one-time npm setup.
+
+## Project
+
+- [Contributing](CONTRIBUTING.md)
+- [Security](SECURITY.md)
+- [License](LICENSE) (MIT)
+- [Changelog](CHANGELOG.md)
+- [Code of Conduct](CODE_OF_CONDUCT.md)
+- [Publishing](docs/publishing.md)

package/dist/index.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+// Minimal MCP server (stdio) wrapping OpenAI images.generate and images.edit.
+import fs from 'node:fs';
+import path from 'node:path';
+import OpenAI, { toFile } from 'openai';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+const IMAGE_MODEL = process.env.OPENAI_IMAGE_MODEL || 'gpt-image-2.6-flare';
+// Reported on MCP initialize. Read from package.json so release-please version bumps stay in sync.
+const pkg = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+// Lazy client: a missing key becomes a tool error, not a startup crash.
+// The SDK reads OPENAI_API_KEY and OPENAI_BASE_URL from env itself; the key is never logged.
+let client;
+const openai = () => (client ??= new OpenAI({ maxRetries: 2, timeout: 180_000 }));
+// Loose schemas on purpose: the API validates values, so new options need no code change.
+const extra = z.record(z.string(), z.unknown()).optional()
+    .describe('Extra API params shallow-merged into the request last, e.g. {"complexity":"high"}');
+const outputDir = z.string().refine(path.isAbsolute, 'must be an absolute path')
+    .describe('Absolute directory to save images in. Follow your workspace conventions: the current project folder if any, else your own tmp dir.');
+const imageOptions = {
+    output_dir: outputDir,
+    model: z.string().optional().describe(`Image model (default ${IMAGE_MODEL}). e.g. gpt-image-2.6-flare (fast), gpt-image-2.6-sunburst (detail/precise edits), gpt-image-2.5-flare, gpt-image-2.5-sunburst`),
+    size: z.string().optional().describe('auto, 1024x1024, 1536x1024, 1024x1536, or WIDTHxHEIGHT (both multiples of 16, aspect 1:3 to 3:1, max 3840x2160). For GIF this is the size of each frame; keep it small (e.g. 512x512) to fit the pixel budget'),
+    quality: z.string().optional().describe('auto (default), low, medium, high, xhigh, max'),
+    complexity: z.string().optional().describe('Planning effort, separate from quality: low, medium, high (2.6 default high)'),
+    n: z.number().int().min(1).max(10).optional().describe('Number of images, 1-10'),
+    background: z.string().optional().describe('auto (default), opaque, transparent (transparent needs png, webp or svg)'),
+    output_format: z.string().optional().describe('png (default), jpeg, webp; generate also supports gif (animated) and svg'),
+    output_compression: z.number().int().min(0).max(100).optional().describe('0-100, jpeg/webp only'),
+    frame_count: z.number().int().min(2).optional().describe('GIF only: number of frames (default 9; SDK says 2-16, guide says 2-64). Describe the motion and a return to the starting pose in the prompt for a smooth loop'),
+    frame_duration_ms: z.number().int().min(20).optional().describe('GIF only: ms per frame, 20-2000, rounded to 10 (default 200)'),
+    moderation: z.string().optional().describe('auto (default), low'),
+    safety_identifier: z.string().optional().describe('Optional stable hashed end-user id for OpenAI abuse monitoring'),
+    extra,
+};
+// Defined fields first, then `extra` on top. Undefined values are dropped.
+function merge(defaults, { extra, ...fields }) {
+    const defined = Object.fromEntries(Object.entries(fields).filter(([, v]) => v !== undefined));
+    return { ...defaults, ...defined, ...extra };
+}
+const stamp = () => new Date().toISOString().replace(/[:.]/g, '-');
+const ok = (data) => ({ content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] });
+function toolError(e) {
+    // APIError carries status/code/type/param; `error` holds the raw body (e.g. moderation_blocked details).
+    const err = e instanceof OpenAI.APIError
+        ? { status: e.status, code: e.code, type: e.type, param: e.param, message: e.message, request_id: e.requestID, error: e.error }
+        : { message: e instanceof Error ? e.message : String(e) };
+    return { isError: true, content: [{ type: 'text', text: JSON.stringify(err, null, 2) }] };
+}
+const MIME = { png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', webp: 'image/webp' };
+const upload = (p) => toFile(fs.createReadStream(p), path.basename(p), { type: MIME[path.extname(p).slice(1).toLowerCase()] ?? 'application/octet-stream' });
+// Write b64 images to disk; return only paths + metadata (no base64 into the agent's context).
+function saveImages(res, dir, model, requestedFormat) {
+    const format = res.output_format ?? requestedFormat ?? 'png';
+    fs.mkdirSync(dir, { recursive: true });
+    const prefix = stamp();
+    const files = [], urls = [], revised = [];
+    (res.data ?? []).forEach((d, i) => {
+        if (d.revised_prompt)
+            revised.push(d.revised_prompt);
+        if (d.url)
+            urls.push(d.url);
+        if (!d.b64_json)
+            return;
+        const file = path.join(dir, `image-${prefix}-${i}.${format}`);
+        fs.writeFileSync(file, Buffer.from(d.b64_json, 'base64'));
+        files.push(file);
+    });
+    return ok({
+        model, files, ...(urls.length && { urls }), usage: res.usage ?? null,
+        ...(revised.length && { revised_prompt: revised.length === 1 ? revised[0] : revised }),
+        size: res.size, quality: res.quality, output_format: format,
+    });
+}
+const server = new McpServer({ name: 'openai-image', version: pkg.version });
+server.registerTool('openai_image_generate', {
+    description: 'Generate images (OpenAI images.generate): still images, animated GIF (output_format=gif) or SVG. Saves files to output_dir and returns their paths.',
+    inputSchema: {
+        prompt: z.string().describe('Text prompt (max 32000 chars)'),
+        ...imageOptions,
+        svg: z.object({ model: z.string(), reasoning: z.record(z.string(), z.unknown()).optional() }).optional()
+            .describe('SVG only (output_format=svg, n=1): author model and reasoning, e.g. {"model":"...","reasoning":{"effort":"high"}}. Needs SVG model-selection access; omit otherwise'),
+    },
+}, async ({ output_dir, ...args }) => {
+    try {
+        const params = { ...merge({ model: IMAGE_MODEL }, args), stream: false };
+        return saveImages(await openai().images.generate(params), output_dir, String(params.model), params.output_format);
+    }
+    catch (e) {
+        return toolError(e);
+    }
+});
+server.registerTool('openai_image_edit', {
+    description: 'Edit images or compose from up to 16 reference images (OpenAI images.edit), optionally guided by a mask or markup overlay. Saves files to output_dir and returns their paths.',
+    inputSchema: {
+        prompt: z.string().describe('Edit instructions'),
+        image_paths: z.array(z.string()).min(1).describe('Local paths of one or more input/reference images'),
+        mask_path: z.string().optional().describe('Optional PNG mask, same size as the first image (transparent = area to edit). Cannot combine with markup_path'),
+        markup_path: z.string().optional().describe('Optional transparent PNG overlay with marks/arrows/notes drawn on it, same size as the first image, to guide the edit. Cannot combine with mask_path'),
+        input_fidelity: z.string().optional().describe('high or low; gpt-image-1.5 / 1-mini only, omit for gpt-image-2 and later'),
+        ...imageOptions,
+    },
+}, async ({ output_dir, image_paths, mask_path, markup_path, ...rest }) => {
+    try {
+        const params = {
+            ...merge({ model: IMAGE_MODEL }, rest),
+            image: await Promise.all(image_paths.map(upload)), // SDK type: Uploadable | Array<Uploadable>
+            ...(mask_path && { mask: await upload(mask_path) }),
+            ...(markup_path && { markup: await upload(markup_path) }),
+            stream: false,
+        };
+        return saveImages(await openai().images.edit(params), output_dir, String(params.model), params.output_format);
+    }
+    catch (e) {
+        return toolError(e);
+    }
+});
+await server.connect(new StdioServerTransport());

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@felixpy/openai-image",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "MCP server for OpenAI image generation and editing, including GIF and SVG",
+  "type": "module",
+  "license": "MIT",
+  "author": "Felix Yang (felixpy)",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "openai-image": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/felixpy/openai-image.git"
+  },
+  "bugs": {
+    "url": "https://github.com/felixpy/openai-image/issues"
+  },
+  "homepage": "https://github.com/felixpy/openai-image#readme",
+  "keywords": [
+    "mcp",
+    "openai",
+    "gpt-image",
+    "image-generation",
+    "image-editing",
+    "model-context-protocol"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "pretest": "npm run build",
+    "test": "node --test test/smoke.test.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.32.2",
+    "openai": "7.51.0",
+    "zod": "4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "26.6.6",
+    "typescript": "7.0.2"
+  }
+}