Metadata-Version: 2.4
Name: tai-mcp
Version: 0.1.0
Summary: Local stdio MCP for the tai-openapi image generation API.
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: httpx<1,>=0.27.0
Requires-Dist: mcp<2,>=1.27
Requires-Dist: openai<3,>=2
Requires-Dist: pydantic-settings<3,>=2.4.0
Provides-Extra: dev
Requires-Dist: pytest<9,>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio<1,>=0.23.0; extra == "dev"
Requires-Dist: ruff<1,>=0.5.0; extra == "dev"

# tai-mcp

`tai-mcp` 是一个仅通过 stdio 运行的本地 MCP，把 `tai-openapi` 的 OpenAI 兼容图片生成和
编辑接口封装为 MCP 工具。它不监听端口，也不提供 HTTP、鉴权、CORS、健康检查或 Docker
部署入口。

## 工具

- `generate_image`：调用 `POST /v1/images/generations` 生成图片。
- `edit_image`：调用 `POST /v1/images/edits` 编辑一张或多张图片。
- `get_image_model_capabilities`：查询编辑模型的图片数量、mask、size 和扩展参数约束。
- `list_image_models`：列出上游当前启用的模型。

生成和编辑都支持 `response_format="url"`（默认）与 `response_format="b64_json"`：

- `url`：MCP 返回包含上游图片 URL 的 JSON 文本，不下载图片。
- `b64_json`：MCP 返回标准 `ImageContent` 和图片元数据。

## 图片编辑输入

`edit_image.images` 是有序的本地图片绝对路径列表，`mask` 是可选的本地图片绝对路径。
支持 PNG、JPEG 和 WebP。MCP 在本机读取文件，再通过 OpenAI 兼容的 multipart `image[]`
和 `mask` 文件字段上传到 `tai-openapi`，图片内容不经过 MCP JSON/base64 传输。

路径必须满足以下条件：

- 使用普通文件系统绝对路径，例如 `C:\Users\me\Pictures\source.png`；不要使用 `file://`；
- 最终解析路径位于 `MCP_ALLOWED_IMAGE_ROOTS` 配置的目录中；
- 文件扩展名和实际图片格式一致；
- 单个文件不超过 `MCP_MAX_IMAGE_BYTES`。

相对路径、HTTP URL、base64 和 Data URL 不再作为编辑输入接受。

示例：

```json
{
  "prompt": "Make the bodywork brighter",
  "images": [
    "C:\\Users\\me\\Pictures\\car.png",
    "C:\\Users\\me\\Pictures\\reference.png"
  ],
  "model": "tai-image-to-image",
  "response_format": "url",
  "parameters": {"denoise": 0.55}
}
```

编辑前建议先调用 `get_image_model_capabilities(model)`，按返回的 `input.min_images`、
`input.max_images`、`input.mask`、`input.size`、`input.prompt_required` 和
`parameters_schema` 组织参数。

## 安装与配置

要求 Python 3.12+ 和 [uv](https://docs.astral.sh/uv/)。

```powershell
Copy-Item .env.example .env
uv sync --extra dev
```

在 `.env` 中至少配置现有的 `TAI_OPENAPI_*` 变量：

```dotenv
TAI_OPENAPI_BASE_URL=http://127.0.0.1:8000/v1
TAI_OPENAPI_API_KEY=replace-with-tai-openapi-api-key
TAI_IMAGE_MODEL=tai-text-to-image
TAI_IMAGE_EDIT_MODEL=tai-image-to-image
MCP_ALLOWED_IMAGE_ROOTS=C:\Users\me\Pictures
```

| 环境变量 | 默认值 | 说明 |
| --- | --- | --- |
| `TAI_OPENAPI_BASE_URL` | `http://127.0.0.1:8000/v1` | OpenAI 兼容接口地址，必须以 `/v1` 结尾 |
| `TAI_OPENAPI_API_KEY` | 无 | 上游 Bearer Token，必填 |
| `TAI_IMAGE_MODEL` | `tai-text-to-image` | `generate_image` 默认模型 |
| `TAI_IMAGE_EDIT_MODEL` | `tai-image-to-image` | `edit_image` 默认模型 |
| `MCP_REQUEST_TIMEOUT_SECONDS` | `330` | 上游请求总超时 |
| `MCP_CONNECT_TIMEOUT_SECONDS` | `10` | 上游连接超时 |
| `MCP_MAX_IMAGE_BYTES` | `20971520` | 单张输入图片和 `b64_json` 输出图片的最大大小 |
| `MCP_ALLOWED_IMAGE_ROOTS` | `.` | 允许读取图片的目录；Windows 使用分号分隔多个目录 |

## 本地运行与注册

直接启动 stdio MCP：

```powershell
uv run python -m tai_mcp
```

注册到 Codex 时，让进程工作目录指向本项目，以便读取 `.env`：

```powershell
codex mcp add tai-images -- `
  powershell.exe -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass `
  -File C:\path\to\tai-mcp\run-stdio.ps1
```

不要把真实 API Key 写入 `.env.example`、Codex 命令参数、Git 或日志。

## 测试

```powershell
uv run --extra dev python -m pytest
uv run --extra dev python -m ruff check .
uv run --extra dev python -m ruff format --check .
```
