@mmerterden/multi-agent-pipeline 11.1.0 → 11.3.0

package/pipeline/skills/figma-common/figma-utility/scripts/figma-utility.py

@@ -1,808 +0,0 @@
-#!/usr/bin/env python3
-"""
-Figma Utility Script
-Standalone tool for querying Figma data via REST API and MCP.
-
-Usage:
-    python3 figma-utility.py <command> [options]
-
-Commands:
-    screenshot   --url <figma-url> [--output path] [--scale 1|2|3|4]
-    metadata     --url <figma-url> [--output path]
-    properties   --url <figma-url> [--output path]
-    tokens       --url <figma-url> [--output path]
-    context      --url <figma-url> [--output path]
-    code-connect --url <figma-url> [--output path]
-    node         --url <figma-url> [--output path] [--depth N]
-    components   --url <figma-url> [--output path]
-    styles       --url <figma-url> [--output path]
-    file         --url <figma-url> [--output path] [--depth N]
-    whoami
-
-Token resolution: --figma-token / --mcp-token CLI arg > macOS Keychain > Claude Code credentials
-
-Exit 0 = success (prints result to stdout)
-Exit 1 = failure (prints JSON error to stderr)
-"""
-
-import argparse
-import base64
-import http.client
-import json
-import os
-import re
-import subprocess
-import sys
-from pathlib import Path
-from urllib.error import HTTPError, URLError
-from urllib.parse import urlparse
-from urllib.request import Request, urlopen
-
-
-# ─── Globals ─────────────────────────────────────────────────────────────────
-
-MCP_MODE = None       # "remote" or "local"
-MCP_URL = "http://127.0.0.1:3845/mcp"
-MCP_TOKEN = None
-SESSION_ID = None
-FIGMA_TOKEN = None
-
-
-def log(msg):
-    print(f"[figma-utility] {msg}", file=sys.stderr)
-
-
-def error_exit(code, message, hint=""):
-    print(json.dumps({
-        "status": "error",
-        "message": message,
-        "hint": hint,
-    }, indent=2), file=sys.stderr)
-    sys.exit(code)
-
-
-# ─── URL Parsing ─────────────────────────────────────────────────────────────
-
-def parse_figma_url(url):
-    """Extract fileKey and nodeId from a Figma URL.
-
-    Returns (fileKey, nodeId) where nodeId uses colon format (e.g. '123:456').
-    nodeId may be None if not present in the URL.
-    """
-    if not url:
-        return None, None
-
-    # Match: figma.com/design/{fileKey}/... or figma.com/file/{fileKey}/...
-    m = re.search(r'figma\.com/(?:design|file)/([A-Za-z0-9]+)', url)
-    if not m:
-        # Try branch URL
-        m = re.search(r'figma\.com/(?:design|file)/[^/]+/[^?]*\?.*branch-id=([A-Za-z0-9]+)', url)
-    file_key = m.group(1) if m else None
-
-    # Extract node-id from query params
-    node_id = None
-    nm = re.search(r'node-id=([0-9]+-[0-9]+)', url)
-    if nm:
-        node_id = nm.group(1).replace("-", ":")
-    else:
-        nm = re.search(r'node-id=([0-9]+%3A[0-9]+)', url)
-        if nm:
-            node_id = nm.group(1).replace("%3A", ":")
-
-    return file_key, node_id
-
-
-# ─── Token Resolution ────────────────────────────────────────────────────────
-
-def get_figma_token(cli_token=None):
-    """Resolve Figma REST API token: CLI arg > Keychain FIGMA_ACCESS_TOKEN."""
-    if cli_token:
-        return cli_token
-    try:
-        token = subprocess.check_output(
-            ["security", "find-generic-password", "-a", os.environ["USER"],
-             "-s", "FIGMA_ACCESS_TOKEN", "-w"],
-            stderr=subprocess.DEVNULL,
-        ).decode().strip()
-        if token:
-            log("REST token from Keychain: FIGMA_ACCESS_TOKEN")
-            return token
-    except (subprocess.CalledProcessError, KeyError):
-        pass
-    return None
-
-
-def get_mcp_token(cli_token=None):
-    """Resolve MCP OAuth token: CLI arg > Keychain FIGMA_MCP_TOKEN > Claude Code credentials."""
-    if cli_token:
-        return cli_token
-    # Keychain: dedicated entry
-    try:
-        token = subprocess.check_output(
-            ["security", "find-generic-password", "-a", os.environ["USER"],
-             "-s", "FIGMA_MCP_TOKEN", "-w"],
-            stderr=subprocess.DEVNULL,
-        ).decode().strip()
-        if token:
-            log("MCP token from Keychain: FIGMA_MCP_TOKEN")
-            return token
-    except (subprocess.CalledProcessError, KeyError):
-        pass
-    # Keychain: extract from Claude Code credentials
-    try:
-        raw = subprocess.check_output(
-            ["security", "find-generic-password", "-s", "Claude Code-credentials",
-             "-a", os.environ["USER"], "-w"],
-            stderr=subprocess.DEVNULL,
-        ).decode()
-        match = re.search(
-            r'"figma-remote\|[^"]+":\{[^}]*"accessToken":"([^"]+)"', raw
-        )
-        if match:
-            log("MCP token extracted from Claude Code credentials")
-            return match.group(1)
-    except (subprocess.CalledProcessError, KeyError):
-        pass
-    return None
-
-
-# ─── REST API ────────────────────────────────────────────────────────────────
-
-def figma_get(endpoint):
-    """GET from Figma REST API. Returns parsed JSON."""
-    if not FIGMA_TOKEN:
-        error_exit(1, "No Figma REST API token found.",
-                   "Run /figma-setup or pass --figma-token.")
-    url = f"https://api.figma.com/v1/{endpoint}"
-    req = Request(url, headers={"X-Figma-Token": FIGMA_TOKEN})
-    try:
-        with urlopen(req, timeout=60) as resp:
-            return json.loads(resp.read().decode())
-    except HTTPError as e:
-        body = e.read().decode() if hasattr(e, 'read') else ""
-        error_exit(1, f"Figma API HTTP {e.code}: {body[:300]}",
-                   f"Endpoint: {endpoint}")
-    except URLError as e:
-        error_exit(1, f"Figma API connection error: {e.reason}",
-                   "Check your network connection.")
-
-
-def download_file(url, dest):
-    """Download a URL to a local file path."""
-    req = Request(url)
-    with urlopen(req, timeout=60) as resp:
-        Path(dest).parent.mkdir(parents=True, exist_ok=True)
-        with open(dest, "wb") as f:
-            f.write(resp.read())
-    return True
-
-
-# ─── MCP Helpers ─────────────────────────────────────────────────────────────
-
-def _parse_sse_json(raw):
-    """Parse JSON from SSE response. Handles multiline data payloads."""
-    data_start = raw.find("\ndata: ")
-    if data_start == -1:
-        data_start = raw.find("data: ")
-    if data_start == -1:
-        return None
-
-    json_str = raw[raw.index("data: ", data_start) + 6:].strip()
-    try:
-        return json.loads(json_str)
-    except json.JSONDecodeError:
-        depth = 0
-        end = 0
-        for i, ch in enumerate(json_str):
-            if ch == "{":
-                depth += 1
-            elif ch == "}":
-                depth -= 1
-                if depth == 0:
-                    end = i + 1
-                    break
-        if end > 0:
-            try:
-                return json.loads(json_str[:end])
-            except json.JSONDecodeError:
-                pass
-    return None
-
-
-def _mcp_post_local(body_dict):
-    """POST to local MCP (HTTP, session-based)."""
-    parsed = urlparse(MCP_URL)
-    conn = http.client.HTTPConnection(parsed.hostname, parsed.port, timeout=120)
-    headers = {
-        "Content-Type": "application/json",
-        "Accept": "application/json, text/event-stream",
-    }
-    if SESSION_ID:
-        headers["mcp-session-id"] = SESSION_ID
-    conn.request("POST", parsed.path, body=json.dumps(body_dict), headers=headers)
-    resp = conn.getresponse()
-    session = resp.getheader("mcp-session-id")
-    raw = resp.read().decode()
-    conn.close()
-    return _parse_sse_json(raw), session
-
-
-def _mcp_post_remote(body_dict):
-    """POST to remote MCP (HTTPS, Bearer auth, stateless)."""
-    conn = http.client.HTTPSConnection("mcp.figma.com", timeout=120)
-    headers = {
-        "Content-Type": "application/json",
-        "Accept": "application/json, text/event-stream",
-        "Authorization": f"Bearer {MCP_TOKEN}",
-    }
-    conn.request("POST", "/mcp", body=json.dumps(body_dict), headers=headers)
-    resp = conn.getresponse()
-    raw = resp.read().decode()
-    conn.close()
-    if resp.status != 200:
-        raise RuntimeError(f"Remote MCP HTTP {resp.status}: {raw[:200]}")
-    return _parse_sse_json(raw), None
-
-
-def _mcp_post(body_dict):
-    if MCP_MODE == "remote":
-        return _mcp_post_remote(body_dict)
-    else:
-        return _mcp_post_local(body_dict)
-
-
-def mcp_init():
-    """Initialize MCP connection. Tries local first, falls back to remote."""
-    global MCP_MODE, SESSION_ID
-
-    init_body = {
-        "jsonrpc": "2.0",
-        "method": "initialize",
-        "params": {
-            "capabilities": {},
-            "clientInfo": {"name": "figma-utility", "version": "1.0.0"},
-            "protocolVersion": "2025-03-26",
-        },
-        "id": 1,
-    }
-
-    # Try local first (faster, no rate limits)
-    try:
-        log(f"MCP: trying local ({MCP_URL})...")
-        result, session = _mcp_post_local(init_body)
-        if session:
-            SESSION_ID = session
-            MCP_MODE = "local"
-            log(f"MCP: local connected (session: {SESSION_ID[:12]}...)")
-            return True
-    except Exception as exc:
-        log(f"MCP: local failed ({exc})")
-
-    # Fall back to remote
-    if MCP_TOKEN:
-        try:
-            log("MCP: trying remote (mcp.figma.com)...")
-            result, _ = _mcp_post_remote(init_body)
-            if result:
-                MCP_MODE = "remote"
-                log("MCP: remote connected")
-                return True
-        except Exception as exc:
-            log(f"MCP: remote failed ({exc})")
-
-    return False
-
-
-_MCP_CALL_ID = 10
-
-
-def mcp_call(tool_name, arguments, file_key=None):
-    """Call an MCP tool. Returns (texts, images) lists."""
-    global _MCP_CALL_ID
-    _MCP_CALL_ID += 1
-
-    # Remote MCP requires fileKey
-    if MCP_MODE == "remote" and file_key and "fileKey" not in arguments:
-        arguments = {**arguments, "fileKey": file_key}
-
-    body = {
-        "jsonrpc": "2.0",
-        "method": "tools/call",
-        "params": {"name": tool_name, "arguments": arguments},
-        "id": _MCP_CALL_ID,
-    }
-
-    result_json, _ = _mcp_post(body)
-    if not result_json:
-        raise RuntimeError(f"MCP {tool_name}: empty response")
-    if "error" in result_json:
-        raise RuntimeError(f"MCP {tool_name}: {result_json['error']}")
-
-    texts = []
-    images = []
-    content = (result_json.get("result") or {}).get("content", [])
-    for item in content:
-        if item.get("type") == "text":
-            texts.append(item["text"])
-        elif item.get("type") == "image":
-            images.append({
-                "mimeType": item.get("mimeType", "image/png"),
-                "data": item.get("data", ""),
-            })
-    return texts, images
-
-
-# ─── Commands ────────────────────────────────────────────────────────────────
-
-def cmd_screenshot(file_key, node_id, output_path=None, scale=2):
-    """Get PNG screenshot of a node."""
-    # Try REST API first (returns URL, more efficient for saving)
-    if FIGMA_TOKEN:
-        log(f"Fetching screenshot via REST API (scale={scale})...")
-        data = figma_get(f"images/{file_key}?ids={node_id}&format=png&scale={scale}")
-        images = data.get("images", {})
-        img_url = images.get(node_id)
-        if img_url:
-            if output_path:
-                download_file(img_url, output_path)
-                log(f"Screenshot saved: {output_path}")
-                print(json.dumps({
-                    "status": "ok",
-                    "command": "screenshot",
-                    "output": output_path,
-                    "source": "rest-api",
-                }, indent=2))
-                return
-            else:
-                print(json.dumps({
-                    "status": "ok",
-                    "command": "screenshot",
-                    "url": img_url,
-                    "source": "rest-api",
-                    "hint": "Use --output to save to file",
-                }, indent=2))
-                return
-
-    # Fallback to MCP
-    if MCP_MODE:
-        log("Fetching screenshot via MCP...")
-        texts, images = mcp_call("get_screenshot", {"nodeId": node_id}, file_key)
-        if images:
-            img_data = base64.b64decode(images[0]["data"])
-            if output_path:
-                Path(output_path).parent.mkdir(parents=True, exist_ok=True)
-                with open(output_path, "wb") as f:
-                    f.write(img_data)
-                log(f"Screenshot saved: {output_path} ({len(img_data)} bytes)")
-                print(json.dumps({
-                    "status": "ok",
-                    "command": "screenshot",
-                    "output": output_path,
-                    "bytes": len(img_data),
-                    "source": f"mcp-{MCP_MODE}",
-                }, indent=2))
-                return
-            else:
-                print(json.dumps({
-                    "status": "ok",
-                    "command": "screenshot",
-                    "bytes": len(img_data),
-                    "source": f"mcp-{MCP_MODE}",
-                    "hint": "Use --output to save to file (base64 data available via MCP)",
-                }, indent=2))
-                return
-
-    error_exit(1, "No screenshot source available.",
-               "Provide --figma-token for REST API or ensure MCP is available.")
-
-
-def cmd_metadata(file_key, node_id, output_path=None):
-    """Get layer hierarchy (XML) of a node."""
-    if not MCP_MODE:
-        error_exit(1, "MCP required for metadata.", "Ensure Figma Desktop or remote MCP is available.")
-
-    log("Fetching metadata via MCP...")
-    texts, _ = mcp_call("get_metadata", {"nodeId": node_id}, file_key)
-    result = "\n".join(texts)
-
-    if output_path:
-        Path(output_path).parent.mkdir(parents=True, exist_ok=True)
-        Path(output_path).write_text(result)
-        log(f"Metadata saved: {output_path} ({len(result)} chars)")
-
-    print(result)
-
-
-def cmd_properties(file_key, node_id, output_path=None):
-    """Get component properties/variants via REST API."""
-    log("Fetching node data via REST API...")
-    data = figma_get(f"files/{file_key}/nodes?ids={node_id}")
-
-    nodes = data.get("nodes", {})
-    node_data = nodes.get(node_id, {})
-    document = node_data.get("document", {})
-
-    # Extract component property definitions
-    prop_defs = document.get("componentPropertyDefinitions", {})
-
-    # Also check children for component set
-    if not prop_defs and document.get("type") == "COMPONENT_SET":
-        children = document.get("children", [])
-        if children:
-            prop_defs = children[0].get("componentPropertyDefinitions", {})
-
-    # Build structured output
-    properties = {}
-    for prop_name, prop_def in prop_defs.items():
-        properties[prop_name] = {
-            "type": prop_def.get("type"),
-            "defaultValue": prop_def.get("defaultValue"),
-        }
-        if prop_def.get("variantOptions"):
-            properties[prop_name]["options"] = prop_def["variantOptions"]
-
-    result = {
-        "status": "ok",
-        "command": "properties",
-        "nodeId": node_id,
-        "name": document.get("name", ""),
-        "type": document.get("type", ""),
-        "propertyCount": len(properties),
-        "properties": properties,
-    }
-
-    # Count variants if component set
-    if document.get("type") == "COMPONENT_SET":
-        result["variantCount"] = len(document.get("children", []))
-
-    output = json.dumps(result, indent=2)
-    if output_path:
-        Path(output_path).parent.mkdir(parents=True, exist_ok=True)
-        Path(output_path).write_text(output)
-        log(f"Properties saved: {output_path}")
-
-    print(output)
-
-
-def cmd_tokens(file_key, node_id, output_path=None):
-    """Get design tokens/variables for a node."""
-    if not MCP_MODE:
-        # Fallback to REST API (may 403 on non-Enterprise)
-        log("MCP unavailable, trying REST API for variables...")
-        try:
-            data = figma_get(f"files/{file_key}/variables/local")
-            output = json.dumps({"status": "ok", "command": "tokens", "source": "rest-api", "data": data}, indent=2)
-            if output_path:
-                Path(output_path).parent.mkdir(parents=True, exist_ok=True)
-                Path(output_path).write_text(output)
-            print(output)
-            return
-        except SystemExit:
-            error_exit(1, "Neither MCP nor REST API available for tokens.",
-                       "Ensure Figma Desktop or remote MCP is available.")
-
-    log("Fetching tokens via MCP...")
-    texts, _ = mcp_call("get_variable_defs", {"nodeId": node_id}, file_key)
-    result_text = "\n".join(texts)
-
-    # Try to parse as JSON for structured output
-    try:
-        token_data = json.loads(result_text)
-        output = json.dumps({
-            "status": "ok",
-            "command": "tokens",
-            "source": f"mcp-{MCP_MODE}",
-            "tokenCount": len(token_data) if isinstance(token_data, dict) else None,
-            "data": token_data,
-        }, indent=2)
-    except json.JSONDecodeError:
-        output = result_text
-
-    if output_path:
-        Path(output_path).parent.mkdir(parents=True, exist_ok=True)
-        Path(output_path).write_text(output)
-        log(f"Tokens saved: {output_path}")
-
-    print(output)
-
-
-def cmd_context(file_key, node_id, output_path=None):
-    """Get design context (code generation) for a node."""
-    if not MCP_MODE:
-        error_exit(1, "MCP required for design context.", "Ensure Figma Desktop or remote MCP is available.")
-
-    log("Fetching design context via MCP...")
-    args = {
-        "nodeId": node_id,
-        "disableCodeConnect": True,
-    }
-    texts, _ = mcp_call("get_design_context", args, file_key)
-    result = "\n".join(texts)
-
-    if output_path:
-        Path(output_path).parent.mkdir(parents=True, exist_ok=True)
-        Path(output_path).write_text(result)
-        log(f"Design context saved: {output_path} ({len(result)} chars)")
-
-    print(result)
-
-
-def cmd_code_connect(file_key, node_id, output_path=None):
-    """Get Code Connect mappings for a node."""
-    if not MCP_MODE:
-        error_exit(1, "MCP required for Code Connect.", "Ensure Figma Desktop or remote MCP is available.")
-
-    log("Fetching Code Connect mappings via MCP...")
-    args = {"nodeId": node_id, "codeConnectLabel": "SwiftUI"}
-    texts, _ = mcp_call("get_code_connect_map", args, file_key)
-    result = "\n".join(texts)
-
-    # Try to structure the output
-    try:
-        cc_data = json.loads(result)
-        output = json.dumps({
-            "status": "ok",
-            "command": "code-connect",
-            "source": f"mcp-{MCP_MODE}",
-            "mappings": cc_data,
-        }, indent=2)
-    except json.JSONDecodeError:
-        output = result
-
-    if output_path:
-        Path(output_path).parent.mkdir(parents=True, exist_ok=True)
-        Path(output_path).write_text(output)
-        log(f"Code Connect saved: {output_path}")
-
-    print(output)
-
-
-def cmd_node(file_key, node_id, output_path=None, depth=None):
-    """Get raw node data from REST API."""
-    log("Fetching node data via REST API...")
-    endpoint = f"files/{file_key}/nodes?ids={node_id}"
-    if depth is not None:
-        endpoint += f"&depth={depth}"
-
-    data = figma_get(endpoint)
-    output = json.dumps(data, indent=2)
-
-    if output_path:
-        Path(output_path).parent.mkdir(parents=True, exist_ok=True)
-        Path(output_path).write_text(output)
-        log(f"Node data saved: {output_path} ({len(output)} chars)")
-
-    print(output)
-
-
-def cmd_components(file_key, output_path=None):
-    """List all components in a Figma file."""
-    log("Fetching components via REST API...")
-    data = figma_get(f"files/{file_key}/components")
-
-    components = data.get("meta", {}).get("components", [])
-    result = {
-        "status": "ok",
-        "command": "components",
-        "fileKey": file_key,
-        "count": len(components),
-        "components": [
-            {
-                "key": c.get("key"),
-                "name": c.get("name"),
-                "nodeId": c.get("node_id"),
-                "containingFrame": c.get("containing_frame", {}).get("name"),
-                "pageName": c.get("containing_frame", {}).get("pageName"),
-            }
-            for c in components
-        ],
-    }
-    output = json.dumps(result, indent=2)
-
-    if output_path:
-        Path(output_path).parent.mkdir(parents=True, exist_ok=True)
-        Path(output_path).write_text(output)
-        log(f"Components saved: {output_path}")
-
-    print(output)
-
-
-def cmd_styles(file_key, output_path=None):
-    """Get all styles in a Figma file."""
-    log("Fetching styles via REST API...")
-    data = figma_get(f"files/{file_key}/styles")
-
-    styles = data.get("meta", {}).get("styles", [])
-    result = {
-        "status": "ok",
-        "command": "styles",
-        "fileKey": file_key,
-        "count": len(styles),
-        "styles": [
-            {
-                "key": s.get("key"),
-                "name": s.get("name"),
-                "styleType": s.get("style_type"),
-                "nodeId": s.get("node_id"),
-                "description": s.get("description"),
-            }
-            for s in styles
-        ],
-    }
-    output = json.dumps(result, indent=2)
-
-    if output_path:
-        Path(output_path).parent.mkdir(parents=True, exist_ok=True)
-        Path(output_path).write_text(output)
-        log(f"Styles saved: {output_path}")
-
-    print(output)
-
-
-def cmd_file(file_key, output_path=None, depth=None):
-    """Get file document tree (summary)."""
-    log("Fetching file tree via REST API...")
-    endpoint = f"files/{file_key}"
-    if depth is not None:
-        endpoint += f"?depth={depth}"
-
-    data = figma_get(endpoint)
-
-    # Build summary
-    doc = data.get("document", {})
-    pages = []
-    for page in doc.get("children", []):
-        page_info = {
-            "name": page.get("name"),
-            "id": page.get("id"),
-            "childCount": len(page.get("children", [])),
-        }
-        pages.append(page_info)
-
-    result = {
-        "status": "ok",
-        "command": "file",
-        "fileName": data.get("name"),
-        "lastModified": data.get("lastModified"),
-        "version": data.get("version"),
-        "pageCount": len(pages),
-        "pages": pages,
-    }
-
-    # If output requested, save full data; otherwise print summary
-    if output_path:
-        full_output = json.dumps(data, indent=2)
-        Path(output_path).parent.mkdir(parents=True, exist_ok=True)
-        Path(output_path).write_text(full_output)
-        log(f"File data saved: {output_path} ({len(full_output)} chars)")
-        print(json.dumps(result, indent=2))
-    else:
-        print(json.dumps(result, indent=2))
-
-
-def cmd_whoami():
-    """Check MCP auth status."""
-    if not MCP_MODE:
-        error_exit(1, "MCP not available.", "Ensure Figma Desktop or remote MCP is available.")
-
-    if MCP_MODE == "local":
-        print(json.dumps({
-            "status": "ok",
-            "command": "whoami",
-            "mode": "local",
-            "message": "Connected to local Figma MCP (Figma Desktop)",
-            "endpoint": MCP_URL,
-        }, indent=2))
-        return
-
-    # Remote: call whoami
-    log("Calling whoami on remote MCP...")
-    texts, _ = mcp_call("whoami", {})
-    result = "\n".join(texts)
-    try:
-        user_data = json.loads(result)
-        print(json.dumps({
-            "status": "ok",
-            "command": "whoami",
-            "mode": "remote",
-            "data": user_data,
-        }, indent=2))
-    except json.JSONDecodeError:
-        print(json.dumps({
-            "status": "ok",
-            "command": "whoami",
-            "mode": "remote",
-            "raw": result,
-        }, indent=2))
-
-
-# ─── Main ────────────────────────────────────────────────────────────────────
-
-def main():
-    parser = argparse.ArgumentParser(
-        description="Figma Utility  -  query Figma data via REST API and MCP",
-        formatter_class=argparse.RawDescriptionHelpFormatter,
-    )
-    parser.add_argument("command", choices=[
-        "screenshot", "metadata", "properties", "tokens", "context",
-        "code-connect", "node", "components", "styles", "file", "whoami",
-    ])
-    parser.add_argument("--url", help="Figma URL")
-    parser.add_argument("--file-key", help="Figma file key (alternative to URL)")
-    parser.add_argument("--node-id", help="Node ID in colon format e.g. 123:456 (alternative to URL)")
-    parser.add_argument("--output", "-o", help="Save output to file path")
-    parser.add_argument("--scale", type=int, default=2, choices=[1, 2, 3, 4],
-                        help="Screenshot scale (default: 2)")
-    parser.add_argument("--depth", type=int, help="Depth limit for node/file tree")
-    parser.add_argument("--figma-token", help="Figma REST API token (falls back to Keychain)")
-    parser.add_argument("--mcp-token", help="MCP OAuth token (falls back to Keychain)")
-    parser.add_argument("--mcp-url", default="http://127.0.0.1:3845/mcp",
-                        help="Local MCP endpoint URL")
-
-    args = parser.parse_args()
-
-    # ── Resolve tokens ──
-    global FIGMA_TOKEN, MCP_TOKEN, MCP_URL
-    FIGMA_TOKEN = get_figma_token(args.figma_token)
-    MCP_TOKEN = get_mcp_token(args.mcp_token)
-    MCP_URL = args.mcp_url
-
-    # ── Parse URL or use explicit file-key/node-id ──
-    file_key = args.file_key
-    node_id = args.node_id
-
-    if args.url:
-        url_fk, url_nid = parse_figma_url(args.url)
-        file_key = file_key or url_fk
-        node_id = node_id or url_nid
-
-    # ── Validate required params ──
-    if args.command == "whoami":
-        # whoami doesn't need URL
-        pass
-    elif args.command in ("components", "styles", "file"):
-        # These only need file_key
-        if not file_key:
-            error_exit(1, "File key required.", "Provide --url or --file-key.")
-    else:
-        # All other commands need file_key + node_id
-        if not file_key:
-            error_exit(1, "File key required.", "Provide --url or --file-key.")
-        if not node_id:
-            error_exit(1, "Node ID required.", "Provide a URL with node-id or --node-id.")
-
-    # ── Init MCP for commands that need it ──
-    mcp_commands = {"metadata", "tokens", "context", "code-connect", "whoami", "screenshot"}
-    if args.command in mcp_commands:
-        mcp_ok = mcp_init()
-        if not mcp_ok and args.command not in ("screenshot", "tokens"):
-            error_exit(1, "MCP connection failed.",
-                       "Ensure Figma Desktop is running (Dev Mode) or remote MCP token is available.")
-
-    # ── Dispatch ──
-    if args.command == "screenshot":
-        cmd_screenshot(file_key, node_id, args.output, args.scale)
-    elif args.command == "metadata":
-        cmd_metadata(file_key, node_id, args.output)
-    elif args.command == "properties":
-        cmd_properties(file_key, node_id, args.output)
-    elif args.command == "tokens":
-        cmd_tokens(file_key, node_id, args.output)
-    elif args.command == "context":
-        cmd_context(file_key, node_id, args.output)
-    elif args.command == "code-connect":
-        cmd_code_connect(file_key, node_id, args.output)
-    elif args.command == "node":
-        cmd_node(file_key, node_id, args.output, args.depth)
-    elif args.command == "components":
-        cmd_components(file_key, args.output)
-    elif args.command == "styles":
-        cmd_styles(file_key, args.output)
-    elif args.command == "file":
-        cmd_file(file_key, args.output, args.depth)
-    elif args.command == "whoami":
-        cmd_whoami()
-
-
-if __name__ == "__main__":
-    main()