profile_server.py

#!/usr/bin/env python3
"""
Stream Deck Profile Writer MCP Server

Writes directly to the Elgato Stream Deck desktop app profile manifests instead
of taking exclusive USB control of the hardware.
"""

from __future__ import annotations

import asyncio
import json
import logging
from typing import Any

from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp.types import TextContent, Tool

from profile_manager import (
    PageNotFoundError,
    ProfileManager,
    ProfileManagerError,
    ProfileNotFoundError,
    ProfileValidationError,
    StreamDeckAppRunningError,
)

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
    datefmt="%Y-%m-%d %H:%M:%S",
)
logger = logging.getLogger("streamdeck-profile-mcp")

manager = ProfileManager()
server = Server("streamdeck-profile-mcp")


@server.list_tools()
async def list_tools() -> list[Tool]:
    """List available profile writer tools."""

    button_schema = {
        "type": "object",
        "properties": {
            "controller": {
                "type": "string",
                "enum": ["keypad", "key", "button", "encoder", "dial"],
                "default": "keypad",
                "description": (
                    "Which physical controller this button targets. "
                    "'keypad' (default) addresses the LCD keys; "
                    "'encoder' (aka 'dial') addresses the rotary/touch dials on "
                    "Stream Deck + and + XL. "
                    "The key/position indexes are scoped to the chosen controller."
                ),
            },
            "key": {
                "type": "integer",
                "description": (
                    "Button index scoped to the chosen controller (0-based). "
                    "For keypad controllers the index is row-major "
                    "(left-to-right, then top-to-bottom). "
                    "For encoder/dial controllers it is a simple 0..N-1 dial index."
                ),
            },
            "position": {
                "type": "string",
                "description": (
                    "Native position string 'col,row' within the chosen controller. "
                    "Use this when you already know the grid slot."
                ),
            },
            "title": {
                "type": "string",
                "description": "Button title to write into the first active state.",
            },
            "icon_path": {
                "type": "string",
                "description": (
                    "Path to a local icon file. PNG preferred; other formats are converted. "
                    "Keypad buttons: 72x72 key face image. Encoder buttons: 72x72 dial Icon "
                    "overlay on the touchstrip."
                ),
            },
            "strip_background_path": {
                "type": "string",
                "description": (
                    "Encoder/dial only: path to a 200x100 PNG used as the touchstrip "
                    "segment background behind the dial. Generate one with "
                    "streamdeck_create_icon(shape='touchstrip'). Writing this field on a "
                    "keypad button is an error."
                ),
            },
            "encoder_layout": {
                "type": "string",
                "enum": ["$X1", "$A0", "$A1", "$B1", "$B2", "$C1"],
                "description": (
                    "Encoder/dial only: built-in Elgato touchstrip layout. Omit for "
                    "the default (no declared layout → Elgato default composition with "
                    "full-strip background show-through). Choose a variant for plugin-"
                    "rendered layouts: $X1 (title + centered icon), $A0 (title + full-"
                    "width image), $A1 (title + icon + value slot), $B1 (progress bar), "
                    "$B2 (gradient progress), $C1 (dual icon/progress rows). Selecting "
                    "a layout forgoes strip-background show-through — the declared "
                    "layout replaces the default composition. Do not combine with "
                    "path/action_type/plugin_uuid/action_uuid."
                ),
            },
            "path": {
                "type": "string",
                "description": (
                    "Convenience field for Open actions. "
                    "Usually a script generated by streamdeck_create_action."
                ),
            },
            "action_type": {
                "type": "string",
                "description": "Convenience action type: 'next_page' or 'previous_page'.",
            },
            "action": {
                "type": "object",
                "description": "Full native Stream Deck action object to write at this position.",
            },
            "plugin_uuid": {
                "type": "string",
                "description": (
                    "For advanced actions, the plugin UUID used "
                    "when building a native action object."
                ),
            },
            "plugin_name": {
                "type": "string",
            },
            "plugin_version": {
                "type": "string",
            },
            "action_uuid": {
                "type": "string",
                "description": (
                    "For advanced actions, the native action UUID, "
                    "for example com.elgato.streamdeck.page.next."
                ),
            },
            "action_name": {
                "type": "string",
            },
            "settings": {
                "type": "object",
                "description": "Native action settings object.",
            },
            "state": {
                "type": "integer",
            },
            "font_size": {
                "type": "integer",
            },
            "title_color": {
                "type": "string",
                "description": "Hex color for the title, for example #ffffff.",
            },
            "title_alignment": {
                "type": "string",
                "description": "Title placement such as top or bottom.",
            },
            "show_title": {
                "type": "boolean",
            },
        },
    }

    return [
        Tool(
            name="streamdeck_read_profiles",
            description=(
                "List Stream Deck desktop profiles from the active "
                "ProfilesV3 or ProfilesV2 directory."
            ),
            inputSchema={
                "type": "object",
                "properties": {},
            },
        ),
        Tool(
            name="streamdeck_read_page",
            description="Read a profile page by profile name or ID and page index or directory ID.",
            inputSchema={
                "type": "object",
                "properties": {
                    "profile_name": {
                        "type": "string",
                        "description": "Exact profile name as shown in the Elgato app.",
                    },
                    "profile_id": {
                        "type": "string",
                        "description": (
                            "Directory-based profile ID, usually the "
                            ".sdProfile folder name without the suffix."
                        ),
                    },
                    "page_index": {
                        "type": "integer",
                        "description": "Zero-based page index from streamdeck_read_profiles.",
                    },
                    "directory_id": {
                        "type": "string",
                        "description": (
                            "Page directory ID from streamdeck_read_profiles. "
                            "This is the safest target for updates."
                        ),
                    },
                },
            },
        ),
        Tool(
            name="streamdeck_write_page",
            description=(
                "Create a new page or replace/update an existing Stream Deck desktop "
                "page manifest. IMPORTANT: the Elgato desktop app overwrites profile "
                "manifests from its in-memory state on quit, so writes made while the "
                "app is running are lost. This tool refuses to write when the app is "
                "running unless auto_quit_app=True is passed. Call streamdeck_restart_app "
                "once your edits are complete to make the changes visible on the device."
            ),
            inputSchema={
                "type": "object",
                "properties": {
                    "profile_name": {"type": "string"},
                    "profile_id": {"type": "string"},
                    "page_index": {"type": "integer"},
                    "directory_id": {"type": "string"},
                    "page_name": {
                        "type": "string",
                        "description": "Optional page name stored in the page manifest.",
                    },
                    "buttons": {
                        "type": "array",
                        "items": button_schema,
                        "description": (
                            "Buttons to write. Use streamdeck_create_action "
                            "to build Open or script-backed actions."
                        ),
                    },
                    "clear_existing": {
                        "type": "boolean",
                        "description": (
                            "If true, replace the page contents with the "
                            "provided buttons. Defaults to true."
                        ),
                    },
                    "create_new": {
                        "type": "boolean",
                        "description": "Create a new page instead of updating an existing one.",
                    },
                    "make_current": {
                        "type": "boolean",
                        "description": (
                            "When true, make the page the active current page after writing."
                        ),
                    },
                    "auto_quit_app": {
                        "type": "boolean",
                        "description": (
                            "If true and the Elgato Stream Deck desktop app is "
                            "running, quit it (graceful AppleScript first, then "
                            "killall) before writing. Required when the app is "
                            "running or the write will raise an error. Defaults to "
                            "false so callers must explicitly consent to quitting it."
                        ),
                    },
                },
            },
        ),
        Tool(
            name="streamdeck_create_icon",
            description=(
                "Generate a 72x72 PNG icon. Supply 'icon' (a Material Design Icons "
                "name such as 'mdi:cpu-64-bit', 'mdi:volume-high', 'mdi:github') OR "
                "'text' for a centered text icon — not both. For labels on icon "
                "buttons, set the button's 'title' field on streamdeck_write_page "
                "instead of baking text here (Elgato overlays titles on images). "
                "~7400 MDI icons are bundled and resolved offline; unknown names "
                "return close-match suggestions. Returns the PNG filesystem path."
            ),
            inputSchema={
                "type": "object",
                "properties": {
                    "icon": {
                        "type": "string",
                        "description": (
                            "Material Design Icons name, e.g. 'mdi:cpu-64-bit', "
                            "'mdi:volume-high', 'mdi:microphone'. The 'mdi:' prefix is "
                            "optional. Aliases are honored."
                        ),
                    },
                    "icon_color": {
                        "type": "string",
                        "description": (
                            "Hex color for the icon glyph, e.g. '#00ff88'. "
                            "Defaults to text_color."
                        ),
                    },
                    "icon_scale": {
                        "type": "number",
                        "description": (
                            "Fraction of the canvas the glyph bounding box fills "
                            "(0.1-1.0). Defaults to 1.0 — edge-to-edge, matching how "
                            "Elgato's own icons fill the touchstrip slot. Reduce to "
                            "~0.75-0.85 for keypad buttons that also have a bottom "
                            "title so the glyph doesn't touch the label."
                        ),
                    },
                    "shape": {
                        "type": "string",
                        "enum": ["button", "touchstrip"],
                        "description": (
                            "Output canvas. 'button' (default) is 72x72 — keypad keys "
                            "and encoder dial faces. 'touchstrip' is 200x100 — per-segment "
                            "background above a Stream Deck + / + XL dial; pair with a "
                            "button's strip_background_path on streamdeck_write_page."
                        ),
                    },
                    "transparent_bg": {
                        "type": "boolean",
                        "description": (
                            "Generate an RGBA PNG with a transparent canvas instead of "
                            "filling with bg_color. Use this for dial Icons that overlay a "
                            "touchstrip background so the glyph composes naturally. Leave "
                            "false (default) for keypad faces and touchstrip backgrounds."
                        ),
                    },
                    "text": {
                        "type": "string",
                        "description": (
                            "Text for a centered text-only icon. Mutually exclusive "
                            "with 'icon'. For icon buttons that need a label, use "
                            "the button's 'title' field on streamdeck_write_page."
                        ),
                    },
                    "bg_color": {"type": "string"},
                    "text_color": {"type": "string"},
                    "font_size": {"type": "integer"},
                    "filename": {"type": "string"},
                },
            },
        ),
        Tool(
            name="streamdeck_create_action",
            description=(
                "Create an executable shell script in ~/StreamDeckScripts "
                "and return a native Open action block for it."
            ),
            inputSchema={
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string",
                        "description": (
                            "Human-readable action name used for the "
                            "script filename and button label."
                        ),
                    },
                    "command": {
                        "type": "string",
                        "description": "Shell command to run when the button is pressed.",
                    },
                    "working_directory": {
                        "type": "string",
                        "description": (
                            "Optional working directory to cd into before executing the command."
                        ),
                    },
                    "filename": {
                        "type": "string",
                        "description": "Optional override for the script filename.",
                    },
                },
                "required": ["name", "command"],
            },
        ),
        Tool(
            name="streamdeck_restart_app",
            description="Restart the macOS Stream Deck desktop app after profile changes.",
            inputSchema={
                "type": "object",
                "properties": {},
            },
        ),
        Tool(
            name="streamdeck_install_mcp_plugin",
            description=(
                "Install the bundled streamdeck-mcp Stream Deck plugin into the user's "
                "Elgato Plugins directory. The plugin is a minimal shell that declares "
                "encoder support so that per-instance touchstrip icons and backgrounds "
                "written by streamdeck_write_page survive an Elgato app restart. Idempotent "
                "— returns installed=false when already present unless force=true. "
                "streamdeck_write_page also auto-installs this plugin when an encoder "
                "button targets it, so most callers do not need to invoke this directly."
            ),
            inputSchema={
                "type": "object",
                "properties": {
                    "force": {
                        "type": "boolean",
                        "description": (
                            "Reinstall the plugin even if it already exists. Useful after "
                            "upgrading streamdeck-mcp."
                        ),
                    }
                },
            },
        ),
    ]


@server.call_tool()
async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]:
    """Handle profile writer tool calls."""

    try:
        if name == "streamdeck_read_profiles":
            profiles = manager.list_profiles()
            return [TextContent(type="text", text=json.dumps(profiles, indent=2))]

        if name == "streamdeck_read_page":
            payload = manager.read_page(
                profile_name=arguments.get("profile_name"),
                profile_id=arguments.get("profile_id"),
                page_index=arguments.get("page_index"),
                directory_id=arguments.get("directory_id"),
            )
            return [TextContent(type="text", text=json.dumps(payload, indent=2))]

        if name == "streamdeck_write_page":
            result = manager.write_page(
                profile_name=arguments.get("profile_name"),
                profile_id=arguments.get("profile_id"),
                page_index=arguments.get("page_index"),
                directory_id=arguments.get("directory_id"),
                page_name=arguments.get("page_name"),
                buttons=arguments.get("buttons"),
                clear_existing=arguments.get("clear_existing", True),
                create_new=arguments.get("create_new", False),
                make_current=arguments.get("make_current", False),
                auto_quit_app=arguments.get("auto_quit_app", False),
            )
            return [TextContent(type="text", text=json.dumps(result, indent=2))]

        if name == "streamdeck_create_icon":
            _scale = arguments.get("icon_scale")
            result = manager.create_icon(
                text=arguments.get("text"),
                icon=arguments.get("icon"),
                icon_color=arguments.get("icon_color"),
                icon_scale=1.0 if _scale is None else _scale,
                bg_color=arguments.get("bg_color", "#000000"),
                text_color=arguments.get("text_color", "#ffffff"),
                font_size=arguments.get("font_size", 18),
                filename=arguments.get("filename"),
                shape=arguments.get("shape", "button"),
                transparent_bg=bool(arguments.get("transparent_bg", False)),
            )
            return [TextContent(type="text", text=json.dumps(result, indent=2))]

        if name == "streamdeck_install_mcp_plugin":
            result = manager.install_mcp_plugin(force=bool(arguments.get("force", False)))
            return [TextContent(type="text", text=json.dumps(result, indent=2))]

        if name == "streamdeck_create_action":
            result = manager.create_action(
                name=arguments["name"],
                command=arguments["command"],
                working_directory=arguments.get("working_directory"),
                filename=arguments.get("filename"),
            )
            return [TextContent(type="text", text=json.dumps(result, indent=2))]

        if name == "streamdeck_restart_app":
            result = manager.restart_app()
            return [TextContent(type="text", text=json.dumps(result, indent=2))]

        return [TextContent(type="text", text=f"❌ Unknown tool: {name}")]

    except StreamDeckAppRunningError as exc:
        return [TextContent(type="text", text=f"⚠️ {exc}")]
    except (
        ProfileManagerError,
        ProfileNotFoundError,
        PageNotFoundError,
        ProfileValidationError,
    ) as exc:
        return [TextContent(type="text", text=f"❌ {exc}")]
    except Exception as exc:  # pragma: no cover
        logger.exception("Unexpected error in %s", name)
        return [TextContent(type="text", text=f"❌ Unexpected error: {exc}")]


async def main() -> None:
    """Run the profile writer MCP server."""

    logger.info("Starting Stream Deck Profile Writer MCP server")
    async with stdio_server() as (read_stream, write_stream):
        await server.run(read_stream, write_stream, server.create_initialization_options())


def run() -> None:
    """Synchronous wrapper for package entrypoints."""

    asyncio.run(main())


if __name__ == "__main__":
    run()