# Data Hermetica Desktop MCP

Windows desktop automation over local MCP stdio, with a separate optional
[REA](https://github.com/morluto/rea) reverse-engineering MCP server and Ghidra provider.

**Status: first-release candidate.** Linux synthetic checks are recorded in
[the release report](docs/RELEASE-CHECKS.md). Windows installation, interactive GUI,
Ghidra fixture analysis and real client/tunnel acceptance remain pending. No
published release or tested remote-client compatibility is claimed.

## Install on Windows 11 x64

Install Python 3.12 and, for REA, a supported Node/npm bootstrap (Node 24.22.1
satisfies the pinned REA engine). Download/clone into a path you own. In PowerShell:

```powershell
New-Item -ItemType Directory "$HOME\DH Workspace" -Force
.\Setup-Windows.ps1 -Workspace "$HOME\DH Workspace" -WithRea
.\scripts\Test-Release.ps1 -WithRea
```

Follow your organization's PowerShell execution policy. The installer creates a
venv, installs declared dependencies, preserves an existing `policy.json`, and
creates a read-only policy for the selected workspace on first install. It never
installs scheduled tasks or enables GUI/shell automatically. Python direct
requirements are pinned; transitive Python dependencies still need a Windows
lock validated on a clean machine. Node/REA use versioned npm integrity locks.

Register `.venv\Scripts\python.exe` with argument `<checkout>\server.py` in your
MCP client. Use absolute paths and the explicit policy/state environment described
in [connection examples](docs/CONNECTIONS.md). Keep REA a separate registration.

## Permissions

Default discovery exposes only `server_status`, `policy_status`, `list_directory`,
`read_text` and `search_text`. A missing policy fails startup. Empty allowed roots
grant no filesystem access. `DH_ALLOWED_ROOTS` overrides roots using Windows `;`
separators; this is a trusted operator setting. GUI defaults off.

To enable writes, explicitly add `write_text`, `replace_text`, `move_path` and/or
`delete_path` to `enabled_tools` in your private policy. `replace_text` also needs
`write_text`. Delete moves data to `.state/trash`; overwrites save `.state/backups`.
There is no automatic restore command: stop clients, inspect recovery files and
restore selected files manually. Backups and audit state are private local data.

Other preserved tool families require explicit names in `enabled_tools`, plus
applicable `programs`, `powershell_scripts`, `scheduled_tasks`, `event_logs` or
`shell_access_enabled` settings. Consult `server.py` for exact signatures. GUI
also requires `DH_ENABLE_GUI=1` and an interactive Windows session. Restart the
server after policy edits. Never use broad drive roots in the default profile.

Approved programs, arbitrary Python, shell, terminal stdin, process termination,
GUI and REA are high-trust capabilities. A token blocklist/cwd is not a sandbox.
REA does not inherit desktop policy. Use a separate least-privilege account and
designated synthetic analysis workspace. Windows reparse/device/ADS/race and
resource-limit acceptance is pending; do not expose this candidate to untrusted
users or publish an unrestricted hosted endpoint.

## REA, tunnel and local agents

- [REA/Ghidra setup](docs/REA-GHIDRA.md)
- [Codex, Claude Desktop, ChatGPT tunnel and local agent connections](docs/CONNECTIONS.md)
- [Repaired tunnel supervision and acceptance](docs/TUNNEL.md)
- [Install, upgrade, rollback and uninstall](docs/INSTALLATION.md)

The optional `swarm/` code is an MCP client/orchestrator, not a remote MCP gateway.
Remote model endpoints receive selected prompts/tool results. They are opt-in;
use local LM Studio by default and keep credentials outside committed config.

## Development

On Linux, install `requirements.txt` in a venv; Windows GUI dependencies are marked
Windows-only. Run `python -m unittest discover -s tests -v` and
`python verify_mcp.py --writes`. After `npm ci` in both runtime directories,
`python verify_mcp.py --rea` tests REA discovery only. Windows CI is supplied but
has not run until this repository is pushed and Actions executes.

Original code is [MIT licensed](LICENSE). Dependencies retain their own licenses;
see [upstream notices](THIRD_PARTY_NOTICES.md). No third-party binaries, real
policy, credentials, logs, live profiles, source exports or private handoffs ship
in the first commit.