Skip to content

Proposal: expose structured per-monitor DPI inventory #327

Description

@zengfanfan

Problem

Windows-MCP can capture selected displays, but agents cannot query a structured per-monitor inventory before choosing coordinates or validating a DPI-specific run. Existing display data does not expose each monitor's work area, orientation, effective DPI, or scale factor through an MCP tool.

Proposed read-only API

Add a DisplayInventory tool returning a top-level array with one record per active monitor:

[
  {
    "index": 0,
    "device": "\\\\.\\DISPLAY1",
    "primary": true,
    "bounds": {"left": 0, "top": 0, "width": 1920, "height": 1080},
    "work_area": {"left": 0, "top": 0, "width": 1920, "height": 1040},
    "resolution": "1920x1080",
    "orientation": "landscape",
    "effective_dpi": 144,
    "scale": 1.5
  }
]

Implementation notes:

  • Reuse the existing monitor enumeration path.
  • Read effective per-monitor DPI with GetDpiForMonitor and fall back to system DPI when unavailable.
  • Read orientation from EnumDisplaySettings.
  • Preserve virtual-screen coordinates, including negative origins.
  • Keep the tool read-only and dependency-free.
  • Return native structured records and let FastMCP serialize the result.

Duplicate check

I searched all issues/PRs and the current main tree. There is no per-monitor inventory implementation other than my withdrawn earlier proposal (#320/#321). Open PR #81 concerns input coordinate conversion. Open PR #93 includes a single ScreenInfo summary, but not a structured inventory of monitor bounds, work areas, orientation, and effective DPI.

Validation prepared

  • Unit coverage for tool registration/output and DPI/orientation fallbacks.
  • Ruff lint/format checks on the changed files.
  • Manual Windows 10 checks on real 100% and 150% display scaling.

Design choices

  • Expose the data through a standalone read-only DisplayInventory tool so capture tools keep their existing responsibilities.
  • Use effective_dpi and scale for the DPI fields.
  • Return active displays only; inactive and disconnected display devices are excluded.

The complete implementation is available in #329. Feedback is welcome through PR review, but no reply to this issue is required before review or merge.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions