Metadata-Version: 2.4
Name: mcp-face-transform
Version: 2026.5.31.1
Summary: MCP server for the AceDataCloud Face Transform API (keypoints, beautify, age/gender, swap, cartoon, liveness)
Project-URL: Homepage, https://github.com/AceDataCloud/FaceTransformMCP
Project-URL: Documentation, https://docs.acedata.cloud
Project-URL: Repository, https://github.com/AceDataCloud/FaceTransformMCP
Project-URL: Issues, https://github.com/AceDataCloud/FaceTransformMCP/issues
Project-URL: Changelog, https://github.com/AceDataCloud/FaceTransformMCP/blob/main/CHANGELOG.md
Author-email: AceDataCloud <support@acedata.cloud>
Maintainer-email: AceDataCloud <support@acedata.cloud>
License: MIT
License-File: LICENSE
Keywords: acedata,beautify,claude,face,face-swap,face-transform,liveness-detection,llm,mcp,model-context-protocol
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
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 :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: loguru>=0.7.0
Requires-Dist: mcp>=1.2.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: all
Requires-Dist: build>=1.2.0; extra == 'all'
Requires-Dist: mypy>=1.10.0; extra == 'all'
Requires-Dist: pre-commit>=3.7.0; extra == 'all'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'all'
Requires-Dist: pytest-cov>=5.0.0; extra == 'all'
Requires-Dist: pytest>=8.0.0; extra == 'all'
Requires-Dist: respx>=0.21.0; extra == 'all'
Requires-Dist: ruff>=0.4.0; extra == 'all'
Requires-Dist: twine>=5.0.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pre-commit>=3.7.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Provides-Extra: release
Requires-Dist: build>=1.2.0; extra == 'release'
Requires-Dist: twine>=5.0.0; extra == 'release'
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'test'
Requires-Dist: pytest-cov>=5.0.0; extra == 'test'
Requires-Dist: pytest>=8.0.0; extra == 'test'
Requires-Dist: respx>=0.21.0; extra == 'test'
Description-Content-Type: text/markdown

# MCP Face Transform Server

A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that
exposes the AceDataCloud Face Transform API — face keypoint detection,
beautification, age/gender transform, face swap, cartoonization, and liveness
detection.

> **Status:** All Face APIs are currently in **Alpha**. Interfaces may evolve.

## Features

- **Keypoint detection** — 90+ landmarks per face, multi-face supported
- **Beautification** — smoothing, whitening, face slimming, eye enlarging
- **Age transform** — age or de-age a portrait
- **Gender transform** — swap perceived facial gender characteristics
- **Face swap** — move a source face onto a target image (with optional async webhook)
- **Cartoonize** — render a portrait in animated / cartoon style
- **Liveness detection** — distinguish live captures from printed / screen photos

## Installation

```bash
pip install mcp-face-transform
```

## Configuration

Set your AceDataCloud API token:

```bash
export ACEDATACLOUD_API_TOKEN=your_token_here
```

Get your token from [https://platform.acedata.cloud](https://platform.acedata.cloud).

## Usage

### stdio mode (default)

```bash
mcp-face-transform
```

### HTTP mode

```bash
mcp-face-transform --transport http --port 8000
```

## Available Tools

| Tool | Endpoint | Purpose |
|------|----------|---------|
| `face_detect_keypoints` | `POST /face/analyze` | Detect 90+ keypoints per face |
| `face_beautify` | `POST /face/beautify` | Smoothing / whitening / slimming / eye enlarging |
| `face_change_age` | `POST /face/change-age` | Age or de-age a portrait |
| `face_change_gender` | `POST /face/change-gender` | Swap perceived facial gender characteristics |
| `face_swap` | `POST /face/swap` | Move source face onto target image |
| `face_cartoonize` | `POST /face/cartoon` | Convert portrait to cartoon style |
| `face_detect_liveness` | `POST /face/detect-live` | Detect live vs printed/screen face |
| `face_get_usage_guide` | _client-side_ | Concise tool usage reference |

## Example

```text
"Detect all faces in https://example.com/group.jpg and return their keypoints."
→ face_detect_keypoints(image_url="https://example.com/group.jpg")

"Lighten and smooth my portrait."
→ face_beautify(image_url="https://example.com/me.jpg", smoothing=15, whitening=25)

"Replace the face in the scene with the headshot."
→ face_swap(
    source_image_url="https://example.com/headshot.jpg",
    target_image_url="https://example.com/scene.jpg",
  )
```

## Configuration in Claude Desktop / Claude Code

```json
{
  "mcpServers": {
    "face-transform": {
      "command": "uvx",
      "args": ["mcp-face-transform"],
      "env": {
        "ACEDATACLOUD_API_TOKEN": "your_api_token_here"
      }
    }
  }
}
```

Or use the hosted endpoint with bearer auth:

```json
{
  "mcpServers": {
    "face-transform": {
      "url": "https://face.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer your_api_token_here"
      }
    }
  }
}
```

## Development

```bash
pip install -e ".[dev,test]"
pytest --cov=core --cov=tools
ruff check .
```

## License

MIT — see [LICENSE](LICENSE).
