pctr 0.3.2__tar.gz → 0.3.4__tar.gz

{pctr-0.3.2/src/pctr.egg-info → pctr-0.3.4}/PKG-INFO

@@ -1,9 +1,12 @@
 Metadata-Version: 2.4
 Name: pctr
-Version: 0.3.2
+Version: 0.3.4
 Summary: Element-based Windows UI Automation CLI for AI agents. Find controls by name/type/id and click, type, hold, drag, and screenshot - no pixel coordinates.
 Author: Space-lab515
 License-Expression: MIT
+Project-URL: Homepage, https://github.com/Space-lab515/pctr
+Project-URL: Repository, https://github.com/Space-lab515/pctr
+Project-URL: Issues, https://github.com/Space-lab515/pctr/issues
 Keywords: automation,windows,uia,pywinauto,desktop,agent,computer-use,rpa
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Win32 (MS Windows)
@@ -26,6 +29,8 @@ Requires-Dist: pydirectinput>=1.0.4; platform_system == "Windows"
 Requires-Dist: pillow>=9.0; platform_system == "Windows"
 Provides-Extra: vision
 Requires-Dist: ultralytics>=8.2; extra == "vision"
+Provides-Extra: mcp
+Requires-Dist: mcp>=2; extra == "mcp"
 Dynamic: license-file
 
 # pctr
@@ -50,6 +55,28 @@ pip install "pctr[vision]"   # adds ultralytics for `pctr look`
 
 Windows only.
 
+## MCP server
+
+`pctr` ships a Model Context Protocol server so MCP clients (Claude Desktop,
+Cursor, opencode, ...) can drive the Windows desktop directly:
+
+```bash
+pip install "pctr[mcp]"
+```
+
+Add it to your client config (stdio):
+
+```json
+{ "mcpServers": { "pctr": { "command": "pctr-mcp" } } }
+```
+
+(or `"command": "python", "args": ["-m", "pctr.mcp_server"]`)
+
+Tools exposed: `pctr_windows`, `pctr_tree`, `pctr_find`, `pctr_click`,
+`pctr_set`, `pctr_type`, `pctr_keys`, `pctr_hotkey`, `pctr_focus`, `pctr_wait`,
+`pctr_shot`, `pctr_ocr`, `pctr_ocrfind`, `pctr_ocrclick`, `pctr_look`,
+`pctr_desktop`.
+
 ## Commands
 
 | Command | What it does |

{pctr-0.3.2 → pctr-0.3.4}/README.md

@@ -20,6 +20,28 @@ pip install "pctr[vision]"   # adds ultralytics for `pctr look`
 
 Windows only.
 
+## MCP server
+
+`pctr` ships a Model Context Protocol server so MCP clients (Claude Desktop,
+Cursor, opencode, ...) can drive the Windows desktop directly:
+
+```bash
+pip install "pctr[mcp]"
+```
+
+Add it to your client config (stdio):
+
+```json
+{ "mcpServers": { "pctr": { "command": "pctr-mcp" } } }
+```
+
+(or `"command": "python", "args": ["-m", "pctr.mcp_server"]`)
+
+Tools exposed: `pctr_windows`, `pctr_tree`, `pctr_find`, `pctr_click`,
+`pctr_set`, `pctr_type`, `pctr_keys`, `pctr_hotkey`, `pctr_focus`, `pctr_wait`,
+`pctr_shot`, `pctr_ocr`, `pctr_ocrfind`, `pctr_ocrclick`, `pctr_look`,
+`pctr_desktop`.
+
 ## Commands
 
 | Command | What it does |

{pctr-0.3.2 → pctr-0.3.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pctr"
-version = "0.3.2"
+version = "0.3.4"
 description = "Element-based Windows UI Automation CLI for AI agents. Find controls by name/type/id and click, type, hold, drag, and screenshot - no pixel coordinates."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -34,9 +34,16 @@ dependencies = [
 
 [project.optional-dependencies]
 vision = ["ultralytics>=8.2"]
+mcp = ["mcp>=2"]
 
 [project.scripts]
 pctr = "pctr.cli:main"
+pctr-mcp = "pctr.mcp_server:main"
+
+[project.urls]
+Homepage = "https://github.com/Space-lab515/pctr"
+Repository = "https://github.com/Space-lab515/pctr"
+Issues = "https://github.com/Space-lab515/pctr/issues"
 
 [tool.setuptools.packages.find]
 where = ["src"]

pctr-0.3.4/src/pctr/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.3.4"

pctr-0.3.4/src/pctr/mcp_server.py

@@ -0,0 +1,205 @@
+"""pctr MCP server - exposes pctr's Windows UI automation as MCP tools.
+
+Run over stdio (default). Add it to an MCP client (Claude Desktop, Cursor,
+opencode, ...) as:
+
+    { "command": "pctr-mcp" }
+
+or:
+
+    { "command": "python", "args": ["-m", "pctr.mcp_server"] }
+
+Needs the MCP SDK:  pip install "pctr[mcp]"
+"""
+
+import subprocess
+import sys
+
+try:
+    from mcp.server.mcpserver import MCPServer
+except Exception as e:  # pragma: no cover
+    raise SystemExit('pctr-mcp needs the MCP SDK: pip install "pctr[mcp]" (%s)' % e)
+
+try:
+    from pctr import __version__ as _VERSION
+except Exception:  # pragma: no cover
+    _VERSION = ""
+
+server = MCPServer(
+    "pctr",
+    version=_VERSION or "0.3.3",
+    instructions=(
+        "Element-based Windows UI automation. Find controls by name / control "
+        "type / automation id instead of pixel coordinates, then click/type/etc. "
+        "Also: OCR (ocr/ocrfind/ocrclick), YOLO-World (look), and virtual desktops "
+        "(desktop). Windows only."
+    ),
+)
+
+
+def _run(args):
+    """Run the pctr CLI and return stdout (+ stderr and exit code on failure)."""
+    cmd = [sys.executable, "-m", "pctr"] + [str(a) for a in args]
+    p = subprocess.run(cmd, capture_output=True, text=True)
+    out = (p.stdout or "").strip()
+    err = (p.stderr or "").strip()
+    if p.returncode != 0:
+        parts = ["exit=%d" % p.returncode]
+        if out:
+            parts.append(out)
+        if err:
+            parts.append(err)
+        return "\n".join(parts)
+    return out or "(no output)"
+
+
+def _selectors(title=None, process=None, name=None, control_type=None, auto_id=None, nth=None):
+    a = []
+    if title:
+        a += ["--title", title]
+    if process is not None:
+        a += ["--process", str(process)]
+    if name:
+        a += ["--name", name]
+    if control_type:
+        a += ["--control-type", control_type]
+    if auto_id:
+        a += ["--auto-id", auto_id]
+    if nth is not None:
+        a += ["--nth", str(nth)]
+    return a
+
+
+@server.tool(description="List top-level windows (pid | title). Filter by --filter regex or process id.")
+def pctr_windows(filter: str | None = None, process: int | None = None) -> str:
+    a = []
+    if filter:
+        a += ["--filter", filter]
+    if process is not None:
+        a += ["--process", str(process)]
+    return _run(["windows"] + a)
+
+
+@server.tool(description="Dump the UIA control tree of a window. Provide --title (or process). Optional depth/limit.")
+def pctr_tree(title: str | None = None, process: int | None = None, depth: int | None = None, limit: int | None = None) -> str:
+    a = ["tree"] + _selectors(title=title, process=process)
+    if depth is not None:
+        a += ["--depth", str(depth)]
+    if limit is not None:
+        a += ["--limit", str(limit)]
+    return _run(a)
+
+
+@server.tool(description="Find elements in a window and print name/type/id/rect. Any selector works; tree/find need title or process.")
+def pctr_find(title: str | None = None, process: int | None = None, name: str | None = None,
+              control_type: str | None = None, auto_id: str | None = None,
+              nth: int | None = None, limit: int | None = None) -> str:
+    a = ["find"] + _selectors(title=title, process=process, name=name,
+                              control_type=control_type, auto_id=auto_id, nth=nth)
+    if limit is not None:
+        a += ["--limit", str(limit)]
+    return _run(a)
+
+
+@server.tool(description="Click an element. method: auto|invoke|mouse (invoke works cross-desktop).")
+def pctr_click(title: str | None = None, process: int | None = None, name: str | None = None,
+               control_type: str | None = None, auto_id: str | None = None, nth: int | None = None,
+               method: str = "auto", button: str = "left", dbl: bool = False) -> str:
+    a = ["click"] + _selectors(title=title, process=process, name=name,
+                               control_type=control_type, auto_id=auto_id, nth=nth)
+    a += ["--method", method, "--button", button]
+    if dbl:
+        a.append("--dbl")
+    return _run(a)
+
+
+@server.tool(description="Set a field's text via the UIA ValuePattern (exact; prefer over type).")
+def pctr_set(text: str, title: str | None = None, process: int | None = None, name: str | None = None,
+             control_type: str | None = None, auto_id: str | None = None, nth: int | None = None) -> str:
+    a = ["set"] + _selectors(title=title, process=process, name=name,
+                             control_type=control_type, auto_id=auto_id, nth=nth)
+    a += ["--text", text]
+    return _run(a)
+
+
+@server.tool(description="Send keystrokes (global or to an element). NOTE: pywinauto key syntax - { } + ^ % ~ ( ) are interpreted, not literal.")
+def pctr_type(text: str, title: str | None = None, name: str | None = None,
+              delay: float = 0.03, chunk: int = 1) -> str:
+    a = ["type", "--text", text, "--delay", str(delay), "--chunk", str(chunk)]
+    if title:
+        a += ["--title", title]
+    if name:
+        a += ["--name", name]
+    return _run(a)
+
+
+@server.tool(description="Send a global key combo in pywinauto syntax, e.g. {ENTER}. Prefer hotkey for modifiers.")
+def pctr_keys(keys: str) -> str:
+    return _run(["keys", "--keys", keys])
+
+
+@server.tool(description="Send a modifier combo, e.g. ctrl+s, win+shift+s.")
+def pctr_hotkey(keys: str) -> str:
+    return _run(["hotkey", "--keys", keys])
+
+
+@server.tool(description="Bring a window to the foreground.")
+def pctr_focus(title: str | None = None, process: int | None = None) -> str:
+    return _run(["focus"] + _selectors(title=title, process=process))
+
+
+@server.tool(description="Wait until an element exists.")
+def pctr_wait(title: str | None = None, process: int | None = None, name: str | None = None,
+              control_type: str | None = None, auto_id: str | None = None, timeout: float = 10.0) -> str:
+    a = ["wait"] + _selectors(title=title, process=process, name=name,
+                              control_type=control_type, auto_id=auto_id)
+    a += ["--timeout", str(timeout)]
+    return _run(a)
+
+
+@server.tool(description="Screenshot the screen (or a window) to a file path.")
+def pctr_shot(out: str, title: str | None = None, process: int | None = None) -> str:
+    a = ["shot", "--out", out] + _selectors(title=title, process=process)
+    return _run(a)
+
+
+@server.tool(description="OCR the screen (or a window); list recognised words with boxes.")
+def pctr_ocr(title: str | None = None, process: int | None = None) -> str:
+    return _run(["ocr"] + _selectors(title=title, process=process))
+
+
+@server.tool(description="OCR then list words matching --text (single words).")
+def pctr_ocrfind(text: str, title: str | None = None, process: int | None = None) -> str:
+    return _run(["ocrfind", "--text", text] + _selectors(title=title, process=process))
+
+
+@server.tool(description="OCR then click the word matching --text.")
+def pctr_ocrclick(text: str, title: str | None = None, process: int | None = None, nth: int = 0) -> str:
+    return _run(["ocrclick", "--text", text, "--nth", str(nth)] + _selectors(title=title, process=process))
+
+
+@server.tool(description="YOLO-World open-vocabulary detection by text prompt (e.g. 'a blue folder icon').")
+def pctr_look(for_: str, title: str | None = None, process: int | None = None, conf: float | None = None) -> str:
+    a = ["look", "--for", for_] + _selectors(title=title, process=process)
+    if conf is not None:
+        a += ["--conf", str(conf)]
+    return _run(a)
+
+
+@server.tool(description="Virtual desktops: action = list | windows | where | on-current | next | prev | new | close | move-window.")
+def pctr_desktop(action: str, title: str | None = None, process: int | None = None,
+                 desktop: int | None = None, to: int | None = None) -> str:
+    a = ["desktop", action] + _selectors(title=title, process=process)
+    if desktop is not None:
+        a += ["--desktop", str(desktop)]
+    if to is not None:
+        a += ["--to", str(to)]
+    return _run(a)
+
+
+def main():
+    server.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

{pctr-0.3.2 → pctr-0.3.4/src/pctr.egg-info}/PKG-INFO

@@ -1,9 +1,12 @@
 Metadata-Version: 2.4
 Name: pctr
-Version: 0.3.2
+Version: 0.3.4
 Summary: Element-based Windows UI Automation CLI for AI agents. Find controls by name/type/id and click, type, hold, drag, and screenshot - no pixel coordinates.
 Author: Space-lab515
 License-Expression: MIT
+Project-URL: Homepage, https://github.com/Space-lab515/pctr
+Project-URL: Repository, https://github.com/Space-lab515/pctr
+Project-URL: Issues, https://github.com/Space-lab515/pctr/issues
 Keywords: automation,windows,uia,pywinauto,desktop,agent,computer-use,rpa
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Win32 (MS Windows)
@@ -26,6 +29,8 @@ Requires-Dist: pydirectinput>=1.0.4; platform_system == "Windows"
 Requires-Dist: pillow>=9.0; platform_system == "Windows"
 Provides-Extra: vision
 Requires-Dist: ultralytics>=8.2; extra == "vision"
+Provides-Extra: mcp
+Requires-Dist: mcp>=2; extra == "mcp"
 Dynamic: license-file
 
 # pctr
@@ -50,6 +55,28 @@ pip install "pctr[vision]"   # adds ultralytics for `pctr look`
 
 Windows only.
 
+## MCP server
+
+`pctr` ships a Model Context Protocol server so MCP clients (Claude Desktop,
+Cursor, opencode, ...) can drive the Windows desktop directly:
+
+```bash
+pip install "pctr[mcp]"
+```
+
+Add it to your client config (stdio):
+
+```json
+{ "mcpServers": { "pctr": { "command": "pctr-mcp" } } }
+```
+
+(or `"command": "python", "args": ["-m", "pctr.mcp_server"]`)
+
+Tools exposed: `pctr_windows`, `pctr_tree`, `pctr_find`, `pctr_click`,
+`pctr_set`, `pctr_type`, `pctr_keys`, `pctr_hotkey`, `pctr_focus`, `pctr_wait`,
+`pctr_shot`, `pctr_ocr`, `pctr_ocrfind`, `pctr_ocrclick`, `pctr_look`,
+`pctr_desktop`.
+
 ## Commands
 
 | Command | What it does |

{pctr-0.3.2 → pctr-0.3.4}/src/pctr.egg-info/SOURCES.txt

@@ -4,6 +4,7 @@ pyproject.toml
 src/pctr/__init__.py
 src/pctr/__main__.py
 src/pctr/cli.py
+src/pctr/mcp_server.py
 src/pctr.egg-info/PKG-INFO
 src/pctr.egg-info/SOURCES.txt
 src/pctr.egg-info/dependency_links.txt

{pctr-0.3.2 → pctr-0.3.4}/src/pctr.egg-info/entry_points.txt

@@ -1,2 +1,3 @@
 [console_scripts]
 pctr = pctr.cli:main
+pctr-mcp = pctr.mcp_server:main

{pctr-0.3.2 → pctr-0.3.4}/src/pctr.egg-info/requires.txt

@@ -6,5 +6,8 @@ pyautogui>=0.9.54
 pydirectinput>=1.0.4
 pillow>=9.0
 
+[mcp]
+mcp>=2
+
 [vision]
 ultralytics>=8.2

pctr-0.3.2/src/pctr/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.3.2"