Skip to main content
Glama
README.md
# Vantage Workbench

**Read any Windows data — files, registry, event logs, process memory, screenshots, even text inside pictures — from an MCP agent, without taking over the desktop.**

[![tests](https://github.com/ChePan7/vantage-workbench/actions/workflows/tests.yml/badge.svg)](https://github.com/ChePan7/vantage-workbench/actions/workflows/tests.yml)
[![python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
[![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)

`Vantage Workbench` is the working name of the `dsh-data-workbench` plugin: 93 MCP tools behind one idea — *observation should cost the human nothing*. No window flashes on screen, no cursor moves, no focus is stolen, and a hung job costs seconds instead of your whole timeout budget.

![A window captured while it was covered — synthetic demo data](docs/screenshot.png)

## What it does

| Area | Tools | What you get |
|---|---|---|
| **Process memory** | `mem_overview` `mem_read` `mem_scan` `mem_strings` `mem_pointer` `mem_write` `mem_dump` | modules + address map, wildcard/typed scans, printable strings with addresses, pointer chains, write with rollback |
| **Native Windows data** | `win_registry` `win_registry_search` `win_eventlog` `win_wmi` `win_services` `win_tasks` `win_network` `win_sessions` `win_installed` `win_raw_file` `win_dpapi` `win_environment` | 32/64 registry views, parsed events, WQL, live service state, owner-pid sockets, locked files and volumes, DPAPI blobs |
| **Jobs & progress** | `job_download` `job_cli` `job_call` `job_wait` `job_watch` `job_status` `job_list` `job_log` `job_cancel` | everything returns immediately; progress is real (bytes, `%`, items); `job_wait` returns **the moment work ends**; `job_watch` returns on any change; a worker that stops consuming CPU/IO is reported `hung` instead of silently burning the budget |
| **Vision** | `window_capture` `window_gallery` `screen_capture` `monitors` `image_info` `image_crop` | occlusion-proof window capture, every window separately, per-monitor DPI, crop+zoom for small text |
| **OCR** | `image_text` `ocr_languages` | text plus a box per line, through the OCR engine Windows already ships; `pattern=` gives you a clickable centre |
| **Data files** | `data_file_query` `data_pipeline` `data_profile` `data_sqlite_query` `data_catalog` | CSV/TSV/JSON/JSONL/XLSX, SQLite with a WAL-consistent snapshot, multi-file SQL |
| **Desktop automation** | `window_list` `ui_read_*` `ui_click` `ui_type_text` `workflow_execute` … | hidden desktops, off-screen windows, UIA trees, message-level input |
| **Self-observation** | `work_status` `work_mark` `work_timings` `audit_log` | what is running right now, for how long, whether it is moving, and who read what |

## Why it exists

Most automation tools answer "how do I drive this app?". This one answers a different question: **"how do I read this machine without the person in front of it noticing me?"** Everything is built around that:

- **Isolation, not hiding.** A program can run on a `CreateDesktop` desktop the human never sees; a window can be parked at `-32000,-32000` where it still lays out, so `PrintWindow` returns live pixels; anything that has to be visible is operated purely through window messages.
- **Occlusion is not a wall.** `window_capture` walks four paths — `PrintWindow(PW_RENDERFULLCONTENT)`, client-only, window DC, child window — and only falls back to a screen grab when the window is *proven* to be on top at its own centre. A covered window still reads, and a reply never hands you somebody else's pixels dressed up as yours.
- **Silence is not death.** A job is `hung` only when it produces nothing **and** burns no CPU/IO (per-thread `GetThreadTimes`, child-process trees for CLI). A compiler that prints for ten minutes is `working`, not stuck.
- **Boring on purpose.** No debugger attach, no injection, no thread suspension, no input synthesis on the human's desktop. Captures are serialised, screen DCs are released immediately, and every sensitive read lands in `audit.jsonl` (metadata only).

## Quickstart

### As a DSH plugin

```bash
git clone https://github.com/ChePan7/vantage-workbench.git
cp -r vantage-workbench <DSH_HOME>/profiles/<profile>/node_modules/dsh-data-workbench
# add the two insert rows from cordis.patch.yml to the profile patch, then restart DSH
```

The host half (`lib/index.js`) mirrors the Python package into `$DSH_HOME/vantage-mcp/vantage` on start; the MCP row launches `python -m vantage`. Nothing is pinned to a machine.

### As a Python library

```bash
pip install fastmcp pillow psutil
```

```python
from vantage import memory, winsys, jobs, vision, ocr

memory.strings(pid, filter="token", module="app.dll")
memory.pointer_chain(pid, "app.dll+0x20", [0x10, 0x8])
winsys.registry(r"HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion")
winsys.raw_file(r"C:\Windows\System32\config\SOFTWARE", size=64)   # even while locked

j = jobs.start_download("https://example.com/big.iso", save_path="D:/dl/big.iso", sha256="…")
jobs.watch(j["job_id"], timeout_ms=1500)     # returns on change, not on a blind timer
ocr.image_text("shot.png", scale=3, pattern="登录")   # text + clickable centres
```

### From an MCP client

```json
{"title_hint":"Inventory","mode":"auto","max_edge":1600}
{"max_windows":4,"scale":0.4}
{"job_id":"…","timeout_ms":15000,"stall_ms":0}
{"path":"shot.png","scale":3,"pattern":"登录"}
```

## Measured, not claimed

| Scenario | Result |
|---|---|
| 4 MB throttled download, 30 s budget | `job_wait` returned in **2316 ms**, `saved_ms=27684`, sha256 verified |
| Silent but CPU-busy worker (10 s) | `working:true, cpu_ms_s≈571, source:"thread"` — not flagged hung, finished normally |
| Worker that goes quiet and idle | flagged `hung` after the tolerance (10 s), cancel + retry costs seconds |
| Covered Chromium window | full content readable via `PrintWindow`; focus and window positions unchanged |
| Windowless background process | 182 MB readable; command line and environment strings recovered |
| OCR of a 640×140 render | `Vantage OCR 12345`, box `[19.7, 41.7, 120.7, 10.7]`, 0.35 s |
| Regression suite | `python -m unittest discover -s python/tests` → **19 passed** |

## Limits (honest)

- **Integrity level decides memory access.** Admin/SYSTEM/PPL processes are out of reach from a normal user token; protected processes need a kernel driver.
- **Covered UWP/WinUI windows** answer `PrintWindow` with a flat colour. `allow_raise=True` lifts them for ~0.15 s (no focus change) and restores the z-order; that is the user-mode ceiling.
- **Encrypted app databases** (WeChat/QQ styles) yield ciphertext without the app's key; cloud placeholders and BitLocker/EFS volumes are the same story.
- **A synchronous tool call cannot report mid-flight progress** — MCP is one request, one response. Wrap it in `job_call`, or use a tool that reports counters.
- **Exclusive fullscreen games** capture as black; that is a `PrintWindow` limit, not a bug.

## Repository layout

```
lib/index.js            DSH host half (mirrors the python package into $DSH_HOME)
cordis.patch.yml        bundle row: plugin + MCP client
python/vantage/         21 modules — server, memory, winsys, jobs, progress, vision, ocr, …
python/tests/           19 unittest cases (stdlib only)
docs/screenshot.png     the demo above
docs/zh.md              detailed Chinese documentation
```

## Tests

```bash
cd python
python -m unittest discover -s tests -v
```

The suite uses a local HTTP server, a scratch SQLite file, synthetic child processes and generated images; it never touches your real windows or your real `%LOCALAPPDATA%\vantage-mcp` data directory.

## Safety and scope

These are powerful reads: process memory, DPAPI blobs, locked files, screenshots. Use them **on machines you own or are explicitly authorised to inspect**. Every sensitive call is written to `%LOCALAPPDATA%\vantage-mcp\audit.jsonl` (tool, target, duration, result size — never content), so you can always answer "what did I touch?".

## License

MIT — see [LICENSE](LICENSE).