AI Watercolor Generator

AI 水彩画生成器 MCP

通过任何支持本地 stdio 服务的 MCP 客户端，根据文本创作水彩画，或使用 AI 转换本地图片。

此软件包是 AI Watercolor Generator 的官方本地 MCP 服务。它是面向生产 API 的轻量级开源客户端；生成、存储、额度、速率限制和任务处理均由托管服务负责。

功能

• 根据文本提示词生成水彩画。
• 上传本地 JPEG、PNG 或 WebP 图片进行编辑。
• 将上传的图片转换成水彩画。
• 轮询异步任务，直到输出就绪。
• 使用与 REST API 和托管 MCP 服务相同的账户和额度。

要求

• Node.js 20 或更高版本
• AI Watercolor Generator API 密钥
• 用于生成和编辑的账户额度

请妥善保管 API 密钥。不要将其提交到代码仓库，也不要粘贴到问题中。

快速开始

无需全局安装，通过 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 的任务。每隔 2–5 秒调用一次 get_watercolor_task，直到状态变为 succeeded、failed 或 canceled。

编辑本地图片

首先，使用明确的本地文件路径调用 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，支持两种安装方式：

• 托管 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