Add window geometry MCP tools

Fill the gap left by ac_focus_window / ac_close_window with
ac_window_move (combined move + resize via the new MoveWindow
helper), ac_window_minimize / _maximize / _restore on top of
ShowWindow with the right SW_* flags. All tools resolve a
matching hwnd via find_window first so the model can target by
title substring instead of tracking handles itself.

Author: JE-Chen

je_auto_control/utils/mcp_server/tools/_factories.py

@@ -288,6 +288,53 @@ def window_tools() -> List[MCPTool]:
             handler=h.close_window,
             annotations=DESTRUCTIVE,
         ),
+        MCPTool(
+            name="ac_window_move",
+            description=("Move and resize the first matching window to "
+                         "(x, y) with dimensions (width, height). "
+                         "Windows-only."),
+            input_schema=schema({
+                "title_substring": {"type": "string"},
+                "x": {"type": "integer"},
+                "y": {"type": "integer"},
+                "width": {"type": "integer"},
+                "height": {"type": "integer"},
+                "case_sensitive": {"type": "boolean"},
+            }, required=["title_substring", "x", "y", "width", "height"]),
+            handler=h.window_move,
+            annotations=DESTRUCTIVE,
+        ),
+        MCPTool(
+            name="ac_window_minimize",
+            description="Minimise the first matching window.",
+            input_schema=schema({
+                "title_substring": {"type": "string"},
+                "case_sensitive": {"type": "boolean"},
+            }, required=["title_substring"]),
+            handler=h.window_minimize,
+            annotations=DESTRUCTIVE,
+        ),
+        MCPTool(
+            name="ac_window_maximize",
+            description="Maximise the first matching window.",
+            input_schema=schema({
+                "title_substring": {"type": "string"},
+                "case_sensitive": {"type": "boolean"},
+            }, required=["title_substring"]),
+            handler=h.window_maximize,
+            annotations=DESTRUCTIVE,
+        ),
+        MCPTool(
+            name="ac_window_restore",
+            description=("Restore the first matching window to its previous "
+                         "size and position."),
+            input_schema=schema({
+                "title_substring": {"type": "string"},
+                "case_sensitive": {"type": "boolean"},
+            }, required=["title_substring"]),
+            handler=h.window_restore,
+            annotations=DESTRUCTIVE,
+        ),
     ]
 
 

je_auto_control/utils/mcp_server/tools/_handlers.py

@@ -427,6 +427,51 @@ def close_window(title_substring: str,
                                        case_sensitive=case_sensitive))
 
 
+def _resolve_window_hwnd(title_substring: str,
+                         case_sensitive: bool) -> int:
+    from je_auto_control.wrapper.auto_control_window import find_window
+    hit = find_window(title_substring, case_sensitive=case_sensitive)
+    if hit is None:
+        raise ValueError(f"no window matches {title_substring!r}")
+    return int(hit[0])
+
+
+def window_move(title_substring: str, x: int, y: int,
+                width: int, height: int,
+                case_sensitive: bool = False) -> Dict[str, int]:
+    """Move and resize the first window matching ``title_substring`` (Win32 only)."""
+    from je_auto_control.windows.window import windows_window_manage as wm
+    hwnd = _resolve_window_hwnd(title_substring, bool(case_sensitive))
+    if not wm.move_window(hwnd, int(x), int(y), int(width), int(height)):
+        raise RuntimeError("MoveWindow returned 0")
+    return {"hwnd": hwnd, "x": int(x), "y": int(y),
+            "width": int(width), "height": int(height)}
+
+
+def _show_command(title_substring: str, case_sensitive: bool,
+                  cmd_show: int) -> int:
+    """Resolve the window then call ShowWindow with the given cmd."""
+    from je_auto_control.windows.window import windows_window_manage as wm
+    hwnd = _resolve_window_hwnd(title_substring, bool(case_sensitive))
+    wm.show_window(hwnd, int(cmd_show))
+    return hwnd
+
+
+def window_minimize(title_substring: str,
+                    case_sensitive: bool = False) -> int:
+    return _show_command(title_substring, bool(case_sensitive), cmd_show=6)
+
+
+def window_maximize(title_substring: str,
+                    case_sensitive: bool = False) -> int:
+    return _show_command(title_substring, bool(case_sensitive), cmd_show=3)
+
+
+def window_restore(title_substring: str,
+                   case_sensitive: bool = False) -> int:
+    return _show_command(title_substring, bool(case_sensitive), cmd_show=9)
+
+
 def get_clipboard() -> str:
     from je_auto_control.utils.clipboard.clipboard import get_clipboard as _get
     return _get()

je_auto_control/windows/window/windows_window_manage.py

@@ -87,4 +87,15 @@ def show_window(hwnd: int, cmd_show: int) -> None:
     if cmd_show < 0 or cmd_show > 11:  # Win32 ShowWindow 常見範圍
         cmd_show = 1  # 預設為 Normal
     user32.ShowWindow(hwnd, cmd_show)
-    user32.SetForegroundWindow(hwnd)
+    user32.SetForegroundWindow(hwnd)
+
+
+def move_window(hwnd: int, x: int, y: int, width: int, height: int,
+                repaint: bool = True) -> bool:
+    """
+    搬移與調整視窗大小 (一次設定座標與寬高)
+    Move and resize a window in one call.
+    """
+    return bool(user32.MoveWindow(int(hwnd), int(x), int(y),
+                                   int(width), int(height),
+                                   c_bool(bool(repaint))))

test/unit_test/headless/test_mcp_server.py

@@ -1301,6 +1301,55 @@ def test_wait_for_pixel_times_out_when_color_never_matches(monkeypatch):
         raise AssertionError("expected TimeoutError")
 
 
+def test_window_geometry_tools_present_in_default_registry():
+    names = {tool.name for tool in build_default_tool_registry()}
+    assert {"ac_window_move", "ac_window_minimize",
+            "ac_window_maximize", "ac_window_restore"}.issubset(names)
+
+
+def test_window_move_calls_into_windows_manager(monkeypatch):
+    import je_auto_control.utils.mcp_server.tools._handlers as handlers
+    import je_auto_control.wrapper.auto_control_window as window_module
+    monkeypatch.setattr(window_module, "find_window",
+                        lambda title, case_sensitive=False: (123, title))
+    captured = {}
+
+    def fake_move(hwnd, x, y, width, height, repaint=True):
+        captured["call"] = (int(hwnd), int(x), int(y),
+                             int(width), int(height))
+        return True
+
+    from je_auto_control.windows.window import windows_window_manage
+    monkeypatch.setattr(windows_window_manage, "move_window", fake_move)
+
+    by_name = {tool.name: tool for tool in build_default_tool_registry()}
+    record = by_name["ac_window_move"].invoke({
+        "title_substring": "Notepad",
+        "x": 10, "y": 20, "width": 800, "height": 600,
+    })
+    assert captured["call"] == (123, 10, 20, 800, 600)
+    assert record == {"hwnd": 123, "x": 10, "y": 20,
+                       "width": 800, "height": 600}
+
+
+def test_window_minimize_uses_show_command_six(monkeypatch):
+    """ShowWindow flag 6 is SW_MINIMIZE."""
+    import je_auto_control.wrapper.auto_control_window as window_module
+    monkeypatch.setattr(window_module, "find_window",
+                        lambda title, case_sensitive=False: (456, title))
+    seen = {}
+
+    def fake_show(hwnd, cmd_show):
+        seen["call"] = (int(hwnd), int(cmd_show))
+
+    from je_auto_control.windows.window import windows_window_manage
+    monkeypatch.setattr(windows_window_manage, "show_window", fake_show)
+
+    by_name = {tool.name: tool for tool in build_default_tool_registry()}
+    by_name["ac_window_minimize"].invoke({"title_substring": "Notepad"})
+    assert seen["call"] == (456, 6)
+
+
 def test_default_registry_lists_core_automation_tools():
     names = {tool.name for tool in build_default_tool_registry()}
     expected = {