Metadata-Version: 2.5
Name: zjzmei-mcp
Version: 0.1.0
Summary: 最美证件照 MCP 服务：证件照制作、换底色、改大小、变清晰、格式转换
Author: zjzmei
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: id-photo,mcp,workbuddy,证件照
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Graphics
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27
Requires-Dist: mcp<3,>=2.3
Description-Content-Type: text/markdown

# zjzmei-mcp

最美证件照 MCP 服务。让 WorkBuddy、Claude Code 等 MCP 客户端直接制作证件照，并使用换底色、改大小、变清晰、格式转换四个图片工具。

## 运行

需要 [uv](https://docs.astral.sh/uv/) 和一个 MCP 访问密钥。

```bash
ZJZMEI_API_KEY=你的密钥 uvx zjzmei-mcp
```

也可以用 npm 包启动（内部调用 uvx）：`npx -y zjzmei-mcp`。

| 环境变量 | 说明 |
| --- | --- |
| `ZJZMEI_API_KEY` | 必填，MCP 访问密钥 |
| `ZJZMEI_API_BASE` | 可选，业务 API 根地址，默认 `https://zmapi.zjzmei.top/api/v1` |

命令行参数：`--transport stdio|http`（默认 stdio）、`--host`（默认 127.0.0.1）、`--port`（默认 8765）、`--api-base`。

HTTP 模式（Streamable HTTP，地址 `http://<host>:<port>/mcp`）的端点本身没有鉴权，只适合本机或可信内网自用。该模式下不读取服务端本地文件，也不写入 `saveDir`。

## 客户端配置

```json
{
  "mcpServers": {
    "zjzmei": {
      "command": "uvx",
      "args": ["zjzmei-mcp"],
      "env": { "ZJZMEI_API_KEY": "你的密钥" }
    }
  }
}
```

## 工具

| 工具 | 作用 |
| --- | --- |
| `list_spec_categories` | 规格分类 |
| `search_specs` | 按关键字/分类搜索规格（尺寸、DPI、文件大小、默认底色） |
| `get_spec` | 规格详情与可选背景色 |
| `list_background_colors` | 标准底色字典 |
| `upload_photo` | 上传源图，返回可复用的 `assetId` |
| `make_id_photo` | 按规格或像素尺寸制作证件照，可生成排版照 |
| `get_id_photo_colors` | 查询同一会话其他底色的生成状态 |
| `get_id_photo_layouts` | 查询各底色排版照预览 |
| `change_background` | 换底色 |
| `resize_photo` | 压缩到指定 KB 区间并写入 DPI |
| `enhance_photo` | 变清晰（自然 / 高清） |
| `convert_format` | 转换为 JPG / PNG / WEBP |

图片入参可以是本地文件路径、http(s) 图片链接或 `assetId`，源图仅支持 JPG/PNG。返回的图片地址是短期地址；传 `saveDir` 可直接保存到本地。

## 开发

```bash
uv sync
uv run pytest
uv build
```
