{"owner":"CursorTouch","repo":"Windows-MCP","hasSkills":true,"totalSkillsCount":2,"totalTokensCount":8364,"categories":["claude-rule","anthropic-skill"],"hasMcp":true,"mcpConfig":{"mcpServers":{"Windows-MCP":{"command":"npx","args":["-y","@modelcontextprotocol/server-Windows-MCP"]}}},"found":["CLAUDE.md",".claude/skills/windows-mcp-tool-tester/SKILL.md"],"skills":{"CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Project Overview\n\nWindows-MCP is a Python MCP (Model Context Protocol) server that bridges AI LLM agents with the Windows OS, enabling direct desktop automation. It exposes 21 tools via FastMCP:\n\n| Group | Tools |\n|---|---|\n| Capture | `Screenshot`, `Snapshot`, `Scrape`, `DisplayInventory` |\n| Input | `Click`, `Type`, `Scroll`, `Move` (also drag-and-drop via `drag=True`), `Shortcut`, `MultiSelect`, `MultiEdit` |\n| Timing | `Wait`, `WaitFor` |\n| System | `App`, `PowerShell`, `FileSystem`, `Registry`, `Process`, `Clipboard`, `Notification`, `ControlStatus` |\n\nTool names are defined by the `name=` argument of each `@mcp.tool(...)` in `src/windows_mcp/tools/`; that directory is the source of truth. Note the shell tool is registered as `PowerShell`, not `Shell`. Any subset can be removed at startup with `serve --exclude-tools` (e.g. `windows-mcp serve --exclude-tools PowerShell,Registry`).\n\n## Build & Development Commands\n\n```bash\nuv sync --extra dev        # Install runtime and development dependencies\nuv run windows-mcp serve   # Run the MCP server\nuv run --extra dev ruff format .  # Format code\nuv run --extra dev ruff check .   # Lint code\nuv run --extra dev ruff check --fix .  # Lint and auto-fix\nuv run --extra dev pytest         # Run all tests\nuv run --extra dev pytest tests/test_desktop_views.py  # Run a single test file\n```\n\n**Package manager**: UV (not pip). **Python**: 3.14+. **Build backend**: setuptools.\n\n## Architecture\n\nThe codebase follows a layered service architecture under `src/windows_mcp/`:\n\n**Entry point** — `__main__.py`: Builds the FastMCP server, parses CLI flags, and selects the transport. Tool registration is delegated to `tools.register_all()`; an async lifespan initializes the Desktop, WatchDog, and Analytics singletons, which tools resolve lazily through the `get_desktop` / `get_analytics` callables.\n\n**Tools layer** — `tools/`: One module per tool group, each exposing `register(mcp, *, get_desktop, get_analytics)`. `tools/__init__.py` holds the module list and `register_all()`. Tool functions are thin — they normalize arguments and delegate to a service package. The `@with_analytics` decorator wraps each one for telemetry, making it the existing precedent for cross-cutting concerns at the tool boundary.\n\n**Desktop service** — `desktop/service.py`: High-level orchestrator. Manages window operations (launch, resize, switch), screenshots, mouse/keyboard actions, and clipboard. Interfaces with Tree service for UI element discovery. `desktop/views.py` defines data models: `DesktopState`, `Window`, `Size`, `BoundingBox`, `Status`.\n\n**Tree service** — `tree/service.py`: Captures the Windows accessibility tree from active and background windows. Identifies interactive elements and scrollable areas. Uses `ThreadPoolExecutor` for multi-threaded UI traversal. `tree/views.py` defines `TreeElementNode`, `ScrollElementNode`, `TreeState`. `tree/config.py` has control type configurations.\n\n**UIAutomation wrapper** — `uia/`: Low-level abstraction over the Windows UIAutomation COM API via `comtypes`. `core.py` wraps the main automation object, `controls.py` has control-specific logic, `patterns.py` wraps UIAutomation patterns, `enums.py` has COM enumerations, `events.py` handles event subscriptions.\n\n**WatchDog** — `watchdog/service.py`: Runs in a separate thread monitoring UI focus changes via UIAutomation events. Notifies the Tree service of focus changes so the accessibility tree stays current.\n\n**Virtual Desktop Manager** — `vdm/core.py`: Tracks which windows belong to which Windows virtual desktop (Win10/11).\n\n**Domain services** — thin packages backing the system tools: `filesystem/` (read/write/copy/move/delete/list/search/info), `registry/` (get/set/delete/list, implemented via PowerShell cmdlets), `powershell/` (`PowerShellExecutor` plus environment resolution), `process/` (list/kill), `notifications/`. Registry and PowerShell tools shell out, so their latency is dominated by process startup.\n\n**Infrastructure** — `infrastructure/`: cross-cutting concerns. `analytics.py` (optional PostHog telemetry, disabled with `ANONYMIZED_TELEMETRY=false`; records tool names and errors only, never arguments or outputs), `auth.py` and `oauth.py` (bearer-token and OAuth middleware for HTTP transports), `security.py` (SSRF validation, IP allowlist middleware), `config.py` (server configuration). Note `windows_mcp/config.py` at the package root is unrelated — it only holds the `WINDOWS_MCP_DEBUG` helpers.\n\n## Code Style\n\n- Formatter/linter: **Ruff** (line length 100, double quotes)\n- Naming: PEP 8 — `snake_case` functions/variables, `PascalCase` classes, `UPPER_CASE` constants\n- Type hints required on function signatures\n- Google-style docstrings for public functions/classes\n\n## Key Design Details\n\n- Screenshots are capped to 1920x1080 for token efficiency\n- Mouse/keyboard input uses UIA (same coordinate space as BoundingRectangle; no DPI mismatch)\n- Screenshot is the preferred fast visual-context tool; Snapshot is the heavier path for UI element ids and DOM extraction\n- Browser detection (Chrome, Edge, Firefox) triggers special DOM extraction mode in Snapshot\n- Fuzzy string matching (`thefuzz`) is used for element name matching\n- UI element fetching has retry logic (`THREAD_MAX_RETRIES=3` in tree service)\n- The server supports stdio, SSE, and streamable HTTP transports\n\n## Environment Variables\n\n| Variable | Default | Description |\n|---|---|---|\n| `WINDOWS_MCP_SCREENSHOT_SCALE` | `1.0` | Scale factor for screenshots (range `0.1`–`1.0`). Lower on 1440p/4K to stay under Claude Desktop's 1 MB limit. Resolved in `tools/_snapshot_helpers.py`. |\n| `WINDOWS_MCP_SCREENSHOT_BACKEND` | `auto` | Screenshot backend: `auto`, `dxcam`, `mss`, `pillow`. Resolved in `desktop/screenshot.py`. |\n| `WINDOWS_MCP_MAX_TREE_ELEMENTS` | `500` | Max UI elements a single Snapshot/WaitFor tree capture may collect before it stops descending and returns a truncated tree (with a note in the output). Bounds both traversal time and response size on huge flat lists/grids (e.g. an unfiltered inventory view with thousands of rows). Resolved in `tree/budget.py`. |\n| `WINDOWS_MCP_PROFILE_SNAPSHOT` | _(off)_ | Set to `1`/`true`/`yes`/`on` to log per-stage timing for Screenshot/Snapshot. Checked in `tools/_snapshot_helpers.py` and `desktop/service.py`. |\n| `ANONYMIZED_TELEMETRY` | `true` | Set to `false` to disable PostHog telemetry. Checked in `__main__.py` and `infrastructure/analytics.py`. |\n| `POSTHOG_API_KEY` | Project default | Override the PostHog project write key used for anonymous telemetry. Set to an empty string to skip PostHog client initialization. Checked in `infrastructure/analytics.py`. |\n| `POSTHOG_HOST` | `https://us.i.posthog.com` | Override the PostHog host for anonymous telemetry, such as for a self-hosted PostHog deployment. Checked in `infrastructure/analytics.py`. |\n| `WINDOWS_MCP_WATCHDOG` | _(off)_ | Set to `on`/`1`/`true`/`yes`/`enabled` to start the UIA focus WatchDog thread. Unset, or any other value, leaves it off. Opt-in because it only emits debug logging today but can crash the server via the UIA event pump (#332). Resolved in `__main__.py`. |\n| `WINDOWS_MCP_DEBUG` | `false` | Set to `1`/`true`/`yes`/`on` to enable debug mode. Checked in `config.py`. Also available as `--debug` CLI flag. |\n| `WINDOWS_MCP_DISABLE_FLASH` | _(off)_ | Set to `1`/`true`/`yes`/`on` to suppress the orange-red glowing border that briefly appears after every screenshot. Resolved in `desktop/flash_overlay.py`. |\n\n## Security Context\n\nThis server has **full system access** with no sandboxing. `PowerShell`, `FileSystem`, `Registry`, `Process`, and `App` can all perform irreversible operations, and there is no audit log or rollback. The recommended deployment target is a VM or Windows Sandbox. Use `serve --exclude-tools` to drop the tools a given deployment does not need.\n",".claude/skills/windows-mcp-tool-tester/SKILL.md":"---\nname: windows-mcp-tool-tester\ndescription: >\n  Automated testing skill for Windows-MCP tools. Use this skill whenever the user wants to test,\n  validate, benchmark, or evaluate any Windows-MCP tool (App, PowerShell, Screenshot, Snapshot,\n  Click, Type, Scroll, Move, Shortcut, Wait, MultiSelect, MultiEdit, Clipboard, Process,\n  Notification, FileSystem, Registry, Scrape). Triggers on phrases like \"test the Click tool\",\n  \"benchmark Screenshot\", \"validate FileSystem\", \"run QA on Registry\", \"check if PowerShell works\",\n  \"evaluate tool performance\", or any mention of testing/validating a Windows-MCP tool.\n  Each invocation tests exactly ONE tool.\n---\n\n# Windows-MCP Tool Tester\n\nAn automated testing skill that generates comprehensive test cases for a single Windows-MCP tool,\nexecutes them, and produces a structured test report with pass/fail results, performance metrics,\nand actionable recommendations.\n\n## Core Principles\n\n- **One tool per invocation.** If the user doesn't specify which tool to test, ask them before proceeding.\n- **Black-box testing only.** Derive test cases exclusively from the MCP tool description and parameter schema — never read source code. Silence in the schema is a documentation gap, not a testing hint.\n- **Auto-generate test cases** from the tool's MCP description and parameter schema. Cover common scenarios, edge cases, parameter combinations, and error handling paths.\n- **Measure two dimensions**: correctness (return value matches expectations) and response time (end-to-end, including MCP overhead).\n- **Mandatory side-effect verification**: every tool call that may modify system state MUST be independently verified — no exceptions, no sampling.\n- **Safe cleanup**: track process PIDs spawned during testing; only kill those specific PIDs during teardown, never kill by process name alone.\n- **Safety first**: Windows-MCP has full system access with no sandboxing. Tests involving\n  destructive tools (FileSystem delete, Registry set/delete, Process kill, PowerShell) can\n  modify or destroy data. Running in a **VM or Windows Sandbox** is strongly recommended.\n  Before executing destructive test cases, confirm the user accepts the risk. See `SECURITY.md`.\n- **Produce a structured report** at the end (see Step 4).\n\n---\n\n## Step 0: Identify the Target Tool\n\nIf the user hasn't specified a tool, present the full list and ask them to pick one:\n\n> App, PowerShell, Screenshot, Snapshot, Click, Type, Scroll, Move, Shortcut, Wait,\n> MultiSelect, MultiEdit, Clipboard, Process, Notification, FileSystem, Registry, Scrape\n\nOnce a tool is confirmed, proceed to Step 1. Do NOT test multiple tools in one session.\n\n---\n\n## Step 1: Analyze the Tool\n\nRead the tool's MCP description and parameter schema via the MCP server's tool listing. Identify:\n\n1. **All parameters** — name, type, required/optional, default value, allowed values (enums)\n2. **All modes** (if the tool is mode-based, e.g., FileSystem has read/write/copy/move/delete/list/search/info)\n3. **Return value structure** — what the tool returns on success vs. failure\n4. **Side effects** — does it modify system state? (important for test isolation)\n5. **Dependencies** — does it require a running app, an open window, existing files, etc.?\n\nUse this analysis to inform test case generation. If the description is ambiguous or silent on a\nbehavior, note it as a documentation gap and design a test to probe it. The tool's response is\nthe ground truth.\n\n---\n\n## Step 2: Generate Test Cases\n\nDesign test cases that cover the following categories. Not every category applies to every tool —\nuse judgment based on the tool's nature.\n\n### Category A: Basic Functionality (Required)\nTest the tool's primary purpose with standard, well-formed inputs.\n- One test per mode/operation type (e.g., for FileSystem: read, write, list, etc.)\n- Use realistic parameter values\n\n### Category B: Parameter Variations (Required)\n- Test each optional parameter individually to verify it takes effect\n- Test enum parameters with every allowed value\n- Test boolean parameters in both true and false states\n- **For `anyOf` union types**: The schema advertises all listed types as valid, so the tool must handle each correctly.\n  - `anyOf: [boolean, string]` (e.g., `drag`, `use_vision`): test boolean `true`/`false` AND string `\"true\"`/`\"false\"` — both must produce the same behavior.\n  - **Caveat:** MCP transport layers may silently coerce `\"true\"` (string) to `true` (boolean)\n    before the tool sees it. To genuinely probe the string path, also test non-standard truthy\n    strings like `\"yes\"` or `\"1\"` — if those fail while `\"true\"` passes, the tool likely only\n    receives booleans and the string branch is untested.\n  - `anyOf: [<type>, null]` (nullable): test with a valid value AND explicit `null`. An unhandled TypeError on null is a FAIL.\n- Test with default values (omit optional params) vs. explicit values\n\n### Category C: Edge Cases (Required)\n- Empty strings, zero values, negative numbers where applicable\n- Boundary values (e.g., very long text for Type, timeout=0 for PowerShell)\n- Unicode / special characters in string parameters\n- Very large or very small numeric inputs\n\n### Category D: Error Handling (Required)\n- Missing required parameters\n- Invalid parameter types or out-of-range values\n- Referencing nonexistent resources (files, windows, processes, registry keys)\n- Operations that should fail gracefully (e.g., deleting a non-existent file)\n\n### Category E: Parameter Interaction (When Applicable)\n- Combinations of parameters that might interact (e.g., Click with both `loc` and `label`)\n- Mutually exclusive parameters\n- Mode-specific parameter requirements\n- **Cross-mode parameter applicability**: For mode-based tools, pass parameters meant for one\n  mode while calling another (e.g., `window_loc` in `launch` mode). Silently ignoring them is\n  a documentation gap worth reporting.\n\n### Category F: Idempotency & State (When Applicable)\n- For tools marked `idempotentHint: true`: call twice with same args, verify same result\n- For destructive tools: verify cleanup or rollback is possible\n- For stateful tools: verify state changes are reflected correctly\n\n### Test Case Format\n\nFor each test case, define:\n\n```\nID:          TC-{ToolName}-{Number}\nCategory:    A/B/C/D/E/F\nDescription: What this test verifies\nParameters:  The exact parameters to pass\nExpected:    What a correct result looks like (success/failure, key content in response)\nSetup:       Any prerequisite actions (create a file, open an app, etc.)\nTeardown:    Any cleanup actions after the test\n```\n\nPresent the test plan to the user for confirmation before executing.\nAim for **10-20 test cases** depending on tool complexity.\n\nInclude an **estimated execution time**: approximately **30-45 seconds** per test case\n(includes timing calls, tool execution, verification). App launches add 5-10s extra.\nPresent as a range, e.g., \"Estimated execution time: 8-12 minutes (15 test cases)\".\n\n---\n\n## Step 3: Execute Tests\n\n### Pre-Test Step 1: Gather Environment Info\n\nBefore running test cases, collect the test environment details for the report. Use these\nPowerShell commands for reliable results:\n\n```powershell\n# OS version\n(Get-CimInstance Win32_OperatingSystem).Caption + \" \" + (Get-CimInstance Win32_OperatingSystem).Version\n\n# Display resolution (physical pixels)\nGet-CimInstance Win32_VideoController | Select-Object CurrentHorizontalResolution, CurrentVerticalResolution\n\n# Display count\n(Get-CimInstance Win32_PnPEntity | Where-Object { $_.PNPClass -eq 'Monitor' -and $_.Status -eq 'OK' }).Count\n\n# DPI scale factor (96 = 100%, 120 = 125%, 144 = 150%, 192 = 200%)\nGet-ItemProperty 'HKCU:\\Control Panel\\Desktop\\WindowMetrics' -Name AppliedDPI -ErrorAction SilentlyContinue | Select-Object -ExpandProperty AppliedDPI\n```\n\nAlso call Screenshot once — its `Screenshot Original Size` cross-checks the DPI value,\nand its output includes `Active Desktop` and `All Desktops`.\n\n### Pre-Test Step 2: Prepare Environment\n\nFor **input tools** (Type, Click, Scroll, Move, Shortcut, MultiSelect, MultiEdit), prepare the\nenvironment before executing any test cases:\n\n1. **IME (Input Method) state**: Check the Tray Input Indicator in the Snapshot output. If it\n   shows a non-English input mode (e.g., \"Chinese Mode\", \"Japanese Mode\"), switch to English\n   mode first using the `Shortcut` tool (typically `shift` to toggle). **This is critical for\n   Type tool tests** — an active IME will intercept keystrokes and produce incorrect characters.\n   Record the original IME state and restore it after testing.\n\n2. **Label availability check**: Call Snapshot on the test target window and verify whether the\n   element you intend to use with `label` parameter is actually listed in the Interactive Elements.\n   Common pitfalls:\n   - Modern Windows 11 Notepad's text editing area is **not** exposed as an interactive element\n     in the UI tree — use `loc` coordinates instead.\n   - Some complex controls (e.g., rich text editors, canvas-based UIs) may not enumerate child\n     elements.\n   If a planned `label`-based test has no valid label target, adapt the test to use `loc`, or\n   pick a different element that does have a label (e.g., a search box, address bar).\n\n3. **Warm-up call**: Execute 1-2 throwaway tool calls (not counted in test results) to warm up\n   the MCP connection, window focus, and UI tree cache. First calls are typically slower due to\n   cold start effects — excluding them gives more representative performance numbers.\n\n### Test Execution\n\nRun each test case sequentially. For each test:\n\n> **Label freshness rule:** Snapshot labels are a point-in-time snapshot. If any action between\n> tests could change the UI state, call Snapshot again before using `label` parameters.\n\n> **State reset between tests:** Each test case should start from a known, clean state. For\n> input tools sharing a test window (e.g., Notepad), define a standard reset procedure and\n> execute it in Setup:\n> - **Type tests**: Shortcut (Ctrl+A) → Shortcut (Delete) to clear the text area\n> - **Click/Move tests**: Move cursor to a neutral position away from interactive elements\n> - **Scroll tests**: Reset scroll position to top (Ctrl+Home)\n>\n> If a test's Setup includes `clear=true` in the tool call itself, you may skip the manual\n> reset — but verify in the teardown that the state is clean for the next test.\n\n1. **Setup** — perform any prerequisite actions (e.g., create a temp file for FileSystem read tests).\n   When spawning processes, **record their PIDs** for teardown (see Test Isolation Guidelines).\n2. **Record start time** — call PowerShell to capture a precise timestamp in milliseconds **before** calling the tool:\n   ```powershell\n   [long](([System.DateTime]::UtcNow - [System.DateTime]::UnixEpoch).TotalMilliseconds)\n   ```\n   Save the returned integer as `$t_start`.\n3. **Call the MCP tool** with the specified parameters\n4. **Record end time** — immediately after the tool returns, call PowerShell again with the same command. Save as `$t_end`.\n5. **Compute elapsed time** — `elapsed_ms = $t_end - $t_start`. Note: this includes MCP\n   overhead from the timestamp calls themselves (~3-5s each). Use for relative comparison\n   between test cases only. **When testing the PowerShell tool itself**, timing is\n   self-referential — record times as `N/A (self-referential)` and rely on the PowerShell\n   tool's own `timeout` behavior and status codes for performance assessment instead.\n6. **Capture the response** — store the full return value and measure `response_size`:\n   - **Text-only tools**: character count of the returned string.\n   - **Mixed-content tools** (Screenshot, Snapshot): character count of the **text portion only**,\n     note `+image` in the report. Do not attempt to measure image byte size.\n7. **Evaluate correctness** — compare the response against expected behavior:\n   - Does the response indicate success/failure as expected?\n   - Does the response content match expected patterns?\n   - For error cases: does the error message make sense and provide useful information?\n8. **Verify side effects (MANDATORY)** — independently verify EVERY mutating tool call. Never\n   rely solely on the tool's return value. Never skip or sample.\n   **Rule: verification MUST NOT use the same tool under test.** Use a different tool\n   (preferably PowerShell) to cross-check. Verification methods:\n   - **Move/Click**: call Screenshot or Snapshot to verify the expected UI change occurred.\n   - **Type**: use Shortcut (Ctrl+A → Ctrl+C) then PowerShell `Get-Clipboard` to capture\n     exact text for comparison.\n   - **Drag (Move with drag=True)**: call Snapshot to verify the target window actually moved.\n   - **App (launch/resize)**: call PowerShell (`Get-Process`) to verify process exists, and\n     Screenshot/Snapshot to verify window position/size.\n   - **FileSystem**: verify with PowerShell (`Test-Path`, `Get-Content`, `Get-ChildItem`)\n     — never with the FileSystem tool itself.\n   - **Registry**: verify with PowerShell (`Get-ItemProperty`, `reg query`)\n     — never with the Registry tool itself.\n   - **Clipboard (set)**: verify with PowerShell (`Get-Clipboard`)\n     — never with the Clipboard tool itself.\n   - **Process (kill)**: verify with PowerShell (`Get-Process -Id $pid`)\n     — never with the Process tool itself.\n   - **Shortcut**: call Screenshot to verify the shortcut's expected effect occurred.\n   - For read-only tools (Screenshot, Snapshot, Scrape, Process list), this step is not needed.\n   - If verification fails but the tool reported success, mark the test as **FAIL** and note\n     \"tool reported success but side effect not confirmed\" in the root cause analysis.\n9. **Teardown** — clean up any side effects (delete temp files, close apps, etc.)\n\n> **IMPORTANT:** Never estimate response times. Always use the PowerShell measurement above.\n> If unavailable, record `N/A` and explain why.\n\n### Correctness Evaluation Criteria\n\n| Result    | Meaning                                                                                       |\n|-----------|-----------------------------------------------------------------------------------------------|\n| PASS      | Response matches expected behavior exactly                                                    |\n| SOFT PASS | Response is acceptable but slightly different from ideal (e.g., extra whitespace, ordering)    |\n| FAIL      | Response doesn't match expected behavior — includes cases where the tool rejects schema-valid input. Never look up source code to explain away a failure. |\n| ERROR     | Tool threw an unexpected exception or timed out                                               |\n| SKIP      | Test couldn't run due to missing prerequisites (document why)                                 |\n\n### When to SKIP vs. Adapt\n\nIf a planned test case cannot execute as designed (e.g., the target element has no `label` in the\nUI tree, or a required window state cannot be achieved), decide:\n\n- **SKIP** if the prerequisite is truly missing and no workaround exists. Document the reason.\n- **Adapt** if you can achieve the same test intent with a different approach (e.g., use `loc`\n  instead of `label`, use a different target app). Update the test case description and note the\n  adaptation in the report. Adapting is preferred over skipping when the test intent is still\n  achievable.\n\n### Performance Tracking\n\nFor each test case, record **response time (ms)** via PowerShell timestamps and\n**response size** (character count of the raw response text).\n\n> **Warm-up effect:** The first 1-2 tool calls in a session are typically slower due to MCP\n> connection warm-up, UI tree cache initialization, and window focus acquisition. If warm-up\n> calls were performed in Pre-Test, note this in the report. If not, flag the first test case's\n> timing as potentially inflated and exclude it from aggregate statistics (average, median, P95)\n> or mark it separately.\n\n---\n\n## Step 4: Generate the Test Report\n\n**Localization:** If the user specified a language, write the entire report in that language\n(headings, tables, commentary, recommendations). Keep test case IDs (e.g., TC-Move-01) in\nEnglish. The template below is a structural reference — translate all prose while preserving\nthe markdown structure.\n\n````markdown\n# Windows-MCP Tool Test Report: {ToolName}\n\n**Date:** {timestamp}\n**Tool:** {ToolName}\n**Total Test Cases:** {N}\n**PASS:** {P} | **SOFT PASS:** {SP} | **FAIL:** {F} | **ERROR:** {E} | **SKIP:** {S}\n**Overall Pass Rate:** {(P+SP)/N * 100}%\n\n---\n\n## 1. Test Environment\n\n{Record the environment to aid reproducibility. Data gathered in Pre-Test step.}\n\n| Item                     | Value                                                    |\n|--------------------------|----------------------------------------------------------|\n| OS Version               | {e.g., Windows 11 Pro 10.0.26200}                       |\n| Display Resolution       | {e.g., 2560x1440}                                       |\n| Screenshot Original Size | {e.g., 3840x2160 — this is resolution x scale factor}   |\n| Display Count            | {e.g., 1}                                                |\n| Active Virtual Desktop   | {e.g., Desktop 1}                                        |\n| MCP Transport            | {e.g., SSE via http://localhost:8088/sse}                |\n| Scale Factor             | {e.g., 150% (AppliedDPI=144)}                           |\n\n---\n\n## 2. Executive Summary\n\n{2-3 sentences summarizing the overall health of the tool. Highlight critical failures if any.\nNote any patterns — e.g., \"all error-handling tests failed\" or \"basic functionality is solid\nbut Unicode support is incomplete.\" Also assess these dimensions when relevant:}\n\n- **Error message quality**: descriptive and actionable, or cryptic?\n- **Input validation**: does the tool validate params before executing, or fail deep with confusing errors?\n- **Consistency**: do repeated calls with same params return consistent results?\n- **Graceful degradation**: when prerequisites are missing, does the tool explain what's needed?\n\n---\n\n## 3. Failed & Error Test Cases\n\n{For each non-passing test case, provide:}\n\n### TC-{ID}: {Description}\n- **Category:** {category}\n- **Parameters:** `{params}`\n- **Expected:** {what should have happened}\n- **Actual:** {what actually happened}\n- **Side-Effect Verification:** {what the independent verification revealed, if applicable}\n- **Root Cause Analysis:** {your best assessment of why it failed}\n- **Suggested Fix:** {actionable recommendation for the developer}\n\n{If all tests passed, write: \"All test cases passed. No issues to report.\"}\n\n---\n\n## 4. Performance Analysis\n\n> **Note:** All times are end-to-end measurements including MCP transport overhead\n> (serialization, network round-trip, SSE/stdio latency). They do NOT represent pure tool\n> execution time. Use these numbers for **relative comparison** and outlier detection — not\n> as absolute benchmarks. For pure execution time, check server-side logs with\n> `WINDOWS_MCP_PROFILE_SNAPSHOT=1`.\n\n### Response Time\n\n| Test Case | Time (ms) | Assessment |\n|-----------|-----------|------------|\n| TC-XXX-01 | 6500      | Normal     |\n| TC-XXX-02 | 15200     | Slow       |\n| ...       | ...       | ...        |\n\n**Average:** {avg} ms | **Median:** {median} ms | **P95:** {p95} ms | **Max:** {max} ms\n\n**Assessment thresholds (end-to-end including MCP overhead):**\n- Fast: < 5000ms\n- Normal: 5000ms – 10000ms\n- Slow: 10000ms – 20000ms\n- Very Slow: > 20000ms\n\n{Commentary on any outliers or concerning patterns. When a test case is significantly slower\nthan peers, note possible causes: app launch wait, UI tree traversal, screenshot capture, etc.}\n\n### Response Size\n\n| Test Case | Response Size (chars) |\n|-----------|-----------------------|\n| TC-XXX-01 | 245                   |\n| ...       | ...                   |\n\n{Note any unexpectedly large or empty responses.}\n\n---\n\n## 5. Environmental Interference & Notes\n\n{List any environmental factors that affected test execution but are not bugs in the tool itself.\nThese factors help future testers reproduce results and avoid false failures.}\n\n| # | Factor | Impact | Mitigation |\n|---|--------|--------|------------|\n| 1 | {e.g., IME in Chinese mode} | {e.g., TC-Type-01 typed wrong characters} | {e.g., Switched IME to English before retesting} |\n| ... | ... | ... | ... |\n\n**Common environmental factors:**\n- **IME state**: Active non-English input methods intercept keystrokes (affects Type, Shortcut)\n- **Notification popups**: System or app notifications may steal focus mid-test\n- **Background app focus changes**: Chat apps, update dialogs may overlay the test window\n- **Screen lock / screensaver**: Can interrupt long-running test sessions\n- **Clipboard managers**: Third-party clipboard tools may interfere with Clipboard tests\n\n{If no environmental interference occurred, write: \"No environmental interference observed.\"}\n\n---\n\n## 6. Documentation & Schema Gaps\n\n{List any discrepancies between the tool's MCP parameter schema / description and its actual\nbehavior or environmental interactions. These are not necessarily bugs — they are places where\nthe documentation or schema could be improved to set correct expectations for callers.}\n\n| #   | Gap Type                          | Description | Recommendation |\n|-----|-----------------------------------|-------------|----------------|\n| 1   | {schema / description / behavior} | {desc}      | {rec}          |\n| ... | ...                               | ...         | ...            |\n\n**Gap Types:**\n- **schema**: parameter schema (types, required/optional, allowed values) does not match actual behavior\n- **description**: tool description is silent or ambiguous about a behavior that testing revealed\n- **behavior**: tool behaves inconsistently with what the schema + description together imply\n\n{If no gaps were found, write: \"No documentation or schema gaps identified.\"}\n\n---\n\n## 7. All Test Cases\n\n| ID         | Category   | Description | Result | Time (ms) | Response Size |\n|------------|------------|-------------|--------|-----------|---------------|\n| TC-XXX-01  | A - Basic  | {desc}      | PASS   | 6500      | 245           |\n| TC-XXX-02  | B - Params | {desc}      | FAIL   | 8200      | 310           |\n| ...        | ...        | ...         | ...    | ...       | ...           |\n````\n\n---\n\n## Test Isolation Guidelines\n\nTo avoid polluting the system or interfering with user state:\n\n- **FileSystem tests**: Use a dedicated temp directory (e.g., `%TEMP%\\wmcp-test-{timestamp}\\`).\n  Clean up after all tests complete.\n- **Registry tests**: Use a dedicated test key under `HKCU:\\Software\\WMCP-Test-{timestamp}`.\n  Delete the entire key after testing.\n- **Process tests**: Only list processes (don't kill user processes). If testing kill, spawn a\n  sacrificial process first (e.g., `notepad.exe`) and record its PID.\n- **App tests**: Use lightweight apps (Notepad, Calculator). **Record PIDs** of all processes\n  spawned during testing (use `(Start-Process notepad -PassThru).Id` or query process list\n  before/after launch). In teardown, only kill processes by PID — NEVER by name (e.g.,\n  `Stop-Process -Id $pid`, not `Stop-Process -Name notepad`), because the user may have their\n  own instances of the same application running.\n  - **Modern tabbed apps caveat:** Windows 11 Notepad/Terminal may reuse a single process for\n    multiple tabs. Diff the process list before/after each launch to detect new PIDs. Only kill\n    PIDs that did not exist before testing began.\n- **Clipboard tests**: Save and restore the original clipboard content.\n- **Input tools (Click, Type, Scroll, Move, Shortcut)**: Open a dedicated test window\n  (e.g., Notepad) to receive input. Don't interact with user's active work.\n  See also Pre-Test Step 2 for IME state handling — switch to English input mode before testing\n  and restore the original state in final teardown.\n- **Read-only tools (Screenshot, Snapshot, Scrape)**: Safe to run freely.\n- **Notification tests**: User-visible (sends Windows toasts). Avoid repeated or unnecessary\n  notifications. Prefer a single clearly labeled test notification per test case.\n- **PowerShell tests**: Use read-only commands where possible.\n\n---\n\n## Tool-Specific Testing Guidance\n\nHints per tool. Always read the actual schema to discover additional scenarios beyond these.\n\n### App\n- Modes: launch, resize, switch. Test each mode.\n- Launch: test with known apps (notepad, calc), unknown app names\n- Resize: test with valid window_loc/window_size, without an active app\n- Switch: test switching to a running app, to a non-existent app\n\n### PowerShell\n- Simple commands: `echo \"hello\"`, `Get-Date`, `Get-Process | Select-Object -First 3`\n- Timeout behavior: set a very short timeout with a long-running command\n- Encoding: commands with Unicode output\n- Error output: commands that write to stderr\n- Exit codes: commands that fail (e.g., `Get-Item nonexistent`)\n\n### Screenshot\n- Default parameters (no args)\n- With annotation enabled/disabled\n- With reference lines\n- With specific display index\n- Verify return includes image data\n\n### Snapshot\n- Various flag combinations: use_vision, use_dom, use_annotation, use_ui_tree\n- All flags off vs. all flags on\n- With/without reference lines\n\n### Click\n- By coordinates (loc) vs. by label\n- Different button types: left, right, middle\n- clicks=0 (hover), clicks=1 (single), clicks=2 (double)\n- Invalid coordinates (negative, off-screen)\n- Invalid label (non-existent element ID)\n\n### Type\n- Normal text, Unicode text, special characters\n- With and without clear=true\n- With and without press_enter=true\n- Different caret_position values: start, idle, end\n- By coordinates vs. by label\n- **IME sensitivity**: Test with IME active to verify behavior (expect failure if tool uses\n  keystroke simulation rather than Unicode input). This is a high-value edge case because\n  many Windows machines have non-English IMEs installed.\n- **Emoji / surrogate pair characters**: Test with characters outside the Basic Multilingual\n  Plane (e.g., 🌍, 😀) to verify supplementary plane Unicode support.\n- **Empty string**: Test `text=\"\"` — this is a common edge case that may crash if the\n  implementation indexes into the string without a length check.\n\n### Scroll\n- Vertical up/down, horizontal left/right\n- Different wheel_times values (1, 5, 10)\n- By coordinates vs. by label\n\n### Move\n- Simple move to coordinates\n- Drag mode (drag=true)\n- By coordinates vs. by label\n\n### Shortcut\n- Common shortcuts: ctrl+c, ctrl+v, ctrl+a, alt+tab\n- Windows key shortcuts: win+r, win+d\n- Multi-key combinations\n- Invalid key names\n\n### Wait\n- Short duration (1 second)\n- Zero duration\n- Verify actual elapsed time roughly matches requested duration\n\n### MultiSelect\n- Select multiple items by coordinates\n- Select by labels\n- With and without press_ctrl\n- Empty list of items\n\n### MultiEdit\n- Edit multiple fields by coordinates\n- Edit by labels\n- Mixed valid and invalid targets\n\n### Clipboard\n- get mode when clipboard has text\n- get mode when clipboard is empty\n- set mode with normal text\n- set mode with Unicode text\n- Roundtrip: set then get, verify content matches\n\n### Process\n- list mode with default sort\n- list mode with different sort_by values (memory, cpu, name)\n- list mode with name filter\n- list mode with different limit values\n- kill mode with a sacrificial process (spawn notepad, then kill it)\n\n### Notification\n- Valid notification with title, message, app_id\n- Empty title or message\n- Special characters in title/message\n\n### FileSystem\n- Full mode coverage: read, write, copy, move, delete, list, search, info\n- Read: existing file, non-existent file, offset/limit, different encodings\n- Write: new file, overwrite, append\n- List: with and without pattern, recursive, show_hidden\n- Delete: file, empty dir, non-empty dir with recursive\n\n### Registry\n- Full mode coverage: get, set, delete, list\n- Set and get roundtrip\n- Different value types (String, DWord, QWord)\n- Non-existent key/value\n- Use test-only registry path\n\n### Scrape\n- With a URL (lightweight page)\n- With and without query parameter\n- With use_dom enabled (requires open browser)\n- Invalid URL\n"},"files":{"CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Project Overview\n\nWindows-MCP is a Python MCP (Model Context Protocol) server that bridges AI LLM agents with the Windows OS, enabling direct desktop automation. It exposes 21 tools via FastMCP:\n\n| Group | Tools |\n|---|---|\n| Capture | `Screenshot`, `Snapshot`, `Scrape`, `DisplayInventory` |\n| Input | `Click`, `Type`, `Scroll`, `Move` (also drag-and-drop via `drag=True`), `Shortcut`, `MultiSelect`, `MultiEdit` |\n| Timing | `Wait`, `WaitFor` |\n| System | `App`, `PowerShell`, `FileSystem`, `Registry`, `Process`, `Clipboard`, `Notification`, `ControlStatus` |\n\nTool names are defined by the `name=` argument of each `@mcp.tool(...)` in `src/windows_mcp/tools/`; that directory is the source of truth. Note the shell tool is registered as `PowerShell`, not `Shell`. Any subset can be removed at startup with `serve --exclude-tools` (e.g. `windows-mcp serve --exclude-tools PowerShell,Registry`).\n\n## Build & Development Commands\n\n```bash\nuv sync --extra dev        # Install runtime and development dependencies\nuv run windows-mcp serve   # Run the MCP server\nuv run --extra dev ruff format .  # Format code\nuv run --extra dev ruff check .   # Lint code\nuv run --extra dev ruff check --fix .  # Lint and auto-fix\nuv run --extra dev pytest         # Run all tests\nuv run --extra dev pytest tests/test_desktop_views.py  # Run a single test file\n```\n\n**Package manager**: UV (not pip). **Python**: 3.14+. **Build backend**: setuptools.\n\n## Architecture\n\nThe codebase follows a layered service architecture under `src/windows_mcp/`:\n\n**Entry point** — `__main__.py`: Builds the FastMCP server, parses CLI flags, and selects the transport. Tool registration is delegated to `tools.register_all()`; an async lifespan initializes the Desktop, WatchDog, and Analytics singletons, which tools resolve lazily through the `get_desktop` / `get_analytics` callables.\n\n**Tools layer** — `tools/`: One module per tool group, each exposing `register(mcp, *, get_desktop, get_analytics)`. `tools/__init__.py` holds the module list and `register_all()`. Tool functions are thin — they normalize arguments and delegate to a service package. The `@with_analytics` decorator wraps each one for telemetry, making it the existing precedent for cross-cutting concerns at the tool boundary.\n\n**Desktop service** — `desktop/service.py`: High-level orchestrator. Manages window operations (launch, resize, switch), screenshots, mouse/keyboard actions, and clipboard. Interfaces with Tree service for UI element discovery. `desktop/views.py` defines data models: `DesktopState`, `Window`, `Size`, `BoundingBox`, `Status`.\n\n**Tree service** — `tree/service.py`: Captures the Windows accessibility tree from active and background windows. Identifies interactive elements and scrollable areas. Uses `ThreadPoolExecutor` for multi-threaded UI traversal. `tree/views.py` defines `TreeElementNode`, `ScrollElementNode`, `TreeState`. `tree/config.py` has control type configurations.\n\n**UIAutomation wrapper** — `uia/`: Low-level abstraction over the Windows UIAutomation COM API via `comtypes`. `core.py` wraps the main automation object, `controls.py` has control-specific logic, `patterns.py` wraps UIAutomation patterns, `enums.py` has COM enumerations, `events.py` handles event subscriptions.\n\n**WatchDog** — `watchdog/service.py`: Runs in a separate thread monitoring UI focus changes via UIAutomation events. Notifies the Tree service of focus changes so the accessibility tree stays current.\n\n**Virtual Desktop Manager** — `vdm/core.py`: Tracks which windows belong to which Windows virtual desktop (Win10/11).\n\n**Domain services** — thin packages backing the system tools: `filesystem/` (read/write/copy/move/delete/list/search/info), `registry/` (get/set/delete/list, implemented via PowerShell cmdlets), `powershell/` (`PowerShellExecutor` plus environment resolution), `process/` (list/kill), `notifications/`. Registry and PowerShell tools shell out, so their latency is dominated by process startup.\n\n**Infrastructure** — `infrastructure/`: cross-cutting concerns. `analytics.py` (optional PostHog telemetry, disabled with `ANONYMIZED_TELEMETRY=false`; records tool names and errors only, never arguments or outputs), `auth.py` and `oauth.py` (bearer-token and OAuth middleware for HTTP transports), `security.py` (SSRF validation, IP allowlist middleware), `config.py` (server configuration). Note `windows_mcp/config.py` at the package root is unrelated — it only holds the `WINDOWS_MCP_DEBUG` helpers.\n\n## Code Style\n\n- Formatter/linter: **Ruff** (line length 100, double quotes)\n- Naming: PEP 8 — `snake_case` functions/variables, `PascalCase` classes, `UPPER_CASE` constants\n- Type hints required on function signatures\n- Google-style docstrings for public functions/classes\n\n## Key Design Details\n\n- Screenshots are capped to 1920x1080 for token efficiency\n- Mouse/keyboard input uses UIA (same coordinate space as BoundingRectangle; no DPI mismatch)\n- Screenshot is the preferred fast visual-context tool; Snapshot is the heavier path for UI element ids and DOM extraction\n- Browser detection (Chrome, Edge, Firefox) triggers special DOM extraction mode in Snapshot\n- Fuzzy string matching (`thefuzz`) is used for element name matching\n- UI element fetching has retry logic (`THREAD_MAX_RETRIES=3` in tree service)\n- The server supports stdio, SSE, and streamable HTTP transports\n\n## Environment Variables\n\n| Variable | Default | Description |\n|---|---|---|\n| `WINDOWS_MCP_SCREENSHOT_SCALE` | `1.0` | Scale factor for screenshots (range `0.1`–`1.0`). Lower on 1440p/4K to stay under Claude Desktop's 1 MB limit. Resolved in `tools/_snapshot_helpers.py`. |\n| `WINDOWS_MCP_SCREENSHOT_BACKEND` | `auto` | Screenshot backend: `auto`, `dxcam`, `mss`, `pillow`. Resolved in `desktop/screenshot.py`. |\n| `WINDOWS_MCP_MAX_TREE_ELEMENTS` | `500` | Max UI elements a single Snapshot/WaitFor tree capture may collect before it stops descending and returns a truncated tree (with a note in the output). Bounds both traversal time and response size on huge flat lists/grids (e.g. an unfiltered inventory view with thousands of rows). Resolved in `tree/budget.py`. |\n| `WINDOWS_MCP_PROFILE_SNAPSHOT` | _(off)_ | Set to `1`/`true`/`yes`/`on` to log per-stage timing for Screenshot/Snapshot. Checked in `tools/_snapshot_helpers.py` and `desktop/service.py`. |\n| `ANONYMIZED_TELEMETRY` | `true` | Set to `false` to disable PostHog telemetry. Checked in `__main__.py` and `infrastructure/analytics.py`. |\n| `POSTHOG_API_KEY` | Project default | Override the PostHog project write key used for anonymous telemetry. Set to an empty string to skip PostHog client initialization. Checked in `infrastructure/analytics.py`. |\n| `POSTHOG_HOST` | `https://us.i.posthog.com` | Override the PostHog host for anonymous telemetry, such as for a self-hosted PostHog deployment. Checked in `infrastructure/analytics.py`. |\n| `WINDOWS_MCP_WATCHDOG` | _(off)_ | Set to `on`/`1`/`true`/`yes`/`enabled` to start the UIA focus WatchDog thread. Unset, or any other value, leaves it off. Opt-in because it only emits debug logging today but can crash the server via the UIA event pump (#332). Resolved in `__main__.py`. |\n| `WINDOWS_MCP_DEBUG` | `false` | Set to `1`/`true`/`yes`/`on` to enable debug mode. Checked in `config.py`. Also available as `--debug` CLI flag. |\n| `WINDOWS_MCP_DISABLE_FLASH` | _(off)_ | Set to `1`/`true`/`yes`/`on` to suppress the orange-red glowing border that briefly appears after every screenshot. Resolved in `desktop/flash_overlay.py`. |\n\n## Security Context\n\nThis server has **full system access** with no sandboxing. `PowerShell`, `FileSystem`, `Registry`, `Process`, and `App` can all perform irreversible operations, and there is no audit log or rollback. The recommended deployment target is a VM or Windows Sandbox. Use `serve --exclude-tools` to drop the tools a given deployment does not need.\n",".claude/skills/windows-mcp-tool-tester/SKILL.md":"---\nname: windows-mcp-tool-tester\ndescription: >\n  Automated testing skill for Windows-MCP tools. Use this skill whenever the user wants to test,\n  validate, benchmark, or evaluate any Windows-MCP tool (App, PowerShell, Screenshot, Snapshot,\n  Click, Type, Scroll, Move, Shortcut, Wait, MultiSelect, MultiEdit, Clipboard, Process,\n  Notification, FileSystem, Registry, Scrape). Triggers on phrases like \"test the Click tool\",\n  \"benchmark Screenshot\", \"validate FileSystem\", \"run QA on Registry\", \"check if PowerShell works\",\n  \"evaluate tool performance\", or any mention of testing/validating a Windows-MCP tool.\n  Each invocation tests exactly ONE tool.\n---\n\n# Windows-MCP Tool Tester\n\nAn automated testing skill that generates comprehensive test cases for a single Windows-MCP tool,\nexecutes them, and produces a structured test report with pass/fail results, performance metrics,\nand actionable recommendations.\n\n## Core Principles\n\n- **One tool per invocation.** If the user doesn't specify which tool to test, ask them before proceeding.\n- **Black-box testing only.** Derive test cases exclusively from the MCP tool description and parameter schema — never read source code. Silence in the schema is a documentation gap, not a testing hint.\n- **Auto-generate test cases** from the tool's MCP description and parameter schema. Cover common scenarios, edge cases, parameter combinations, and error handling paths.\n- **Measure two dimensions**: correctness (return value matches expectations) and response time (end-to-end, including MCP overhead).\n- **Mandatory side-effect verification**: every tool call that may modify system state MUST be independently verified — no exceptions, no sampling.\n- **Safe cleanup**: track process PIDs spawned during testing; only kill those specific PIDs during teardown, never kill by process name alone.\n- **Safety first**: Windows-MCP has full system access with no sandboxing. Tests involving\n  destructive tools (FileSystem delete, Registry set/delete, Process kill, PowerShell) can\n  modify or destroy data. Running in a **VM or Windows Sandbox** is strongly recommended.\n  Before executing destructive test cases, confirm the user accepts the risk. See `SECURITY.md`.\n- **Produce a structured report** at the end (see Step 4).\n\n---\n\n## Step 0: Identify the Target Tool\n\nIf the user hasn't specified a tool, present the full list and ask them to pick one:\n\n> App, PowerShell, Screenshot, Snapshot, Click, Type, Scroll, Move, Shortcut, Wait,\n> MultiSelect, MultiEdit, Clipboard, Process, Notification, FileSystem, Registry, Scrape\n\nOnce a tool is confirmed, proceed to Step 1. Do NOT test multiple tools in one session.\n\n---\n\n## Step 1: Analyze the Tool\n\nRead the tool's MCP description and parameter schema via the MCP server's tool listing. Identify:\n\n1. **All parameters** — name, type, required/optional, default value, allowed values (enums)\n2. **All modes** (if the tool is mode-based, e.g., FileSystem has read/write/copy/move/delete/list/search/info)\n3. **Return value structure** — what the tool returns on success vs. failure\n4. **Side effects** — does it modify system state? (important for test isolation)\n5. **Dependencies** — does it require a running app, an open window, existing files, etc.?\n\nUse this analysis to inform test case generation. If the description is ambiguous or silent on a\nbehavior, note it as a documentation gap and design a test to probe it. The tool's response is\nthe ground truth.\n\n---\n\n## Step 2: Generate Test Cases\n\nDesign test cases that cover the following categories. Not every category applies to every tool —\nuse judgment based on the tool's nature.\n\n### Category A: Basic Functionality (Required)\nTest the tool's primary purpose with standard, well-formed inputs.\n- One test per mode/operation type (e.g., for FileSystem: read, write, list, etc.)\n- Use realistic parameter values\n\n### Category B: Parameter Variations (Required)\n- Test each optional parameter individually to verify it takes effect\n- Test enum parameters with every allowed value\n- Test boolean parameters in both true and false states\n- **For `anyOf` union types**: The schema advertises all listed types as valid, so the tool must handle each correctly.\n  - `anyOf: [boolean, string]` (e.g., `drag`, `use_vision`): test boolean `true`/`false` AND string `\"true\"`/`\"false\"` — both must produce the same behavior.\n  - **Caveat:** MCP transport layers may silently coerce `\"true\"` (string) to `true` (boolean)\n    before the tool sees it. To genuinely probe the string path, also test non-standard truthy\n    strings like `\"yes\"` or `\"1\"` — if those fail while `\"true\"` passes, the tool likely only\n    receives booleans and the string branch is untested.\n  - `anyOf: [<type>, null]` (nullable): test with a valid value AND explicit `null`. An unhandled TypeError on null is a FAIL.\n- Test with default values (omit optional params) vs. explicit values\n\n### Category C: Edge Cases (Required)\n- Empty strings, zero values, negative numbers where applicable\n- Boundary values (e.g., very long text for Type, timeout=0 for PowerShell)\n- Unicode / special characters in string parameters\n- Very large or very small numeric inputs\n\n### Category D: Error Handling (Required)\n- Missing required parameters\n- Invalid parameter types or out-of-range values\n- Referencing nonexistent resources (files, windows, processes, registry keys)\n- Operations that should fail gracefully (e.g., deleting a non-existent file)\n\n### Category E: Parameter Interaction (When Applicable)\n- Combinations of parameters that might interact (e.g., Click with both `loc` and `label`)\n- Mutually exclusive parameters\n- Mode-specific parameter requirements\n- **Cross-mode parameter applicability**: For mode-based tools, pass parameters meant for one\n  mode while calling another (e.g., `window_loc` in `launch` mode). Silently ignoring them is\n  a documentation gap worth reporting.\n\n### Category F: Idempotency & State (When Applicable)\n- For tools marked `idempotentHint: true`: call twice with same args, verify same result\n- For destructive tools: verify cleanup or rollback is possible\n- For stateful tools: verify state changes are reflected correctly\n\n### Test Case Format\n\nFor each test case, define:\n\n```\nID:          TC-{ToolName}-{Number}\nCategory:    A/B/C/D/E/F\nDescription: What this test verifies\nParameters:  The exact parameters to pass\nExpected:    What a correct result looks like (success/failure, key content in response)\nSetup:       Any prerequisite actions (create a file, open an app, etc.)\nTeardown:    Any cleanup actions after the test\n```\n\nPresent the test plan to the user for confirmation before executing.\nAim for **10-20 test cases** depending on tool complexity.\n\nInclude an **estimated execution time**: approximately **30-45 seconds** per test case\n(includes timing calls, tool execution, verification). App launches add 5-10s extra.\nPresent as a range, e.g., \"Estimated execution time: 8-12 minutes (15 test cases)\".\n\n---\n\n## Step 3: Execute Tests\n\n### Pre-Test Step 1: Gather Environment Info\n\nBefore running test cases, collect the test environment details for the report. Use these\nPowerShell commands for reliable results:\n\n```powershell\n# OS version\n(Get-CimInstance Win32_OperatingSystem).Caption + \" \" + (Get-CimInstance Win32_OperatingSystem).Version\n\n# Display resolution (physical pixels)\nGet-CimInstance Win32_VideoController | Select-Object CurrentHorizontalResolution, CurrentVerticalResolution\n\n# Display count\n(Get-CimInstance Win32_PnPEntity | Where-Object { $_.PNPClass -eq 'Monitor' -and $_.Status -eq 'OK' }).Count\n\n# DPI scale factor (96 = 100%, 120 = 125%, 144 = 150%, 192 = 200%)\nGet-ItemProperty 'HKCU:\\Control Panel\\Desktop\\WindowMetrics' -Name AppliedDPI -ErrorAction SilentlyContinue | Select-Object -ExpandProperty AppliedDPI\n```\n\nAlso call Screenshot once — its `Screenshot Original Size` cross-checks the DPI value,\nand its output includes `Active Desktop` and `All Desktops`.\n\n### Pre-Test Step 2: Prepare Environment\n\nFor **input tools** (Type, Click, Scroll, Move, Shortcut, MultiSelect, MultiEdit), prepare the\nenvironment before executing any test cases:\n\n1. **IME (Input Method) state**: Check the Tray Input Indicator in the Snapshot output. If it\n   shows a non-English input mode (e.g., \"Chinese Mode\", \"Japanese Mode\"), switch to English\n   mode first using the `Shortcut` tool (typically `shift` to toggle). **This is critical for\n   Type tool tests** — an active IME will intercept keystrokes and produce incorrect characters.\n   Record the original IME state and restore it after testing.\n\n2. **Label availability check**: Call Snapshot on the test target window and verify whether the\n   element you intend to use with `label` parameter is actually listed in the Interactive Elements.\n   Common pitfalls:\n   - Modern Windows 11 Notepad's text editing area is **not** exposed as an interactive element\n     in the UI tree — use `loc` coordinates instead.\n   - Some complex controls (e.g., rich text editors, canvas-based UIs) may not enumerate child\n     elements.\n   If a planned `label`-based test has no valid label target, adapt the test to use `loc`, or\n   pick a different element that does have a label (e.g., a search box, address bar).\n\n3. **Warm-up call**: Execute 1-2 throwaway tool calls (not counted in test results) to warm up\n   the MCP connection, window focus, and UI tree cache. First calls are typically slower due to\n   cold start effects — excluding them gives more representative performance numbers.\n\n### Test Execution\n\nRun each test case sequentially. For each test:\n\n> **Label freshness rule:** Snapshot labels are a point-in-time snapshot. If any action between\n> tests could change the UI state, call Snapshot again before using `label` parameters.\n\n> **State reset between tests:** Each test case should start from a known, clean state. For\n> input tools sharing a test window (e.g., Notepad), define a standard reset procedure and\n> execute it in Setup:\n> - **Type tests**: Shortcut (Ctrl+A) → Shortcut (Delete) to clear the text area\n> - **Click/Move tests**: Move cursor to a neutral position away from interactive elements\n> - **Scroll tests**: Reset scroll position to top (Ctrl+Home)\n>\n> If a test's Setup includes `clear=true` in the tool call itself, you may skip the manual\n> reset — but verify in the teardown that the state is clean for the next test.\n\n1. **Setup** — perform any prerequisite actions (e.g., create a temp file for FileSystem read tests).\n   When spawning processes, **record their PIDs** for teardown (see Test Isolation Guidelines).\n2. **Record start time** — call PowerShell to capture a precise timestamp in milliseconds **before** calling the tool:\n   ```powershell\n   [long](([System.DateTime]::UtcNow - [System.DateTime]::UnixEpoch).TotalMilliseconds)\n   ```\n   Save the returned integer as `$t_start`.\n3. **Call the MCP tool** with the specified parameters\n4. **Record end time** — immediately after the tool returns, call PowerShell again with the same command. Save as `$t_end`.\n5. **Compute elapsed time** — `elapsed_ms = $t_end - $t_start`. Note: this includes MCP\n   overhead from the timestamp calls themselves (~3-5s each). Use for relative comparison\n   between test cases only. **When testing the PowerShell tool itself**, timing is\n   self-referential — record times as `N/A (self-referential)` and rely on the PowerShell\n   tool's own `timeout` behavior and status codes for performance assessment instead.\n6. **Capture the response** — store the full return value and measure `response_size`:\n   - **Text-only tools**: character count of the returned string.\n   - **Mixed-content tools** (Screenshot, Snapshot): character count of the **text portion only**,\n     note `+image` in the report. Do not attempt to measure image byte size.\n7. **Evaluate correctness** — compare the response against expected behavior:\n   - Does the response indicate success/failure as expected?\n   - Does the response content match expected patterns?\n   - For error cases: does the error message make sense and provide useful information?\n8. **Verify side effects (MANDATORY)** — independently verify EVERY mutating tool call. Never\n   rely solely on the tool's return value. Never skip or sample.\n   **Rule: verification MUST NOT use the same tool under test.** Use a different tool\n   (preferably PowerShell) to cross-check. Verification methods:\n   - **Move/Click**: call Screenshot or Snapshot to verify the expected UI change occurred.\n   - **Type**: use Shortcut (Ctrl+A → Ctrl+C) then PowerShell `Get-Clipboard` to capture\n     exact text for comparison.\n   - **Drag (Move with drag=True)**: call Snapshot to verify the target window actually moved.\n   - **App (launch/resize)**: call PowerShell (`Get-Process`) to verify process exists, and\n     Screenshot/Snapshot to verify window position/size.\n   - **FileSystem**: verify with PowerShell (`Test-Path`, `Get-Content`, `Get-ChildItem`)\n     — never with the FileSystem tool itself.\n   - **Registry**: verify with PowerShell (`Get-ItemProperty`, `reg query`)\n     — never with the Registry tool itself.\n   - **Clipboard (set)**: verify with PowerShell (`Get-Clipboard`)\n     — never with the Clipboard tool itself.\n   - **Process (kill)**: verify with PowerShell (`Get-Process -Id $pid`)\n     — never with the Process tool itself.\n   - **Shortcut**: call Screenshot to verify the shortcut's expected effect occurred.\n   - For read-only tools (Screenshot, Snapshot, Scrape, Process list), this step is not needed.\n   - If verification fails but the tool reported success, mark the test as **FAIL** and note\n     \"tool reported success but side effect not confirmed\" in the root cause analysis.\n9. **Teardown** — clean up any side effects (delete temp files, close apps, etc.)\n\n> **IMPORTANT:** Never estimate response times. Always use the PowerShell measurement above.\n> If unavailable, record `N/A` and explain why.\n\n### Correctness Evaluation Criteria\n\n| Result    | Meaning                                                                                       |\n|-----------|-----------------------------------------------------------------------------------------------|\n| PASS      | Response matches expected behavior exactly                                                    |\n| SOFT PASS | Response is acceptable but slightly different from ideal (e.g., extra whitespace, ordering)    |\n| FAIL      | Response doesn't match expected behavior — includes cases where the tool rejects schema-valid input. Never look up source code to explain away a failure. |\n| ERROR     | Tool threw an unexpected exception or timed out                                               |\n| SKIP      | Test couldn't run due to missing prerequisites (document why)                                 |\n\n### When to SKIP vs. Adapt\n\nIf a planned test case cannot execute as designed (e.g., the target element has no `label` in the\nUI tree, or a required window state cannot be achieved), decide:\n\n- **SKIP** if the prerequisite is truly missing and no workaround exists. Document the reason.\n- **Adapt** if you can achieve the same test intent with a different approach (e.g., use `loc`\n  instead of `label`, use a different target app). Update the test case description and note the\n  adaptation in the report. Adapting is preferred over skipping when the test intent is still\n  achievable.\n\n### Performance Tracking\n\nFor each test case, record **response time (ms)** via PowerShell timestamps and\n**response size** (character count of the raw response text).\n\n> **Warm-up effect:** The first 1-2 tool calls in a session are typically slower due to MCP\n> connection warm-up, UI tree cache initialization, and window focus acquisition. If warm-up\n> calls were performed in Pre-Test, note this in the report. If not, flag the first test case's\n> timing as potentially inflated and exclude it from aggregate statistics (average, median, P95)\n> or mark it separately.\n\n---\n\n## Step 4: Generate the Test Report\n\n**Localization:** If the user specified a language, write the entire report in that language\n(headings, tables, commentary, recommendations). Keep test case IDs (e.g., TC-Move-01) in\nEnglish. The template below is a structural reference — translate all prose while preserving\nthe markdown structure.\n\n````markdown\n# Windows-MCP Tool Test Report: {ToolName}\n\n**Date:** {timestamp}\n**Tool:** {ToolName}\n**Total Test Cases:** {N}\n**PASS:** {P} | **SOFT PASS:** {SP} | **FAIL:** {F} | **ERROR:** {E} | **SKIP:** {S}\n**Overall Pass Rate:** {(P+SP)/N * 100}%\n\n---\n\n## 1. Test Environment\n\n{Record the environment to aid reproducibility. Data gathered in Pre-Test step.}\n\n| Item                     | Value                                                    |\n|--------------------------|----------------------------------------------------------|\n| OS Version               | {e.g., Windows 11 Pro 10.0.26200}                       |\n| Display Resolution       | {e.g., 2560x1440}                                       |\n| Screenshot Original Size | {e.g., 3840x2160 — this is resolution x scale factor}   |\n| Display Count            | {e.g., 1}                                                |\n| Active Virtual Desktop   | {e.g., Desktop 1}                                        |\n| MCP Transport            | {e.g., SSE via http://localhost:8088/sse}                |\n| Scale Factor             | {e.g., 150% (AppliedDPI=144)}                           |\n\n---\n\n## 2. Executive Summary\n\n{2-3 sentences summarizing the overall health of the tool. Highlight critical failures if any.\nNote any patterns — e.g., \"all error-handling tests failed\" or \"basic functionality is solid\nbut Unicode support is incomplete.\" Also assess these dimensions when relevant:}\n\n- **Error message quality**: descriptive and actionable, or cryptic?\n- **Input validation**: does the tool validate params before executing, or fail deep with confusing errors?\n- **Consistency**: do repeated calls with same params return consistent results?\n- **Graceful degradation**: when prerequisites are missing, does the tool explain what's needed?\n\n---\n\n## 3. Failed & Error Test Cases\n\n{For each non-passing test case, provide:}\n\n### TC-{ID}: {Description}\n- **Category:** {category}\n- **Parameters:** `{params}`\n- **Expected:** {what should have happened}\n- **Actual:** {what actually happened}\n- **Side-Effect Verification:** {what the independent verification revealed, if applicable}\n- **Root Cause Analysis:** {your best assessment of why it failed}\n- **Suggested Fix:** {actionable recommendation for the developer}\n\n{If all tests passed, write: \"All test cases passed. No issues to report.\"}\n\n---\n\n## 4. Performance Analysis\n\n> **Note:** All times are end-to-end measurements including MCP transport overhead\n> (serialization, network round-trip, SSE/stdio latency). They do NOT represent pure tool\n> execution time. Use these numbers for **relative comparison** and outlier detection — not\n> as absolute benchmarks. For pure execution time, check server-side logs with\n> `WINDOWS_MCP_PROFILE_SNAPSHOT=1`.\n\n### Response Time\n\n| Test Case | Time (ms) | Assessment |\n|-----------|-----------|------------|\n| TC-XXX-01 | 6500      | Normal     |\n| TC-XXX-02 | 15200     | Slow       |\n| ...       | ...       | ...        |\n\n**Average:** {avg} ms | **Median:** {median} ms | **P95:** {p95} ms | **Max:** {max} ms\n\n**Assessment thresholds (end-to-end including MCP overhead):**\n- Fast: < 5000ms\n- Normal: 5000ms – 10000ms\n- Slow: 10000ms – 20000ms\n- Very Slow: > 20000ms\n\n{Commentary on any outliers or concerning patterns. When a test case is significantly slower\nthan peers, note possible causes: app launch wait, UI tree traversal, screenshot capture, etc.}\n\n### Response Size\n\n| Test Case | Response Size (chars) |\n|-----------|-----------------------|\n| TC-XXX-01 | 245                   |\n| ...       | ...                   |\n\n{Note any unexpectedly large or empty responses.}\n\n---\n\n## 5. Environmental Interference & Notes\n\n{List any environmental factors that affected test execution but are not bugs in the tool itself.\nThese factors help future testers reproduce results and avoid false failures.}\n\n| # | Factor | Impact | Mitigation |\n|---|--------|--------|------------|\n| 1 | {e.g., IME in Chinese mode} | {e.g., TC-Type-01 typed wrong characters} | {e.g., Switched IME to English before retesting} |\n| ... | ... | ... | ... |\n\n**Common environmental factors:**\n- **IME state**: Active non-English input methods intercept keystrokes (affects Type, Shortcut)\n- **Notification popups**: System or app notifications may steal focus mid-test\n- **Background app focus changes**: Chat apps, update dialogs may overlay the test window\n- **Screen lock / screensaver**: Can interrupt long-running test sessions\n- **Clipboard managers**: Third-party clipboard tools may interfere with Clipboard tests\n\n{If no environmental interference occurred, write: \"No environmental interference observed.\"}\n\n---\n\n## 6. Documentation & Schema Gaps\n\n{List any discrepancies between the tool's MCP parameter schema / description and its actual\nbehavior or environmental interactions. These are not necessarily bugs — they are places where\nthe documentation or schema could be improved to set correct expectations for callers.}\n\n| #   | Gap Type                          | Description | Recommendation |\n|-----|-----------------------------------|-------------|----------------|\n| 1   | {schema / description / behavior} | {desc}      | {rec}          |\n| ... | ...                               | ...         | ...            |\n\n**Gap Types:**\n- **schema**: parameter schema (types, required/optional, allowed values) does not match actual behavior\n- **description**: tool description is silent or ambiguous about a behavior that testing revealed\n- **behavior**: tool behaves inconsistently with what the schema + description together imply\n\n{If no gaps were found, write: \"No documentation or schema gaps identified.\"}\n\n---\n\n## 7. All Test Cases\n\n| ID         | Category   | Description | Result | Time (ms) | Response Size |\n|------------|------------|-------------|--------|-----------|---------------|\n| TC-XXX-01  | A - Basic  | {desc}      | PASS   | 6500      | 245           |\n| TC-XXX-02  | B - Params | {desc}      | FAIL   | 8200      | 310           |\n| ...        | ...        | ...         | ...    | ...       | ...           |\n````\n\n---\n\n## Test Isolation Guidelines\n\nTo avoid polluting the system or interfering with user state:\n\n- **FileSystem tests**: Use a dedicated temp directory (e.g., `%TEMP%\\wmcp-test-{timestamp}\\`).\n  Clean up after all tests complete.\n- **Registry tests**: Use a dedicated test key under `HKCU:\\Software\\WMCP-Test-{timestamp}`.\n  Delete the entire key after testing.\n- **Process tests**: Only list processes (don't kill user processes). If testing kill, spawn a\n  sacrificial process first (e.g., `notepad.exe`) and record its PID.\n- **App tests**: Use lightweight apps (Notepad, Calculator). **Record PIDs** of all processes\n  spawned during testing (use `(Start-Process notepad -PassThru).Id` or query process list\n  before/after launch). In teardown, only kill processes by PID — NEVER by name (e.g.,\n  `Stop-Process -Id $pid`, not `Stop-Process -Name notepad`), because the user may have their\n  own instances of the same application running.\n  - **Modern tabbed apps caveat:** Windows 11 Notepad/Terminal may reuse a single process for\n    multiple tabs. Diff the process list before/after each launch to detect new PIDs. Only kill\n    PIDs that did not exist before testing began.\n- **Clipboard tests**: Save and restore the original clipboard content.\n- **Input tools (Click, Type, Scroll, Move, Shortcut)**: Open a dedicated test window\n  (e.g., Notepad) to receive input. Don't interact with user's active work.\n  See also Pre-Test Step 2 for IME state handling — switch to English input mode before testing\n  and restore the original state in final teardown.\n- **Read-only tools (Screenshot, Snapshot, Scrape)**: Safe to run freely.\n- **Notification tests**: User-visible (sends Windows toasts). Avoid repeated or unnecessary\n  notifications. Prefer a single clearly labeled test notification per test case.\n- **PowerShell tests**: Use read-only commands where possible.\n\n---\n\n## Tool-Specific Testing Guidance\n\nHints per tool. Always read the actual schema to discover additional scenarios beyond these.\n\n### App\n- Modes: launch, resize, switch. Test each mode.\n- Launch: test with known apps (notepad, calc), unknown app names\n- Resize: test with valid window_loc/window_size, without an active app\n- Switch: test switching to a running app, to a non-existent app\n\n### PowerShell\n- Simple commands: `echo \"hello\"`, `Get-Date`, `Get-Process | Select-Object -First 3`\n- Timeout behavior: set a very short timeout with a long-running command\n- Encoding: commands with Unicode output\n- Error output: commands that write to stderr\n- Exit codes: commands that fail (e.g., `Get-Item nonexistent`)\n\n### Screenshot\n- Default parameters (no args)\n- With annotation enabled/disabled\n- With reference lines\n- With specific display index\n- Verify return includes image data\n\n### Snapshot\n- Various flag combinations: use_vision, use_dom, use_annotation, use_ui_tree\n- All flags off vs. all flags on\n- With/without reference lines\n\n### Click\n- By coordinates (loc) vs. by label\n- Different button types: left, right, middle\n- clicks=0 (hover), clicks=1 (single), clicks=2 (double)\n- Invalid coordinates (negative, off-screen)\n- Invalid label (non-existent element ID)\n\n### Type\n- Normal text, Unicode text, special characters\n- With and without clear=true\n- With and without press_enter=true\n- Different caret_position values: start, idle, end\n- By coordinates vs. by label\n- **IME sensitivity**: Test with IME active to verify behavior (expect failure if tool uses\n  keystroke simulation rather than Unicode input). This is a high-value edge case because\n  many Windows machines have non-English IMEs installed.\n- **Emoji / surrogate pair characters**: Test with characters outside the Basic Multilingual\n  Plane (e.g., 🌍, 😀) to verify supplementary plane Unicode support.\n- **Empty string**: Test `text=\"\"` — this is a common edge case that may crash if the\n  implementation indexes into the string without a length check.\n\n### Scroll\n- Vertical up/down, horizontal left/right\n- Different wheel_times values (1, 5, 10)\n- By coordinates vs. by label\n\n### Move\n- Simple move to coordinates\n- Drag mode (drag=true)\n- By coordinates vs. by label\n\n### Shortcut\n- Common shortcuts: ctrl+c, ctrl+v, ctrl+a, alt+tab\n- Windows key shortcuts: win+r, win+d\n- Multi-key combinations\n- Invalid key names\n\n### Wait\n- Short duration (1 second)\n- Zero duration\n- Verify actual elapsed time roughly matches requested duration\n\n### MultiSelect\n- Select multiple items by coordinates\n- Select by labels\n- With and without press_ctrl\n- Empty list of items\n\n### MultiEdit\n- Edit multiple fields by coordinates\n- Edit by labels\n- Mixed valid and invalid targets\n\n### Clipboard\n- get mode when clipboard has text\n- get mode when clipboard is empty\n- set mode with normal text\n- set mode with Unicode text\n- Roundtrip: set then get, verify content matches\n\n### Process\n- list mode with default sort\n- list mode with different sort_by values (memory, cpu, name)\n- list mode with name filter\n- list mode with different limit values\n- kill mode with a sacrificial process (spawn notepad, then kill it)\n\n### Notification\n- Valid notification with title, message, app_id\n- Empty title or message\n- Special characters in title/message\n\n### FileSystem\n- Full mode coverage: read, write, copy, move, delete, list, search, info\n- Read: existing file, non-existent file, offset/limit, different encodings\n- Write: new file, overwrite, append\n- List: with and without pattern, recursive, show_hidden\n- Delete: file, empty dir, non-empty dir with recursive\n\n### Registry\n- Full mode coverage: get, set, delete, list\n- Set and get roundtrip\n- Different value types (String, DWord, QWord)\n- Non-existent key/value\n- Use test-only registry path\n\n### Scrape\n- With a URL (lightweight page)\n- With and without query parameter\n- With use_dom enabled (requires open browser)\n- Invalid URL\n"},"items":[{"name":"SKILL.md","path":".claude/skills/windows-mcp-tool-tester/SKILL.md","rawUrl":"https://raw.githubusercontent.com/CursorTouch/Windows-MCP/HEAD/.claude/skills/windows-mcp-tool-tester/SKILL.md","title":"windows-mcp-tool-tester","category":"anthropic-skill","format":"markdown","content":"---\nname: windows-mcp-tool-tester\ndescription: >\n  Automated testing skill for Windows-MCP tools. Use this skill whenever the user wants to test,\n  validate, benchmark, or evaluate any Windows-MCP tool (App, PowerShell, Screenshot, Snapshot,\n  Click, Type, Scroll, Move, Shortcut, Wait, MultiSelect, MultiEdit, Clipboard, Process,\n  Notification, FileSystem, Registry, Scrape). Triggers on phrases like \"test the Click tool\",\n  \"benchmark Screenshot\", \"validate FileSystem\", \"run QA on Registry\", \"check if PowerShell works\",\n  \"evaluate tool performance\", or any mention of testing/validating a Windows-MCP tool.\n  Each invocation tests exactly ONE tool.\n---\n\n# Windows-MCP Tool Tester\n\nAn automated testing skill that generates comprehensive test cases for a single Windows-MCP tool,\nexecutes them, and produces a structured test report with pass/fail results, performance metrics,\nand actionable recommendations.\n\n## Core Principles\n\n- **One tool per invocation.** If the user doesn't specify which tool to test, ask them before proceeding.\n- **Black-box testing only.** Derive test cases exclusively from the MCP tool description and parameter schema — never read source code. Silence in the schema is a documentation gap, not a testing hint.\n- **Auto-generate test cases** from the tool's MCP description and parameter schema. Cover common scenarios, edge cases, parameter combinations, and error handling paths.\n- **Measure two dimensions**: correctness (return value matches expectations) and response time (end-to-end, including MCP overhead).\n- **Mandatory side-effect verification**: every tool call that may modify system state MUST be independently verified — no exceptions, no sampling.\n- **Safe cleanup**: track process PIDs spawned during testing; only kill those specific PIDs during teardown, never kill by process name alone.\n- **Safety first**: Windows-MCP has full system access with no sandboxing. Tests involving\n  destructive tools (FileSystem delete, Registry set/delete, Process kill, PowerShell) can\n  modify or destroy data. Running in a **VM or Windows Sandbox** is strongly recommended.\n  Before executing destructive test cases, confirm the user accepts the risk. See `SECURITY.md`.\n- **Produce a structured report** at the end (see Step 4).\n\n---\n\n## Step 0: Identify the Target Tool\n\nIf the user hasn't specified a tool, present the full list and ask them to pick one:\n\n> App, PowerShell, Screenshot, Snapshot, Click, Type, Scroll, Move, Shortcut, Wait,\n> MultiSelect, MultiEdit, Clipboard, Process, Notification, FileSystem, Registry, Scrape\n\nOnce a tool is confirmed, proceed to Step 1. Do NOT test multiple tools in one session.\n\n---\n\n## Step 1: Analyze the Tool\n\nRead the tool's MCP description and parameter schema via the MCP server's tool listing. Identify:\n\n1. **All parameters** — name, type, required/optional, default value, allowed values (enums)\n2. **All modes** (if the tool is mode-based, e.g., FileSystem has read/write/copy/move/delete/list/search/info)\n3. **Return value structure** — what the tool returns on success vs. failure\n4. **Side effects** — does it modify system state? (important for test isolation)\n5. **Dependencies** — does it require a running app, an open window, existing files, etc.?\n\nUse this analysis to inform test case generation. If the description is ambiguous or silent on a\nbehavior, note it as a documentation gap and design a test to probe it. The tool's response is\nthe ground truth.\n\n---\n\n## Step 2: Generate Test Cases\n\nDesign test cases that cover the following categories. Not every category applies to every tool —\nuse judgment based on the tool's nature.\n\n### Category A: Basic Functionality (Required)\nTest the tool's primary purpose with standard, well-formed inputs.\n- One test per mode/operation type (e.g., for FileSystem: read, write, list, etc.)\n- Use realistic parameter values\n\n### Category B: Parameter Variations (Required)\n- Test each optional parameter individually to verify it takes effect\n- Test enum parameters with every allowed value\n- Test boolean parameters in both true and false states\n- **For `anyOf` union types**: The schema advertises all listed types as valid, so the tool must handle each correctly.\n  - `anyOf: [boolean, string]` (e.g., `drag`, `use_vision`): test boolean `true`/`false` AND string `\"true\"`/`\"false\"` — both must produce the same behavior.\n  - **Caveat:** MCP transport layers may silently coerce `\"true\"` (string) to `true` (boolean)\n    before the tool sees it. To genuinely probe the string path, also test non-standard truthy\n    strings like `\"yes\"` or `\"1\"` — if those fail while `\"true\"` passes, the tool likely only\n    receives booleans and the string branch is untested.\n  - `anyOf: [<type>, null]` (nullable): test with a valid value AND explicit `null`. An unhandled TypeError on null is a FAIL.\n- Test with default values (omit optional params) vs. explicit values\n\n### Category C: Edge Cases (Required)\n- Empty strings, zero values, negative numbers where applicable\n- Boundary values (e.g., very long text for Type, timeout=0 for PowerShell)\n- Unicode / special characters in string parameters\n- Very large or very small numeric inputs\n\n### Category D: Error Handling (Required)\n- Missing required parameters\n- Invalid parameter types or out-of-range values\n- Referencing nonexistent resources (files, windows, processes, registry keys)\n- Operations that should fail gracefully (e.g., deleting a non-existent file)\n\n### Category E: Parameter Interaction (When Applicable)\n- Combinations of parameters that might interact (e.g., Click with both `loc` and `label`)\n- Mutually exclusive parameters\n- Mode-specific parameter requirements\n- **Cross-mode parameter applicability**: For mode-based tools, pass parameters meant for one\n  mode while calling another (e.g., `window_loc` in `launch` mode). Silently ignoring them is\n  a documentation gap worth reporting.\n\n### Category F: Idempotency & State (When Applicable)\n- For tools marked `idempotentHint: true`: call twice with same args, verify same result\n- For destructive tools: verify cleanup or rollback is possible\n- For stateful tools: verify state changes are reflected correctly\n\n### Test Case Format\n\nFor each test case, define:\n\n```\nID:          TC-{ToolName}-{Number}\nCategory:    A/B/C/D/E/F\nDescription: What this test verifies\nParameters:  The exact parameters to pass\nExpected:    What a correct result looks like (success/failure, key content in response)\nSetup:       Any prerequisite actions (create a file, open an app, etc.)\nTeardown:    Any cleanup actions after the test\n```\n\nPresent the test plan to the user for confirmation before executing.\nAim for **10-20 test cases** depending on tool complexity.\n\nInclude an **estimated execution time**: approximately **30-45 seconds** per test case\n(includes timing calls, tool execution, verification). App launches add 5-10s extra.\nPresent as a range, e.g., \"Estimated execution time: 8-12 minutes (15 test cases)\".\n\n---\n\n## Step 3: Execute Tests\n\n### Pre-Test Step 1: Gather Environment Info\n\nBefore running test cases, collect the test environment details for the report. Use these\nPowerShell commands for reliable results:\n\n```powershell\n# OS version\n(Get-CimInstance Win32_OperatingSystem).Caption + \" \" + (Get-CimInstance Win32_OperatingSystem).Version\n\n# Display resolution (physical pixels)\nGet-CimInstance Win32_VideoController | Select-Object CurrentHorizontalResolution, CurrentVerticalResolution\n\n# Display count\n(Get-CimInstance Win32_PnPEntity | Where-Object { $_.PNPClass -eq 'Monitor' -and $_.Status -eq 'OK' }).Count\n\n# DPI scale factor (96 = 100%, 120 = 125%, 144 = 150%, 192 = 200%)\nGet-ItemProperty 'HKCU:\\Control Panel\\Desktop\\WindowMetrics' -Name AppliedDPI -ErrorAction SilentlyContinue | Select-Object -ExpandProperty AppliedDPI\n```\n\nAlso call Screenshot once — its `Screenshot Original Size` cross-checks the DPI value,\nand its output includes `Active Desktop` and `All Desktops`.\n\n### Pre-Test Step 2: Prepare Environment\n\nFor **input tools** (Type, Click, Scroll, Move, Shortcut, MultiSelect, MultiEdit), prepare the\nenvironment before executing any test cases:\n\n1. **IME (Input Method) state**: Check the Tray Input Indicator in the Snapshot output. If it\n   shows a non-English input mode (e.g., \"Chinese Mode\", \"Japanese Mode\"), switch to English\n   mode first using the `Shortcut` tool (typically `shift` to toggle). **This is critical for\n   Type tool tests** — an active IME will intercept keystrokes and produce incorrect characters.\n   Record the original IME state and restore it after testing.\n\n2. **Label availability check**: Call Snapshot on the test target window and verify whether the\n   element you intend to use with `label` parameter is actually listed in the Interactive Elements.\n   Common pitfalls:\n   - Modern Windows 11 Notepad's text editing area is **not** exposed as an interactive element\n     in the UI tree — use `loc` coordinates instead.\n   - Some complex controls (e.g., rich text editors, canvas-based UIs) may not enumerate child\n     elements.\n   If a planned `label`-based test has no valid label target, adapt the test to use `loc`, or\n   pick a different element that does have a label (e.g., a search box, address bar).\n\n3. **Warm-up call**: Execute 1-2 throwaway tool calls (not counted in test results) to warm up\n   the MCP connection, window focus, and UI tree cache. First calls are typically slower due to\n   cold start effects — excluding them gives more representative performance numbers.\n\n### Test Execution\n\nRun each test case sequentially. For each test:\n\n> **Label freshness rule:** Snapshot labels are a point-in-time snapshot. If any action between\n> tests could change the UI state, call Snapshot again before using `label` parameters.\n\n> **State reset between tests:** Each test case should start from a known, clean state. For\n> input tools sharing a test window (e.g., Notepad), define a standard reset procedure and\n> execute it in Setup:\n> - **Type tests**: Shortcut (Ctrl+A) → Shortcut (Delete) to clear the text area\n> - **Click/Move tests**: Move cursor to a neutral position away from interactive elements\n> - **Scroll tests**: Reset scroll position to top (Ctrl+Home)\n>\n> If a test's Setup includes `clear=true` in the tool call itself, you may skip the manual\n> reset — but verify in the teardown that the state is clean for the next test.\n\n1. **Setup** — perform any prerequisite actions (e.g., create a temp file for FileSystem read tests).\n   When spawning processes, **record their PIDs** for teardown (see Test Isolation Guidelines).\n2. **Record start time** — call PowerShell to capture a precise timestamp in milliseconds **before** calling the tool:\n   ```powershell\n   [long](([System.DateTime]::UtcNow - [System.DateTime]::UnixEpoch).TotalMilliseconds)\n   ```\n   Save the returned integer as `$t_start`.\n3. **Call the MCP tool** with the specified parameters\n4. **Record end time** — immediately after the tool returns, call PowerShell again with the same command. Save as `$t_end`.\n5. **Compute elapsed time** — `elapsed_ms = $t_end - $t_start`. Note: this includes MCP\n   overhead from the timestamp calls themselves (~3-5s each). Use for relative comparison\n   between test cases only. **When testing the PowerShell tool itself**, timing is\n   self-referential — record times as `N/A (self-referential)` and rely on the PowerShell\n   tool's own `timeout` behavior and status codes for performance assessment instead.\n6. **Capture the response** — store the full return value and measure `response_size`:\n   - **Text-only tools**: character count of the returned string.\n   - **Mixed-content tools** (Screenshot, Snapshot): character count of the **text portion only**,\n     note `+image` in the report. Do not attempt to measure image byte size.\n7. **Evaluate correctness** — compare the response against expected behavior:\n   - Does the response indicate success/failure as expected?\n   - Does the response content match expected patterns?\n   - For error cases: does the error message make sense and provide useful information?\n8. **Verify side effects (MANDATORY)** — independently verify EVERY mutating tool call. Never\n   rely solely on the tool's return value. Never skip or sample.\n   **Rule: verification MUST NOT use the same tool under test.** Use a different tool\n   (preferably PowerShell) to cross-check. Verification methods:\n   - **Move/Click**: call Screenshot or Snapshot to verify the expected UI change occurred.\n   - **Type**: use Shortcut (Ctrl+A → Ctrl+C) then PowerShell `Get-Clipboard` to capture\n     exact text for comparison.\n   - **Drag (Move with drag=True)**: call Snapshot to verify the target window actually moved.\n   - **App (launch/resize)**: call PowerShell (`Get-Process`) to verify process exists, and\n     Screenshot/Snapshot to verify window position/size.\n   - **FileSystem**: verify with PowerShell (`Test-Path`, `Get-Content`, `Get-ChildItem`)\n     — never with the FileSystem tool itself.\n   - **Registry**: verify with PowerShell (`Get-ItemProperty`, `reg query`)\n     — never with the Registry tool itself.\n   - **Clipboard (set)**: verify with PowerShell (`Get-Clipboard`)\n     — never with the Clipboard tool itself.\n   - **Process (kill)**: verify with PowerShell (`Get-Process -Id $pid`)\n     — never with the Process tool itself.\n   - **Shortcut**: call Screenshot to verify the shortcut's expected effect occurred.\n   - For read-only tools (Screenshot, Snapshot, Scrape, Process list), this step is not needed.\n   - If verification fails but the tool reported success, mark the test as **FAIL** and note\n     \"tool reported success but side effect not confirmed\" in the root cause analysis.\n9. **Teardown** — clean up any side effects (delete temp files, close apps, etc.)\n\n> **IMPORTANT:** Never estimate response times. Always use the PowerShell measurement above.\n> If unavailable, record `N/A` and explain why.\n\n### Correctness Evaluation Criteria\n\n| Result    | Meaning                                                                                       |\n|-----------|-----------------------------------------------------------------------------------------------|\n| PASS      | Response matches expected behavior exactly                                                    |\n| SOFT PASS | Response is acceptable but slightly different from ideal (e.g., extra whitespace, ordering)    |\n| FAIL      | Response doesn't match expected behavior — includes cases where the tool rejects schema-valid input. Never look up source code to explain away a failure. |\n| ERROR     | Tool threw an unexpected exception or timed out                                               |\n| SKIP      | Test couldn't run due to missing prerequisites (document why)                                 |\n\n### When to SKIP vs. Adapt\n\nIf a planned test case cannot execute as designed (e.g., the target element has no `label` in the\nUI tree, or a required window state cannot be achieved), decide:\n\n- **SKIP** if the prerequisite is truly missing and no workaround exists. Document the reason.\n- **Adapt** if you can achieve the same test intent with a different approach (e.g., use `loc`\n  instead of `label`, use a different target app). Update the test case description and note the\n  adaptation in the report. Adapting is preferred over skipping when the test intent is still\n  achievable.\n\n### Performance Tracking\n\nFor each test case, record **response time (ms)** via PowerShell timestamps and\n**response size** (character count of the raw response text).\n\n> **Warm-up effect:** The first 1-2 tool calls in a session are typically slower due to MCP\n> connection warm-up, UI tree cache initialization, and window focus acquisition. If warm-up\n> calls were performed in Pre-Test, note this in the report. If not, flag the first test case's\n> timing as potentially inflated and exclude it from aggregate statistics (average, median, P95)\n> or mark it separately.\n\n---\n\n## Step 4: Generate the Test Report\n\n**Localization:** If the user specified a language, write the entire report in that language\n(headings, tables, commentary, recommendations). Keep test case IDs (e.g., TC-Move-01) in\nEnglish. The template below is a structural reference — translate all prose while preserving\nthe markdown structure.\n\n````markdown\n# Windows-MCP Tool Test Report: {ToolName}\n\n**Date:** {timestamp}\n**Tool:** {ToolName}\n**Total Test Cases:** {N}\n**PASS:** {P} | **SOFT PASS:** {SP} | **FAIL:** {F} | **ERROR:** {E} | **SKIP:** {S}\n**Overall Pass Rate:** {(P+SP)/N * 100}%\n\n---\n\n## 1. Test Environment\n\n{Record the environment to aid reproducibility. Data gathered in Pre-Test step.}\n\n| Item                     | Value                                                    |\n|--------------------------|----------------------------------------------------------|\n| OS Version               | {e.g., Windows 11 Pro 10.0.26200}                       |\n| Display Resolution       | {e.g., 2560x1440}                                       |\n| Screenshot Original Size | {e.g., 3840x2160 — this is resolution x scale factor}   |\n| Display Count            | {e.g., 1}                                                |\n| Active Virtual Desktop   | {e.g., Desktop 1}                                        |\n| MCP Transport            | {e.g., SSE via http://localhost:8088/sse}                |\n| Scale Factor             | {e.g., 150% (AppliedDPI=144)}                           |\n\n---\n\n## 2. Executive Summary\n\n{2-3 sentences summarizing the overall health of the tool. Highlight critical failures if any.\nNote any patterns — e.g., \"all error-handling tests failed\" or \"basic functionality is solid\nbut Unicode support is incomplete.\" Also assess these dimensions when relevant:}\n\n- **Error message quality**: descriptive and actionable, or cryptic?\n- **Input validation**: does the tool validate params before executing, or fail deep with confusing errors?\n- **Consistency**: do repeated calls with same params return consistent results?\n- **Graceful degradation**: when prerequisites are missing, does the tool explain what's needed?\n\n---\n\n## 3. Failed & Error Test Cases\n\n{For each non-passing test case, provide:}\n\n### TC-{ID}: {Description}\n- **Category:** {category}\n- **Parameters:** `{params}`\n- **Expected:** {what should have happened}\n- **Actual:** {what actually happened}\n- **Side-Effect Verification:** {what the independent verification revealed, if applicable}\n- **Root Cause Analysis:** {your best assessment of why it failed}\n- **Suggested Fix:** {actionable recommendation for the developer}\n\n{If all tests passed, write: \"All test cases passed. No issues to report.\"}\n\n---\n\n## 4. Performance Analysis\n\n> **Note:** All times are end-to-end measurements including MCP transport overhead\n> (serialization, network round-trip, SSE/stdio latency). They do NOT represent pure tool\n> execution time. Use these numbers for **relative comparison** and outlier detection — not\n> as absolute benchmarks. For pure execution time, check server-side logs with\n> `WINDOWS_MCP_PROFILE_SNAPSHOT=1`.\n\n### Response Time\n\n| Test Case | Time (ms) | Assessment |\n|-----------|-----------|------------|\n| TC-XXX-01 | 6500      | Normal     |\n| TC-XXX-02 | 15200     | Slow       |\n| ...       | ...       | ...        |\n\n**Average:** {avg} ms | **Median:** {median} ms | **P95:** {p95} ms | **Max:** {max} ms\n\n**Assessment thresholds (end-to-end including MCP overhead):**\n- Fast: < 5000ms\n- Normal: 5000ms – 10000ms\n- Slow: 10000ms – 20000ms\n- Very Slow: > 20000ms\n\n{Commentary on any outliers or concerning patterns. When a test case is significantly slower\nthan peers, note possible causes: app launch wait, UI tree traversal, screenshot capture, etc.}\n\n### Response Size\n\n| Test Case | Response Size (chars) |\n|-----------|-----------------------|\n| TC-XXX-01 | 245                   |\n| ...       | ...                   |\n\n{Note any unexpectedly large or empty responses.}\n\n---\n\n## 5. Environmental Interference & Notes\n\n{List any environmental factors that affected test execution but are not bugs in the tool itself.\nThese factors help future testers reproduce results and avoid false failures.}\n\n| # | Factor | Impact | Mitigation |\n|---|--------|--------|------------|\n| 1 | {e.g., IME in Chinese mode} | {e.g., TC-Type-01 typed wrong characters} | {e.g., Switched IME to English before retesting} |\n| ... | ... | ... | ... |\n\n**Common environmental factors:**\n- **IME state**: Active non-English input methods intercept keystrokes (affects Type, Shortcut)\n- **Notification popups**: System or app notifications may steal focus mid-test\n- **Background app focus changes**: Chat apps, update dialogs may overlay the test window\n- **Screen lock / screensaver**: Can interrupt long-running test sessions\n- **Clipboard managers**: Third-party clipboard tools may interfere with Clipboard tests\n\n{If no environmental interference occurred, write: \"No environmental interference observed.\"}\n\n---\n\n## 6. Documentation & Schema Gaps\n\n{List any discrepancies between the tool's MCP parameter schema / description and its actual\nbehavior or environmental interactions. These are not necessarily bugs — they are places where\nthe documentation or schema could be improved to set correct expectations for callers.}\n\n| #   | Gap Type                          | Description | Recommendation |\n|-----|-----------------------------------|-------------|----------------|\n| 1   | {schema / description / behavior} | {desc}      | {rec}          |\n| ... | ...                               | ...         | ...            |\n\n**Gap Types:**\n- **schema**: parameter schema (types, required/optional, allowed values) does not match actual behavior\n- **description**: tool description is silent or ambiguous about a behavior that testing revealed\n- **behavior**: tool behaves inconsistently with what the schema + description together imply\n\n{If no gaps were found, write: \"No documentation or schema gaps identified.\"}\n\n---\n\n## 7. All Test Cases\n\n| ID         | Category   | Description | Result | Time (ms) | Response Size |\n|------------|------------|-------------|--------|-----------|---------------|\n| TC-XXX-01  | A - Basic  | {desc}      | PASS   | 6500      | 245           |\n| TC-XXX-02  | B - Params | {desc}      | FAIL   | 8200      | 310           |\n| ...        | ...        | ...         | ...    | ...       | ...           |\n````\n\n---\n\n## Test Isolation Guidelines\n\nTo avoid polluting the system or interfering with user state:\n\n- **FileSystem tests**: Use a dedicated temp directory (e.g., `%TEMP%\\wmcp-test-{timestamp}\\`).\n  Clean up after all tests complete.\n- **Registry tests**: Use a dedicated test key under `HKCU:\\Software\\WMCP-Test-{timestamp}`.\n  Delete the entire key after testing.\n- **Process tests**: Only list processes (don't kill user processes). If testing kill, spawn a\n  sacrificial process first (e.g., `notepad.exe`) and record its PID.\n- **App tests**: Use lightweight apps (Notepad, Calculator). **Record PIDs** of all processes\n  spawned during testing (use `(Start-Process notepad -PassThru).Id` or query process list\n  before/after launch). In teardown, only kill processes by PID — NEVER by name (e.g.,\n  `Stop-Process -Id $pid`, not `Stop-Process -Name notepad`), because the user may have their\n  own instances of the same application running.\n  - **Modern tabbed apps caveat:** Windows 11 Notepad/Terminal may reuse a single process for\n    multiple tabs. Diff the process list before/after each launch to detect new PIDs. Only kill\n    PIDs that did not exist before testing began.\n- **Clipboard tests**: Save and restore the original clipboard content.\n- **Input tools (Click, Type, Scroll, Move, Shortcut)**: Open a dedicated test window\n  (e.g., Notepad) to receive input. Don't interact with user's active work.\n  See also Pre-Test Step 2 for IME state handling — switch to English input mode before testing\n  and restore the original state in final teardown.\n- **Read-only tools (Screenshot, Snapshot, Scrape)**: Safe to run freely.\n- **Notification tests**: User-visible (sends Windows toasts). Avoid repeated or unnecessary\n  notifications. Prefer a single clearly labeled test notification per test case.\n- **PowerShell tests**: Use read-only commands where possible.\n\n---\n\n## Tool-Specific Testing Guidance\n\nHints per tool. Always read the actual schema to discover additional scenarios beyond these.\n\n### App\n- Modes: launch, resize, switch. Test each mode.\n- Launch: test with known apps (notepad, calc), unknown app names\n- Resize: test with valid window_loc/window_size, without an active app\n- Switch: test switching to a running app, to a non-existent app\n\n### PowerShell\n- Simple commands: `echo \"hello\"`, `Get-Date`, `Get-Process | Select-Object -First 3`\n- Timeout behavior: set a very short timeout with a long-running command\n- Encoding: commands with Unicode output\n- Error output: commands that write to stderr\n- Exit codes: commands that fail (e.g., `Get-Item nonexistent`)\n\n### Screenshot\n- Default parameters (no args)\n- With annotation enabled/disabled\n- With reference lines\n- With specific display index\n- Verify return includes image data\n\n### Snapshot\n- Various flag combinations: use_vision, use_dom, use_annotation, use_ui_tree\n- All flags off vs. all flags on\n- With/without reference lines\n\n### Click\n- By coordinates (loc) vs. by label\n- Different button types: left, right, middle\n- clicks=0 (hover), clicks=1 (single), clicks=2 (double)\n- Invalid coordinates (negative, off-screen)\n- Invalid label (non-existent element ID)\n\n### Type\n- Normal text, Unicode text, special characters\n- With and without clear=true\n- With and without press_enter=true\n- Different caret_position values: start, idle, end\n- By coordinates vs. by label\n- **IME sensitivity**: Test with IME active to verify behavior (expect failure if tool uses\n  keystroke simulation rather than Unicode input). This is a high-value edge case because\n  many Windows machines have non-English IMEs installed.\n- **Emoji / surrogate pair characters**: Test with characters outside the Basic Multilingual\n  Plane (e.g., 🌍, 😀) to verify supplementary plane Unicode support.\n- **Empty string**: Test `text=\"\"` — this is a common edge case that may crash if the\n  implementation indexes into the string without a length check.\n\n### Scroll\n- Vertical up/down, horizontal left/right\n- Different wheel_times values (1, 5, 10)\n- By coordinates vs. by label\n\n### Move\n- Simple move to coordinates\n- Drag mode (drag=true)\n- By coordinates vs. by label\n\n### Shortcut\n- Common shortcuts: ctrl+c, ctrl+v, ctrl+a, alt+tab\n- Windows key shortcuts: win+r, win+d\n- Multi-key combinations\n- Invalid key names\n\n### Wait\n- Short duration (1 second)\n- Zero duration\n- Verify actual elapsed time roughly matches requested duration\n\n### MultiSelect\n- Select multiple items by coordinates\n- Select by labels\n- With and without press_ctrl\n- Empty list of items\n\n### MultiEdit\n- Edit multiple fields by coordinates\n- Edit by labels\n- Mixed valid and invalid targets\n\n### Clipboard\n- get mode when clipboard has text\n- get mode when clipboard is empty\n- set mode with normal text\n- set mode with Unicode text\n- Roundtrip: set then get, verify content matches\n\n### Process\n- list mode with default sort\n- list mode with different sort_by values (memory, cpu, name)\n- list mode with name filter\n- list mode with different limit values\n- kill mode with a sacrificial process (spawn notepad, then kill it)\n\n### Notification\n- Valid notification with title, message, app_id\n- Empty title or message\n- Special characters in title/message\n\n### FileSystem\n- Full mode coverage: read, write, copy, move, delete, list, search, info\n- Read: existing file, non-existent file, offset/limit, different encodings\n- Write: new file, overwrite, append\n- List: with and without pattern, recursive, show_hidden\n- Delete: file, empty dir, non-empty dir with recursive\n\n### Registry\n- Full mode coverage: get, set, delete, list\n- Set and get roundtrip\n- Different value types (String, DWord, QWord)\n- Non-existent key/value\n- Use test-only registry path\n\n### Scrape\n- With a URL (lightweight page)\n- With and without query parameter\n- With use_dom enabled (requires open browser)\n- Invalid URL\n","frontmatter":{"name":"windows-mcp-tool-tester","description":"Automated testing skill for Windows-MCP tools. Use this skill whenever the user wants to test, validate, benchmark, or evaluate any Windows-MCP tool (App, PowerShell, Screenshot, Snapshot, Click, Type, Scroll, Move, Shortcut, Wait, MultiSelect, MultiEdit, Clipboard, Process, Notification, FileSystem, Registry, Scrape). Triggers on phrases like \"test the Click tool\", \"benchmark Screenshot\", \"validate FileSystem\", \"run QA on Registry\", \"check if PowerShell works\", \"evaluate tool performance\", or any mention of testing/validating a Windows-MCP tool. Each invocation tests exactly ONE tool.\n"},"isInternal":false,"tokens":6406,"sizeBytes":28340},{"name":"CLAUDE.md","path":"CLAUDE.md","rawUrl":"https://raw.githubusercontent.com/CursorTouch/Windows-MCP/HEAD/CLAUDE.md","title":"Claude Agent Guidelines & System Prompt","category":"claude-rule","format":"markdown","content":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Project Overview\n\nWindows-MCP is a Python MCP (Model Context Protocol) server that bridges AI LLM agents with the Windows OS, enabling direct desktop automation. It exposes 21 tools via FastMCP:\n\n| Group | Tools |\n|---|---|\n| Capture | `Screenshot`, `Snapshot`, `Scrape`, `DisplayInventory` |\n| Input | `Click`, `Type`, `Scroll`, `Move` (also drag-and-drop via `drag=True`), `Shortcut`, `MultiSelect`, `MultiEdit` |\n| Timing | `Wait`, `WaitFor` |\n| System | `App`, `PowerShell`, `FileSystem`, `Registry`, `Process`, `Clipboard`, `Notification`, `ControlStatus` |\n\nTool names are defined by the `name=` argument of each `@mcp.tool(...)` in `src/windows_mcp/tools/`; that directory is the source of truth. Note the shell tool is registered as `PowerShell`, not `Shell`. Any subset can be removed at startup with `serve --exclude-tools` (e.g. `windows-mcp serve --exclude-tools PowerShell,Registry`).\n\n## Build & Development Commands\n\n```bash\nuv sync --extra dev        # Install runtime and development dependencies\nuv run windows-mcp serve   # Run the MCP server\nuv run --extra dev ruff format .  # Format code\nuv run --extra dev ruff check .   # Lint code\nuv run --extra dev ruff check --fix .  # Lint and auto-fix\nuv run --extra dev pytest         # Run all tests\nuv run --extra dev pytest tests/test_desktop_views.py  # Run a single test file\n```\n\n**Package manager**: UV (not pip). **Python**: 3.14+. **Build backend**: setuptools.\n\n## Architecture\n\nThe codebase follows a layered service architecture under `src/windows_mcp/`:\n\n**Entry point** — `__main__.py`: Builds the FastMCP server, parses CLI flags, and selects the transport. Tool registration is delegated to `tools.register_all()`; an async lifespan initializes the Desktop, WatchDog, and Analytics singletons, which tools resolve lazily through the `get_desktop` / `get_analytics` callables.\n\n**Tools layer** — `tools/`: One module per tool group, each exposing `register(mcp, *, get_desktop, get_analytics)`. `tools/__init__.py` holds the module list and `register_all()`. Tool functions are thin — they normalize arguments and delegate to a service package. The `@with_analytics` decorator wraps each one for telemetry, making it the existing precedent for cross-cutting concerns at the tool boundary.\n\n**Desktop service** — `desktop/service.py`: High-level orchestrator. Manages window operations (launch, resize, switch), screenshots, mouse/keyboard actions, and clipboard. Interfaces with Tree service for UI element discovery. `desktop/views.py` defines data models: `DesktopState`, `Window`, `Size`, `BoundingBox`, `Status`.\n\n**Tree service** — `tree/service.py`: Captures the Windows accessibility tree from active and background windows. Identifies interactive elements and scrollable areas. Uses `ThreadPoolExecutor` for multi-threaded UI traversal. `tree/views.py` defines `TreeElementNode`, `ScrollElementNode`, `TreeState`. `tree/config.py` has control type configurations.\n\n**UIAutomation wrapper** — `uia/`: Low-level abstraction over the Windows UIAutomation COM API via `comtypes`. `core.py` wraps the main automation object, `controls.py` has control-specific logic, `patterns.py` wraps UIAutomation patterns, `enums.py` has COM enumerations, `events.py` handles event subscriptions.\n\n**WatchDog** — `watchdog/service.py`: Runs in a separate thread monitoring UI focus changes via UIAutomation events. Notifies the Tree service of focus changes so the accessibility tree stays current.\n\n**Virtual Desktop Manager** — `vdm/core.py`: Tracks which windows belong to which Windows virtual desktop (Win10/11).\n\n**Domain services** — thin packages backing the system tools: `filesystem/` (read/write/copy/move/delete/list/search/info), `registry/` (get/set/delete/list, implemented via PowerShell cmdlets), `powershell/` (`PowerShellExecutor` plus environment resolution), `process/` (list/kill), `notifications/`. Registry and PowerShell tools shell out, so their latency is dominated by process startup.\n\n**Infrastructure** — `infrastructure/`: cross-cutting concerns. `analytics.py` (optional PostHog telemetry, disabled with `ANONYMIZED_TELEMETRY=false`; records tool names and errors only, never arguments or outputs), `auth.py` and `oauth.py` (bearer-token and OAuth middleware for HTTP transports), `security.py` (SSRF validation, IP allowlist middleware), `config.py` (server configuration). Note `windows_mcp/config.py` at the package root is unrelated — it only holds the `WINDOWS_MCP_DEBUG` helpers.\n\n## Code Style\n\n- Formatter/linter: **Ruff** (line length 100, double quotes)\n- Naming: PEP 8 — `snake_case` functions/variables, `PascalCase` classes, `UPPER_CASE` constants\n- Type hints required on function signatures\n- Google-style docstrings for public functions/classes\n\n## Key Design Details\n\n- Screenshots are capped to 1920x1080 for token efficiency\n- Mouse/keyboard input uses UIA (same coordinate space as BoundingRectangle; no DPI mismatch)\n- Screenshot is the preferred fast visual-context tool; Snapshot is the heavier path for UI element ids and DOM extraction\n- Browser detection (Chrome, Edge, Firefox) triggers special DOM extraction mode in Snapshot\n- Fuzzy string matching (`thefuzz`) is used for element name matching\n- UI element fetching has retry logic (`THREAD_MAX_RETRIES=3` in tree service)\n- The server supports stdio, SSE, and streamable HTTP transports\n\n## Environment Variables\n\n| Variable | Default | Description |\n|---|---|---|\n| `WINDOWS_MCP_SCREENSHOT_SCALE` | `1.0` | Scale factor for screenshots (range `0.1`–`1.0`). Lower on 1440p/4K to stay under Claude Desktop's 1 MB limit. Resolved in `tools/_snapshot_helpers.py`. |\n| `WINDOWS_MCP_SCREENSHOT_BACKEND` | `auto` | Screenshot backend: `auto`, `dxcam`, `mss`, `pillow`. Resolved in `desktop/screenshot.py`. |\n| `WINDOWS_MCP_MAX_TREE_ELEMENTS` | `500` | Max UI elements a single Snapshot/WaitFor tree capture may collect before it stops descending and returns a truncated tree (with a note in the output). Bounds both traversal time and response size on huge flat lists/grids (e.g. an unfiltered inventory view with thousands of rows). Resolved in `tree/budget.py`. |\n| `WINDOWS_MCP_PROFILE_SNAPSHOT` | _(off)_ | Set to `1`/`true`/`yes`/`on` to log per-stage timing for Screenshot/Snapshot. Checked in `tools/_snapshot_helpers.py` and `desktop/service.py`. |\n| `ANONYMIZED_TELEMETRY` | `true` | Set to `false` to disable PostHog telemetry. Checked in `__main__.py` and `infrastructure/analytics.py`. |\n| `POSTHOG_API_KEY` | Project default | Override the PostHog project write key used for anonymous telemetry. Set to an empty string to skip PostHog client initialization. Checked in `infrastructure/analytics.py`. |\n| `POSTHOG_HOST` | `https://us.i.posthog.com` | Override the PostHog host for anonymous telemetry, such as for a self-hosted PostHog deployment. Checked in `infrastructure/analytics.py`. |\n| `WINDOWS_MCP_WATCHDOG` | _(off)_ | Set to `on`/`1`/`true`/`yes`/`enabled` to start the UIA focus WatchDog thread. Unset, or any other value, leaves it off. Opt-in because it only emits debug logging today but can crash the server via the UIA event pump (#332). Resolved in `__main__.py`. |\n| `WINDOWS_MCP_DEBUG` | `false` | Set to `1`/`true`/`yes`/`on` to enable debug mode. Checked in `config.py`. Also available as `--debug` CLI flag. |\n| `WINDOWS_MCP_DISABLE_FLASH` | _(off)_ | Set to `1`/`true`/`yes`/`on` to suppress the orange-red glowing border that briefly appears after every screenshot. Resolved in `desktop/flash_overlay.py`. |\n\n## Security Context\n\nThis server has **full system access** with no sandboxing. `PowerShell`, `FileSystem`, `Registry`, `Process`, and `App` can all perform irreversible operations, and there is no audit log or rollback. The recommended deployment target is a VM or Windows Sandbox. Use `serve --exclude-tools` to drop the tools a given deployment does not need.\n","isInternal":false,"tokens":1958,"sizeBytes":8031}],"systemPromptSnippet":"<yakaai_skills repo=\"CursorTouch/Windows-MCP\">\n<!-- File: .claude/skills/windows-mcp-tool-tester/SKILL.md (Tokens: ~6406 | Category: anthropic-skill) -->\n---\nname: windows-mcp-tool-tester\ndescription: >\n  Automated testing skill for Windows-MCP tools. Use this skill whenever the user wants to test,\n  validate, benchmark, or evaluate any Windows-MCP tool (App, PowerShell, Screenshot, Snapshot,\n  Click, Type, Scroll, Move, Shortcut, Wait, MultiSelect, MultiEdit, Clipboard, Process,\n  Notification, FileSystem, Registry, Scrape). Triggers on phrases like \"test the Click tool\",\n  \"benchmark Screenshot\", \"validate FileSystem\", \"run QA on Registry\", \"check if PowerShell works\",\n  \"evaluate tool performance\", or any mention of testing/validating a Windows-MCP tool.\n  Each invocation tests exactly ONE tool.\n---\n\n# Windows-MCP Tool Tester\n\nAn automated testing skill that generates comprehensive test cases for a single Windows-MCP tool,\nexecutes them, and produces a structured test report with pass/fail results, performance metrics,\nand actionable recommendations.\n\n## Core Principles\n\n- **One tool per invocation.** If the user doesn't specify which tool to test, ask them before proceeding.\n- **Black-box testing only.** Derive test cases exclusively from the MCP tool description and parameter schema — never read source code. Silence in the schema is a documentation gap, not a testing hint.\n- **Auto-generate test cases** from the tool's MCP description and parameter schema. Cover common scenarios, edge cases, parameter combinations, and error handling paths.\n- **Measure two dimensions**: correctness (return value matches expectations) and response time (end-to-end, including MCP overhead).\n- **Mandatory side-effect verification**: every tool call that may modify system state MUST be independently verified — no exceptions, no sampling.\n- **Safe cleanup**: track process PIDs spawned during testing; only kill those specific PIDs during teardown, never kill by process name alone.\n- **Safety first**: Windows-MCP has full system access with no sandboxing. Tests involving\n  destructive tools (FileSystem delete, Registry set/delete, Process kill, PowerShell) can\n  modify or destroy data. Running in a **VM or Windows Sandbox** is strongly recommended.\n  Before executing destructive test cases, confirm the user accepts the risk. See `SECURITY.md`.\n- **Produce a structured report** at the end (see Step 4).\n\n---\n\n## Step 0: Identify the Target Tool\n\nIf the user hasn't specified a tool, present the full list and ask them to pick one:\n\n> App, PowerShell, Screenshot, Snapshot, Click, Type, Scroll, Move, Shortcut, Wait,\n> MultiSelect, MultiEdit, Clipboard, Process, Notification, FileSystem, Registry, Scrape\n\nOnce a tool is confirmed, proceed to Step 1. Do NOT test multiple tools in one session.\n\n---\n\n## Step 1: Analyze the Tool\n\nRead the tool's MCP description and parameter schema via the MCP server's tool listing. Identify:\n\n1. **All parameters** — name, type, required/optional, default value, allowed values (enums)\n2. **All modes** (if the tool is mode-based, e.g., FileSystem has read/write/copy/move/delete/list/search/info)\n3. **Return value structure** — what the tool returns on success vs. failure\n4. **Side effects** — does it modify system state? (important for test isolation)\n5. **Dependencies** — does it require a running app, an open window, existing files, etc.?\n\nUse this analysis to inform test case generation. If the description is ambiguous or silent on a\nbehavior, note it as a documentation gap and design a test to probe it. The tool's response is\nthe ground truth.\n\n---\n\n## Step 2: Generate Test Cases\n\nDesign test cases that cover the following categories. Not every category applies to every tool —\nuse judgment based on the tool's nature.\n\n### Category A: Basic Functionality (Required)\nTest the tool's primary purpose with standard, well-formed inputs.\n- One test per mode/operation type (e.g., for FileSystem: read, write, list, etc.)\n- Use realistic parameter values\n\n### Category B: Parameter Variations (Required)\n- Test each optional parameter individually to verify it takes effect\n- Test enum parameters with every allowed value\n- Test boolean parameters in both true and false states\n- **For `anyOf` union types**: The schema advertises all listed types as valid, so the tool must handle each correctly.\n  - `anyOf: [boolean, string]` (e.g., `drag`, `use_vision`): test boolean `true`/`false` AND string `\"true\"`/`\"false\"` — both must produce the same behavior.\n  - **Caveat:** MCP transport layers may silently coerce `\"true\"` (string) to `true` (boolean)\n    before the tool sees it. To genuinely probe the string path, also test non-standard truthy\n    strings like `\"yes\"` or `\"1\"` — if those fail while `\"true\"` passes, the tool likely only\n    receives booleans and the string branch is untested.\n  - `anyOf: [<type>, null]` (nullable): test with a valid value AND explicit `null`. An unhandled TypeError on null is a FAIL.\n- Test with default values (omit optional params) vs. explicit values\n\n### Category C: Edge Cases (Required)\n- Empty strings, zero values, negative numbers where applicable\n- Boundary values (e.g., very long text for Type, timeout=0 for PowerShell)\n- Unicode / special characters in string parameters\n- Very large or very small numeric inputs\n\n### Category D: Error Handling (Required)\n- Missing required parameters\n- Invalid parameter types or out-of-range values\n- Referencing nonexistent resources (files, windows, processes, registry keys)\n- Operations that should fail gracefully (e.g., deleting a non-existent file)\n\n### Category E: Parameter Interaction (When Applicable)\n- Combinations of parameters that might interact (e.g., Click with both `loc` and `label`)\n- Mutually exclusive parameters\n- Mode-specific parameter requirements\n- **Cross-mode parameter applicability**: For mode-based tools, pass parameters meant for one\n  mode while calling another (e.g., `window_loc` in `launch` mode). Silently ignoring them is\n  a documentation gap worth reporting.\n\n### Category F: Idempotency & State (When Applicable)\n- For tools marked `idempotentHint: true`: call twice with same args, verify same result\n- For destructive tools: verify cleanup or rollback is possible\n- For stateful tools: verify state changes are reflected correctly\n\n### Test Case Format\n\nFor each test case, define:\n\n```\nID:          TC-{ToolName}-{Number}\nCategory:    A/B/C/D/E/F\nDescription: What this test verifies\nParameters:  The exact parameters to pass\nExpected:    What a correct result looks like (success/failure, key content in response)\nSetup:       Any prerequisite actions (create a file, open an app, etc.)\nTeardown:    Any cleanup actions after the test\n```\n\nPresent the test plan to the user for confirmation before executing.\nAim for **10-20 test cases** depending on tool complexity.\n\nInclude an **estimated execution time**: approximately **30-45 seconds** per test case\n(includes timing calls, tool execution, verification). App launches add 5-10s extra.\nPresent as a range, e.g., \"Estimated execution time: 8-12 minutes (15 test cases)\".\n\n---\n\n## Step 3: Execute Tests\n\n### Pre-Test Step 1: Gather Environment Info\n\nBefore running test cases, collect the test environment details for the report. Use these\nPowerShell commands for reliable results:\n\n```powershell\n# OS version\n(Get-CimInstance Win32_OperatingSystem).Caption + \" \" + (Get-CimInstance Win32_OperatingSystem).Version\n\n# Display resolution (physical pixels)\nGet-CimInstance Win32_VideoController | Select-Object CurrentHorizontalResolution, CurrentVerticalResolution\n\n# Display count\n(Get-CimInstance Win32_PnPEntity | Where-Object { $_.PNPClass -eq 'Monitor' -and $_.Status -eq 'OK' }).Count\n\n# DPI scale factor (96 = 100%, 120 = 125%, 144 = 150%, 192 = 200%)\nGet-ItemProperty 'HKCU:\\Control Panel\\Desktop\\WindowMetrics' -Name AppliedDPI -ErrorAction SilentlyContinue | Select-Object -ExpandProperty AppliedDPI\n```\n\nAlso call Screenshot once — its `Screenshot Original Size` cross-checks the DPI value,\nand its output includes `Active Desktop` and `All Desktops`.\n\n### Pre-Test Step 2: Prepare Environment\n\nFor **input tools** (Type, Click, Scroll, Move, Shortcut, MultiSelect, MultiEdit), prepare the\nenvironment before executing any test cases:\n\n1. **IME (Input Method) state**: Check the Tray Input Indicator in the Snapshot output. If it\n   shows a non-English input mode (e.g., \"Chinese Mode\", \"Japanese Mode\"), switch to English\n   mode first using the `Shortcut` tool (typically `shift` to toggle). **This is critical for\n   Type tool tests** — an active IME will intercept keystrokes and produce incorrect characters.\n   Record the original IME state and restore it after testing.\n\n2. **Label availability check**: Call Snapshot on the test target window and verify whether the\n   element you intend to use with `label` parameter is actually listed in the Interactive Elements.\n   Common pitfalls:\n   - Modern Windows 11 Notepad's text editing area is **not** exposed as an interactive element\n     in the UI tree — use `loc` coordinates instead.\n   - Some complex controls (e.g., rich text editors, canvas-based UIs) may not enumerate child\n     elements.\n   If a planned `label`-based test has no valid label target, adapt the test to use `loc`, or\n   pick a different element that does have a label (e.g., a search box, address bar).\n\n3. **Warm-up call**: Execute 1-2 throwaway tool calls (not counted in test results) to warm up\n   the MCP connection, window focus, and UI tree cache. First calls are typically slower due to\n   cold start effects — excluding them gives more representative performance numbers.\n\n### Test Execution\n\nRun each test case sequentially. For each test:\n\n> **Label freshness rule:** Snapshot labels are a point-in-time snapshot. If any action between\n> tests could change the UI state, call Snapshot again before using `label` parameters.\n\n> **State reset between tests:** Each test case should start from a known, clean state. For\n> input tools sharing a test window (e.g., Notepad), define a standard reset procedure and\n> execute it in Setup:\n> - **Type tests**: Shortcut (Ctrl+A) → Shortcut (Delete) to clear the text area\n> - **Click/Move tests**: Move cursor to a neutral position away from interactive elements\n> - **Scroll tests**: Reset scroll position to top (Ctrl+Home)\n>\n> If a test's Setup includes `clear=true` in the tool call itself, you may skip the manual\n> reset — but verify in the teardown that the state is clean for the next test.\n\n1. **Setup** — perform any prerequisite actions (e.g., create a temp file for FileSystem read tests).\n   When spawning processes, **record their PIDs** for teardown (see Test Isolation Guidelines).\n2. **Record start time** — call PowerShell to capture a precise timestamp in milliseconds **before** calling the tool:\n   ```powershell\n   [long](([System.DateTime]::UtcNow - [System.DateTime]::UnixEpoch).TotalMilliseconds)\n   ```\n   Save the returned integer as `$t_start`.\n3. **Call the MCP tool** with the specified parameters\n4. **Record end time** — immediately after the tool returns, call PowerShell again with the same command. Save as `$t_end`.\n5. **Compute elapsed time** — `elapsed_ms = $t_end - $t_start`. Note: this includes MCP\n   overhead from the timestamp calls themselves (~3-5s each). Use for relative comparison\n   between test cases only. **When testing the PowerShell tool itself**, timing is\n   self-referential — record times as `N/A (self-referential)` and rely on the PowerShell\n   tool's own `timeout` behavior and status codes for performance assessment instead.\n6. **Capture the response** — store the full return value and measure `response_size`:\n   - **Text-only tools**: character count of the returned string.\n   - **Mixed-content tools** (Screenshot, Snapshot): character count of the **text portion only**,\n     note `+image` in the report. Do not attempt to measure image byte size.\n7. **Evaluate correctness** — compare the response against expected behavior:\n   - Does the response indicate success/failure as expected?\n   - Does the response content match expected patterns?\n   - For error cases: does the error message make sense and provide useful information?\n8. **Verify side effects (MANDATORY)** — independently verify EVERY mutating tool call. Never\n   rely solely on the tool's return value. Never skip or sample.\n   **Rule: verification MUST NOT use the same tool under test.** Use a different tool\n   (preferably PowerShell) to cross-check. Verification methods:\n   - **Move/Click**: call Screenshot or Snapshot to verify the expected UI change occurred.\n   - **Type**: use Shortcut (Ctrl+A → Ctrl+C) then PowerShell `Get-Clipboard` to capture\n     exact text for comparison.\n   - **Drag (Move with drag=True)**: call Snapshot to verify the target window actually moved.\n   - **App (launch/resize)**: call PowerShell (`Get-Process`) to verify process exists, and\n     Screenshot/Snapshot to verify window position/size.\n   - **FileSystem**: verify with PowerShell (`Test-Path`, `Get-Content`, `Get-ChildItem`)\n     — never with the FileSystem tool itself.\n   - **Registry**: verify with PowerShell (`Get-ItemProperty`, `reg query`)\n     — never with the Registry tool itself.\n   - **Clipboard (set)**: verify with PowerShell (`Get-Clipboard`)\n     — never with the Clipboard tool itself.\n   - **Process (kill)**: verify with PowerShell (`Get-Process -Id $pid`)\n     — never with the Process tool itself.\n   - **Shortcut**: call Screenshot to verify the shortcut's expected effect occurred.\n   - For read-only tools (Screenshot, Snapshot, Scrape, Process list), this step is not needed.\n   - If verification fails but the tool reported success, mark the test as **FAIL** and note\n     \"tool reported success but side effect not confirmed\" in the root cause analysis.\n9. **Teardown** — clean up any side effects (delete temp files, close apps, etc.)\n\n> **IMPORTANT:** Never estimate response times. Always use the PowerShell measurement above.\n> If unavailable, record `N/A` and explain why.\n\n### Correctness Evaluation Criteria\n\n| Result    | Meaning                                                                                       |\n|-----------|-----------------------------------------------------------------------------------------------|\n| PASS      | Response matches expected behavior exactly                                                    |\n| SOFT PASS | Response is acceptable but slightly different from ideal (e.g., extra whitespace, ordering)    |\n| FAIL      | Response doesn't match expected behavior — includes cases where the tool rejects schema-valid input. Never look up source code to explain away a failure. |\n| ERROR     | Tool threw an unexpected exception or timed out                                               |\n| SKIP      | Test couldn't run due to missing prerequisites (document why)                                 |\n\n### When to SKIP vs. Adapt\n\nIf a planned test case cannot execute as designed (e.g., the target element has no `label` in the\nUI tree, or a required window state cannot be achieved), decide:\n\n- **SKIP** if the prerequisite is truly missing and no workaround exists. Document the reason.\n- **Adapt** if you can achieve the same test intent with a different approach (e.g., use `loc`\n  instead of `label`, use a different target app). Update the test case description and note the\n  adaptation in the report. Adapting is preferred over skipping when the test intent is still\n  achievable.\n\n### Performance Tracking\n\nFor each test case, record **response time (ms)** via PowerShell timestamps and\n**response size** (character count of the raw response text).\n\n> **Warm-up effect:** The first 1-2 tool calls in a session are typically slower due to MCP\n> connection warm-up, UI tree cache initialization, and window focus acquisition. If warm-up\n> calls were performed in Pre-Test, note this in the report. If not, flag the first test case's\n> timing as potentially inflated and exclude it from aggregate statistics (average, median, P95)\n> or mark it separately.\n\n---\n\n## Step 4: Generate the Test Report\n\n**Localization:** If the user specified a language, write the entire report in that language\n(headings, tables, commentary, recommendations). Keep test case IDs (e.g., TC-Move-01) in\nEnglish. The template below is a structural reference — translate all prose while preserving\nthe markdown structure.\n\n````markdown\n# Windows-MCP Tool Test Report: {ToolName}\n\n**Date:** {timestamp}\n**Tool:** {ToolName}\n**Total Test Cases:** {N}\n**PASS:** {P} | **SOFT PASS:** {SP} | **FAIL:** {F} | **ERROR:** {E} | **SKIP:** {S}\n**Overall Pass Rate:** {(P+SP)/N * 100}%\n\n---\n\n## 1. Test Environment\n\n{Record the environment to aid reproducibility. Data gathered in Pre-Test step.}\n\n| Item                     | Value                                                    |\n|--------------------------|----------------------------------------------------------|\n| OS Version               | {e.g., Windows 11 Pro 10.0.26200}                       |\n| Display Resolution       | {e.g., 2560x1440}                                       |\n| Screenshot Original Size | {e.g., 3840x2160 — this is resolution x scale factor}   |\n| Display Count            | {e.g., 1}                                                |\n| Active Virtual Desktop   | {e.g., Desktop 1}                                        |\n| MCP Transport            | {e.g., SSE via http://localhost:8088/sse}                |\n| Scale Factor             | {e.g., 150% (AppliedDPI=144)}                           |\n\n---\n\n## 2. Executive Summary\n\n{2-3 sentences summarizing the overall health of the tool. Highlight critical failures if any.\nNote any patterns — e.g., \"all error-handling tests failed\" or \"basic functionality is solid\nbut Unicode support is incomplete.\" Also assess these dimensions when relevant:}\n\n- **Error message quality**: descriptive and actionable, or cryptic?\n- **Input validation**: does the tool validate params before executing, or fail deep with confusing errors?\n- **Consistency**: do repeated calls with same params return consistent results?\n- **Graceful degradation**: when prerequisites are missing, does the tool explain what's needed?\n\n---\n\n## 3. Failed & Error Test Cases\n\n{For each non-passing test case, provide:}\n\n### TC-{ID}: {Description}\n- **Category:** {category}\n- **Parameters:** `{params}`\n- **Expected:** {what should have happened}\n- **Actual:** {what actually happened}\n- **Side-Effect Verification:** {what the independent verification revealed, if applicable}\n- **Root Cause Analysis:** {your best assessment of why it failed}\n- **Suggested Fix:** {actionable recommendation for the developer}\n\n{If all tests passed, write: \"All test cases passed. No issues to report.\"}\n\n---\n\n## 4. Performance Analysis\n\n> **Note:** All times are end-to-end measurements including MCP transport overhead\n> (serialization, network round-trip, SSE/stdio latency). They do NOT represent pure tool\n> execution time. Use these numbers for **relative comparison** and outlier detection — not\n> as absolute benchmarks. For pure execution time, check server-side logs with\n> `WINDOWS_MCP_PROFILE_SNAPSHOT=1`.\n\n### Response Time\n\n| Test Case | Time (ms) | Assessment |\n|-----------|-----------|------------|\n| TC-XXX-01 | 6500      | Normal     |\n| TC-XXX-02 | 15200     | Slow       |\n| ...       | ...       | ...        |\n\n**Average:** {avg} ms | **Median:** {median} ms | **P95:** {p95} ms | **Max:** {max} ms\n\n**Assessment thresholds (end-to-end including MCP overhead):**\n- Fast: < 5000ms\n- Normal: 5000ms – 10000ms\n- Slow: 10000ms – 20000ms\n- Very Slow: > 20000ms\n\n{Commentary on any outliers or concerning patterns. When a test case is significantly slower\nthan peers, note possible causes: app launch wait, UI tree traversal, screenshot capture, etc.}\n\n### Response Size\n\n| Test Case | Response Size (chars) |\n|-----------|-----------------------|\n| TC-XXX-01 | 245                   |\n| ...       | ...                   |\n\n{Note any unexpectedly large or empty responses.}\n\n---\n\n## 5. Environmental Interference & Notes\n\n{List any environmental factors that affected test execution but are not bugs in the tool itself.\nThese factors help future testers reproduce results and avoid false failures.}\n\n| # | Factor | Impact | Mitigation |\n|---|--------|--------|------------|\n| 1 | {e.g., IME in Chinese mode} | {e.g., TC-Type-01 typed wrong characters} | {e.g., Switched IME to English before retesting} |\n| ... | ... | ... | ... |\n\n**Common environmental factors:**\n- **IME state**: Active non-English input methods intercept keystrokes (affects Type, Shortcut)\n- **Notification popups**: System or app notifications may steal focus mid-test\n- **Background app focus changes**: Chat apps, update dialogs may overlay the test window\n- **Screen lock / screensaver**: Can interrupt long-running test sessions\n- **Clipboard managers**: Third-party clipboard tools may interfere with Clipboard tests\n\n{If no environmental interference occurred, write: \"No environmental interference observed.\"}\n\n---\n\n## 6. Documentation & Schema Gaps\n\n{List any discrepancies between the tool's MCP parameter schema / description and its actual\nbehavior or environmental interactions. These are not necessarily bugs — they are places where\nthe documentation or schema could be improved to set correct expectations for callers.}\n\n| #   | Gap Type                          | Description | Recommendation |\n|-----|-----------------------------------|-------------|----------------|\n| 1   | {schema / description / behavior} | {desc}      | {rec}          |\n| ... | ...                               | ...         | ...            |\n\n**Gap Types:**\n- **schema**: parameter schema (types, required/optional, allowed values) does not match actual behavior\n- **description**: tool description is silent or ambiguous about a behavior that testing revealed\n- **behavior**: tool behaves inconsistently with what the schema + description together imply\n\n{If no gaps were found, write: \"No documentation or schema gaps identified.\"}\n\n---\n\n## 7. All Test Cases\n\n| ID         | Category   | Description | Result | Time (ms) | Response Size |\n|------------|------------|-------------|--------|-----------|---------------|\n| TC-XXX-01  | A - Basic  | {desc}      | PASS   | 6500      | 245           |\n| TC-XXX-02  | B - Params | {desc}      | FAIL   | 8200      | 310           |\n| ...        | ...        | ...         | ...    | ...       | ...           |\n````\n\n---\n\n## Test Isolation Guidelines\n\nTo avoid polluting the system or interfering with user state:\n\n- **FileSystem tests**: Use a dedicated temp directory (e.g., `%TEMP%\\wmcp-test-{timestamp}\\`).\n  Clean up after all tests complete.\n- **Registry tests**: Use a dedicated test key under `HKCU:\\Software\\WMCP-Test-{timestamp}`.\n  Delete the entire key after testing.\n- **Process tests**: Only list processes (don't kill user processes). If testing kill, spawn a\n  sacrificial process first (e.g., `notepad.exe`) and record its PID.\n- **App tests**: Use lightweight apps (Notepad, Calculator). **Record PIDs** of all processes\n  spawned during testing (use `(Start-Process notepad -PassThru).Id` or query process list\n  before/after launch). In teardown, only kill processes by PID — NEVER by name (e.g.,\n  `Stop-Process -Id $pid`, not `Stop-Process -Name notepad`), because the user may have their\n  own instances of the same application running.\n  - **Modern tabbed apps caveat:** Windows 11 Notepad/Terminal may reuse a single process for\n    multiple tabs. Diff the process list before/after each launch to detect new PIDs. Only kill\n    PIDs that did not exist before testing began.\n- **Clipboard tests**: Save and restore the original clipboard content.\n- **Input tools (Click, Type, Scroll, Move, Shortcut)**: Open a dedicated test window\n  (e.g., Notepad) to receive input. Don't interact with user's active work.\n  See also Pre-Test Step 2 for IME state handling — switch to English input mode before testing\n  and restore the original state in final teardown.\n- **Read-only tools (Screenshot, Snapshot, Scrape)**: Safe to run freely.\n- **Notification tests**: User-visible (sends Windows toasts). Avoid repeated or unnecessary\n  notifications. Prefer a single clearly labeled test notification per test case.\n- **PowerShell tests**: Use read-only commands where possible.\n\n---\n\n## Tool-Specific Testing Guidance\n\nHints per tool. Always read the actual schema to discover additional scenarios beyond these.\n\n### App\n- Modes: launch, resize, switch. Test each mode.\n- Launch: test with known apps (notepad, calc), unknown app names\n- Resize: test with valid window_loc/window_size, without an active app\n- Switch: test switching to a running app, to a non-existent app\n\n### PowerShell\n- Simple commands: `echo \"hello\"`, `Get-Date`, `Get-Process | Select-Object -First 3`\n- Timeout behavior: set a very short timeout with a long-running command\n- Encoding: commands with Unicode output\n- Error output: commands that write to stderr\n- Exit codes: commands that fail (e.g., `Get-Item nonexistent`)\n\n### Screenshot\n- Default parameters (no args)\n- With annotation enabled/disabled\n- With reference lines\n- With specific display index\n- Verify return includes image data\n\n### Snapshot\n- Various flag combinations: use_vision, use_dom, use_annotation, use_ui_tree\n- All flags off vs. all flags on\n- With/without reference lines\n\n### Click\n- By coordinates (loc) vs. by label\n- Different button types: left, right, middle\n- clicks=0 (hover), clicks=1 (single), clicks=2 (double)\n- Invalid coordinates (negative, off-screen)\n- Invalid label (non-existent element ID)\n\n### Type\n- Normal text, Unicode text, special characters\n- With and without clear=true\n- With and without press_enter=true\n- Different caret_position values: start, idle, end\n- By coordinates vs. by label\n- **IME sensitivity**: Test with IME active to verify behavior (expect failure if tool uses\n  keystroke simulation rather than Unicode input). This is a high-value edge case because\n  many Windows machines have non-English IMEs installed.\n- **Emoji / surrogate pair characters**: Test with characters outside the Basic Multilingual\n  Plane (e.g., 🌍, 😀) to verify supplementary plane Unicode support.\n- **Empty string**: Test `text=\"\"` — this is a common edge case that may crash if the\n  implementation indexes into the string without a length check.\n\n### Scroll\n- Vertical up/down, horizontal left/right\n- Different wheel_times values (1, 5, 10)\n- By coordinates vs. by label\n\n### Move\n- Simple move to coordinates\n- Drag mode (drag=true)\n- By coordinates vs. by label\n\n### Shortcut\n- Common shortcuts: ctrl+c, ctrl+v, ctrl+a, alt+tab\n- Windows key shortcuts: win+r, win+d\n- Multi-key combinations\n- Invalid key names\n\n### Wait\n- Short duration (1 second)\n- Zero duration\n- Verify actual elapsed time roughly matches requested duration\n\n### MultiSelect\n- Select multiple items by coordinates\n- Select by labels\n- With and without press_ctrl\n- Empty list of items\n\n### MultiEdit\n- Edit multiple fields by coordinates\n- Edit by labels\n- Mixed valid and invalid targets\n\n### Clipboard\n- get mode when clipboard has text\n- get mode when clipboard is empty\n- set mode with normal text\n- set mode with Unicode text\n- Roundtrip: set then get, verify content matches\n\n### Process\n- list mode with default sort\n- list mode with different sort_by values (memory, cpu, name)\n- list mode with name filter\n- list mode with different limit values\n- kill mode with a sacrificial process (spawn notepad, then kill it)\n\n### Notification\n- Valid notification with title, message, app_id\n- Empty title or message\n- Special characters in title/message\n\n### FileSystem\n- Full mode coverage: read, write, copy, move, delete, list, search, info\n- Read: existing file, non-existent file, offset/limit, different encodings\n- Write: new file, overwrite, append\n- List: with and without pattern, recursive, show_hidden\n- Delete: file, empty dir, non-empty dir with recursive\n\n### Registry\n- Full mode coverage: get, set, delete, list\n- Set and get roundtrip\n- Different value types (String, DWord, QWord)\n- Non-existent key/value\n- Use test-only registry path\n\n### Scrape\n- With a URL (lightweight page)\n- With and without query parameter\n- With use_dom enabled (requires open browser)\n- Invalid URL\n\n<!-- File: CLAUDE.md (Tokens: ~1958 | Category: claude-rule) -->\n# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Project Overview\n\nWindows-MCP is a Python MCP (Model Context Protocol) server that bridges AI LLM agents with the Windows OS, enabling direct desktop automation. It exposes 21 tools via FastMCP:\n\n| Group | Tools |\n|---|---|\n| Capture | `Screenshot`, `Snapshot`, `Scrape`, `DisplayInventory` |\n| Input | `Click`, `Type`, `Scroll`, `Move` (also drag-and-drop via `drag=True`), `Shortcut`, `MultiSelect`, `MultiEdit` |\n| Timing | `Wait`, `WaitFor` |\n| System | `App`, `PowerShell`, `FileSystem`, `Registry`, `Process`, `Clipboard`, `Notification`, `ControlStatus` |\n\nTool names are defined by the `name=` argument of each `@mcp.tool(...)` in `src/windows_mcp/tools/`; that directory is the source of truth. Note the shell tool is registered as `PowerShell`, not `Shell`. Any subset can be removed at startup with `serve --exclude-tools` (e.g. `windows-mcp serve --exclude-tools PowerShell,Registry`).\n\n## Build & Development Commands\n\n```bash\nuv sync --extra dev        # Install runtime and development dependencies\nuv run windows-mcp serve   # Run the MCP server\nuv run --extra dev ruff format .  # Format code\nuv run --extra dev ruff check .   # Lint code\nuv run --extra dev ruff check --fix .  # Lint and auto-fix\nuv run --extra dev pytest         # Run all tests\nuv run --extra dev pytest tests/test_desktop_views.py  # Run a single test file\n```\n\n**Package manager**: UV (not pip). **Python**: 3.14+. **Build backend**: setuptools.\n\n## Architecture\n\nThe codebase follows a layered service architecture under `src/windows_mcp/`:\n\n**Entry point** — `__main__.py`: Builds the FastMCP server, parses CLI flags, and selects the transport. Tool registration is delegated to `tools.register_all()`; an async lifespan initializes the Desktop, WatchDog, and Analytics singletons, which tools resolve lazily through the `get_desktop` / `get_analytics` callables.\n\n**Tools layer** — `tools/`: One module per tool group, each exposing `register(mcp, *, get_desktop, get_analytics)`. `tools/__init__.py` holds the module list and `register_all()`. Tool functions are thin — they normalize arguments and delegate to a service package. The `@with_analytics` decorator wraps each one for telemetry, making it the existing precedent for cross-cutting concerns at the tool boundary.\n\n**Desktop service** — `desktop/service.py`: High-level orchestrator. Manages window operations (launch, resize, switch), screenshots, mouse/keyboard actions, and clipboard. Interfaces with Tree service for UI element discovery. `desktop/views.py` defines data models: `DesktopState`, `Window`, `Size`, `BoundingBox`, `Status`.\n\n**Tree service** — `tree/service.py`: Captures the Windows accessibility tree from active and background windows. Identifies interactive elements and scrollable areas. Uses `ThreadPoolExecutor` for multi-threaded UI traversal. `tree/views.py` defines `TreeElementNode`, `ScrollElementNode`, `TreeState`. `tree/config.py` has control type configurations.\n\n**UIAutomation wrapper** — `uia/`: Low-level abstraction over the Windows UIAutomation COM API via `comtypes`. `core.py` wraps the main automation object, `controls.py` has control-specific logic, `patterns.py` wraps UIAutomation patterns, `enums.py` has COM enumerations, `events.py` handles event subscriptions.\n\n**WatchDog** — `watchdog/service.py`: Runs in a separate thread monitoring UI focus changes via UIAutomation events. Notifies the Tree service of focus changes so the accessibility tree stays current.\n\n**Virtual Desktop Manager** — `vdm/core.py`: Tracks which windows belong to which Windows virtual desktop (Win10/11).\n\n**Domain services** — thin packages backing the system tools: `filesystem/` (read/write/copy/move/delete/list/search/info), `registry/` (get/set/delete/list, implemented via PowerShell cmdlets), `powershell/` (`PowerShellExecutor` plus environment resolution), `process/` (list/kill), `notifications/`. Registry and PowerShell tools shell out, so their latency is dominated by process startup.\n\n**Infrastructure** — `infrastructure/`: cross-cutting concerns. `analytics.py` (optional PostHog telemetry, disabled with `ANONYMIZED_TELEMETRY=false`; records tool names and errors only, never arguments or outputs), `auth.py` and `oauth.py` (bearer-token and OAuth middleware for HTTP transports), `security.py` (SSRF validation, IP allowlist middleware), `config.py` (server configuration). Note `windows_mcp/config.py` at the package root is unrelated — it only holds the `WINDOWS_MCP_DEBUG` helpers.\n\n## Code Style\n\n- Formatter/linter: **Ruff** (line length 100, double quotes)\n- Naming: PEP 8 — `snake_case` functions/variables, `PascalCase` classes, `UPPER_CASE` constants\n- Type hints required on function signatures\n- Google-style docstrings for public functions/classes\n\n## Key Design Details\n\n- Screenshots are capped to 1920x1080 for token efficiency\n- Mouse/keyboard input uses UIA (same coordinate space as BoundingRectangle; no DPI mismatch)\n- Screenshot is the preferred fast visual-context tool; Snapshot is the heavier path for UI element ids and DOM extraction\n- Browser detection (Chrome, Edge, Firefox) triggers special DOM extraction mode in Snapshot\n- Fuzzy string matching (`thefuzz`) is used for element name matching\n- UI element fetching has retry logic (`THREAD_MAX_RETRIES=3` in tree service)\n- The server supports stdio, SSE, and streamable HTTP transports\n\n## Environment Variables\n\n| Variable | Default | Description |\n|---|---|---|\n| `WINDOWS_MCP_SCREENSHOT_SCALE` | `1.0` | Scale factor for screenshots (range `0.1`–`1.0`). Lower on 1440p/4K to stay under Claude Desktop's 1 MB limit. Resolved in `tools/_snapshot_helpers.py`. |\n| `WINDOWS_MCP_SCREENSHOT_BACKEND` | `auto` | Screenshot backend: `auto`, `dxcam`, `mss`, `pillow`. Resolved in `desktop/screenshot.py`. |\n| `WINDOWS_MCP_MAX_TREE_ELEMENTS` | `500` | Max UI elements a single Snapshot/WaitFor tree capture may collect before it stops descending and returns a truncated tree (with a note in the output). Bounds both traversal time and response size on huge flat lists/grids (e.g. an unfiltered inventory view with thousands of rows). Resolved in `tree/budget.py`. |\n| `WINDOWS_MCP_PROFILE_SNAPSHOT` | _(off)_ | Set to `1`/`true`/`yes`/`on` to log per-stage timing for Screenshot/Snapshot. Checked in `tools/_snapshot_helpers.py` and `desktop/service.py`. |\n| `ANONYMIZED_TELEMETRY` | `true` | Set to `false` to disable PostHog telemetry. Checked in `__main__.py` and `infrastructure/analytics.py`. |\n| `POSTHOG_API_KEY` | Project default | Override the PostHog project write key used for anonymous telemetry. Set to an empty string to skip PostHog client initialization. Checked in `infrastructure/analytics.py`. |\n| `POSTHOG_HOST` | `https://us.i.posthog.com` | Override the PostHog host for anonymous telemetry, such as for a self-hosted PostHog deployment. Checked in `infrastructure/analytics.py`. |\n| `WINDOWS_MCP_WATCHDOG` | _(off)_ | Set to `on`/`1`/`true`/`yes`/`enabled` to start the UIA focus WatchDog thread. Unset, or any other value, leaves it off. Opt-in because it only emits debug logging today but can crash the server via the UIA event pump (#332). Resolved in `__main__.py`. |\n| `WINDOWS_MCP_DEBUG` | `false` | Set to `1`/`true`/`yes`/`on` to enable debug mode. Checked in `config.py`. Also available as `--debug` CLI flag. |\n| `WINDOWS_MCP_DISABLE_FLASH` | _(off)_ | Set to `1`/`true`/`yes`/`on` to suppress the orange-red glowing border that briefly appears after every screenshot. Resolved in `desktop/flash_overlay.py`. |\n\n## Security Context\n\nThis server has **full system access** with no sandboxing. `PowerShell`, `FileSystem`, `Registry`, `Process`, and `App` can all perform irreversible operations, and there is no audit log or rollback. The recommended deployment target is a VM or Windows Sandbox. Use `serve --exclude-tools` to drop the tools a given deployment does not need.\n</yakaai_skills>"}