listScreens

Instructions

Implementation Reference

• src/index.ts:19-50 (handler)

  The handler function that executes the listScreens tool logic. It fetches available screens using getAvailableScreens, formats them into a text list, and returns as MCP content. Includes error handling.

  async () => {
  	try {
  		console.log("Listing available screens...")
  		const screens = await getAvailableScreens()
  
  		// Format the output for display
  		const screenList = screens
  			.map((screen) => `Screen ${screen.id}: ${screen.description}`)
  			.join("\n")
  
  		return {
  			content: [
  				{
  					type: "text",
  					text: `Available screens:\n${screenList}`
  				}
  			]
  		}
  	} catch (error: unknown) {
  		console.error("Error listing screens:", error)
  		const errorMessage =
  			error instanceof Error ? error.message : String(error)
  		return {
  			content: [
  				{
  					type: "text",
  					text: `Error listing screens: ${errorMessage}`
  				}
  			]
  		}
  	}
  }

• src/index.ts:15-51 (registration)

  Registers the listScreens tool with the MCP server, including name, description, empty schema, and inline handler function.

  server.tool(
  	"listScreens",
  	"List available screens/displays that can be captured",
  	{},
  	async () => {
  		try {
  			console.log("Listing available screens...")
  			const screens = await getAvailableScreens()
  
  			// Format the output for display
  			const screenList = screens
  				.map((screen) => `Screen ${screen.id}: ${screen.description}`)
  				.join("\n")
  
  			return {
  				content: [
  					{
  						type: "text",
  						text: `Available screens:\n${screenList}`
  					}
  				]
  			}
  		} catch (error: unknown) {
  			console.error("Error listing screens:", error)
  			const errorMessage =
  				error instanceof Error ? error.message : String(error)
  			return {
  				content: [
  					{
  						type: "text",
  						text: `Error listing screens: ${errorMessage}`
  					}
  				]
  			}
  		}
  	}
  )

• src/index.ts:18-18 (schema)

  Input schema for listScreens tool: empty object indicating no parameters required.

  {},

• src/take-screenshot.ts:109-256 (helper)

  Core helper function that implements screen listing logic using platform-specific system commands (detailed parsing for macOS via system_profiler), with platform fallbacks and robust error handling.

  // Add a helper function to list available screens (macOS only)
  export async function getAvailableScreens(): Promise<
  	{ id: number; description: string }[]
  > {
  	try {
  		const platform = os.platform()
  
  		if (platform === "darwin") {
  			// Use system_profiler to get display information
  			const { stdout } = await execAsync(
  				"system_profiler SPDisplaysDataType"
  			)
  
  			// Parse the system_profiler output to properly identify displays
  			// First, separate the output into sections for each display
  			const displayData = stdout
  				.split("Graphics/Displays:")
  				.filter((section) => section.trim().length > 0)
  
  			if (displayData.length === 0) {
  				// Fallback if no displays were found
  				return [{ id: 1, description: "Main Display" }]
  			}
  
  			// Initial display list with Main Display
  			const displays: { id: number; description: string }[] = []
  
  			// Scan through raw output and extract display sections
  			const displaySections = stdout
  				.split(/^\s*\w+:/m)
  				.filter(
  					(section) =>
  						section.includes("Display Type") ||
  						section.includes("Resolution") ||
  						section.includes("Type:")
  				)
  
  			// Check if we're dealing with a more specific format
  			if (displaySections.length === 0) {
  				// Fallback to main display only
  				return [{ id: 1, description: "Main Display" }]
  			}
  
  			// Process each section to extract display info
  			for (let i = 0; i < displaySections.length; i++) {
  				const section = displaySections[i]
  				const lines = section.split("\n").map((line) => line.trim())
  
  				let displayName = ""
  				let resolution = ""
  				let displayType = ""
  
  				// Extract relevant display information
  				for (const line of lines) {
  					if (
  						line.includes("Display Type:") ||
  						line.includes("Type:")
  					) {
  						displayType = line.split(":")[1]?.trim() || "Unknown"
  					} else if (line.includes("Resolution:")) {
  						resolution = line.split(":")[1]?.trim() || ""
  					} else if (line.includes("Name:")) {
  						displayName = line.split(":")[1]?.trim() || ""
  					}
  				}
  
  				// Combine information for a descriptive name
  				let description = displayName || displayType || "Display"
  				if (resolution) {
  					description += ` (${resolution})`
  				}
  
  				// Add to display list
  				displays.push({
  					id: i + 1, // Display IDs in screencapture start at 1
  					description
  				})
  			}
  
  			// If we found displays but none matched our parsing, add a fallback
  			if (displays.length === 0) {
  				displays.push({ id: 1, description: "Main Display" })
  			}
  
  			// Use an alternative method: Check output from "system_profiler SPDisplaysDataType"
  			if (displays.length <= 1) {
  				// Try running a different command to get screen info
  				try {
  					const { stdout: screenInfo } = await execAsync(
  						"system_profiler SPDisplaysDataType | grep Resolution"
  					)
  					const resolutions = screenInfo
  						.split("\n")
  						.filter((line) => line.includes("Resolution"))
  
  					// If we have multiple resolutions, we likely have multiple screens
  					if (resolutions.length > 1) {
  						displays.length = 0 // Clear existing displays
  
  						// Add each detected display
  						for (let i = 0; i < resolutions.length; i++) {
  							const resolution =
  								resolutions[i].split(":")[1]?.trim() || ""
  							displays.push({
  								id: i + 1,
  								description:
  									i === 0
  										? `Main Display (${resolution})`
  										: `External Display ${i} (${resolution})`
  							})
  						}
  					}
  				} catch (err) {
  					console.error("Error getting alternative screen info:", err)
  				}
  			}
  
  			return displays
  		}
  
  		if (platform === "win32") {
  			// Windows implementation (placeholder)
  			return [
  				{
  					id: 0,
  					description:
  						"Primary Screen (multi-screen selection not supported yet)"
  				}
  			]
  		}
  
  		if (platform === "linux") {
  			// Linux implementation (placeholder)
  			return [
  				{
  					id: 0,
  					description:
  						"Primary Screen (multi-screen selection not supported yet)"
  				}
  			]
  		}
  
  		throw new Error(`Unsupported platform: ${platform}`)
  	} catch (error) {
  		console.error("Error listing screens:", error)
  		return [{ id: 1, description: "Main Display" }]
  	}
  }