AI Watercolor Generator

AI Watercolor Generator MCP

ローカル stdio サーバーに対応した任意の MCP クライアントから、テキストをもとに水彩画を作成したり、ローカル画像を AI で変換したりできます。

このパッケージは、AI Watercolor Generator の公式ローカル MCP サーバーです。これは本番 API 向けの小規模なオープンソースクライアントです。生成、保存、クレジット、レート制限、タスク処理はホスト型サービス上で行われます。

機能

• テキストプロンプトから水彩画を生成します。
• ローカルの JPEG、PNG、または WebP 画像をアップロードして編集します。
• アップロードした画像を水彩画に変換します。
• 出力の準備ができるまで非同期タスクをポーリングします。
• REST API およびホスト型 MCP サーバーと同じアカウントおよびクレジットを使用します。

必要条件

• Node.js 20 以降
• AI Watercolor Generator API キー
• 生成および編集用のアカウントクレジット

API キーは非公開にしてください。リポジトリにコミットしたり、issue に貼り付けたりしないでください。

クイックスタート

グローバルインストールせずに npm 経由で MCP サーバーを実行します。

AIWATERCOLOR_API_KEY=YOUR_AIWATERCOLOR_API_KEY \
  npx -y @ai-watercolor-generator/mcp

プロセスは stdio 経由で通信するため、通常は対話的に使うのではなく、MCP クライアントによって起動されます。

クライアントの設定

Codex

Codex CLI、Codex IDE 拡張機能、ChatGPT デスクトップアプリは、同じ Codex ホスト上で MCP 設定を共有します。これを ~/.codex/config.toml に追加し、Codex を起動する環境で AIWATERCOLOR_API_KEY を設定してください。

[mcp_servers.ai_watercolor_generator]
command = "npx"
args = ["-y", "@ai-watercolor-generator/mcp"]
env_vars = ["AIWATERCOLOR_API_KEY"]

クライアントを再起動し、codex mcp list を実行するか、/mcp を使って接続を確認します。Codex 公式 MCP ドキュメントを参照してください。

Cursor

このサーバーをプロジェクトの .cursor/mcp.json またはグローバル MCP 設定に追加します。

{
  "mcpServers": {
    "ai-watercolor-generator": {
      "command": "npx",
      "args": ["-y", "@ai-watercolor-generator/mcp"],
      "env": {
        "AIWATERCOLOR_API_KEY": "YOUR_AIWATERCOLOR_API_KEY"
      }
    }
  }
}

Cursor MCP ドキュメントを参照してください。

Claude Desktop およびその他の JSON ベースのクライアント

クライアントのローカル MCP 設定で、同じ stdio 設定を使用します。

{
  "mcpServers": {
    "ai-watercolor-generator": {
      "command": "npx",
      "args": ["-y", "@ai-watercolor-generator/mcp"],
      "env": {
        "AIWATERCOLOR_API_KEY": "YOUR_AIWATERCOLOR_API_KEY"
      }
    }
  }
}

保存後、クライアントを再起動します。Claude Desktop では、Extensions インターフェースを通じてローカル MCP サーバーを表示できる場合があります。現在の設定手順については、Anthropic のローカル MCP サーバーガイドを参照してください。

ツール

ツール	目的
generate_watercolor	非同期のテキストから水彩画への変換タスクを送信します
upload_watercolor_input	最大 10 MiB のローカル JPEG、PNG、または WebP ファイルをアップロードします
edit_watercolor	アップロードした画像 URL を使って非同期の水彩画編集を送信します
get_watercolor_task	タスクの状態、出力、または失敗の詳細を取得します

テキストから生成する

プロンプトを指定して generate_watercolor を呼び出します。任意のフィールドは model、aspect_ratio、resolution、idempotency_key です。

{
  "prompt": "A red cottage beside a quiet lake, soft wet-on-wet washes",
  "model": "watercolor-lite",
  "aspect_ratio": "4:3",
  "resolution": "1k"
}

このツールは、状態が queued または processing のタスクを返します。状態が succeeded、failed、または canceled になるまで、2～5 秒ごとに get_watercolor_task を呼び出してください。

ローカル画像を編集する

まず、明示的なローカルファイルパスを指定して upload_watercolor_input を呼び出します。

{
  "file_path": "/absolute/path/to/source-image.png"
}

次に、返された url を edit_watercolor に渡します。

{
  "prompt": "Preserve the composition with soft transparent watercolor washes",
  "input_images": [
    "https://cdn.aiwatercolorgenerator.com/api-inputs/.../upload.png"
  ],
  "model": "watercolor-lite",
  "aspect_ratio": "auto",
  "resolution": "1k"
}

アップロードツールは、ツール呼び出しで明示的に指定されたパスのみを読み込みます。ディレクトリをスキャンしたり、glob パターンを展開したりすることはありません。画像は AI Watercolor Generator の信頼できるストレージにアップロードされ、その後、ホスト型 API で処理されます。

モデルとクレジット

API は現在、watercolor-lite、nano-banana-2、nano-banana-pro、gpt-image-2 をサポートしています。モデル、解像度、操作によってクレジットの消費量が変わります。失敗またはキャンセルされたタスクには、ホスト型 API で定められたクレジットが返金されます。

現在のモデル、クレジット消費量、制限、エラーコード、スキーマについては、API ドキュメントをご覧ください。

ホスト型 MCP サーバーとの関係

公式の MCP Registry エントリーは com.aiwatercolorgenerator/watercolor で、次の 2 種類のインストール方法に対応しています。

• ホスト型 Streamable HTTP：https://www.aiwatercolorgenerator.com/api/mcp
• ローカル stdio：この npm パッケージ

クライアントが認証付きの Streamable HTTP に対応している場合は、ホスト型エンドポイントを使用してください。stdio との互換性が必要な場合、または MCP ツールでローカル画像のパスをアップロードする場合は、このローカルパッケージを使用してください。

セキュリティとプライバシー

• API キーは AIWATERCOLOR_API_KEY から読み込まれ、意図的にログに記録されることはありません。
• upload_watercolor_input を呼び出すと、ローカル画像はホスト型アップロード API に送信されます。
• ツールの呼び出しにはアカウントのクレジットが消費され、API のレート制限と同時実行数の制限が適用されます。
• MCP クライアントで承認する前に、ファイルパスとツール呼び出しを確認してください。
• 脆弱性は SECURITY.md に従って報告してください。

開発

pnpm install
pnpm format:check
pnpm typecheck
pnpm test
pnpm pack --dry-run

テストスイートは HTTP リクエストをモックし、ビルド済み stdio 実行ファイルとの実際のサブプロセスハンドシェイクを含みます。通常の開発テストに本番用 API キーは必要ありません。

リンク

• AI Watercolor Generator
• API キーを作成
• REST API ドキュメント
• MCP ドキュメント
• OpenAPI ドキュメント
• 公式 MCP Registry の掲載ページ

ライセンス

MIT