capture-win-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

capture-win-mcp is a Model Context Protocol (MCP) server that enables AI assistants to interact with macOS windows. It provides two primary capabilities:

1. Listing all windows organized by macOS Spaces (virtual desktops)
2. Capturing screenshots of specific windows by ID

The server leverages yabai (a tiling window manager) for accurate window tracking and macOS's built-in screencapture utility for screenshot capture.

Architecture

Module Structure

• capture_win_mcp/tracker.py: Core window tracking logic

  • EnhancedSpaceTracker class interfaces with yabai via subprocess calls
  • Queries spaces (yabai -m query --spaces) and windows (yabai -m query --windows)
  • Maintains cached spaces_data and windows_data as JSON lists
  • All yabai calls have 5-second timeouts for safety

• capture_win_mcp/server.py: MCP server implementation

  • Uses the official Python MCP SDK (mcp package)
  • Exposes two tools: list_windows and capture_window
  • Runs via stdio transport (stdin/stdout)
  • Returns images as base64-encoded PNG data

• main.py: Legacy standalone CLI tool (kept for backward compatibility)

Data Flow

1. List Windows:

   • Tool called → tracker.refresh() queries yabai → data cached
   • Returns either structured JSON or human-readable summary
   • Organizes windows by Space with metadata (app, title, ID, position, visibility)

2. Capture Window:

   • Tool called with window_id → tracker.refresh() verifies window exists
   • screencapture -x -l <window_id> captures to /tmp/capture_win_<id>.png
   • Image read, base64-encoded, temporary file deleted
   • Returns text metadata + ImageContent with base64 data

Development Commands

Environment Setup

# Create virtual environment with uv
uv venv
source .venv/bin/activate  # or `. .venv/bin/activate`

# Install in editable mode
uv pip install -e .