list_windows

Instructions

Implementation Reference

• capture_win_mcp/server.py:79-141 (handler)

  Main handler function for the list_windows tool. Refreshes tracker data, handles JSON or summary output formats, and returns structured or human-readable window lists organized by macOS Spaces.

  async def handle_list_windows(arguments: dict) -> list[TextContent]:
      """Handle list_windows tool call."""
      try:
          # Refresh tracker data
          tracker.refresh()
  
          format_type = arguments.get("format", "json")
  
          if format_type == "json":
              # Return structured JSON data
              data = tracker.get_all_data()
              return [
                  TextContent(
                      type="text",
                      text=json.dumps(data, indent=2)
                  )
              ]
          else:  # summary format
              # Return human-readable summary
              data = tracker.get_all_data()
              windows_by_space = tracker.get_windows_by_space()
  
              summary_lines = []
              summary_lines.append(f"Total Spaces: {data['summary']['total_spaces']}")
              summary_lines.append(f"Total Windows: {data['summary']['total_windows']}")
              summary_lines.append("")
  
              # Create space map for quick lookup
              space_map = {s.get('index'): s for s in data['spaces']}
  
              for space_index in sorted(windows_by_space.keys()):
                  windows = windows_by_space[space_index]
                  space_info = space_map.get(space_index, {})
                  space_label = space_info.get('label', '(unlabeled)')
                  is_visible = space_info.get('is-visible', False)
                  visibility = "VISIBLE" if is_visible else "hidden"
  
                  summary_lines.append(f"Space {space_index}: {space_label} ({visibility})")
                  summary_lines.append(f"  {len(windows)} window(s)")
  
                  for window in windows:
                      app_name = window.get('app', 'Unknown')
                      title = window.get('title', '(Untitled)')
                      win_id = window.get('id', 0)
                      summary_lines.append(f"    - [{app_name}] {title} (ID: {win_id})")
  
                  summary_lines.append("")
  
              return [
                  TextContent(
                      type="text",
                      text="\n".join(summary_lines)
                  )
              ]
  
      except Exception as e:
          return [
              TextContent(
                  type="text",
                  text=f"Error listing windows: {str(e)}"
              )
          ]

• capture_win_mcp/server.py:29-44 (schema)

  Tool schema defining the list_windows tool, including name, description, and optional 'format' input parameter.

  Tool(
      name="list_windows",
      description="List all windows organized by macOS Space. Returns detailed information about windows, spaces, and which windows belong to which Space.",
      inputSchema={
          "type": "object",
          "properties": {
              "format": {
                  "type": "string",
                  "description": "Output format: 'json' (structured data) or 'summary' (human-readable)",
                  "enum": ["json", "summary"],
                  "default": "json"
              }
          },
          "required": []
      }
  ),

• capture_win_mcp/server.py:71-72 (registration)

  Tool dispatch logic in the call_tool handler that routes list_windows calls to the handle_list_windows function.

  if name == "list_windows":
      return await handle_list_windows(arguments)

• capture_win_mcp/tracker.py:59-65 (helper)

  Refreshes the tracker by querying yabai for current spaces and windows data, called by the list_windows handler.

  def refresh(self):
      """Refresh space and window data."""
      if self.has_yabai:
          self.spaces_data = self._query_yabai_spaces()
          self.windows_data = self._query_yabai_windows()
      else:
          raise RuntimeError("yabai not found. Install with: brew install koekeishiya/formulae/yabai")

• capture_win_mcp/tracker.py:45-57 (helper)

  Core utility that executes yabai query to list all windows, providing the raw data for the list_windows tool.

  def _query_yabai_windows(self) -> List[Dict]:
      """Query yabai for window information."""
      try:
          result = subprocess.run(
              ['yabai', '-m', 'query', '--windows'],
              capture_output=True,
              text=True,
              timeout=5
          )
          return json.loads(result.stdout)
      except Exception as e:
          print(f"Warning: Could not query yabai windows: {e}")
          return []