@mmerterden/multi-agent-pipeline 8.6.0

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

@@ -0,0 +1,808 @@
+#!/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()