Metadata-Version: 2.5
Name: zjzmei-mcp
Version: 0.2.1
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 客户端直接制作证件照，并使用换底色、改大小、变清晰、格式转换四个图片工具。

## 远程服务（推荐）

官方远程端点无需安装任何运行时，Streamable HTTP 客户端直接连接，密钥放在请求头：

```json
{
  "mcpServers": {
    "zjzmei": {
      "type": "streamableHttp",
      "url": "https://zmapi.zjzmei.top/mcp",
      "headers": { "Authorization": "Bearer 你的密钥" }
    }
  }
}
```

远程服务读不到你电脑上的文件：本地照片先调用 `create_upload_link`，按返回的命令 `curl -F "file=@照片路径" <上传链接>` 上传（链接 10 分钟内有效、只能用一次，最大 20MB），再把返回的 `assetId` 传给制作工具。结果地址 5 分钟内有效，请及时下载。

## 本地运行（stdio）

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

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

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

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

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

### 自托管 HTTP 模式

`--transport http` 启动 Streamable HTTP 服务（`/mcp`，无状态、JSON 响应），供远程客户端使用：

- 按请求鉴权：`Authorization: Bearer <密钥>`（兼容 `X-Api-Key`），密钥由业务后端判定；缺失或无效返回 401，后端不可用返回 503。进程不需要 `ZJZMEI_API_KEY`。
- `POST /mcp-upload/{token}`：`create_upload_link` 签发的一次性上传入口（multipart 字段 `file` 或原始图片字节）。令牌存在进程内存，只能单副本部署。
- `GET /healthz`：健康检查。
- 不读取服务端本地文件，不写 `saveDir`。`--public-base-url` 决定上传链接的对外地址；`--allowed-hosts` 开启 Host 头校验。

## 客户端配置

```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` |
| `create_upload_link` | 仅 HTTP 模式：签发一次性上传链接，用 curl 上传本地照片 |
| `make_id_photo` | 按规格或像素尺寸制作证件照，可生成排版照 |
| `get_id_photo_colors` | 查询同一会话其他底色的生成状态 |
| `get_id_photo_layouts` | 查询各底色排版照预览 |
| `change_background` | 换底色 |
| `resize_photo` | 压缩到指定 KB 区间并写入 DPI |
| `enhance_photo` | 变清晰（自然 / 高清） |
| `convert_format` | 转换为 JPG / PNG / WEBP |

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

## 开发

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