pctr 0.3.3__tar.gz → 0.3.5__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {pctr-0.3.3/src/pctr.egg-info → pctr-0.3.5}/PKG-INFO +87 -10
- {pctr-0.3.3 → pctr-0.3.5}/README.md +78 -5
- {pctr-0.3.3 → pctr-0.3.5}/pyproject.toml +9 -6
- pctr-0.3.5/src/pctr/__init__.py +1 -0
- {pctr-0.3.3 → pctr-0.3.5}/src/pctr/cli.py +353 -15
- {pctr-0.3.3 → pctr-0.3.5}/src/pctr/data/AGENTS.md +4 -0
- {pctr-0.3.3 → pctr-0.3.5}/src/pctr/data/SKILL.md +59 -5
- pctr-0.3.5/src/pctr/mcp_server.py +220 -0
- pctr-0.3.5/src/pctr/py.typed +0 -0
- {pctr-0.3.3 → pctr-0.3.5/src/pctr.egg-info}/PKG-INFO +87 -10
- {pctr-0.3.3 → pctr-0.3.5}/src/pctr.egg-info/SOURCES.txt +2 -0
- {pctr-0.3.3 → pctr-0.3.5}/src/pctr.egg-info/entry_points.txt +1 -0
- {pctr-0.3.3 → pctr-0.3.5}/src/pctr.egg-info/requires.txt +6 -0
- pctr-0.3.3/src/pctr/__init__.py +0 -1
- {pctr-0.3.3 → pctr-0.3.5}/LICENSE +0 -0
- {pctr-0.3.3 → pctr-0.3.5}/setup.cfg +0 -0
- {pctr-0.3.3 → pctr-0.3.5}/src/pctr/__main__.py +0 -0
- {pctr-0.3.3 → pctr-0.3.5}/src/pctr.egg-info/dependency_links.txt +0 -0
- {pctr-0.3.3 → pctr-0.3.5}/src/pctr.egg-info/top_level.txt +0 -0
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: pctr
|
|
3
|
-
Version: 0.3.
|
|
3
|
+
Version: 0.3.5
|
|
4
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.
|
|
5
|
-
Author:
|
|
5
|
+
Author: NTUserDev
|
|
6
6
|
License-Expression: MIT
|
|
7
|
-
Project-URL: Homepage, https://github.com/
|
|
8
|
-
Project-URL: Repository, https://github.com/
|
|
9
|
-
Project-URL: Issues, https://github.com/
|
|
7
|
+
Project-URL: Homepage, https://github.com/NTUserDev/pctr
|
|
8
|
+
Project-URL: Repository, https://github.com/NTUserDev/pctr
|
|
9
|
+
Project-URL: Issues, https://github.com/NTUserDev/pctr/issues
|
|
10
10
|
Keywords: automation,windows,uia,pywinauto,desktop,agent,computer-use,rpa
|
|
11
11
|
Classifier: Development Status :: 4 - Beta
|
|
12
12
|
Classifier: Environment :: Win32 (MS Windows)
|
|
@@ -29,6 +29,10 @@ Requires-Dist: pydirectinput>=1.0.4; platform_system == "Windows"
|
|
|
29
29
|
Requires-Dist: pillow>=9.0; platform_system == "Windows"
|
|
30
30
|
Provides-Extra: vision
|
|
31
31
|
Requires-Dist: ultralytics>=8.2; extra == "vision"
|
|
32
|
+
Provides-Extra: mcp
|
|
33
|
+
Requires-Dist: mcp>=2; extra == "mcp"
|
|
34
|
+
Provides-Extra: all
|
|
35
|
+
Requires-Dist: pctr[mcp,vision]; extra == "all"
|
|
32
36
|
Dynamic: license-file
|
|
33
37
|
|
|
34
38
|
# pctr
|
|
@@ -44,15 +48,57 @@ mouse and keyboard input. On top of UIA it also offers **OCR**
|
|
|
44
48
|
(`Windows.Media.Ocr`) and **YOLO-World** open-vocabulary detection for text and
|
|
45
49
|
objects that aren't exposed as controls.
|
|
46
50
|
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
*Driven entirely by pctr itself - list windows, map virtual desktops, dump a
|
|
54
|
+
control tree, `set` a field, read it back with OCR, screenshot it, and YOLO-World
|
|
55
|
+
detect. Recorded with OBS, which pctr also piloted.*
|
|
56
|
+
|
|
47
57
|
## Install
|
|
48
58
|
|
|
49
59
|
```bash
|
|
50
|
-
pip install pctr
|
|
51
|
-
pip install "pctr[vision]" #
|
|
60
|
+
pip install pctr # core (UIA + OCR)
|
|
61
|
+
pip install "pctr[vision]" # + ultralytics, for `pctr look`
|
|
62
|
+
pip install "pctr[mcp]" # + MCP SDK, for the MCP server
|
|
63
|
+
pip install "pctr[all]" # everything
|
|
52
64
|
```
|
|
53
65
|
|
|
54
66
|
Windows only.
|
|
55
67
|
|
|
68
|
+
## MCP server
|
|
69
|
+
|
|
70
|
+
`pctr` ships a Model Context Protocol server so MCP clients (Claude Desktop,
|
|
71
|
+
Cursor, opencode, ...) can drive the Windows desktop directly:
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
pip install "pctr[mcp]"
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Add it to your client config (stdio):
|
|
78
|
+
|
|
79
|
+
```json
|
|
80
|
+
{ "mcpServers": { "pctr": { "command": "pctr-mcp" } } }
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
(or `"command": "python", "args": ["-m", "pctr.mcp_server"]`)
|
|
84
|
+
|
|
85
|
+
Tools exposed: `pctr_windows`, `pctr_tree`, `pctr_find`, `pctr_click`,
|
|
86
|
+
`pctr_set`, `pctr_type`, `pctr_keys`, `pctr_hotkey`, `pctr_focus`, `pctr_wait`,
|
|
87
|
+
`pctr_shot`, `pctr_ocr`, `pctr_ocrfind`, `pctr_ocrclick`, `pctr_look`,
|
|
88
|
+
`pctr_desktop`.
|
|
89
|
+
|
|
90
|
+
Or run/manage it from the CLI:
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
pctr mcp status # SDK + server state
|
|
94
|
+
pctr mcp start --transport streamable-http --port 8765 # background HTTP server
|
|
95
|
+
pctr mcp restart | pctr mcp stop
|
|
96
|
+
pctr mcp help
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
`stdio` runs in the foreground (what a client spawns); `sse` / `streamable-http`
|
|
100
|
+
run in the background, reachable at `http://127.0.0.1:8765/mcp` (or `…/sse`).
|
|
101
|
+
|
|
56
102
|
## Commands
|
|
57
103
|
|
|
58
104
|
| Command | What it does |
|
|
@@ -73,13 +119,17 @@ Windows only.
|
|
|
73
119
|
| `pctr move --x N --y N` / `down` / `up` / `hold --ms N` | Raw mouse control (`--direct` for games). |
|
|
74
120
|
| `pctr drag --start x,y --end x,y [--duration S]` | Drag between two points. |
|
|
75
121
|
| `pctr keydown / keyup --key a` / `keyhold --key w --ms 1500` | Hold keyboard keys (`--direct` for games). |
|
|
76
|
-
| `pctr ocr [--title RE]` | OCR the screen/window; list words with boxes. |
|
|
77
|
-
| `pctr ocrfind --text RE` | OCR then list matches with click centers (single words). |
|
|
78
|
-
| `pctr ocrclick --text RE [--nth N]` | OCR then click a word. |
|
|
122
|
+
| `pctr ocr [--title RE] [--lang TAG]` | OCR the screen/window; list words with boxes. |
|
|
123
|
+
| `pctr ocrfind --text RE [--lang TAG]` | OCR then list matches with click centers (single words). |
|
|
124
|
+
| `pctr ocrclick --text RE [--nth N] [--lang TAG]` | OCR then click a word. |
|
|
79
125
|
| `pctr look --for "a dog" [--title RE] [--conf X]` | YOLO-World detect objects by text prompt. |
|
|
80
126
|
| `pctr lookclick --for "a dog" [--nth N]` | Detect then click the top match. |
|
|
127
|
+
| `pctr mcp <start\|stop\|restart\|status\|help>` | Manage the MCP server (stdio or background http/sse). |
|
|
81
128
|
| `pctr skill [--install]` / `pctr setup` | Print/install the agent skill + an AGENTS.md section. |
|
|
82
129
|
|
|
130
|
+
Global flags: `--json` (machine-readable output) and `--file FILE` (run a batch
|
|
131
|
+
of commands from a file).
|
|
132
|
+
|
|
83
133
|
Common filters: `--title` (regex), `--name` (regex), `--control-type`
|
|
84
134
|
(`Button`, `Edit`, `Pane`, `MenuItem`, …), `--auto-id`, `--nth`, `--process`.
|
|
85
135
|
|
|
@@ -94,6 +144,33 @@ pctr click --title "Notepad" --name "^File$"
|
|
|
94
144
|
pctr set --title "Notepad" --name "Text Editor" --text "hello"
|
|
95
145
|
```
|
|
96
146
|
|
|
147
|
+
## JSON output
|
|
148
|
+
|
|
149
|
+
Add `--json` (global, or per-command) for machine-readable output from
|
|
150
|
+
`windows`, `tree`, `find`, `ocr`, `ocrfind`, `look`, and `desktop`:
|
|
151
|
+
|
|
152
|
+
```bash
|
|
153
|
+
pctr windows --json
|
|
154
|
+
# [{"hwnd":1234,"pid":5678,"title":"Untitled - Notepad"}, ...]
|
|
155
|
+
|
|
156
|
+
pctr desktop list --json
|
|
157
|
+
# [{"index":0,"guid":"ae37…","current":true,"windows":11}, ...]
|
|
158
|
+
|
|
159
|
+
pctr look --for "a car" --json
|
|
160
|
+
# [{"label":"a car","conf":0.86,"x":512,"y":300,"box":[400,220,620,380]}, ...]
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
Progress and warnings go to stderr, so stdout stays valid JSON.
|
|
164
|
+
|
|
165
|
+
## Batch files
|
|
166
|
+
|
|
167
|
+
```bash
|
|
168
|
+
pctr --file script.txt # one command per line; # comments and blanks skipped
|
|
169
|
+
pctr --json --file script.txt # --json applies to every line
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
Stops on the first failing line and reports its line number.
|
|
173
|
+
|
|
97
174
|
## Virtual desktops
|
|
98
175
|
|
|
99
176
|
```bash
|
|
@@ -11,15 +11,57 @@ mouse and keyboard input. On top of UIA it also offers **OCR**
|
|
|
11
11
|
(`Windows.Media.Ocr`) and **YOLO-World** open-vocabulary detection for text and
|
|
12
12
|
objects that aren't exposed as controls.
|
|
13
13
|
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
*Driven entirely by pctr itself - list windows, map virtual desktops, dump a
|
|
17
|
+
control tree, `set` a field, read it back with OCR, screenshot it, and YOLO-World
|
|
18
|
+
detect. Recorded with OBS, which pctr also piloted.*
|
|
19
|
+
|
|
14
20
|
## Install
|
|
15
21
|
|
|
16
22
|
```bash
|
|
17
|
-
pip install pctr
|
|
18
|
-
pip install "pctr[vision]" #
|
|
23
|
+
pip install pctr # core (UIA + OCR)
|
|
24
|
+
pip install "pctr[vision]" # + ultralytics, for `pctr look`
|
|
25
|
+
pip install "pctr[mcp]" # + MCP SDK, for the MCP server
|
|
26
|
+
pip install "pctr[all]" # everything
|
|
19
27
|
```
|
|
20
28
|
|
|
21
29
|
Windows only.
|
|
22
30
|
|
|
31
|
+
## MCP server
|
|
32
|
+
|
|
33
|
+
`pctr` ships a Model Context Protocol server so MCP clients (Claude Desktop,
|
|
34
|
+
Cursor, opencode, ...) can drive the Windows desktop directly:
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
pip install "pctr[mcp]"
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Add it to your client config (stdio):
|
|
41
|
+
|
|
42
|
+
```json
|
|
43
|
+
{ "mcpServers": { "pctr": { "command": "pctr-mcp" } } }
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
(or `"command": "python", "args": ["-m", "pctr.mcp_server"]`)
|
|
47
|
+
|
|
48
|
+
Tools exposed: `pctr_windows`, `pctr_tree`, `pctr_find`, `pctr_click`,
|
|
49
|
+
`pctr_set`, `pctr_type`, `pctr_keys`, `pctr_hotkey`, `pctr_focus`, `pctr_wait`,
|
|
50
|
+
`pctr_shot`, `pctr_ocr`, `pctr_ocrfind`, `pctr_ocrclick`, `pctr_look`,
|
|
51
|
+
`pctr_desktop`.
|
|
52
|
+
|
|
53
|
+
Or run/manage it from the CLI:
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
pctr mcp status # SDK + server state
|
|
57
|
+
pctr mcp start --transport streamable-http --port 8765 # background HTTP server
|
|
58
|
+
pctr mcp restart | pctr mcp stop
|
|
59
|
+
pctr mcp help
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
`stdio` runs in the foreground (what a client spawns); `sse` / `streamable-http`
|
|
63
|
+
run in the background, reachable at `http://127.0.0.1:8765/mcp` (or `…/sse`).
|
|
64
|
+
|
|
23
65
|
## Commands
|
|
24
66
|
|
|
25
67
|
| Command | What it does |
|
|
@@ -40,13 +82,17 @@ Windows only.
|
|
|
40
82
|
| `pctr move --x N --y N` / `down` / `up` / `hold --ms N` | Raw mouse control (`--direct` for games). |
|
|
41
83
|
| `pctr drag --start x,y --end x,y [--duration S]` | Drag between two points. |
|
|
42
84
|
| `pctr keydown / keyup --key a` / `keyhold --key w --ms 1500` | Hold keyboard keys (`--direct` for games). |
|
|
43
|
-
| `pctr ocr [--title RE]` | OCR the screen/window; list words with boxes. |
|
|
44
|
-
| `pctr ocrfind --text RE` | OCR then list matches with click centers (single words). |
|
|
45
|
-
| `pctr ocrclick --text RE [--nth N]` | OCR then click a word. |
|
|
85
|
+
| `pctr ocr [--title RE] [--lang TAG]` | OCR the screen/window; list words with boxes. |
|
|
86
|
+
| `pctr ocrfind --text RE [--lang TAG]` | OCR then list matches with click centers (single words). |
|
|
87
|
+
| `pctr ocrclick --text RE [--nth N] [--lang TAG]` | OCR then click a word. |
|
|
46
88
|
| `pctr look --for "a dog" [--title RE] [--conf X]` | YOLO-World detect objects by text prompt. |
|
|
47
89
|
| `pctr lookclick --for "a dog" [--nth N]` | Detect then click the top match. |
|
|
90
|
+
| `pctr mcp <start\|stop\|restart\|status\|help>` | Manage the MCP server (stdio or background http/sse). |
|
|
48
91
|
| `pctr skill [--install]` / `pctr setup` | Print/install the agent skill + an AGENTS.md section. |
|
|
49
92
|
|
|
93
|
+
Global flags: `--json` (machine-readable output) and `--file FILE` (run a batch
|
|
94
|
+
of commands from a file).
|
|
95
|
+
|
|
50
96
|
Common filters: `--title` (regex), `--name` (regex), `--control-type`
|
|
51
97
|
(`Button`, `Edit`, `Pane`, `MenuItem`, …), `--auto-id`, `--nth`, `--process`.
|
|
52
98
|
|
|
@@ -61,6 +107,33 @@ pctr click --title "Notepad" --name "^File$"
|
|
|
61
107
|
pctr set --title "Notepad" --name "Text Editor" --text "hello"
|
|
62
108
|
```
|
|
63
109
|
|
|
110
|
+
## JSON output
|
|
111
|
+
|
|
112
|
+
Add `--json` (global, or per-command) for machine-readable output from
|
|
113
|
+
`windows`, `tree`, `find`, `ocr`, `ocrfind`, `look`, and `desktop`:
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
pctr windows --json
|
|
117
|
+
# [{"hwnd":1234,"pid":5678,"title":"Untitled - Notepad"}, ...]
|
|
118
|
+
|
|
119
|
+
pctr desktop list --json
|
|
120
|
+
# [{"index":0,"guid":"ae37…","current":true,"windows":11}, ...]
|
|
121
|
+
|
|
122
|
+
pctr look --for "a car" --json
|
|
123
|
+
# [{"label":"a car","conf":0.86,"x":512,"y":300,"box":[400,220,620,380]}, ...]
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
Progress and warnings go to stderr, so stdout stays valid JSON.
|
|
127
|
+
|
|
128
|
+
## Batch files
|
|
129
|
+
|
|
130
|
+
```bash
|
|
131
|
+
pctr --file script.txt # one command per line; # comments and blanks skipped
|
|
132
|
+
pctr --json --file script.txt # --json applies to every line
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
Stops on the first failing line and reports its line number.
|
|
136
|
+
|
|
64
137
|
## Virtual desktops
|
|
65
138
|
|
|
66
139
|
```bash
|
|
@@ -4,12 +4,12 @@ build-backend = "setuptools.build_meta"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "pctr"
|
|
7
|
-
version = "0.3.
|
|
7
|
+
version = "0.3.5"
|
|
8
8
|
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."
|
|
9
9
|
readme = "README.md"
|
|
10
10
|
requires-python = ">=3.10"
|
|
11
11
|
license = "MIT"
|
|
12
|
-
authors = [{ name = "
|
|
12
|
+
authors = [{ name = "NTUserDev" }]
|
|
13
13
|
keywords = ["automation", "windows", "uia", "pywinauto", "desktop", "agent", "computer-use", "rpa"]
|
|
14
14
|
classifiers = [
|
|
15
15
|
"Development Status :: 4 - Beta",
|
|
@@ -34,17 +34,20 @@ dependencies = [
|
|
|
34
34
|
|
|
35
35
|
[project.optional-dependencies]
|
|
36
36
|
vision = ["ultralytics>=8.2"]
|
|
37
|
+
mcp = ["mcp>=2"]
|
|
38
|
+
all = ["pctr[vision,mcp]"]
|
|
37
39
|
|
|
38
40
|
[project.scripts]
|
|
39
41
|
pctr = "pctr.cli:main"
|
|
42
|
+
pctr-mcp = "pctr.mcp_server:main"
|
|
40
43
|
|
|
41
44
|
[project.urls]
|
|
42
|
-
Homepage = "https://github.com/
|
|
43
|
-
Repository = "https://github.com/
|
|
44
|
-
Issues = "https://github.com/
|
|
45
|
+
Homepage = "https://github.com/NTUserDev/pctr"
|
|
46
|
+
Repository = "https://github.com/NTUserDev/pctr"
|
|
47
|
+
Issues = "https://github.com/NTUserDev/pctr/issues"
|
|
45
48
|
|
|
46
49
|
[tool.setuptools.packages.find]
|
|
47
50
|
where = ["src"]
|
|
48
51
|
|
|
49
52
|
[tool.setuptools.package-data]
|
|
50
|
-
pctr = ["data/*.md"]
|
|
53
|
+
pctr = ["data/*.md", "py.typed"]
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
__version__ = "0.3.5"
|