spritehatch-mcp 0.1.0__py3-none-any.whl

spritehatch_mcp/__init__.py

@@ -0,0 +1,2 @@
+"""SpriteHatch MCP server: lets AI agents generate 2D game assets with SpriteHatch and bring them into the game."""
+__version__ = '0.1.0'

spritehatch_mcp/__main__.py

@@ -0,0 +1,26 @@
+"""spritehatch-mcp            → local server over stdio (Claude Code, Cursor, Codex…); needs SPRITEHATCH_API_KEY.
+spritehatch-mcp --http     → hosted server (streamable HTTP); each request brings its key in the Authorization header."""
+import argparse
+import os
+
+from .server import Config, build
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog='spritehatch-mcp', description='SpriteHatch MCP server')
+    parser.add_argument('--http', action='store_true', help='serve over streamable HTTP (hosted mode) instead of stdio')
+    parser.add_argument('--host', default=os.environ.get('SPRITEHATCH_MCP_HOST', '127.0.0.1'))
+    parser.add_argument('--port', type=int, default=int(os.environ.get('SPRITEHATCH_MCP_PORT', '7870')))
+    args = parser.parse_args()
+    if args.http:
+        config = Config.from_env('hosted')
+        build(config).run('streamable-http', host=args.host, port=args.port, streamable_http_path='/mcp')
+    else:
+        config = Config.from_env('local')
+        if not config.api_key:
+            parser.exit(2, 'SPRITEHATCH_API_KEY is not set. Create a key in SpriteHatch > My account > API keys.\n')
+        build(config).run('stdio')
+
+
+if __name__ == '__main__':
+    main()

spritehatch_mcp/api.py

@@ -0,0 +1,84 @@
+"""Async client for the SpriteHatch HTTP API (the same API documented at /docs/api).
+
+Every call carries the customer's API key (`Authorization: Bearer sg_live_…`), so ownership, plan limits (API = Pro and
+Studio) and credit charging stay where they already are: in the SpriteHatch server. This module only translates HTTP
+failures into errors an agent can act on.
+"""
+from __future__ import annotations
+
+import httpx2 as httpx   # the HTTP client the MCP SDK already ships (httpx fork)
+
+# HTTP status → stable code + what the agent should do. The server's `detail` text is still in Portuguese.
+ERRORS = {
+    0: ('unreachable', 'Could not reach SpriteHatch. Check SPRITEHATCH_URL and the network, then try again.'),
+    400: ('invalid_request', 'The request was rejected; fix the arguments described in `detail`.'),
+    401: ('invalid_api_key', 'The API key is missing, wrong or deleted. The user creates one in SpriteHatch > My account > '
+                             'API keys and sets SPRITEHATCH_API_KEY (local) or the Authorization header (hosted).'),
+    402: ('insufficient_credits', 'Not enough credits. Tell the user the cost and balance; do not retry.'),
+    403: ('not_allowed', 'The plan does not include the API/MCP (Pro and Studio do), or this action needs the web app.'),
+    404: ('not_found', 'The asset, project or job does not exist or belongs to another account. Use list_assets / list_projects.'),
+    409: ('busy_or_changed', 'The asset is not ready yet, another generation on the same animation is running, or the '
+                            'version changed. Call wait_for_jobs, then try again.'),
+    422: ('invalid_request', 'Some argument has the wrong type or is out of range.'),
+    502: ('upstream_error', 'A payment/upstream service failed. Try again later.'),
+    504: ('timeout', 'SpriteHatch took too long to answer. Try again; generation jobs keep running on the server.'),
+    503: ('service_unavailable', 'A SpriteHatch service (vision planner or judge) is temporarily unavailable. Try again later.'),
+}
+
+
+class ApiError(Exception):
+    def __init__(self, status: int, detail: str):
+        self.status = status
+        self.detail = detail
+        self.code, self.hint = ERRORS.get(status, ('server_error', 'Unexpected server error. Try again later.'))
+        super().__init__(f'{self.code} ({status}): {detail}')
+
+    def as_dict(self) -> dict:
+        return {'error': self.code, 'status': self.status, 'detail': self.detail, 'what_to_do': self.hint}
+
+
+class Api:
+    def __init__(self, base_url: str, key: str, timeout: float = 60.0):
+        if not key:
+            raise ApiError(401, 'Nenhuma chave de API configurada.')
+        self.base_url = base_url.rstrip('/')
+        self._client = httpx.AsyncClient(base_url=self.base_url, timeout=timeout, follow_redirects=True,
+                                         headers={'Authorization': f'Bearer {key}', 'User-Agent': 'spritehatch-mcp'})
+
+    async def __aenter__(self) -> Api:
+        return self
+
+    async def __aexit__(self, *_) -> None:
+        await self._client.aclose()
+
+    async def _send(self, method: str, path: str, **kwargs) -> httpx.Response:
+        try:
+            response = await self._client.request(method, path, **kwargs)
+        except httpx.TimeoutException:
+            raise ApiError(504, 'O servidor demorou para responder.')
+        except httpx.HTTPError as error:
+            raise ApiError(0, f'Não foi possível falar com o SpriteHatch em {self.base_url}: {error}')
+        if response.status_code >= 400:
+            try:
+                detail = response.json().get('detail')
+            except ValueError:
+                detail = None
+            if not isinstance(detail, str):
+                detail = str(detail or response.text[:300] or response.reason_phrase)
+            raise ApiError(response.status_code, detail)
+        return response
+
+    async def get(self, path: str, **params):
+        return (await self._send('GET', path, params={k: v for k, v in params.items() if v is not None})).json()
+
+    async def post(self, path: str, body: dict | None = None, *, data: dict | None = None, files: dict | None = None):
+        if files is not None:
+            return (await self._send('POST', path, data=data or {}, files=files)).json()
+        return (await self._send('POST', path, json=body or {})).json()
+
+    async def patch(self, path: str, body: dict):
+        return (await self._send('PATCH', path, json=body)).json()
+
+    async def get_bytes(self, path: str, **params) -> tuple[bytes, httpx.Headers]:
+        response = await self._send('GET', path, params={k: v for k, v in params.items() if v is not None})
+        return response.content, response.headers

spritehatch_mcp/files.py

@@ -0,0 +1,185 @@
+"""Files in and out: reference images the agent passes, and exports it takes home.
+
+Local (stdio) mode reads images from disk and unpacks exports into the game project. Hosted mode cannot touch the
+agent's disk, so it accepts URLs/base64 and serves each export from a short-lived link.
+"""
+from __future__ import annotations
+
+import asyncio
+import base64
+import binascii
+import io
+import ipaddress
+import json
+import re
+import secrets
+import socket
+import time
+import zipfile
+from pathlib import Path
+from urllib.parse import urlparse
+
+import httpx2 as httpx   # the HTTP client the MCP SDK already ships (httpx fork)
+
+MAX_IMAGE = 15 * 1024 * 1024
+LINK_TTL = 30 * 60
+
+
+async def load_image(ref: str, allow_paths: bool) -> tuple[str, bytes]:
+    """`ref` is a local path (local mode only), an http(s) URL, a data URL or raw base64 → (filename, bytes)."""
+    ref = ref.strip()
+    if ref.startswith(('http://', 'https://')):
+        if not allow_paths:   # hosted: never fetch the server's own network (SSRF); redirects are checked hop by hop
+            await _public_only(ref)
+        async with httpx.AsyncClient(timeout=30, follow_redirects=allow_paths) as client:
+            response = await client.get(ref)
+            hops = 0
+            while not allow_paths and response.is_redirect and hops < 3:
+                ref = str(response.next_request.url) if response.next_request else ''
+                await _public_only(ref)
+                response = await client.get(ref)
+                hops += 1
+        if response.status_code >= 400:
+            raise ValueError(f'Could not download the reference image ({response.status_code}).')
+        data, name = response.content, Path(ref.split('?')[0]).name or 'reference.png'
+    elif ref.startswith('data:'):
+        data, name = _b64(ref.split(',', 1)[-1]), 'reference.png'
+    elif allow_paths and (Path(ref).expanduser().exists()):
+        path = Path(ref).expanduser()
+        data, name = path.read_bytes(), path.name
+    elif re.fullmatch(r'[A-Za-z0-9+/=\s]{200,}', ref):
+        data, name = _b64(ref), 'reference.png'
+    elif allow_paths:
+        raise ValueError(f'Reference image not found: {ref}')
+    else:
+        raise ValueError('The hosted server cannot read local files: pass the image as an https URL or base64/data URL.')
+    if len(data) > MAX_IMAGE:
+        raise ValueError('The reference image is larger than 15 MB.')
+    return name, data
+
+
+async def _public_only(url: str) -> None:
+    host = urlparse(url).hostname
+    if not host:
+        raise ValueError('Invalid image URL.')
+    try:
+        infos = await asyncio.get_running_loop().getaddrinfo(host, None)
+    except socket.gaierror:
+        raise ValueError(f'Could not resolve {host}.')
+    for info in infos:
+        address = ipaddress.ip_address(info[4][0])
+        if not address.is_global:
+            raise ValueError('The image URL must be a public address.')
+
+
+def _b64(text: str) -> bytes:
+    try:
+        return base64.b64decode(re.sub(r'\s+', '', text), validate=True)
+    except (binascii.Error, ValueError):
+        raise ValueError('The reference image is not valid base64.')
+
+
+def manifest(zip_bytes: bytes, target: str) -> dict:
+    """What the agent needs to wire the export into code, read from the files inside the zip."""
+    out: dict = {'files': [], 'clips': {}, 'notes': []}
+    with zipfile.ZipFile(io.BytesIO(zip_bytes)) as archive:
+        names = [n for n in archive.namelist() if not n.endswith('/')]
+        out['files'] = names[:60] + ([f'... {len(names) - 60} more'] if len(names) > 60 else [])
+        for name in names:
+            if not name.endswith('.json'):
+                continue
+            try:
+                data = json.loads(archive.read(name))
+            except ValueError:
+                continue
+            if not isinstance(data, dict):
+                continue
+            meta = data.get('meta') if isinstance(data.get('meta'), dict) else None
+            if meta and 'clips' in meta:   # character atlas (TexturePacker hash + clips)
+                out['atlas'] = name
+                out['image'] = meta.get('image')
+                out['cell'] = meta.get('cell')
+                out['pixel_art'] = bool(meta.get('pixel'))
+                out['clips'] = {k: {f: v.get(f) for f in ('animation', 'direction', 'fps', 'loop', 'frames')}
+                                for k, v in meta['clips'].items()}
+            elif str(data.get('schema', '')).startswith('sprite-ability'):
+                out['ability'] = {k: data.get(k) for k in (
+                    'schema', 'name', 'mode', 'gesture', 'effects', 'anchors', 'release', 'speed', 'speed_units', 'effect_scale',
+                    'effect_scale_units', 'emission_lead_ms', 'emission_fade_ms', 'projectile_grow_ms', 'stream_duration_ms',
+                    'projectile_facing', 'anchor_space', 'target_height', 'cell') if data.get(k) is not None}
+                out['ability_file'] = name
+            elif 'frames' in data and 'blend' in data:   # standalone effect
+                out['effect'] = {k: data.get(k) for k in ('name', 'frame_size', 'fps', 'loop', 'blend', 'pivot')}
+                out['effect']['frame_count'] = len(data.get('frames') or [])
+            elif name.endswith('tiles.json') or 'tiles' in data:
+                out['tileset'] = {k: data.get(k) for k in ('tile', 'tile_size', 'mode', 'columns', 'order', 'bits') if k in data}
+            elif 'layers' in data:
+                out['scene'] = {'layers': data.get('layers')}
+        for doc in ('COMPOSITION.txt', 'README.txt', 'STREAM.txt'):
+            hit = next((n for n in names if n.endswith(doc)), None)
+            if hit:
+                out['notes'].append({'file': hit, 'text': archive.read(hit).decode('utf-8', 'replace')[:1800]})
+    out['how_to_use'] = HOW_TO.get(target, HOW_TO['atlas'])
+    if 'ability' in out:
+        out['how_to_use'] += ' ' + HOW_TO['ability']
+    return out
+
+
+HOW_TO = {
+    'godot': 'Godot 4: the .tres is a SpriteFrames resource; assign it to an AnimatedSprite2D and play("<animation>_<direction>"). '
+             'Offset the sprite so the pivot (cell.pivot, at the feet) sits on the node origin.',
+    'unity': 'Unity: copy the folder into Assets/. The Editor/SpriteGeneratorImporter.cs script slices the sheet with the foot '
+             'pivot and creates one AnimationClip per row (looping clips have loopTime on). Point filtering for pixel art.',
+    'gamemaker': 'GameMaker: import each spr_*_stripN.png with "Import Strip Image"; N is the frame count. Set the origin '
+                 'to the pivot from the atlas JSON.',
+    'rpgmaker': 'RPG Maker: copy $<name>.png into img/characters (3×4 walk sheet).',
+    'atlas': 'Generic: <name>.png + <name>.json (TexturePacker hash). meta.clips lists every animation_direction with fps, '
+             'loop and frame names; every frame has the same cell size and a normalized pivot at the feet.',
+    'strips': 'One horizontal PNG strip per animation_direction; frame width = cell.width.',
+    'frames': 'One PNG per frame, in folders per animation_direction.',
+    'gif': 'GIF previews only (not for the game).',
+    'ability': 'Ability: play the gesture; start the emission effect emission_lead_ms before gesture.release_frame at the '
+               'anchor for the current direction (normalized in the gesture cell); at the release frame spawn the '
+               'projectile (or stream) at effect_scale × target_height and move it at speed × target_height px/s facing '
+               'right (mirror for W); on hit play impact once. Collision and damage are game code. See COMPOSITION.txt.',
+}
+
+
+class LinkStore:
+    """Hosted mode: exports are kept in memory for 30 minutes behind an unguessable link."""
+
+    def __init__(self):
+        self._files: dict[str, tuple[str, bytes, float]] = {}
+
+    def put(self, filename: str, data: bytes) -> str:
+        now = time.time()
+        self._files = {k: v for k, v in self._files.items() if v[2] > now}
+        while sum(len(v[1]) for v in self._files.values()) + len(data) > 256 * 1024 * 1024 and self._files:
+            self._files.pop(next(iter(self._files)))
+        token = secrets.token_urlsafe(24)
+        self._files[token] = (filename, data, now + LINK_TTL)
+        return token
+
+    def get(self, token: str) -> tuple[str, bytes] | None:
+        item = self._files.get(token)
+        if not item or item[2] < time.time():
+            return None
+        return item[0], item[1]
+
+
+def unpack(zip_bytes: bytes, dest: Path) -> list[str]:
+    dest.mkdir(parents=True, exist_ok=True)
+    root = dest.resolve()
+    written = []
+    with zipfile.ZipFile(io.BytesIO(zip_bytes)) as archive:
+        for member in archive.infolist():
+            target = (dest / member.filename).resolve()
+            if not target.is_relative_to(root):   # zip slip
+                continue
+            if member.is_dir():
+                target.mkdir(parents=True, exist_ok=True)
+                continue
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_bytes(archive.read(member))
+            written.append(str(target))
+    return written

spritehatch_mcp/guards.py

@@ -0,0 +1,139 @@
+"""Spending guardrails for one MCP session (user decision, 2026-10-21: session budget + confirmation above a limit).
+
+- `budget`: credits this session may spend in total. Refunded jobs (failures) give the credits back.
+- `confirm_above`: spending more than this WITHOUT the user's approval needs it. The count is cumulative since the last
+  approval, so splitting a big request into small ones does not get around it. Approval comes through MCP elicitation
+  (the client shows a yes/no to the human) or a one-time `confirm_token` that the agent only sends after asking the user.
+  An elicitation that is declined or cancelled is not treated as the user's answer: some clients decline automatically
+  without showing anything, so the agent is told to ask in the conversation instead.
+- `auto_improvements`: how many paid "improve" rounds an agent may run on one animation before it must show the result
+  to the user. Keeps an agent from looping regenerations on its own.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import secrets
+import time
+from dataclasses import dataclass, field
+
+TOKEN_TTL = 15 * 60
+MAX_FAILURES = 2
+
+
+@dataclass
+class Session:
+    budget: int
+    confirm_above: int
+    auto_improvements: int = 1
+    spent: int = 0
+    unapproved: int = 0                                         # credits spent since the user's last approval
+    jobs: dict[str, int] = field(default_factory=dict)          # job id → credits charged (to return refunds)
+    requests: dict[str, str] = field(default_factory=dict)      # job id → fingerprint of the request that made it
+    failures: dict[str, int] = field(default_factory=dict)      # request fingerprint → failed jobs
+    settled: set[str] = field(default_factory=set)
+    pending: dict[str, tuple[str, int, float]] = field(default_factory=dict)   # token → (fingerprint, cost, expires)
+    improvements: dict[str, int] = field(default_factory=dict)  # "asset/animation" → paid improve rounds
+    plans: dict[str, dict] = field(default_factory=dict)        # plan id → animation plan from plan_animation
+    seen: float = field(default_factory=time.time)
+
+    @property
+    def remaining(self) -> int:
+        return max(0, self.budget - self.spent)
+
+    def view(self) -> dict:
+        return {'budget': self.budget, 'spent': self.spent, 'remaining': self.remaining, 'confirm_above': self.confirm_above,
+                'spent_since_last_approval': self.unapproved}
+
+    def record(self, jobs: list[dict], tool: str = '', args: dict | None = None) -> None:
+        request = fingerprint(tool, args or {}) if tool else ''
+        for job in jobs:
+            if job and job.get('id') and job['id'] not in self.jobs:
+                cost = int(job.get('cost') or 0)
+                self.jobs[job['id']] = cost
+                self.requests[job['id']] = request
+                self.spent += cost
+
+    def settle(self, job: dict) -> None:
+        """Count each finished job once: a failure counts against its request, and a refund goes back to the budget."""
+        jid = job.get('id')
+        if job.get('status') not in ('done', 'error') or jid in self.settled:
+            return
+        self.settled.add(jid)
+        if job['status'] == 'error' and self.requests.get(jid):
+            self.failures[self.requests[jid]] = self.failures.get(self.requests[jid], 0) + 1
+        if jid in self.jobs and (job.get('refunded') or job.get('partial_refund')):
+            self.spent = max(0, self.spent - (self.jobs[jid] if job.get('refunded') else int(job.get('partial_refund') or 0)))
+
+    def check(self, tool: str, args: dict, cost: int, token: str | None) -> dict | None:
+        """None = go ahead. Otherwise the dict explains why not (budget) or asks for approval (confirmation)."""
+        if self.failures.get(fingerprint(tool, args), 0) >= MAX_FAILURES:
+            return {'status': 'stop_failing', 'message': f'This exact request already failed {MAX_FAILURES} times in this session '
+                    '(the credits were refunded). Do not retry it: tell the user what failed, or change the request.'}
+        if cost <= 0:
+            return None
+        if cost > self.remaining:
+            return {'status': 'budget_exceeded', 'cost': cost, 'session': self.view(),
+                    'message': f'This request costs {cost} credits but only {self.remaining} remain in this session budget. '
+                               'Do not split it into smaller requests to get around the budget. Tell the user; only they can '
+                               'raise the budget (SPRITEHATCH_BUDGET locally, X-SpriteHatch-Budget header when hosted).'}
+        if self.unapproved + cost <= self.confirm_above:
+            self.unapproved += cost
+            return None
+        wanted = fingerprint(tool, args)
+        now = time.time()
+        self.pending = {t: v for t, v in self.pending.items() if v[2] > now}
+        if token and token in self.pending and self.pending[token][0] == wanted:
+            del self.pending[token]
+            self.approved()
+            return None
+        token = secrets.token_urlsafe(9)
+        self.pending[token] = (wanted, cost, now + TOKEN_TTL)
+        since = f' ({self.unapproved} already spent since the last approval)' if self.unapproved else ''
+        return {'status': 'confirmation_required', 'cost': cost, 'session': self.view(), 'confirm_token': token,
+                'message': f'This request costs {cost} credits{since}, above the {self.confirm_above}-credit limit of spending '
+                           'without the user\'s approval. Ask the user in the conversation (say what will be generated and the '
+                           'cost). Only if they approve, call the same tool again with the same arguments plus confirm_token '
+                           '(expires in 15 minutes). If they refuse, do not retry it, and never split it into smaller requests: '
+                           'the limit counts everything spent since the last approval.'}
+
+    def approved(self) -> None:
+        """The user approved this request: spending without approval starts counting again from zero."""
+        self.unapproved = 0
+
+    def may_improve(self, asset: str, animation: str) -> bool:
+        return self.improvements.get(f'{asset}/{animation}', 0) < self.auto_improvements
+
+    def improved(self, asset: str, animation: str) -> None:
+        key = f'{asset}/{animation}'
+        self.improvements[key] = self.improvements.get(key, 0) + 1
+
+
+def fingerprint(tool: str, args: dict) -> str:
+    clean = {k: v for k, v in args.items() if k not in ('confirm_token', 'ctx') and v is not None}
+    return hashlib.sha256(f'{tool}:{json.dumps(clean, sort_keys=True, default=str)}'.encode()).hexdigest()
+
+
+class Sessions:
+    """Local mode has one session (the process). Hosted mode keys sessions by MCP session id (or API key) and forgets
+    idle ones after a day."""
+
+    def __init__(self, budget: int, confirm_above: int, auto_improvements: int = 1):
+        self.defaults = (budget, confirm_above, auto_improvements)
+        self._all: dict[str, Session] = {}
+
+    def get(self, key: str, budget: int | None = None, confirm_above: int | None = None) -> Session:
+        now = time.time()
+        if len(self._all) > 500:
+            self._all = {k: s for k, s in self._all.items() if now - s.seen < 86400}
+        session = self._all.get(key)
+        if session is None:
+            b, c, a = self.defaults
+            session = self._all[key] = Session(b, c, a)
+        # hosted clients send their limits on every request; the latest ones win (connections may share a session)
+        if budget is not None:
+            session.budget = budget
+        if confirm_above is not None:
+            session.confirm_above = confirm_above
+        session.seen = now
+        return session