Metadata-Version: 2.4
Name: aiwan-workbuddy-image-tools-mcp
Version: 0.7.0
Summary: Background keying, transparent-margin trimming, sheet splitting, resizing and format conversion for game UI assets, exposed as a WorkBuddy connector
License: MIT
Project-URL: Homepage, https://www.workbuddy.cn
Keywords: workbuddy,connector,mcp,image,image-processing,background-removal,chroma-key,sprite-sheet,game-assets,pillow
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Multimedia :: Graphics :: Editors
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp<2,>=1.9
Requires-Dist: Pillow>=10
Requires-Dist: numpy>=1.23

# WorkBuddy Image Tools

Five deterministic image operations for game-UI assets, packaged as a
[WorkBuddy](https://www.workbuddy.cn) connector. Everything runs locally: no
uploads, no network calls, no model inference — just Pillow doing pixel maths,
and only metadata comes back to the caller.

The point is token economy. Instead of asking a model to *regenerate* the
picture, you translate "把这个按钮的背景去掉" into one strict command and let
the function do the work.

## Install

```bash
pip install aiwan-workbuddy-image-tools-mcp
```

## Commands

```bash
image-tools matte   cover.png                          # 抠掉纯色背景
image-tools matte   --mode color --color "#00FF00" a.png
image-tools trim    cutout.png --padding 2             # 切掉四周透明空白
image-tools split   sheet.png                          # 合图拆成多个透明 PNG
image-tools split   --mode grid --rows 2 --cols 3 sprite.png
image-tools resize  --width 400 cover.png              # 缩放
image-tools convert --format webp screenshot.png       # 转格式
```

| Command | What it does | Input |
|---|---|---|
| `matte` | remove a flat-colour or green-screen background | solid / green backdrop |
| `trim` | crop to the content boundary | needs an alpha channel |
| `split` | split a sheet into separate transparent PNGs | transparent / solid backdrop |
| `resize` | width / height / scale, LANCZOS | any image |
| `convert` | png / jpg / webp / gif / bmp / tiff / avif | any image |

## Output contract

Every command writes exactly one JSON object to stdout:

```json
{
  "ok": true,
  "format": "PNG",
  "width": 512,
  "height": 512,
  "bytes": 38120,
  "kb": 37.2,
  "output": "D:/out/cover_matte.png"
}
```

Failures exit non-zero with a Chinese JSON error on stderr that names the
offending field and how to fix it:

```json
{
  "ok": false,
  "error": "InvalidArgument",
  "message": "threshold 不能大于 255（收到 300）",
  "field": "threshold",
  "value": 300,
  "hint": "默认 30，常用 20-60；背景不干净时调大"
}
```

Input is validated *before* a single pixel is touched — missing image, wrong
types, out-of-range values, unreadable files, undecodable bytes and
source-overwriting output paths are all rejected without writing anything.

## MCP server

The same five operations are exposed over stdio for MCP clients:

```bash
image-tools-mcp                      # stdio
image-tools-mcp --transport http    # streamable HTTP
```

Tools: `image_matte`, `image_trim`, `image_split`, `image_resize`,
`image_convert`.

## Limits

- Background removal is **colour distance**, not semantic segmentation.
  Flat colours and green screens work; photos, gradients, textures and
  checkerboard backdrops are rejected with an explicit error.
- Input up to 12 MB and 100 MP; a 3000×3000 matte takes ~1.7 s.
- Windows, macOS and Linux.

## License

MIT
