image-generate-mcp-remote 0.9.1__tar.gz

image_generate_mcp_remote-0.9.1/.env.example

@@ -0,0 +1,19 @@
+IMG_GEN_GPT_IMAGE_2_OFFICIAL_API_KEY=
+IMG_GEN_GPT_IMAGE_2_OFFICIAL_BASE_URL=https://www.uocode.com/v1
+IMG_GEN_GPT_IMAGE_2_OFFICIAL_MODEL=gpt-image-2
+IMG_GEN_GPT_IMAGE_2_OFFICIAL_SUPPORTED_MODELS=gpt-image-2
+
+IMG_GEN_NANO_BANANA_2_OFFICIAL_API_KEY=
+IMG_GEN_NANO_BANANA_2_OFFICIAL_BASE_URL=https://www.uocode.com
+IMG_GEN_NANO_BANANA_2_OFFICIAL_MODEL=gemini-3.1-flash-image-preview
+IMG_GEN_NANO_BANANA_2_OFFICIAL_SUPPORTED_MODELS=gemini-3.1-flash-image-preview
+
+IMG_GEN_GPT_IMAGE_2_URL_API_KEY=
+IMG_GEN_GPT_IMAGE_2_URL_BASE_URL=https://www.right.codes/draw/v1
+IMG_GEN_GPT_IMAGE_2_URL_MODEL=gpt-image-2-vip
+IMG_GEN_GPT_IMAGE_2_URL_SUPPORTED_MODELS=gpt-image-2-vip
+
+IMAGE_OUTPUT_DIR=storage/images
+IMAGE_BASE_URL=
+IMAGE_HTTP_TIMEOUT_SECONDS=600
+LOG_LEVEL=INFO

image_generate_mcp_remote-0.9.1/.github/workflows/release.yml

@@ -0,0 +1,66 @@
+name: release
+
+on:
+  release:
+    types:
+      - published
+  workflow_dispatch:
+
+jobs:
+  publish:
+    name: Build and publish package
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Install project dependencies
+        run: uv sync --frozen --extra dev
+
+      - name: Run tests before publish
+        run: uv run pytest
+
+      - name: Build distributions
+        run: uv build --no-sources
+
+      - name: Detect publish mode
+        id: publish-mode
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.UV_PUBLISH_TOKEN }}
+        run: |
+          if [ -n "$UV_PUBLISH_TOKEN" ]; then
+            echo "mode=token" >> "$GITHUB_OUTPUT"
+          else
+            echo "mode=trusted" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Upload distributions to release
+        if: github.event_name == 'release'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release upload "${{ github.event.release.tag_name }}" dist/* --clobber
+
+      - name: Publish distributions to PyPI with token
+        if: ${{ steps.publish-mode.outputs.mode == 'token' }}
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.UV_PUBLISH_TOKEN }}
+        run: uv publish
+
+      - name: Publish distributions to PyPI with trusted publishing
+        if: ${{ steps.publish-mode.outputs.mode == 'trusted' }}
+        run: uv publish

image_generate_mcp_remote-0.9.1/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.env
+storage/

image_generate_mcp_remote-0.9.1/.python-version

@@ -0,0 +1 @@
+3.11

image_generate_mcp_remote-0.9.1/AGENTS.md

@@ -0,0 +1,96 @@
+# AGENTS Handbook (image-generate-mcp-remote)
+
+本文件定义 `image-generate-mcp-remote/` 范围内的 Python 编码规范。
+
+## 1) 类型标注总原则
+
+- 所有 Python 函数的入参、返回值必须显式标注类型。
+- 所有类变量、实例变量必须显式标注类型。
+- 禁止在业务代码的函数入参、返回值、类变量定义中直接使用 `Any`。
+- 若能确定具体类型，必须写具体类型；不得为了省事退化成 `Any`、`object`、宽泛 `dict` 或宽泛 `list`。
+
+## 2) JSON 相关类型约定
+
+涉及通用 JSON 数据时，统一优先使用以下类型别名语义：
+
+```python
+from typing import TypeAlias
+
+JSONScalar: TypeAlias = str | int | float | bool | None
+JSONValue: TypeAlias = JSONScalar | list["JSONValue"] | dict[str, "JSONValue"]
+JSONMap: TypeAlias = dict[str, JSONValue]
+```
+
+- 若值可明确为某个结构体，不得继续使用 `JSONMap` 兜底，必须定义真实类型。
+- `JSONScalar` 仅用于确属标量的值；不要把有明确业务含义的字段长期保留为裸 `str` 或裸 `int`。
+
+## 3) 枚举与常量
+
+- 若某字段是字符串枚举或数字枚举，必须定义枚举类型，不得在代码中散落魔法字面量。
+- 字符串枚举优先使用 `StrEnum`；数字枚举按语义使用 `IntEnum` 或 `Enum`。
+- 真正使用该值时，应引用枚举成员，而不是再次手写原始字串或数字。
+- 若某值是固定定值且具有明确业务意义，必须提取为命名常量，不得直接硬编码。
+
+示例：
+
+```python
+from enum import StrEnum
+
+REQUEST_STATUS_PENDING = "pending"
+
+
+class RequestStatus(StrEnum):
+    PENDING = "pending"
+    RUNNING = "running"
+    DONE = "done"
+```
+
+- 若该值属于“有限候选集合”，优先建枚举。
+- 若该值属于“单一协议常量 / 元数据键 / 固定开关值”，优先建常量。
+
+## 4) 结构化参数与返回值
+
+- 若函数参数本质上是一个固定结构，不得使用 `tuple[...]` 位置拼装多个值传递业务语义。
+- 不得使用 `dict[str, Any]`、`dict[str, object]` 表达稳定结构的入参或返回值。
+- 对于稳定结构，必须定义真实类型，如 `dataclass`、`pydantic.BaseModel`、具名类。
+- 若返回值包含多个具名字段，同样优先返回结构化对象，而不是匿名元组或宽泛字典。
+
+推荐方向：
+
+- 领域/服务层稳定载荷：优先 `dataclass` 或 `pydantic.BaseModel`
+- 配置对象：优先 `BaseModel` 或明确配置类
+- 协议对象：优先具名模型类与类型别名组合
+
+## 5) 宽泛类型禁用清单
+
+以下写法在本目录范围内默认禁止，除非是三方库边界适配且无法收窄：
+
+- `Any`
+- `dict[str, Any]`
+- `list[Any]`
+- `tuple[Any, ...]`
+- 无业务语义的裸 `object`
+
+如确实处于外部系统边界，必须先在边界层完成解析、校验、收窄，再进入业务代码。
+
+## 6) 建模要求
+
+- 参数一旦存在业务名称、业务约束、字段含义，就应建模，不要把结构藏在 tuple 下标或 dict key 里。
+- 类字段类型应直接表达真实含义，例如状态、模式、资源类型、事件名，应优先使用枚举或具名类型。
+- 不允许因为“当前先跑通”而省略类型；类型本身就是可读性与可靠性的一部分。
+
+## 7) 代码评审判定标准
+
+出现以下情况，视为不符合本规范：
+
+- 新增函数参数或返回值含 `Any`
+- 新增类字段使用 `Any`
+- 业务枚举值仍以裸字符串/裸数字直接流转
+- 固定结构仍以 `tuple`、`dict[str, Any]`、匿名字典传递
+- 明明可以写成具体类型，却退化为宽泛类型
+
+## 8) 落地优先级
+
+- 第一优先级：新增代码必须完全遵守本规范。
+- 第二优先级：修改旧代码时，若触达相关函数、模型、字段，应顺手把对应类型收窄到本规范要求。
+- 第三优先级：所有新增协议常量、状态值、事件值、模式值，应在首次引入时完成枚举或常量化。

image_generate_mcp_remote-0.9.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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.

image_generate_mcp_remote-0.9.1/PKG-INFO

@@ -0,0 +1,287 @@
+Metadata-Version: 2.4
+Name: image-generate-mcp-remote
+Version: 0.9.1
+Summary: Remote MCP server for image generation
+Project-URL: Homepage, https://github.com/zztdandan/image-generate-mcp-remote
+Project-URL: Repository, https://github.com/zztdandan/image-generate-mcp-remote
+Project-URL: Issues, https://github.com/zztdandan/image-generate-mcp-remote/issues
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: mcp[cli]>=1.12.0
+Requires-Dist: pydantic-settings>=2.10.0
+Requires-Dist: pydantic>=2.11.0
+Requires-Dist: python-dotenv>=1.1.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=1.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.12.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# image-generate-mcp-remote
+
+一个基于 UV + Python 的远程 MCP 图片生成服务，统一封装 OpenAI Images 兼容接口与 Gemini `generateContent` 生图接口。
+
+> 本子项目运行时复用工作区根目录 `.venv`。在本目录执行 `uv` 命令时，会通过工作区环境注入使用统一虚拟环境。
+
+## 项目能力
+
+- 提供 `gpt_image_2_official` 工具，兼容 OpenAI Images 风格的文生图与参考图编辑
+- 提供 `nano_banana_2_official` 工具，兼容 Gemini `generateContent` 风格的文生图与参考图编辑
+- 提供 `gpt-image-2-url` 工具，兼容 `https://www.right.codes/draw/v1/images/generations` 并自动下载返回图片 URL
+- 提供 `list_image_tools_catalog` 工具，用于输出当前服务的默认配置、有效模型与非敏感环境变量信息
+- 默认网关已切换到 `uocode`
+
+## 默认上游配置
+
+### OpenAI Images 兼容
+
+- 默认 `BASE_URL`：`https://www.uocode.com/v1`
+- 默认模型：`gpt-image-2`
+- 典型接口：
+  - `POST /v1/images/generations`
+  - `POST /v1/images/edits`
+
+### Gemini 原生兼容
+
+- 默认 `BASE_URL`：`https://www.uocode.com`
+- 默认模型：`gemini-3.1-flash-image-preview`
+- 典型接口：
+  - `POST /v1beta/models/{model}:generateContent`
+
+## 安装与启动
+
+## 通过 uv 安装使用
+
+`uv` 本身没有单独的“官方包仓库”，常规做法是把包发布到 `PyPI`，然后让用户通过 `uv` 直接下载运行。
+
+当 `v0.9.1` 发布到 `PyPI` 后，可直接这样使用：
+
+```bash
+# 临时运行，不落本地项目源码
+uvx image-generate-mcp-remote --transport stdio
+
+# 或安装为全局工具
+uv tool install image-generate-mcp-remote
+image-generate-mcp-remote --transport stdio
+```
+
+### 1. 安装依赖
+
+```bash
+uv sync
+cp .env.example .env
+```
+
+### 2. 配置环境变量
+
+至少填写你要使用的工具对应 API Key：
+
+- `IMG_GEN_GPT_IMAGE_2_OFFICIAL_API_KEY`
+- `IMG_GEN_NANO_BANANA_2_OFFICIAL_API_KEY`
+
+### 3. 启动服务
+
+```bash
+# Streamable HTTP（默认）
+uv run image-generate-mcp-remote --transport streamable-http --host 127.0.0.1 --port 3001
+
+# SSE
+uv run image-generate-mcp-remote --transport sse --host 127.0.0.1 --port 3001
+
+# stdio（本地 MCP 客户端直连）
+uv run image-generate-mcp-remote --transport stdio
+```
+
+## 当前实际部署（systemd --user）
+
+本项目当前真正使用中的远端 MCP 服务，不是 `stdio` 直连，而是 `systemd --user` 托管的 `streamable-http` 服务。
+
+- 服务名：`image-generate-mcp.service`
+- unit 文件位置模式：`~/.config/systemd/user/image-generate-mcp.service`
+- 工作目录：部署目录 `<deploy-root>`
+- 环境文件：`<deploy-root>/.env`
+- 当前接入地址：`http://127.0.0.1:25235/mcp`
+
+部署、更新、修改环境变量、重启服务、OpenCode MCP JSON 配置的完整说明见：
+
+- `SYSTEMD_DEPLOYMENT_GUIDE.md`
+
+对于当前这个远端服务，需要特别注意：
+
+- 改 OpenCode MCP JSON 里的 `env`，不会改变已启动服务的环境变量
+- 要改服务配置，必须修改 `<deploy-root>/.env` 或 `image-generate-mcp.service`
+- 改 `.env` 后执行 `systemctl --user restart image-generate-mcp.service`
+- 改 `.service` 后执行 `systemctl --user daemon-reload && systemctl --user restart image-generate-mcp.service`
+
+## MCP 配置方式
+
+以下配置示例均为当前项目可直接使用的正确写法。
+
+### 方式一：stdio 直连（推荐本地开发）
+
+适用于大多数支持本地命令启动 MCP Server 的客户端。
+
+```json
+{
+  "mcpServers": {
+    "image-generate-mcp-remote": {
+      "command": "uv",
+      "args": [
+        "run",
+        "image-generate-mcp-remote",
+        "--transport",
+        "stdio"
+      ],
+      "cwd": "/absolute/path/to/image-generate-mcp-remote",
+      "env": {
+        "IMG_GEN_GPT_IMAGE_2_OFFICIAL_API_KEY": "sk-xxxx",
+        "IMG_GEN_GPT_IMAGE_2_OFFICIAL_BASE_URL": "https://www.uocode.com/v1",
+        "IMG_GEN_GPT_IMAGE_2_OFFICIAL_MODEL": "gpt-image-2",
+        "IMG_GEN_GPT_IMAGE_2_OFFICIAL_SUPPORTED_MODELS": "gpt-image-2",
+        "IMG_GEN_NANO_BANANA_2_OFFICIAL_API_KEY": "sk-xxxx",
+        "IMG_GEN_NANO_BANANA_2_OFFICIAL_BASE_URL": "https://www.uocode.com",
+        "IMG_GEN_NANO_BANANA_2_OFFICIAL_MODEL": "gemini-3.1-flash-image-preview",
+        "IMG_GEN_NANO_BANANA_2_OFFICIAL_SUPPORTED_MODELS": "gemini-3.1-flash-image-preview",
+        "IMAGE_OUTPUT_DIR": "storage/images",
+        "IMAGE_BASE_URL": "",
+        "IMAGE_HTTP_TIMEOUT_SECONDS": "600",
+        "LOG_LEVEL": "INFO"
+      }
+    }
+  }
+}
+```
+
+### 方式二：Streamable HTTP 远程接入
+
+先启动服务：
+
+```bash
+uv run image-generate-mcp-remote --transport streamable-http --host 127.0.0.1 --port 3001
+```
+
+服务默认 MCP 路径为：`/mcp`
+
+```json
+{
+  "mcpServers": {
+    "image-generate-mcp-remote": {
+      "url": "http://127.0.0.1:3001/mcp"
+    }
+  }
+}
+```
+
+### 方式三：SSE 远程接入
+
+先启动服务：
+
+```bash
+uv run image-generate-mcp-remote --transport sse --host 127.0.0.1 --port 3001
+```
+
+服务默认路径为：
+
+- SSE 入口：`/sse`
+- 消息通道：`/messages/`
+
+对于要求分别填写 SSE 地址与消息地址的客户端，可使用：
+
+- `http://127.0.0.1:3001/sse`
+- `http://127.0.0.1:3001/messages/`
+
+## 工具列表
+
+### `list_image_tools_catalog`
+
+输出当前服务暴露的图片工具目录，包括：
+
+- 默认网关地址
+- 当前有效模型
+- 支持模型列表
+- 非敏感环境变量生效值
+
+### `gpt_image_2_official`
+
+OpenAI Images 兼容工具。
+
+- `mode=generate` 时调用文生图
+- `mode=edit` 时调用参考图编辑 / 图生图
+- 默认请求上游：`https://www.uocode.com/v1`
+- 若传入 `size="宽x高"`，服务会自动归一化到支持的 30 档常用尺寸后再请求上游
+
+### `nano_banana_2_official`
+
+Gemini `generateContent` 兼容工具。
+
+- `mode=generate` 时调用文生图
+- `mode=edit` 时调用参考图编辑 / 图生图
+- 默认请求上游：`https://www.uocode.com`
+
+### `gpt-image-2-url`
+
+URL 返回型 `gpt-image-2` 独立工具。
+
+- 调用接口：`POST /images/generations`
+- 默认请求上游：`https://www.right.codes/draw/v1`
+- 默认模型：`gpt-image-2-vip`
+- 上游返回 `https` 图片地址后，服务会自动下载并保存到 `save_path`
+- 返回结果继续复用统一 `ImageToolResult` 结构，保留耗时、token 使用量与上游响应摘要
+- 仅接受共享的 30 档 `size="宽x高"` 预设尺寸
+
+## 环境变量说明
+
+### GPT Image 工具
+
+| 变量名 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `IMG_GEN_GPT_IMAGE_2_OFFICIAL_API_KEY` | 是 | 空 | `gpt_image_2_official` 使用的 API Key |
+| `IMG_GEN_GPT_IMAGE_2_OFFICIAL_BASE_URL` | 否 | `https://www.uocode.com/v1` | OpenAI Images 兼容网关地址 |
+| `IMG_GEN_GPT_IMAGE_2_OFFICIAL_MODEL` | 否 | `gpt-image-2` | 默认调用模型 |
+| `IMG_GEN_GPT_IMAGE_2_OFFICIAL_SUPPORTED_MODELS` | 否 | `gpt-image-2` | 允许调用的模型白名单，逗号分隔 |
+
+### Nano Banana 工具
+
+| 变量名 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `IMG_GEN_NANO_BANANA_2_OFFICIAL_API_KEY` | 是 | 空 | `nano_banana_2_official` 使用的 API Key |
+| `IMG_GEN_NANO_BANANA_2_OFFICIAL_BASE_URL` | 否 | `https://www.uocode.com` | Gemini 原生兼容网关地址 |
+| `IMG_GEN_NANO_BANANA_2_OFFICIAL_MODEL` | 否 | `gemini-3.1-flash-image-preview` | 默认调用模型 |
+| `IMG_GEN_NANO_BANANA_2_OFFICIAL_SUPPORTED_MODELS` | 否 | `gemini-3.1-flash-image-preview` | 允许调用的模型白名单，逗号分隔 |
+
+### 通用变量
+
+| 变量名 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `IMAGE_OUTPUT_DIR` | 否 | `storage/images` | 生成图片的落盘目录 |
+| `IMAGE_BASE_URL` | 否 | 空 | 若需要对外暴露图片 URL，可配置对应静态资源基地址 |
+| `IMAGE_HTTP_TIMEOUT_SECONDS` | 否 | `600` | 上游图片生成请求超时时间，单位秒 |
+| `LOG_LEVEL` | 否 | `INFO` | 日志级别 |
+
+### GPT Image 2 URL 工具
+
+| 变量名 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `IMG_GEN_GPT_IMAGE_2_URL_API_KEY` | 是 | 空 | `gpt-image-2-url` 使用的 API Key |
+| `IMG_GEN_GPT_IMAGE_2_URL_BASE_URL` | 否 | `https://www.right.codes/draw/v1` | URL 返回型网关地址 |
+| `IMG_GEN_GPT_IMAGE_2_URL_MODEL` | 否 | `gpt-image-2-vip` | 默认调用模型 |
+| `IMG_GEN_GPT_IMAGE_2_URL_SUPPORTED_MODELS` | 否 | `gpt-image-2-vip` | 允许调用的模型白名单，逗号分隔 |
+
+## 调试与验证
+
+```bash
+uv run pytest
+```
+
+## 发布说明
+
+- GitHub Release：创建如 `v0.9.1` 的 release 后，会自动触发 `.github/workflows/release.yml`
+- PyPI 发布：工作流使用 `uv build --no-sources` 与 `uv publish`
+- Trusted Publishing：建议在 `PyPI` 中为仓库 `zztdandan/image-generate-mcp-remote` 配置 GitHub Actions trusted publisher，并将 workflow 文件名填写为 `.github/workflows/release.yml`、environment 填写 `pypi`
+- Token 回退方案：若暂不使用 Trusted Publishing，可在 GitHub 仓库 secrets 中配置 `UV_PUBLISH_TOKEN`，同一工作流会自动读取并发布
+
+## 许可证
+
+本项目采用 `MIT` 许可证，完整文本见 `LICENSE`。