pixelweaver 0.1.0

package/server/src/pixelweaver/mcp_server.py

@@ -0,0 +1,234 @@
+"""MCP tool server for PixelWeaver.
+
+Exposes PixelWeaver operations as MCP tools so that LLMs (via Claude Code,
+Claude Desktop, etc.) can programmatically create and edit pixel art.
+
+Runs as a separate process using stdio transport. Start with:
+    pixelweaver mcp [--data-dir ./projects]
+
+Architecture
+------------
+The MCP server does NOT own its own state.  Before each tool execution it
+pulls the latest state from the collaboration server (HTTP on port 7779),
+runs the tool logic locally, then pushes the modified state back.  The
+collab server broadcasts a full-state patch to all WebSocket clients so
+the frontend sees every MCP mutation in real time.
+
+The collaboration server must be running for MCP to work.  If it is
+unreachable the MCP server returns a clear error to the LLM.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from contextlib import asynccontextmanager
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+from mcp.types import ImageContent, TextContent
+
+from pixelweaver.connections import ConnectionManager
+from pixelweaver.mcp_bridge import (
+    CollabServerUnreachableError,
+    deserialize_into_state,
+    pull_full_state,
+    push_full_state,
+    serialize_state,
+)
+from pixelweaver.mcp_registry import MCPCommandRegistry
+from pixelweaver.mcp_resources import (
+    init_mcp_resources,
+    init_mcp_subscriptions,
+    notify_resource_subscribers,
+)
+from pixelweaver.state import ServerState
+
+logger = logging.getLogger(__name__)
+
+# Module-level instances used by the MCP server process.
+# State is populated from the collab server on each tool call -- not from disk.
+_state: ServerState | None = None
+_connections: ConnectionManager | None = None
+_registry: MCPCommandRegistry | None = None
+
+
+def _ensure_initialized() -> MCPCommandRegistry:
+    """Lazily initialize the local state/registry on first tool call.
+
+    Unlike the old architecture, we do NOT load projects from disk here.
+    State is synced from the collab server before each tool execution
+    (see _sync_from_collab / _push_to_collab in the handler wrapper).
+    """
+    global _state, _connections, _registry
+    if _registry is not None:
+        return _registry
+
+    _state = ServerState()
+    # ConnectionManager is still needed by MCPCommandRegistry's constructor,
+    # but its broadcast calls are effectively no-ops (no WS clients connect
+    # to the stdio process).  State propagation happens via the HTTP push.
+    _connections = ConnectionManager()
+    _registry = MCPCommandRegistry(_state, _connections)
+    return _registry
+
+
+async def _sync_from_collab() -> None:
+    """Pull the latest state from the collab server into _state.
+
+    Raises CollabServerUnreachableError if the server cannot be reached.
+    """
+    assert _state is not None
+    data = await pull_full_state()
+    deserialize_into_state(_state, data)
+
+
+async def _push_to_collab() -> None:
+    """Push the current _state to the collab server (triggers WS broadcast).
+
+    Raises CollabServerUnreachableError if the server cannot be reached.
+    """
+    assert _state is not None
+    state_dict = serialize_state(_state)
+    await push_full_state(state_dict)
+
+
+# ---------------------------------------------------------------------------
+# FastMCP server
+# ---------------------------------------------------------------------------
+
+@asynccontextmanager
+async def mcp_lifespan(server: FastMCP):
+    """Initialize state when the MCP server starts."""
+    _ensure_initialized()
+    yield
+
+
+mcp = FastMCP(
+    "PixelWeaver",
+    instructions=(
+        "PixelWeaver is a pixel art sprite editor. Use these tools to create "
+        "projects, draw shapes, manage layers and frames, and export artwork. "
+        "Start by creating a project with create_project, then use drawing "
+        "tools to add pixel art. Use get_canvas_thumbnail to see the result. "
+        "NOTE: The PixelWeaver collaboration server must be running on port "
+        "7779 for these tools to work."
+    ),
+    lifespan=mcp_lifespan,
+)
+
+
+def _format_result(result: dict[str, Any]) -> list[TextContent | ImageContent]:
+    """Convert a registry result dict into MCP content blocks.
+
+    Mutation results include a thumbnail as an ImageContent block.
+    All results include a TextContent block with the JSON data.
+    """
+    content: list[TextContent | ImageContent] = []
+
+    # Extract and remove thumbnail before serializing to text
+    thumbnail_b64 = result.pop("thumbnail", None)
+
+    content.append(TextContent(type="text", text=json.dumps(result, indent=2)))
+
+    if thumbnail_b64:
+        content.append(ImageContent(
+            type="image",
+            data=thumbnail_b64,
+            mimeType="image/png",
+        ))
+
+    return content
+
+
+# ---------------------------------------------------------------------------
+# Auto-register all tools from the registry
+# ---------------------------------------------------------------------------
+# We register a generic handler for each tool defined in the registry.
+# The tool definitions (names, descriptions, schemas) come from the registry;
+# the actual FastMCP tool functions delegate to registry.execute_tool().
+
+
+def _make_tool_handler(tool_name: str):
+    """Create an async handler closure for a specific tool name.
+
+    Each handler:
+      1. Pulls latest state from the collab server
+      2. Executes the tool locally via the registry
+      3. Pushes modified state back (for mutating tools)
+    If the collab server is unreachable, returns a clear error.
+    """
+
+    async def handler(**kwargs: Any) -> list[TextContent | ImageContent]:
+        registry = _ensure_initialized()
+        tool_def = registry.get_tool_def(tool_name)
+
+        # Pull latest state from the collab server
+        try:
+            await _sync_from_collab()
+        except CollabServerUnreachableError as exc:
+            return _format_result({
+                "success": False,
+                "error": (
+                    f"Collab server unreachable: {exc}. "
+                    "Make sure the PixelWeaver server is running "
+                    "(pixelweaver serve --port 7779)."
+                ),
+            })
+
+        # Execute the tool locally
+        result = await registry.execute_tool(tool_name, kwargs)
+
+        # Push modified state back if the tool mutates state
+        if tool_def and tool_def.mutates and result.get("success", False):
+            try:
+                await _push_to_collab()
+            except CollabServerUnreachableError as exc:
+                # Tool succeeded locally but failed to propagate -- warn
+                result["warning"] = (
+                    f"Tool executed but failed to sync to collab server: {exc}"
+                )
+
+            # Notify subscribed MCP clients that resources have changed.
+            await notify_resource_subscribers(mcp)
+
+        return _format_result(result)
+
+    # FastMCP uses the function name as the tool name
+    handler.__name__ = tool_name
+    handler.__qualname__ = tool_name
+    return handler
+
+
+def init_mcp_tools() -> None:
+    """Register all tools from the registry onto the FastMCP server.
+
+    Call this explicitly from the server startup path. Importing this module
+    no longer has side effects; this keeps tests and tooling from paying the
+    cost of initializing the MCP registry unless they actually need it.
+    """
+    registry = _ensure_initialized()
+    for tool_def_dict in registry.get_tool_definitions():
+        name = tool_def_dict["name"]
+        desc = tool_def_dict["description"]
+        handler = _make_tool_handler(name)
+        # Use add_tool with the raw handler; FastMCP will expose it
+        mcp.add_tool(handler, name=name, description=desc)
+
+    # Register MCP resources (project state, canvas, frame, palette)
+    init_mcp_resources(mcp)
+
+    # Wire up resource subscription/unsubscription handlers and
+    # advertise subscribe=True in the server capabilities.
+    init_mcp_subscriptions(mcp)
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+
+def run_mcp_server() -> None:
+    """Run the MCP server on stdio transport (blocking)."""
+    init_mcp_tools()
+    mcp.run(transport="stdio")

package/server/src/pixelweaver/protocol.py

@@ -0,0 +1,219 @@
+"""Pydantic models for the PixelWeaver WebSocket JSON protocol.
+
+Client -> Server message types:
+    command        -- dispatch a drawing/editing command
+    sync_request   -- request full state snapshot
+    undo           -- undo last command
+    redo           -- redo last undone command
+
+Server -> Client message types:
+    command_ack       -- command accepted
+    command_reject    -- command rejected with reason
+    state_sync        -- full state snapshot
+    command_broadcast -- a command executed by another client
+    error             -- generic error
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+# ---------------------------------------------------------------------------
+# Client -> Server
+# ---------------------------------------------------------------------------
+
+
+class CommandPayload(BaseModel):
+    """The inner command object sent by the client."""
+
+    type: str
+    plugin: str
+    version: str
+    params: dict[str, Any] = Field(default_factory=dict)
+    id: str
+    timestamp: int
+
+
+class CommandMessage(BaseModel):
+    """Client dispatches a command for execution."""
+
+    type: Literal["command"]
+    id: str
+    command: CommandPayload
+
+
+class SyncRequestMessage(BaseModel):
+    """Client requests a full state snapshot."""
+
+    type: Literal["sync_request"]
+    id: str
+
+
+class UndoMessage(BaseModel):
+    """Client requests undo of the last command."""
+
+    type: Literal["undo"]
+    id: str
+
+
+class RedoMessage(BaseModel):
+    """Client requests redo of the last undone command."""
+
+    type: Literal["redo"]
+    id: str
+
+
+# Union discriminator for incoming messages
+ClientMessage = CommandMessage | SyncRequestMessage | UndoMessage | RedoMessage
+
+
+# ---------------------------------------------------------------------------
+# Server -> Client
+# ---------------------------------------------------------------------------
+
+
+class CommandAckMessage(BaseModel):
+    """Server confirms a command was accepted and executed."""
+
+    type: Literal["command_ack"] = "command_ack"
+    id: str
+    command_id: str
+    success: Literal[True] = True
+
+
+class CommandRejectMessage(BaseModel):
+    """Server rejects a command with a reason."""
+
+    type: Literal["command_reject"] = "command_reject"
+    id: str
+    command_id: str
+    error: str
+
+
+class StateSyncMessage(BaseModel):
+    """Full state snapshot sent to the client."""
+
+    type: Literal["state_sync"] = "state_sync"
+    id: str
+    state: dict[str, Any]
+
+
+class CommandBroadcastMessage(BaseModel):
+    """Broadcast of a command executed by another client."""
+
+    type: Literal["command_broadcast"] = "command_broadcast"
+    command: dict[str, Any]
+    source: str
+
+
+class ErrorMessage(BaseModel):
+    """Generic error message."""
+
+    type: Literal["error"] = "error"
+    id: str
+    error: str
+
+
+ServerMessage = (
+    CommandAckMessage
+    | CommandRejectMessage
+    | StateSyncMessage
+    | CommandBroadcastMessage
+    | ErrorMessage
+)
+
+
+# ---------------------------------------------------------------------------
+# Data Patches -- server-to-client state synchronization
+# ---------------------------------------------------------------------------
+# When the server modifies state (via MCP or other operations), it broadcasts
+# patches describing the pre-computed results.  The frontend applies these
+# directly without re-executing commands.
+
+
+class StatePatch(BaseModel):
+    """Base for all state patches."""
+
+    type: str
+
+
+class PixelPatch(StatePatch):
+    """A patch to pixel data on a specific layer/frame."""
+
+    type: Literal["pixel"] = "pixel"
+    layer_id: str
+    frame_index: int
+    data: list[int]  # flat RGBA
+    width: int
+    height: int
+
+
+class LayerPatch(StatePatch):
+    """A patch to the layer tree structure."""
+
+    type: Literal["layer"] = "layer"
+    action: str  # add, remove, update
+    layer: dict[str, Any] | None = None
+    layer_id: str | None = None
+
+
+class CanvasPatch(StatePatch):
+    """A patch to canvas dimensions."""
+
+    type: Literal["canvas"] = "canvas"
+    width: int
+    height: int
+
+
+class FramePatch(StatePatch):
+    """A patch to frame structure (add/remove/reorder/set_duration)."""
+
+    type: Literal["frame"] = "frame"
+    action: str
+    frame_index: int | None = None
+    frame_data: dict[str, Any] | None = None
+    from_index: int | None = None
+    to_index: int | None = None
+    duration_ms: int | None = None
+
+
+class FullStatePatch(StatePatch):
+    """A full state replacement (initial sync or large MCP operations)."""
+
+    type: Literal["full_state"] = "full_state"
+    snapshot: dict[str, Any]
+
+
+class PatchMessage(BaseModel):
+    """Wrapper message broadcast via WebSocket carrying one or more patches."""
+
+    type: Literal["state_patch"] = "state_patch"
+    project_name: str
+    patches: list[dict[str, Any]]  # StatePatch dicts
+    command_id: str | None = None
+
+
+# ---------------------------------------------------------------------------
+# Parsing helper
+# ---------------------------------------------------------------------------
+
+
+def parse_client_message(raw: dict[str, Any]) -> ClientMessage:
+    """Parse a raw dict into one of the client message types.
+
+    Raises ValueError if the message is malformed or has an unknown type.
+    """
+    msg_type = raw.get("type")
+    match msg_type:
+        case "command":
+            return CommandMessage.model_validate(raw)
+        case "sync_request":
+            return SyncRequestMessage.model_validate(raw)
+        case "undo":
+            return UndoMessage.model_validate(raw)
+        case "redo":
+            return RedoMessage.model_validate(raw)
+        case _:
+            raise ValueError(f"Unknown message type: {msg_type!r}")