synfig-mcp 1.0.3__py3-none-any.whl

synfig_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""
+synfig-mcp: Live Model Context Protocol control of Synfig Studio.
+"""
+
+__version__ = "0.8.0-rc2"

synfig_mcp/__main__.py

@@ -0,0 +1,8 @@
+"""
+Entrypoint for python -m synfig_mcp.
+"""
+
+from synfig_mcp.server import main
+
+if __name__ == "__main__":
+    main()

synfig_mcp/assets/__init__.py

@@ -0,0 +1,8 @@
+"""
+Licensed Asset Pipeline (Phase A5).
+"""
+
+from synfig_mcp.assets.models import AssetManifest, AssetMetadata, LicensePolicy
+from synfig_mcp.assets.pipeline import AssetPipeline
+
+__all__ = ["AssetManifest", "AssetMetadata", "AssetPipeline", "LicensePolicy"]

synfig_mcp/assets/models.py

@@ -0,0 +1,129 @@
+"""
+Data models for the Licensed Asset Pipeline, Provenance Manifest, and License Policies (Phase A5).
+"""
+
+from __future__ import annotations
+
+import datetime
+
+from pydantic import BaseModel, Field
+
+
+class LicensePolicy(BaseModel):
+    """
+    Configurable license policy for external assets.
+    Default configuration is strict: allows CC0/PDM, blocks ND/NC, flags BY/BY-SA.
+    """
+
+    allow_cc0: bool = Field(default=True, description="Allow CC0 / Public Domain Dedication.")
+    allow_pdm: bool = Field(default=True, description="Allow Public Domain Mark.")
+    allow_by: bool = Field(default=False, description="Allow CC BY (attribution required).")
+    allow_by_sa: bool = Field(default=False, description="Allow CC BY-SA (Share-Alike required).")
+    allow_commercial: bool = Field(
+        default=True, description="Whether project requires commercial use."
+    )
+    block_nd: bool = Field(default=True, description="Block NoDerivatives (we transform assets).")
+    block_nc: bool = Field(default=True, description="Block NonCommercial if commercial.")
+    skip_mature: bool = Field(default=True, description="Reject mature/NSFW flagged content.")
+
+    def evaluate_license(self, license_code: str, is_mature: bool = False) -> tuple[bool, str]:
+        """
+        Evaluate a license code against policy.
+        Returns: (allowed: bool, reason: str).
+        """
+        if self.skip_mature and is_mature:
+            return False, "Asset is flagged as mature content."
+
+        code = license_code.lower().strip()
+
+        if code in ("cc0", "pdm", "public-domain"):
+            return True, "Permitted by policy (Public Domain / CC0)."
+
+        if "nd" in code and self.block_nd:
+            return (
+                False,
+                f"License '{code}' contains No-Derivatives (ND) clause; animation transformations prohibited.",
+            )
+
+        if "nc" in code and self.block_nc and self.allow_commercial:
+            return (
+                False,
+                f"License '{code}' contains Non-Commercial (NC) restriction on a commercial project.",
+            )
+
+        if code == "by":
+            if self.allow_by:
+                return True, "Permitted by policy with attribution."
+            return False, "License 'by' requires attribution and is disabled under strict policy."
+
+        if code in ("by-sa", "sa"):
+            if self.allow_by_sa:
+                return True, "Permitted by policy with Share-Alike obligation."
+            return (
+                False,
+                "License 'by-sa' requires Share-Alike and is disabled under strict policy.",
+            )
+
+        return False, f"License '{code}' is not permitted under active policy."
+
+
+class AssetMetadata(BaseModel):
+    """Provenance and licensing metadata captured at download time."""
+
+    id: str = Field(description="Unique asset identifier (e.g. 'openverse_12345').")
+    provider: str = Field(description="Source provider ('openverse', 'wikimedia', 'local').")
+    title: str = Field(description="Asset title or filename.")
+    creator: str = Field(default="Unknown", description="Original creator or copyright holder.")
+    license_code: str = Field(description="Standard license identifier ('cc0', 'pdm', 'by', etc.).")
+    license_url: str = Field(default="", description="Authoritative URL for license terms.")
+    attribution_text: str = Field(default="", description="Ready-to-use attribution snippet.")
+    download_url: str = Field(default="", description="Original HTTPS source download URL.")
+    thumbnail_url: str | None = Field(default=None, description="Small preview URL.")
+    filesize_bytes: int = Field(default=0, description="Size on disk in bytes.")
+    sha256: str = Field(default="", description="Cryptographic SHA-256 hash.")
+    local_path: str = Field(default="", description="Local file path within workspace.")
+    retrieved_at: str = Field(
+        default_factory=lambda: datetime.datetime.now(datetime.UTC).isoformat(),
+        description="ISO 8601 UTC timestamp of download.",
+    )
+    rights_declaration: str = Field(
+        default="", description="Declared rights basis ('own', 'licensed', 'cc0', 'public-domain')."
+    )
+    mature: bool = Field(default=False, description="Whether asset is flagged as mature.")
+
+
+class AssetManifest(BaseModel):
+    """Collection manifest of all imported assets stored at assets/manifest.json."""
+
+    version: str = Field(default="1.0")
+    assets: list[AssetMetadata] = Field(default_factory=list)
+
+    def generate_attribution_md(self) -> str:
+        """Auto-generate ATTRIBUTION.md for legal compliance and project distribution."""
+        lines = [
+            "# Project Asset Attribution & License Provenance",
+            "",
+            "> Auto-generated by Synfig MCP Asset Pipeline.",
+            "> Every external asset used in this animation project is recorded with source and terms snapshot.",
+            "",
+            "| Asset Title | Creator | License | Provider | SHA-256 | Local File |",
+            "|---|---|---|---|---|---|",
+        ]
+        for a in self.assets:
+            c_link = f"[{a.creator}]({a.license_url})" if a.license_url else a.creator
+            lines.append(
+                f"| **{a.title}** | {c_link} | `{a.license_code.upper()}` | {a.provider} | `{a.sha256[:12]}...` | `{a.local_path}` |"
+            )
+
+        lines.extend(
+            [
+                "",
+                "## Attribution Statements",
+                "",
+            ]
+        )
+        for a in self.assets:
+            if a.attribution_text:
+                lines.append(f"- **{a.title}**: {a.attribution_text}")
+
+        return "\n".join(lines) + "\n"

synfig_mcp/assets/pipeline.py

@@ -0,0 +1,226 @@
+"""
+Asset Pipeline: Manages downloading, hardened sanitization, cryptographic hashing,
+manifest recording, and attribution generation (Phase A5).
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+from synfig_mcp.assets.models import AssetManifest, AssetMetadata, LicensePolicy
+from synfig_mcp.assets.providers.base import BaseAssetProvider
+from synfig_mcp.assets.providers.mock_provider import MockAssetProvider
+from synfig_mcp.assets.providers.openverse import OpenverseAssetProvider
+from synfig_mcp.assets.security.raster_hardening import harden_raster_image
+from synfig_mcp.assets.security.svg_sanitizer import sanitize_svg
+from synfig_mcp.assets.security.url_validator import validate_asset_url
+from synfig_mcp.security.sandbox import get_default_allowed_roots
+
+
+class AssetPipeline:
+    """Orchestrator for the licensed internet asset pipeline."""
+
+    def __init__(
+        self,
+        policy: LicensePolicy | None = None,
+        providers: list[BaseAssetProvider] | None = None,
+    ) -> None:
+        self.policy = policy or LicensePolicy()
+        self.providers: dict[str, BaseAssetProvider] = {
+            "openverse": OpenverseAssetProvider(),
+            "mock": MockAssetProvider(),
+        }
+        if providers:
+            for p in providers:
+                self.providers[p.name] = p
+
+    def get_provider(self, name: str) -> BaseAssetProvider:
+        """Resolve asset provider, falling back to mock provider for offline resilience."""
+        return self.providers.get(name.lower(), self.providers["mock"])
+
+    def _get_assets_dir(self) -> Path:
+        """Return workspace assets directory."""
+        workspace = get_default_allowed_roots()[0]
+        assets_dir = workspace / "assets"
+        assets_dir.mkdir(parents=True, exist_ok=True)
+        return assets_dir
+
+    def _load_manifest(self) -> AssetManifest:
+        """Load manifest.json from workspace assets directory."""
+        manifest_file = self._get_assets_dir() / "manifest.json"
+        if manifest_file.exists():
+            try:
+                data = json.loads(manifest_file.read_text(encoding="utf-8"))
+                return AssetManifest.model_validate(data)
+            except Exception:
+                pass
+        return AssetManifest()
+
+    def _save_manifest(self, manifest: AssetManifest) -> None:
+        """Save updated manifest.json and regenerate ATTRIBUTION.md."""
+        assets_dir = self._get_assets_dir()
+        manifest_file = assets_dir / "manifest.json"
+        manifest_file.write_text(json.dumps(manifest.model_dump(), indent=2), encoding="utf-8")
+
+        attribution_file = assets_dir / "ATTRIBUTION.md"
+        attribution_file.write_text(manifest.generate_attribution_md(), encoding="utf-8")
+
+    async def search(
+        self,
+        query: str,
+        provider: str = "openverse",
+        license_type: str | None = None,
+        page: int = 1,
+    ) -> list[dict[str, Any]]:
+        """Search provider for media assets returning token-efficient text descriptors."""
+        prov = self.get_provider(provider)
+        return await prov.search(query=query, license_type=license_type, page=page)
+
+    async def preview(
+        self,
+        asset_id: str,
+        provider: str = "openverse",
+    ) -> dict[str, Any]:
+        """Fetch small thumbnail preview image as base64."""
+        prov = self.get_provider(provider)
+        raw_bytes = await prov.fetch_preview(asset_id)
+        if not raw_bytes:
+            return {"success": False, "error": f"Preview unavailable for asset '{asset_id}'"}
+
+        return {
+            "success": True,
+            "asset_id": asset_id,
+            "thumbnail_base64": base64.b64encode(raw_bytes).decode("utf-8"),
+        }
+
+    async def download_asset(
+        self,
+        asset_id: str,
+        provider: str = "openverse",
+    ) -> dict[str, Any]:
+        """
+        Download, validate, sanitize, hash, and record external asset.
+        """
+        prov = self.get_provider(provider)
+        meta = await prov.get_details(asset_id)
+        if not meta:
+            return {"success": False, "error": f"Asset '{asset_id}' not found."}
+
+        # 1. License Policy evaluation
+        allowed, reason = self.policy.evaluate_license(meta.license_code)
+        if not allowed:
+            return {
+                "success": False,
+                "error": f"License check failed: {reason}",
+                "license_code": meta.license_code,
+            }
+
+        # 2. SSRF URL validation
+        validate_asset_url(meta.download_url)
+
+        # 3. Download bytes with limits
+        req = urllib.request.Request(meta.download_url, headers={"User-Agent": "SynfigMCP/0.8.0"})
+        with urllib.request.urlopen(req, timeout=15.0) as resp:
+            content_bytes = resp.read(25 * 1024 * 1024)  # 25 MB max download ceiling
+
+        assets_dir = self._get_assets_dir()
+        is_svg = b"<svg" in content_bytes[:2048].lower()
+
+        ext = ".svg" if is_svg else ".png"
+        clean_filename = f"{meta.id}{ext}"
+        target_path = assets_dir / clean_filename
+
+        # 4. Content sanitization and hardening
+        if is_svg:
+            sanitized_xml = sanitize_svg(content_bytes)
+            target_path.write_text(sanitized_xml, encoding="utf-8")
+        else:
+            temp_raw = assets_dir / f"tmp_{meta.id}"
+            temp_raw.write_bytes(content_bytes)
+            try:
+                harden_raster_image(temp_raw, target_path)
+            finally:
+                if temp_raw.exists():
+                    temp_raw.unlink()
+
+        # 5. Cryptographic SHA-256 hash & Provenance record
+        final_bytes = target_path.read_bytes()
+        sha256_hash = hashlib.sha256(final_bytes).hexdigest()
+
+        meta.sha256 = sha256_hash
+        meta.local_path = str(target_path)
+        meta.filesize_bytes = len(final_bytes)
+
+        manifest = self._load_manifest()
+        # Update or append
+        manifest.assets = [a for a in manifest.assets if a.id != meta.id]
+        manifest.assets.append(meta)
+        self._save_manifest(manifest)
+
+        return {
+            "success": True,
+            "asset_id": meta.id,
+            "title": meta.title,
+            "license": meta.license_code,
+            "local_path": str(target_path),
+            "sha256": sha256_hash,
+            "attribution": meta.attribution_text,
+        }
+
+    async def import_local_asset(
+        self,
+        file_path: str,
+        rights: str,
+        title: str,
+        creator: str,
+        license_code: str = "own",
+    ) -> dict[str, Any]:
+        """
+        Import local asset with mandatory rights declaration in {own, licensed, cc0, public-domain}.
+        """
+        valid_rights = {"own", "licensed", "cc0", "public-domain"}
+        declared = rights.lower().strip()
+        if declared not in valid_rights:
+            return {
+                "success": False,
+                "error": f"Invalid rights declaration '{rights}'. Must be one of: {sorted(valid_rights)}",
+            }
+
+        p = Path(file_path)
+        if not p.exists():
+            return {"success": False, "error": f"File '{file_path}' does not exist."}
+
+        raw_bytes = p.read_bytes()
+        sha256_hash = hashlib.sha256(raw_bytes).hexdigest()
+        asset_id = f"local_{sha256_hash[:10]}"
+
+        meta = AssetMetadata(
+            id=asset_id,
+            provider="local",
+            title=title or p.name,
+            creator=creator or "Local User",
+            license_code=license_code,
+            rights_declaration=declared,
+            download_url="local://workspace",
+            sha256=sha256_hash,
+            local_path=str(p.resolve()),
+            filesize_bytes=len(raw_bytes),
+        )
+
+        manifest = self._load_manifest()
+        manifest.assets = [a for a in manifest.assets if a.id != meta.id]
+        manifest.assets.append(meta)
+        self._save_manifest(manifest)
+
+        return {
+            "success": True,
+            "asset_id": asset_id,
+            "rights": declared,
+            "sha256": sha256_hash,
+            "local_path": str(p.resolve()),
+        }

synfig_mcp/assets/providers/base.py

@@ -0,0 +1,37 @@
+"""
+Abstract base class for Asset Provider adapters (Phase A5).
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from synfig_mcp.assets.models import AssetMetadata
+
+
+class BaseAssetProvider(ABC):
+    """Abstract interface for external media and asset providers."""
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Provider identifier."""
+
+    @abstractmethod
+    async def search(
+        self,
+        query: str,
+        license_type: str | None = None,
+        page: int = 1,
+        page_size: int = 10,
+    ) -> list[dict[str, Any]]:
+        """Search provider for media assets, returning compact text descriptors."""
+
+    @abstractmethod
+    async def get_details(self, asset_id: str) -> AssetMetadata | None:
+        """Fetch complete licensing and provenance details for an asset."""
+
+    @abstractmethod
+    async def fetch_preview(self, asset_id: str) -> bytes | None:
+        """Fetch small thumbnail image bytes for LLM preview."""

synfig_mcp/assets/providers/mock_provider.py

@@ -0,0 +1,103 @@
+"""
+Offline Mock Asset Provider: Serves deterministic licensed fixtures for air-gapped CI and testing.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from synfig_mcp.assets.models import AssetMetadata
+from synfig_mcp.assets.providers.base import BaseAssetProvider
+
+# 1x1 valid PNG bytes
+MOCK_PNG_BYTES = (
+    b"\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\x01\x00\x00\x00\x01"
+    b"\x08\x06\x00\x00\x00\x1f\x15\xc4\x89\x00\x00\x00\rIDATx\x9cc\xf8\xcf"
+    b"\xc0\xf0\x1f\x00\x05\x00\x01\xff\x89\x99=\x1d\x00\x00\x00\x00IEND\xaeB`\x82"
+)
+
+MOCK_FIXTURES: dict[str, dict[str, Any]] = {
+    "mock_cloud_01": {
+        "id": "mock_cloud_01",
+        "provider": "mock",
+        "title": "Stylized Vector Cloud",
+        "creator": "OpenArtist",
+        "license_code": "cc0",
+        "license_url": "https://creativecommons.org/publicdomain/zero/1.0/",
+        "attribution_text": "Stylized Vector Cloud by OpenArtist is dedicated to the public domain via CC0 1.0.",
+        "download_url": "https://raw.githubusercontent.com/synfig/assets/cloud.png",
+        "thumbnail_url": "https://raw.githubusercontent.com/synfig/assets/cloud_thumb.png",
+        "filesize_bytes": len(MOCK_PNG_BYTES),
+        "mature": False,
+    },
+    "mock_tree_02": {
+        "id": "mock_tree_02",
+        "provider": "mock",
+        "title": "Silhouette Pine Tree",
+        "creator": "CommonsUser",
+        "license_code": "by",
+        "license_url": "https://creativecommons.org/licenses/by/4.0/",
+        "attribution_text": "Silhouette Pine Tree by CommonsUser, used under CC BY 4.0.",
+        "download_url": "https://raw.githubusercontent.com/synfig/assets/tree.png",
+        "thumbnail_url": "https://raw.githubusercontent.com/synfig/assets/tree_thumb.png",
+        "filesize_bytes": len(MOCK_PNG_BYTES),
+        "mature": False,
+    },
+    "mock_nd_restricted": {
+        "id": "mock_nd_restricted",
+        "provider": "mock",
+        "title": "Restricted Photo",
+        "creator": "StrictPhotographer",
+        "license_code": "by-nd",
+        "license_url": "https://creativecommons.org/licenses/by-nd/4.0/",
+        "attribution_text": "Restricted Photo by StrictPhotographer (CC BY-ND 4.0)",
+        "download_url": "https://raw.githubusercontent.com/synfig/assets/photo.png",
+        "filesize_bytes": len(MOCK_PNG_BYTES),
+        "mature": False,
+    },
+}
+
+
+class MockAssetProvider(BaseAssetProvider):
+    """In-memory fixture provider for testing license filtering and pipeline execution."""
+
+    @property
+    def name(self) -> str:
+        return "mock"
+
+    async def search(
+        self,
+        query: str,
+        license_type: str | None = None,
+        page: int = 1,
+        page_size: int = 10,
+    ) -> list[dict[str, Any]]:
+        del page, page_size
+        results: list[dict[str, Any]] = []
+        q = query.lower()
+
+        for f in MOCK_FIXTURES.values():
+            if q in f["title"].lower() or q in f["id"].lower():
+                if license_type and f["license_code"] != license_type.lower():
+                    continue
+                results.append(
+                    {
+                        "id": f["id"],
+                        "title": f["title"],
+                        "creator": f["creator"],
+                        "license": f["license_code"],
+                        "provider": self.name,
+                    }
+                )
+        return results
+
+    async def get_details(self, asset_id: str) -> AssetMetadata | None:
+        raw = MOCK_FIXTURES.get(asset_id)
+        if not raw:
+            return None
+        return AssetMetadata(**raw)
+
+    async def fetch_preview(self, asset_id: str) -> bytes | None:
+        if asset_id in MOCK_FIXTURES:
+            return MOCK_PNG_BYTES
+        return None

synfig_mcp/assets/providers/openverse.py

@@ -0,0 +1,108 @@
+"""
+Openverse API Provider Adapter (Phase A5).
+Searches CC-licensed media via https://api.openverse.org/v1/images/.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.parse
+import urllib.request
+from typing import Any
+
+from synfig_mcp.assets.models import AssetMetadata
+from synfig_mcp.assets.providers.base import BaseAssetProvider
+from synfig_mcp.assets.security.url_validator import validate_asset_url
+
+OPENVERSE_API_URL = "https://api.openverse.org/v1/images/"
+
+
+class OpenverseAssetProvider(BaseAssetProvider):
+    """Adapter for searching and retrieving open-licensed assets from Openverse."""
+
+    @property
+    def name(self) -> str:
+        return "openverse"
+
+    async def search(
+        self,
+        query: str,
+        license_type: str | None = None,
+        page: int = 1,
+        page_size: int = 10,
+    ) -> list[dict[str, Any]]:
+        params = {
+            "q": query,
+            "page": str(page),
+            "page_size": str(min(page_size, 20)),
+        }
+        if license_type:
+            params["license"] = license_type.lower()
+
+        url = f"{OPENVERSE_API_URL}?{urllib.parse.urlencode(params)}"
+        validate_asset_url(url)
+
+        req = urllib.request.Request(
+            url, headers={"User-Agent": "SynfigMCP/0.8.0 (Studio-Grade Animation)"}
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=10.0) as resp:
+                data = json.loads(resp.read().decode("utf-8"))
+        except Exception:
+            return []
+
+        results: list[dict[str, Any]] = []
+        for item in data.get("results", []):
+            results.append(
+                {
+                    "id": f"ov_{item.get('id', '')}",
+                    "title": item.get("title", "Untitled"),
+                    "creator": item.get("creator", "Unknown"),
+                    "license": item.get("license", "unknown"),
+                    "provider": self.name,
+                    "filesize": item.get("filesize", 0),
+                }
+            )
+        return results
+
+    async def get_details(self, asset_id: str) -> AssetMetadata | None:
+        clean_id = asset_id.replace("ov_", "")
+        url = f"{OPENVERSE_API_URL}{clean_id}/"
+        validate_asset_url(url)
+
+        req = urllib.request.Request(
+            url, headers={"User-Agent": "SynfigMCP/0.8.0 (Studio-Grade Animation)"}
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=10.0) as resp:
+                data = json.loads(resp.read().decode("utf-8"))
+        except Exception:
+            return None
+
+        return AssetMetadata(
+            id=asset_id,
+            provider=self.name,
+            title=data.get("title", "Untitled"),
+            creator=data.get("creator", "Unknown"),
+            license_code=data.get("license", "unknown"),
+            license_url=data.get("license_url", ""),
+            attribution_text=data.get("attribution", ""),
+            download_url=data.get("url", ""),
+            thumbnail_url=data.get("thumbnail", None),
+            filesize_bytes=data.get("filesize", 0),
+            mature=bool(data.get("mature", False)),
+        )
+
+    async def fetch_preview(self, asset_id: str) -> bytes | None:
+        meta = await self.get_details(asset_id)
+        if not meta or not meta.thumbnail_url:
+            return None
+
+        validate_asset_url(meta.thumbnail_url)
+        req = urllib.request.Request(meta.thumbnail_url, headers={"User-Agent": "SynfigMCP/0.8.0"})
+        try:
+            with urllib.request.urlopen(req, timeout=10.0) as resp:
+                data = resp.read()
+                return bytes(data) if isinstance(data, (bytes, bytearray)) else None
+        except Exception:
+            return None