# idphoto-mcp — 证件照 MCP Server

> 本地证件照生成：人脸检测 + 抠图换底 + 规格裁切 + 相纸排版 + 合规校验。
> **全离线、CPU、隐私不出机器**（证件照是身份证级生物特征，本地处理更安全）。

## 演示

![操作演示](assets/demo_usage.gif)

![照片→证件照](assets/demo_photo.png)

> 自拍/任意照片 → 标准证件照（人脸对齐构图，本地处理）

## 为什么做这个

- 全网 **0 个本地证件照 MCP**（现有 2 个都是云端 API 转发，隐私反而是负分）
- HivisionIDPhotos（21k★）算法已开源 Apache-2.0，但**没人做 MCP 封装**
- 中国办证/考试/签证全要证件照，规格严格，需求是国民刚需

**本项目的差异化**（不重造算法，补没人做好的三层）：
1. **MCP 封装**：6 个工具，AI 工作流可直接调用
2. **结构化规格库**：20 个规格含 mm/像素/用途/官方出处（修正上游尺寸错误，如国标二寸是 35×49mm）
3. **合规校验器**：返回 pass/fail + 原因（现有工具只给结果不给判断）

## 核心能力

| 工具 | 说明 |
|---|---|
| `list_specs` | 全部规格（证件照/考试/签证/护照/社保），可按类别过滤 |
| `get_spec_info` | 单规格详情（含换算像素） |
| `make_id_photo_tool` ⭐ | 人像 → 抠图 → 换底 → 规格裁切 → 标准证件照 |
| `change_background_tool` | 仅换底色 |
| `make_print_sheet_tool` | 相纸排版（六寸/五寸/A4/3R/4R）+ 裁剪线 |
| `validate_id_photo_tool` ⭐ | 合规校验（人脸完整/尺寸/占比） |

## 规格库（示例）

| spec_id | 名称 | mm | 像素@300dpi | 用途 |
|---|---|---|---|---|
| one_inch | 一寸 | 25×35 | 295×413 | 教资/通用 |
| two_inch | 二寸 | 35×49 | 413×579 | 证件（国标修正版） |
| passport_cn | 护照 | 33×48 | 390×567 | 白底 |
| us_visa | 美签 | 51×51 | 602×602 | 正方形白底 |
| civil_servant | 公务员 | 25×35 | 295×413 | 国考报名 |

## 安装

```bash
pip install idphoto-mcp-server
python -m idphoto_mcp.download_models   # 下载 hivision_modnet.onnx (24.7MB) + yunet.onnx
```

## 使用（Claude Desktop）

```json
{
  "mcpServers": {
    "idphoto": {
      "command": "idphoto-mcp",
      "args": []
    }
  }
}
```

## 演示用例

```
调用 make_id_photo_tool(input_path="我的照片.jpg", spec_id="one_inch", bg_color="blue")
→ 输出 295x413 一寸蓝底证件照

调用 make_print_sheet_tool(paper="six_inch", spec_id="one_inch")
→ 六寸相纸排 16 张，带裁剪线，直接打印

调用 validate_id_photo_tool(spec_id="us_visa")
→ pass/fail + 人脸占比/尺寸报告
```

## License

MIT。图像管线复用 HivisionIDPhotos（Apache-2.0）。

---

## 系列（Chinese MCP Suite）

> 中文内容创作/工具 MCP 全家桶，全本地、CPU、离线：


- [tts-mcp-server](https://github.com/Gollum-code/tts-mcp-server) — TTS聚合+字幕对齐
- **idphoto-mcp**（本仓库）— 本地证件照
- [audio-post-mcp](https://github.com/Gollum-code/audio-post-mcp) — 音频后期
- [video-workflow-mcp](https://github.com/Gollum-code/video-workflow-mcp) — 视频工作流
- [poetry-mcp](https://github.com/Gollum-code/poetry-mcp) — 古诗文
- [script-mcp](https://github.com/Gollum-code/script-mcp) — 口播文案
- [asset-mcp](https://github.com/Gollum-code/asset-mcp) — 素材库
- [idiom-mcp](https://github.com/Gollum-code/idiom-mcp) — 成语典故
- [weather-mcp](https://github.com/Gollum-code/weather-mcp) — 天气/空气