Capture Win MCP

Instructions

Implementation Reference

• capture_win_mcp/server.py:143-241 (handler)

  The primary handler function implementing the capture_window tool logic. It processes input arguments, verifies the window, uses subprocess to run macOS 'screencapture' command on the window ID, encodes the resulting PNG to base64, and returns TextContent with description and ImageContent with the screenshot.

  async def handle_capture_window(arguments: dict) -> list[ImageContent | TextContent]:
      """Handle capture_window tool call."""
      try:
          window_id = arguments.get("window_id")
          include_shadow = arguments.get("include_shadow", True)
  
          if window_id is None:
              return [
                  TextContent(
                      type="text",
                      text="Error: window_id is required"
                  )
              ]
  
          # Refresh tracker to verify window exists
          tracker.refresh()
          window = tracker.get_window_by_id(window_id)
  
          if not window:
              return [
                  TextContent(
                      type="text",
                      text=f"Error: Window with ID {window_id} not found"
                  )
              ]
  
          # Create temporary file for screenshot
          temp_file = Path(f"/tmp/capture_win_{window_id}.png")
  
          # Build screencapture command
          cmd = ["screencapture", "-x"]  # -x: no sound
  
          if not include_shadow:
              cmd.append("-o")  # -o: no shadow
  
          cmd.extend(["-l", str(window_id)])  # -l: capture window by ID
          cmd.append(str(temp_file))
  
          # Capture the window
          result = subprocess.run(
              cmd,
              capture_output=True,
              text=True,
              timeout=10
          )
  
          if result.returncode != 0:
              return [
                  TextContent(
                      type="text",
                      text=f"Error capturing window: {result.stderr}"
                  )
              ]
  
          # Read and encode the image
          if not temp_file.exists():
              return [
                  TextContent(
                      type="text",
                      text="Error: Screenshot file not created"
                  )
              ]
  
          image_data = temp_file.read_bytes()
          base64_image = base64.b64encode(image_data).decode('utf-8')
  
          # Clean up temporary file
          temp_file.unlink()
  
          # Get window details for context
          app_name = window.get('app', 'Unknown')
          title = window.get('title', '(Untitled)')
  
          return [
              TextContent(
                  type="text",
                  text=f"Captured window: [{app_name}] {title} (ID: {window_id})"
              ),
              ImageContent(
                  type="image",
                  data=base64_image,
                  mimeType="image/png"
              )
          ]
  
      except subprocess.TimeoutExpired:
          return [
              TextContent(
                  type="text",
                  text="Error: Screenshot capture timed out"
              )
          ]
      except Exception as e:
          return [
              TextContent(
                  type="text",
                  text=f"Error capturing window: {str(e)}"
              )
          ]

• capture_win_mcp/server.py:48-62 (schema)

  Input JSON schema for the capture_window tool, specifying the required 'window_id' parameter and optional 'include_shadow' boolean.

  inputSchema={
      "type": "object",
      "properties": {
          "window_id": {
              "type": "integer",
              "description": "The window ID to capture (from list_windows)"
          },
          "include_shadow": {
              "type": "boolean",
              "description": "Include window shadow in the capture",
              "default": True
          }
      },
      "required": ["window_id"]
  }

• capture_win_mcp/server.py:45-63 (registration)

  Tool registration in list_tools(): defines the MCP Tool object for 'capture_window' with name, description, and input schema.

  Tool(
      name="capture_window",
      description="Capture a screenshot of a specific window by its ID. Returns the image as base64-encoded PNG. Use list_windows first to get window IDs.",
      inputSchema={
          "type": "object",
          "properties": {
              "window_id": {
                  "type": "integer",
                  "description": "The window ID to capture (from list_windows)"
              },
              "include_shadow": {
                  "type": "boolean",
                  "description": "Include window shadow in the capture",
                  "default": True
              }
          },
          "required": ["window_id"]
      }
  )

• capture_win_mcp/server.py:73-74 (registration)

  Dispatch registration in @app.call_tool(): routes calls to 'capture_window' to the handler function.

  elif name == "capture_window":
      return await handle_capture_window(arguments)