mcp-face-transform 2026.5.31.0__tar.gz

mcp_face_transform-2026.5.31.0/.env.example

@@ -0,0 +1,16 @@
+# Environment template - copy to .env and fill in your values
+# Get your API token from https://platform.acedata.cloud
+
+# AceDataCloud API Configuration (REQUIRED)
+ACEDATACLOUD_API_TOKEN=your_api_token_here
+ACEDATACLOUD_API_BASE_URL=https://api.acedata.cloud
+
+# Face Configuration (Optional)
+FACE_REQUEST_TIMEOUT=180
+
+# MCP Server Configuration (Optional)
+MCP_SERVER_NAME=face
+MCP_TRANSPORT=stdio
+
+# Logging (Optional)
+LOG_LEVEL=INFO

mcp_face_transform-2026.5.31.0/.gitignore

@@ -0,0 +1,82 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Ruff
+.ruff_cache/
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project specific
+*.log

mcp_face_transform-2026.5.31.0/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Calendar Versioning](https://calver.org/).
+
+## [Unreleased]
+
+### Added
+
+- Initial release of MCP Face Transform Server.
+- Seven face tools wrapping the AceDataCloud Face Transform API:
+  - `face_detect_keypoints` — `POST /face/analyze` (90+ keypoints per face)
+  - `face_beautify` — `POST /face/beautify`
+  - `face_change_age` — `POST /face/change-age`
+  - `face_change_gender` — `POST /face/change-gender`
+  - `face_swap` — `POST /face/swap` (optional async `callback_url`)
+  - `face_cartoonize` — `POST /face/cartoon`
+  - `face_detect_liveness` — `POST /face/detect-live`
+  - `face_get_usage_guide` — concise tool reference
+- Two MCP prompts: `face_guide`, `face_workflow_examples`.
+- stdio and Streamable HTTP transports.
+- OAuth 2.1 (PKCE) support for hosted Claude.ai deployment.
+- Bearer-token authentication for direct HTTP access.
+- JetBrains AI Assistant plugin scaffold and VS Code extension scaffold.
+- GitHub Actions pipeline for PyPI / GitHub Release / MCP Registry / Smithery /
+  VS Code Marketplace / JetBrains Marketplace / Docker Hub publication.

mcp_face_transform-2026.5.31.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 AceDataCloud
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_face_transform-2026.5.31.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: mcp-face-transform
+Version: 2026.5.31.0
+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).

mcp_face_transform-2026.5.31.0/README.md

@@ -0,0 +1,120 @@
+# 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).

mcp_face_transform-2026.5.31.0/core/__init__.py

@@ -0,0 +1,15 @@
+"""Core module for MCP Face Transform server."""
+
+from core.client import FaceClient
+from core.config import settings
+from core.exceptions import FaceAPIError, FaceAuthError, FaceValidationError
+from core.server import mcp
+
+__all__ = [
+    "FaceClient",
+    "settings",
+    "mcp",
+    "FaceAPIError",
+    "FaceAuthError",
+    "FaceValidationError",
+]

mcp_face_transform-2026.5.31.0/core/client.py

@@ -0,0 +1,160 @@
+"""HTTP client for Face Transform API."""
+
+import contextvars
+import json
+from typing import Any
+
+import httpx
+from loguru import logger
+
+from core.config import settings
+from core.exceptions import FaceAPIError, FaceAuthError, FaceError, FaceTimeoutError
+
+# Context variable for per-request API token (used in HTTP/remote mode).
+_request_api_token: contextvars.ContextVar[str | None] = contextvars.ContextVar(
+    "_request_api_token", default=None
+)
+
+
+def set_request_api_token(token: str | None) -> None:
+    """Set the API token for the current request context (HTTP mode)."""
+    _request_api_token.set(token)
+
+
+def get_request_api_token() -> str | None:
+    """Get the API token from the current request context."""
+    return _request_api_token.get()
+
+
+class FaceClient:
+    """Async HTTP client for the AceDataCloud Face Transform API."""
+
+    def __init__(self, api_token: str | None = None, base_url: str | None = None):
+        self.api_token = api_token if api_token is not None else settings.api_token
+        self.base_url = base_url or settings.api_base_url
+        self.timeout = settings.request_timeout
+
+        logger.info(f"FaceClient initialized with base_url: {self.base_url}")
+        logger.debug(f"API token configured: {'Yes' if self.api_token else 'No'}")
+        logger.debug(f"Request timeout: {self.timeout}s")
+
+    def _get_headers(self) -> dict[str, str]:
+        token = get_request_api_token() or self.api_token
+        if not token:
+            logger.error("API token not configured!")
+            raise FaceAuthError("API token not configured")
+
+        return {
+            "accept": "application/json",
+            "authorization": f"Bearer {token}",
+            "content-type": "application/json",
+        }
+
+    def _handle_error_response(self, response: httpx.Response) -> None:
+        status = response.status_code
+        try:
+            body = response.json()
+        except Exception:
+            body = {}
+
+        error_obj = body.get("error", {}) if isinstance(body, dict) else {}
+        code = error_obj.get("code", f"http_{status}")
+        message = (
+            error_obj.get("message")
+            or (body.get("detail") if isinstance(body, dict) else None)
+            or response.text
+            or f"HTTP {status}"
+        )
+
+        logger.error(f"API error {status} [{code}]: {message}")
+
+        if status in (401, 403):
+            raise FaceAuthError(message)
+        raise FaceAPIError(message=message, code=code, status_code=status)
+
+    async def request(
+        self,
+        method: str,
+        endpoint: str,
+        *,
+        payload: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        timeout: float | None = None,
+    ) -> dict[str, Any]:
+        method_upper = method.upper()
+        url = f"{self.base_url}{endpoint}"
+        request_timeout = timeout or self.timeout
+
+        logger.info(f"🚀 {method_upper} {url}")
+        if payload is not None:
+            logger.debug(f"Request payload: {json.dumps(payload, ensure_ascii=False, indent=2)}")
+        if params is not None:
+            logger.debug(f"Request params: {json.dumps(params, ensure_ascii=False, indent=2)}")
+        logger.debug(f"Timeout: {request_timeout}s")
+
+        async with httpx.AsyncClient() as http_client:
+            try:
+                response = await http_client.request(
+                    method_upper,
+                    url,
+                    json=payload,
+                    params=params,
+                    headers=self._get_headers(),
+                    timeout=request_timeout,
+                )
+                logger.info(f"📥 Response status: {response.status_code}")
+
+                if response.status_code >= 400:
+                    self._handle_error_response(response)
+
+                result = response.json()
+                logger.success("✅ Request successful")
+                return result  # type: ignore[no-any-return]
+
+            except httpx.TimeoutException as e:
+                logger.error(f"⏰ Request timeout after {request_timeout}s: {e}")
+                raise FaceTimeoutError(
+                    f"Request to {endpoint} timed out after {request_timeout}s"
+                ) from e
+
+            except FaceError:
+                raise
+
+            except Exception as e:
+                logger.error(f"❌ Request error: {e}")
+                raise FaceAPIError(message=str(e)) from e
+
+    async def analyze(self, **kwargs: Any) -> dict[str, Any]:
+        logger.info(f"🔍 Analyzing face keypoints for: {kwargs.get('image_url', '')}")
+        return await self.request("POST", "/face/analyze", payload=kwargs)
+
+    async def beautify(self, **kwargs: Any) -> dict[str, Any]:
+        logger.info(f"✨ Beautifying face for: {kwargs.get('image_url', '')}")
+        return await self.request("POST", "/face/beautify", payload=kwargs)
+
+    async def change_age(self, **kwargs: Any) -> dict[str, Any]:
+        logger.info(f"🕰️ Transforming age for: {kwargs.get('image_url', '')}")
+        return await self.request("POST", "/face/change-age", payload=kwargs)
+
+    async def change_gender(self, **kwargs: Any) -> dict[str, Any]:
+        logger.info(f"🔁 Swapping gender for: {kwargs.get('image_url', '')}")
+        return await self.request("POST", "/face/change-gender", payload=kwargs)
+
+    async def swap(self, **kwargs: Any) -> dict[str, Any]:
+        logger.info(
+            f"🔄 Swapping face: source={kwargs.get('source_image_url', '')} "
+            f"target={kwargs.get('target_image_url', '')}"
+        )
+        return await self.request("POST", "/face/swap", payload=kwargs)
+
+    async def cartoon(self, **kwargs: Any) -> dict[str, Any]:
+        logger.info(f"🎨 Cartoonizing face for: {kwargs.get('image_url', '')}")
+        return await self.request("POST", "/face/cartoon", payload=kwargs)
+
+    async def detect_live(self, **kwargs: Any) -> dict[str, Any]:
+        logger.info(f"🛡️ Detecting liveness for: {kwargs.get('image_url', '')}")
+        return await self.request("POST", "/face/detect-live", payload=kwargs)
+
+
+# Global client instance
+client = FaceClient()

mcp_face_transform-2026.5.31.0/core/config.py

@@ -0,0 +1,65 @@
+"""Configuration management for MCP Face Transform server."""
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+# Load .env file from project root
+_env_path = Path(__file__).parent.parent / ".env"
+load_dotenv(dotenv_path=_env_path)
+
+
+@dataclass
+class Settings:
+    """Application settings loaded from environment variables."""
+
+    # API Configuration
+    api_base_url: str = field(
+        default_factory=lambda: os.getenv("ACEDATACLOUD_API_BASE_URL", "https://api.acedata.cloud")
+    )
+    api_token: str = field(default_factory=lambda: os.getenv("ACEDATACLOUD_API_TOKEN", ""))
+
+    # Request Configuration — face endpoints are synchronous; default 180s.
+    request_timeout: float = field(
+        default_factory=lambda: float(os.getenv("FACE_REQUEST_TIMEOUT", "180"))
+    )
+
+    # Server Configuration
+    server_name: str = field(default_factory=lambda: os.getenv("MCP_SERVER_NAME", "face"))
+    transport: str = field(default_factory=lambda: os.getenv("MCP_TRANSPORT", "stdio"))
+    log_level: str = field(default_factory=lambda: os.getenv("LOG_LEVEL", "INFO"))
+
+    # OAuth / Remote Auth Configuration
+    server_url: str = field(default_factory=lambda: os.getenv("MCP_SERVER_URL", ""))
+    auth_base_url: str = field(
+        default_factory=lambda: os.getenv(
+            "ACEDATACLOUD_AUTH_BASE_URL", "https://auth.acedata.cloud"
+        )
+    )
+    platform_base_url: str = field(
+        default_factory=lambda: os.getenv(
+            "ACEDATACLOUD_PLATFORM_BASE_URL", "https://platform.acedata.cloud"
+        )
+    )
+    oauth_client_id: str = field(
+        default_factory=lambda: os.getenv("ACEDATACLOUD_OAUTH_CLIENT_ID", "")
+    )
+
+    def validate(self) -> None:
+        """Validate required settings."""
+        if not self.api_token:
+            raise ValueError(
+                "ACEDATACLOUD_API_TOKEN environment variable is required."
+                "Get your token from https://platform.acedata.cloud"
+            )
+
+    @property
+    def is_configured(self) -> bool:
+        """Check if the API token is configured."""
+        return bool(self.api_token)
+
+
+# Global settings instance
+settings = Settings()