WindowsPC-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.

What This Is

WindowsPC-MCP is a FastMCP server that confines an AI agent's GUI interaction to a Parsec VDD virtual display. The agent gets its own screen with independent cursor/focus — it can only click/type/scroll on its virtual display, but can read all screens for context. As of v0.6.0, a PyQt6 control UI auto-launches alongside the server so the human user can monitor and intervene (Pause / Resume / Join / Stop / Screen-select).

Commands

# Install (PyQt6 mandatory as of v0.6.0)
pip install -e ".[dev]"

# Build the DXGI capture DLL (one-time, needs cl.exe or g++)
cd src/windowspc_mcp/desktop && see BUILD_CAPTURE_DXGI.md

# Run server
windowspc-mcp --transport stdio
windowspc-mcp --transport sse --host localhost --port 8000
windowspc-mcp --no-ui                          # headless (CI / gateways)

# Tests (~1300 tests)
python -m pytest tests/                        # all tests
python -m pytest tests/desktop/                # desktop isolation tests
python -m pytest tests/ui/                     # PyQt6 UI tests (pytest-qt)
python -m pytest tests/confinement/            # confinement tests
python -m pytest tests/display/                # display driver tests
python -m pytest tests/ipc/                    # IPC layer tests
python -m pytest tests/smoke/                  # smoke tests (need VDD hardware)
python -m pytest tests/desktop/test_gate.py -v # single file, verbose
python -m pytest -k "test_switch_to_agent"     # single test by name

# Verify UI builds + renders headlessly
python tools/ui_smoke.py tools/ui_smoke.png

# Lint
ruff check src tests
ruff check --fix src tests

Architecture

Request Flow

MCP Tool call (Click, Type, etc.)
    → guarded_tool decorator (confinement/decorators.py)
        → ToolGuard.check() (state + bounds validation)
            → ConfinementEngine.validate_and_translate() (agent-relative → absolute coords)
                → AgentInputService (input/service.py) → Win32 SendInput