grok-imagine-image-mcp-server 1.0.0

package/.env.example

@@ -0,0 +1,15 @@
+# xAI API Key (Required)
+# Get your API key from: https://console.x.ai/
+XAI_API_KEY=xai-....
+
+# Debug mode (optional)
+# Set to "true" to enable debug logging
+DEBUG=false
+
+# Default output directory for generated images (optional)
+# If not set, images are saved in the current working directory
+# OUTPUT_DIR=/path/to/output
+
+# Include thumbnail in MCP response (optional)
+# Set to "true" to include base64 thumbnail preview in response
+# XAI_IMAGE_THUMBNAIL=false

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Junji Takashima
+
+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.ja.md

@@ -0,0 +1,225 @@
+# Grok Imagine Image MCP Server
+
+[![npm version](https://badge.fury.io/js/grok-imagine-image-mcp-server.svg)](https://www.npmjs.com/package/grok-imagine-image-mcp-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+xAI の Grok Imagine Image API 用 MCP (Model Context Protocol) サーバー。テキストプロンプトからの画像生成と、既存画像の編集をサポートします。
+
+## クイックスタート (npx)
+
+最も簡単な方法は `npx` を使用することです：
+
+```bash
+# APIキーを設定
+export XAI_API_KEY="xai-your-api-key"
+
+# サーバーを実行
+npx grok-imagine-image-mcp-server
+```
+
+## 機能
+
+- **画像生成**: テキストプロンプトから新規画像を生成
+- **画像編集**: 既存画像をプロンプトで編集（grok-imagine-image のみ）
+- **バッチ処理**: CLIで複数画像を一括処理
+- 多様なアスペクト比をサポート（1:1, 4:3, 16:9 など）
+- 解像度: 1k（標準）
+- 一度に最大10枚の画像を生成
+- MCP レスポンスにサムネイルプレビューを含めるオプション
+
+## サポートモデル
+
+| モデル | 価格 | 画像編集 | 備考 |
+|--------|------|---------|------|
+| `grok-imagine-image` | $0.02/枚 | ✅ (+$0.002/入力) | **推奨・デフォルト** |
+
+## 必要条件
+
+- Node.js 18.0.0 以上
+- xAI API キー（[console.x.ai](https://console.x.ai/) から取得）
+
+## インストール
+
+### 方法1: npx（推奨）
+
+```bash
+npx grok-imagine-image-mcp-server
+```
+
+### 方法2: グローバルインストール
+
+```bash
+npm install -g grok-imagine-image-mcp-server
+grok-imagine-image-mcp-server
+```
+
+## 設定
+
+### 環境変数
+
+| 変数 | 必須 | 説明 |
+|------|------|------|
+| `XAI_API_KEY` | Yes | xAI API キー |
+| `DEBUG` | No | `true` でデバッグログを有効化 |
+| `OUTPUT_DIR` | No | 画像のデフォルト出力ディレクトリ |
+| `XAI_IMAGE_THUMBNAIL` | No | `true` でサムネイルを含める |
+
+### Claude Desktop 設定
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "grok-imagine-image": {
+      "command": "npx",
+      "args": ["-y", "grok-imagine-image-mcp-server"],
+      "env": {
+        "XAI_API_KEY": "xai-your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+## ツール
+
+### generate_image
+
+テキストプロンプトから画像を生成します。
+
+| パラメータ | 型 | 必須 | 説明 |
+|-----------|-----|------|------|
+| `prompt` | string | Yes | 生成する画像の説明テキスト |
+| `output_path` | string | No | 出力ファイルパス（デフォルト: generated_image.jpg） |
+| `model` | string | No | モデル（デフォルト: grok-imagine-image） |
+| `n` | number | No | 生成枚数（1-10、デフォルト: 1） |
+| `aspect_ratio` | string | No | アスペクト比（デフォルト: 1:1） |
+| `resolution` | string | No | 解像度（デフォルト: 1k） |
+| `return_base64` | boolean | No | Base64データを返す（デフォルト: false） |
+| `include_thumbnail` | boolean | No | サムネイルを含める（デフォルト: false） |
+
+### edit_image
+
+既存画像を編集します（grok-imagine-image のみ対応）。
+
+| パラメータ | 型 | 必須 | 説明 |
+|-----------|-----|------|------|
+| `prompt` | string | Yes | 編集内容の説明 |
+| `image_path` | string | No* | 編集する画像のファイルパス |
+| `image_base64` | string | No* | 編集する画像のBase64データ |
+| `image_url` | string | No* | 編集する画像のURL |
+| `output_path` | string | No | 出力ファイルパス（デフォルト: edited_image.jpg） |
+| `n` | number | No | 生成枚数（1-10、デフォルト: 1） |
+| `resolution` | string | No | 解像度（デフォルト: 1k）。アスペクト比は入力画像から自動検出。 |
+
+*`image_path`、`image_base64`、`image_url` のいずれか1つが必須
+
+> **注意**: edit_image は入力画像を「参照」として使用し、画像全体を再生成します。全体の構図やスタイルは維持されますが、ピクセル単位の精密な編集（インペインティング）ではありません。スタイル変換、被写体の置換、シーンの変更に適しています。
+
+## バッチ処理 CLI
+
+バッチCLIで複数の画像を一括処理できます：
+
+```bash
+# 設定ファイルでバッチ実行
+npx grok-imagine-image-batch batch.json
+
+# コスト見積もりのみ
+npx grok-imagine-image-batch batch.json --estimate-only
+
+# 出力先とフォーマットを指定
+npx grok-imagine-image-batch batch.json --output-dir ./images --format json
+```
+
+### CLI オプション
+
+| オプション | 説明 | デフォルト |
+|-----------|------|-----------|
+| `--output-dir <path>` | 出力ディレクトリを上書き | 設定ファイルから |
+| `--format <text\|json>` | 出力フォーマット | `text` |
+| `--timeout <ms>` | タイムアウト（ミリ秒） | `600000` |
+| `--max-concurrent <n>` | 最大同時実行数（1-10） | `2` |
+| `--estimate-only` | コスト見積もりのみ（実行しない） | - |
+| `--allow-any-path` | 任意の出力パスを許可（CI/CD用） | - |
+
+### バッチ設定ファイル
+
+```json
+{
+  "jobs": [
+    {
+      "prompt": "美しい山の夕焼け",
+      "output_path": "sunset.jpg",
+      "aspect_ratio": "16:9"
+    },
+    {
+      "prompt": "夜景に変更",
+      "image_path": "input.jpg",
+      "output_path": "edited.jpg"
+    }
+  ],
+  "output_dir": "./output",
+  "max_concurrent": 3,
+  "default_model": "grok-imagine-image",
+  "retry_policy": {
+    "max_retries": 2,
+    "retry_delay_ms": 1000
+  }
+}
+```
+
+設定例は `examples/` ディレクトリを参照してください。
+
+## サポートされているアスペクト比
+
+| アスペクト比 | 用途例 |
+|-------------|--------|
+| `1:1` | 正方形、SNSプロフィール画像（デフォルト） |
+| `3:4` / `4:3` | 標準的な縦長/横長 |
+| `9:16` / `16:9` | スマホ縦 / ワイドスクリーン |
+
+## サポートされている解像度
+
+| 解像度 | 説明 |
+|--------|------|
+| `1k` | 標準解像度（1024x1024、デフォルト） |
+
+
+## 使用例
+
+```
+# 画像生成
+山の上の夕日の画像を16:9で生成して
+
+# 画像編集
+この画像の背景を宇宙に変更して
+```
+
+## API リファレンス
+
+| 機能 | エンドポイント |
+|------|---------------|
+| 画像生成 | `https://api.x.ai/v1/images/generations` |
+| 画像編集 | `https://api.x.ai/v1/images/edits` |
+
+- **ドキュメント**: [docs.x.ai/docs/guides/image-generations](https://docs.x.ai/docs/guides/image-generations)
+
+## 開発
+
+```bash
+git clone https://github.com/takajun/grok-imagine-image-mcp-server.git
+cd grok-imagine-image-mcp-server
+npm install
+npm run build
+npm start
+```
+
+## ライセンス
+
+MIT
+
+## 作者
+
+Junji Takashima <takajyun00@gmail.com>

package/README.md

@@ -0,0 +1,225 @@
+# Grok Imagine Image MCP Server
+
+[![npm version](https://badge.fury.io/js/grok-imagine-image-mcp-server.svg)](https://www.npmjs.com/package/grok-imagine-image-mcp-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+[日本語版 README はこちら](README.ja.md)
+
+MCP (Model Context Protocol) server for xAI's Grok Imagine Image API. Supports image generation from text prompts and editing existing images.
+
+## Quick Start with npx
+
+```bash
+# Set your API key
+export XAI_API_KEY="xai-your-api-key"
+
+# Run the server
+npx grok-imagine-image-mcp-server
+```
+
+## Features
+
+- **Image Generation**: Generate new images from text prompts
+- **Image Editing**: Edit existing images with prompts (grok-imagine-image only)
+- **Batch Processing**: Process multiple images via CLI
+- Various aspect ratios (1:1, 4:3, 16:9, and more)
+- Resolution: 1k (standard)
+- Generate multiple images at once (up to 10)
+- Optional thumbnail preview in MCP responses
+
+## Supported Models
+
+| Model | Price | Image Editing | Notes |
+|-------|-------|---------------|-------|
+| `grok-imagine-image` | $0.02/image | ✅ (+$0.002/input) | **Recommended, Default** |
+
+## Requirements
+
+- Node.js 18.0.0 or higher
+- xAI API key (get from [console.x.ai](https://console.x.ai/))
+
+## Installation
+
+### Option 1: npx (Recommended)
+
+```bash
+npx grok-imagine-image-mcp-server
+```
+
+### Option 2: Global Install
+
+```bash
+npm install -g grok-imagine-image-mcp-server
+grok-imagine-image-mcp-server
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `XAI_API_KEY` | Yes | Your xAI API key |
+| `DEBUG` | No | Set to `true` for debug logging |
+| `OUTPUT_DIR` | No | Default output directory for images |
+| `XAI_IMAGE_THUMBNAIL` | No | Set to `true` to include thumbnails |
+
+### Claude Desktop Configuration
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "grok-imagine-image": {
+      "command": "npx",
+      "args": ["-y", "grok-imagine-image-mcp-server"],
+      "env": {
+        "XAI_API_KEY": "xai-your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+### generate_image
+
+Generate images from text prompts.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `prompt` | string | Yes | Text description of the image to generate |
+| `output_path` | string | No | Output file path (default: generated_image.jpg) |
+| `model` | string | No | Model to use (default: grok-imagine-image) |
+| `n` | number | No | Number of images (1-10, default: 1) |
+| `aspect_ratio` | string | No | Aspect ratio (default: 1:1) |
+| `resolution` | string | No | Resolution (default: 1k) |
+| `return_base64` | boolean | No | Return base64 data (default: false) |
+| `include_thumbnail` | boolean | No | Include thumbnail (default: false) |
+
+### edit_image
+
+Edit existing images (grok-imagine-image only).
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `prompt` | string | Yes | Description of desired edits |
+| `image_path` | string | No* | Path to source image file |
+| `image_base64` | string | No* | Base64 encoded source image |
+| `image_url` | string | No* | URL of source image |
+| `output_path` | string | No | Output file path (default: edited_image.jpg) |
+| `n` | number | No | Number of images (1-10, default: 1) |
+| `resolution` | string | No | Resolution (default: 1k). Aspect ratio is auto-detected from input image. |
+
+*One of `image_path`, `image_base64`, or `image_url` is required
+
+> **Note**: The edit_image tool uses the source image as a reference and regenerates the entire image. It maintains the overall composition and style but is not pixel-level inpainting. Best suited for style transformations, subject replacements, and scene modifications.
+
+## Batch Processing CLI
+
+Process multiple images at once using the batch CLI:
+
+```bash
+# Run batch with config file
+npx grok-imagine-image-batch batch.json
+
+# Estimate cost only
+npx grok-imagine-image-batch batch.json --estimate-only
+
+# Custom output directory
+npx grok-imagine-image-batch batch.json --output-dir ./images --format json
+```
+
+### CLI Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--output-dir <path>` | Override output directory | From config |
+| `--format <text\|json>` | Output format | `text` |
+| `--timeout <ms>` | Timeout in milliseconds | `600000` |
+| `--max-concurrent <n>` | Max concurrent jobs (1-10) | `2` |
+| `--estimate-only` | Estimate cost without executing | - |
+| `--allow-any-path` | Allow any output path (CI/CD) | - |
+
+### Batch Configuration File
+
+```json
+{
+  "jobs": [
+    {
+      "prompt": "A beautiful sunset over mountains",
+      "output_path": "sunset.jpg",
+      "aspect_ratio": "16:9"
+    },
+    {
+      "prompt": "Change to nighttime scene",
+      "image_path": "input.jpg",
+      "output_path": "edited.jpg"
+    }
+  ],
+  "output_dir": "./output",
+  "max_concurrent": 3,
+  "default_model": "grok-imagine-image",
+  "retry_policy": {
+    "max_retries": 2,
+    "retry_delay_ms": 1000
+  }
+}
+```
+
+See `examples/` directory for more configuration examples.
+
+## Supported Aspect Ratios
+
+| Aspect Ratio | Use Case |
+|--------------|----------|
+| `1:1` | Square, social media profiles (default) |
+| `3:4` / `4:3` | Standard portrait/landscape |
+| `9:16` / `16:9` | Smartphone / widescreen |
+
+## Supported Resolutions
+
+| Resolution | Description |
+|------------|-------------|
+| `1k` | Standard resolution (1024x1024, default) |
+
+
+## Usage Examples
+
+```
+# Image generation
+Generate an image of a sunset over mountains with aspect ratio 16:9
+
+# Image editing
+Change the background of this image to space
+```
+
+## API Reference
+
+| Function | Endpoint |
+|----------|----------|
+| Image Generation | `https://api.x.ai/v1/images/generations` |
+| Image Editing | `https://api.x.ai/v1/images/edits` |
+
+- **Documentation**: [docs.x.ai/docs/guides/image-generations](https://docs.x.ai/docs/guides/image-generations)
+
+## Development
+
+```bash
+git clone https://github.com/takajun/grok-imagine-image-mcp-server.git
+cd grok-imagine-image-mcp-server
+npm install
+npm run build
+npm start
+```
+
+## License
+
+MIT
+
+## Author
+
+Junji Takashima <takajyun00@gmail.com>

package/dist/cli/batch.d.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * Batch processing CLI for xAI Grok Imagine Image
+ *
+ * Usage:
+ *   grok-imagine-image-batch <config.json> [options]
+ *
+ * Options:
+ *   --output-dir <path>    Override output directory
+ *   --format <text|json>   Output format (default: text)
+ *   --timeout <ms>         Timeout in milliseconds (default: 600000)
+ *   --max-concurrent <n>   Max concurrent jobs (1-10, default: 2)
+ *   --estimate-only        Estimate cost without executing
+ *   --allow-any-path       Allow any output path (for CI/CD)
+ *   --help, -h             Show help message
+ *   --version, -v          Show version
+ */
+export {};
+//# sourceMappingURL=batch.d.ts.map

package/dist/cli/batch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../../src/cli/batch.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;GAeG"}