winrdp-mcp 0.1.0__tar.gz

winrdp_mcp-0.1.0/.gitattributes

@@ -0,0 +1,8 @@
+# Normalize line endings across platforms
+* text=auto eol=lf
+*.ps1 text eol=crlf
+*.bat text eol=crlf
+*.cmd text eol=crlf
+*.png binary
+*.jpg binary
+*.whl binary

winrdp_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: Lint (ruff)
+        run: ruff check .
+
+      - name: Test (pytest)
+        run: pytest
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Check metadata
+        run: |
+          python -m pip install --upgrade twine
+          twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*

winrdp_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,44 @@
+name: Publish to PyPI
+
+# Publishes on a GitHub Release. Uses PyPI Trusted Publishing (OIDC) — configure the
+# publisher at https://pypi.org/manage/project/winrdp-mcp/settings/publishing/ with:
+#   owner: emog33k   repo: winrdp-mcp   workflow: publish.yml   environment: pypi
+# No API token needs to be stored. (To use a token instead, set PYPI_API_TOKEN secret and
+# add `password: ${{ secrets.PYPI_API_TOKEN }}` to the publish step.)
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build
+        run: |
+          python -m pip install --upgrade build twine
+          python -m build
+          twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # required for Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

winrdp_mcp-0.1.0/.gitignore

@@ -0,0 +1,44 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.whl
+
+# DXT / MCP Bundle build output (vendored deps + packaged extension)
+dxt/server/lib/
+*.dxt
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Test / tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+htmlcov/
+.coverage
+.coverage.*
+
+# winrdp runtime state (never commit — holds the encrypted inventory + vault key)
+# The real data dir is %APPDATA%\winrdp-mcp (or $WINRDP_HOME); guard against a local copy.
+winrdp-mcp-data/
+*.vault.key
+inventory.json
+
+# Local secrets / overrides — keep the checked-in .mcp.json secret-free
+.mcp.local.json
+.env
+*.local
+
+# Editors / OS
+.idea/
+.vscode/
+*.swp
+.DS_Store
+Thumbs.db

winrdp_mcp-0.1.0/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "winrdp": {
+      "command": "python",
+      "args": ["-m", "winrdp_mcp", "serve"]
+    }
+  }
+}

winrdp_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,109 @@
+# Changelog
+
+All notable changes to winrdp-mcp are documented here. Format loosely follows
+[Keep a Changelog](https://keepachangelog.com/); this project uses semantic versioning.
+
+## [0.1.0] — 2026-08-10
+
+Initial release. A zero-config MCP server that provisions and fully administers Windows
+RDP boxes (Win10/11, Server 2016–2025) for Claude & Claude Code.
+
+### Added
+- **144 tools** across 15 groups: hosts/fleet, provisioning & UAC, system, scripting,
+  files, admin, RDP, software, network, deeper Windows management, native GUI automation,
+  wait-for-condition helpers, scheduling/persistence, SSH tunneling, and high-level ops.
+- **MCP prompts** (`prompts.py`) — 5 user-invoked workflows: `provision_and_harden`,
+  `diagnose_box`, `security_audit`, `setup_dev_box`, `open_service_locally`.
+- **MCP resources** (`resources.py`) — `winrdp://hosts` (inventory) and
+  `winrdp://host/{alias}/info` (compact live box summary).
+- **Tool profiles** — `WINRDP_PROFILE=full|admin|rdp|core` exposes a curated tool set.
+- **Ops tools** (`ops.py`) — `health_report`, `apply_baseline`, `whoami_priv`,
+  `failed_logons`, `list_open_ports`.
+- **SSH tunneling** (`tunnel.py`) — `port_forward`/`port_forward_list`/`port_forward_stop`
+  to reach a box's loopback service from the operator machine.
+- **Packaging** — installable from PyPI (`pipx install winrdp-mcp`), with manifests for
+  Smithery (`smithery.yaml`), the MCP registry (`server.json`), and a Claude Desktop
+  extension (`dxt/`), plus CI + trusted-publishing GitHub Actions.
+- **Native GUI automation** (`gui.py`) — drive the interactive RDP desktop with no on-box
+  agent: `send_keys`, `type_text`, `mouse_move`/`mouse_click`/`mouse_drag`, `list_windows`,
+  `focus_window`, UI Automation (`ui_find`/`ui_invoke`/`ui_set_text`), built-in OCR
+  (`ocr_screen`/`find_and_click`), `wait_for_window`, `record_screen` (animated GIF), and
+  `gui_script` (a single-call multi-step sequence with mouse/UIA helpers pre-loaded).
+- **Wait-for-condition helpers** (`waiters.py`) — `wait_for_port`, `wait_for_service`,
+  `wait_for_process`, `wait_for_file`; polled controller-side so any timeout is safe.
+- **File convenience** — `download_file`, `tail_file`, `edit_file` (find/replace),
+  `sync_folder` (zip→upload→expand a local folder), `transfer_between_hosts`.
+- **Scheduling & persistence** (`scheduling.py`) — `schedule_command`, `run_at_startup`,
+  and `persist_as_service` (a resilient auto-restarting service via NSSM) / `unpersist_service`.
+- **Zero-config provisioning ladder** — `provision_host` climbs WinRM → SSH → SMB/WMI
+  cold-start → paste-once bootstrap, enabling WinRM, opening the firewall, and fixing
+  local-admin token filtering on any Windows version.
+- **Real elevation** — full-token execution over WinRM detected via `is_elevated` (direct,
+  fast) with a one-shot SYSTEM Scheduled Task fallback for filtered tokens; `as_user` runs
+  inside the interactive RDP desktop.
+- **On-demand scripting** — `run_python` (auto-installs Python + pip deps), `run_script`
+  (auto interpreter), `run_node`, `pip_install`, `ensure_runtime`.
+- **On-demand tooling** — `stage_tool` (Sysinternals presets / URL / local file),
+  `stage_script`, staged-tool cache management.
+- **First-class RDP** — enable/disable, NLA, custom port, session list/disconnect/logoff,
+  `tscon` handoff, multi-session, `.rdp` generation, `mstsc` launch, RDP Wrapper, live
+  desktop screenshot.
+- **Encrypted multi-host inventory** (Fernet) with tags, active-host targeting, parallel
+  `run_on_hosts` fan-out, and `reboot_and_wait`.
+- **Safety annotations** (`readOnlyHint`/`destructiveHint`) on every tool and a tool
+  allowlist (`WINRDP_ENABLED_TOOLS` / `WINRDP_DISABLED_TOOLS`).
+- Hybrid deployment: `serve` (controller over stdio) and `agent` (on the box); a CLI with
+  `bootstrap`, `add-host`, `list-hosts`, `provision`.
+- Encrypted-at-rest credentials, stderr logging with secret redaction, per-host transport
+  security knobs (`winrm_cert_validation`, `ssh_host_key_policy`).
+
+### Hardened (from an adversarial code review + a live end-to-end run against a real VDS)
+- Removed a thread-based WinRM timeout watchdog that corrupted the non-thread-safe pywinrm
+  session and cascaded HTTP 400s across all subsequent calls.
+- Added transport **self-heal**: reconnect + retry once on a dropped/wedged WinRM
+  connection (`RemoteDisconnected` / HTTP 400).
+- Long installs now run **detached** (`run_long` → scheduled task + poll) so a mid-install
+  disconnect on a small/busy box doesn't fail them.
+- `list_tasks` made lightweight (the per-task `Get-ScheduledTaskInfo` N+1 could hang and
+  drop the connection); details available via `detailed=True`.
+- HTTP-first WinRM ordering (NTLM-encrypted, faster; HTTPS only when `use_ssl`).
+- Argument validation/quoting across all tools; `rdp_connection_file` no longer returns the
+  plaintext password; robust `qwinsta` session parsing; BOM-free file appends.
+- Large-script / large-file handling: a `run_ps` script over ~6 KB is staged to a temp
+  `.ps1` and run via `-File` (avoids the WSMan/cmd command-line length limit that pywinrm's
+  `-EncodedCommand` packing hits, on all transports); the upload chunk was cut to a size
+  that stays under that limit after re-encoding.
+- Fast file channel: WinRM uploads/downloads of any size now transparently use a cached
+  **SMB** (`ADMIN$`, no install) channel when 445 is reachable, else **SFTP** over SSH,
+  falling back to chunked base64 only when neither is available — instant transfers instead
+  of many round-trips. `provision_host(fast_transfer=True)` (default) ensures the channel:
+  it uses SMB when 445 is open, otherwise installs OpenSSH so SFTP is available.
+
+### From production-use feedback
+- `run_powershell`/`run_ps` staging threshold lowered to 2.4 KB so scripts stay under the
+  worst-case command-line limit some boxes enforce (staging is cheap over the fast channel).
+- `file_write(binary=True)` writes decoded base64 bytes for arbitrary binary files.
+- `start_process(wait=False)` redirects the background process's stdout/stderr to log files
+  (returned as `stdout_log`/`stderr_log`) so silent background failures are diagnosable.
+- `as_user`/GUI ops now detect a Disconnected session and fail with an actionable message
+  (reconnect RDP or `rdp_connect_to_console`) instead of running on a non-composed desktop.
+- New `port_forward` / `port_forward_list` / `port_forward_stop`: SSH local tunnels to reach
+  a service bound to a box's 127.0.0.1 (which WinRM-launched processes cannot).
+- `run_powershell(detach=True)` / `start_process(detach=True)`: launch a background process
+  in a Scheduled Task so it runs OUTSIDE the WinRM Job Object and survives the session close
+  (a normal launch dies with the shell — that's why a background server only lived ~1 min).
+- `run_powershell(loopback=True)`: route through a Scheduled Task so the script can reach
+  127.0.0.1 — the WinRM network-logon token blocks outbound loopback, the task's logon does
+  not. (`file_write` already streams over SFTP/SMB, bypassing the WinRM command channel.)
+- Fixed three latent PowerShell brace-balance / output bugs surfaced by a brace-balance
+  audit and live runs: `ensure_remote_dirs` (broke all tool-staging), `tail_file` (returned
+  megabytes of provider metadata), and `find_and_click`.
+
+- Readable output: PowerShell serializes its progress/information streams into stderr as
+  a CLIXML blob. Results are now tidied on every call — real Error/Warning text stays in
+  stderr, `Write-Host`/Information output is recovered into stdout (no duplication, no
+  loss), and only the progress-bar noise is dropped.
+
+### Attribution
+Builds on the MIT-licensed [winremote-mcp](https://github.com/dddabtc/winremote-mcp) and
+[windows-admin-mcp](https://github.com/Cosmicjedi/windows-admin-mcp) — see `NOTICE`.

winrdp_mcp-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,68 @@
+# Contributing to winrdp-mcp
+
+Thanks for helping improve winrdp-mcp. This guide covers the dev setup, the quality bar,
+and how to add a tool.
+
+## Dev setup
+
+```bash
+git clone <your-fork>
+cd Windows-RDP-MCP
+python -m venv .venv
+# Windows:  .venv\Scripts\activate      | POSIX: source .venv/bin/activate
+pip install -e ".[dev,bootstrap]"
+```
+
+The controller runs on any OS (Windows/macOS/Linux); the managed targets are Windows.
+
+## Quality bar
+
+Before opening a PR, all of these must pass:
+
+```bash
+python -m compileall -q winrdp_mcp     # no syntax errors
+ruff check winrdp_mcp tests            # lint (F, E, I, W)
+pytest -q                              # unit tests (30+; Windows-only tests skip elsewhere)
+```
+
+- **Correctness first**, then clarity, then speed. Handle the unhappy paths.
+- **Never** wrap a `pywinrm` call in a thread watchdog — the `Session` is not thread-safe
+  and abandoning a call mid-flight corrupts the connection (see `transports.py`). The
+  per-call bound is `read_timeout_sec`; a dropped/wedged connection is healed by the
+  transport's reconnect-and-retry.
+- **Quote or validate every model-supplied argument** that reaches a command line:
+  `ps.ps_string()` for PowerShell literals, `tools/_validate.py` (enum/charset) for values
+  spliced raw (paths, names, package ids, enums). Several tools run elevated.
+- **Long operations** (minutes-scale installs) must go through `context.run_long()` so a
+  mid-op WinRM disconnect doesn't fail them.
+- **Never** return a secret in a tool result or log it (logs are stderr-only and redacted).
+
+## Adding a tool
+
+1. Add the function inside the relevant module's `register(mcp, ctx)` in `winrdp_mcp/tools/`.
+2. Decorate with `@mcp.tool`; give it a clear docstring (that IS the model-facing API) and
+   an optional `host: Optional[str] = None` first among the box selectors.
+3. Build the PowerShell body with `ps.ps_string()` for any interpolated value; return
+   structured data via `ctx.exec_json(...)` (assign `$result`) or `ctx.exec_ps(...)`.
+4. Classify it in `winrdp_mcp/server.py`: add its name to `READONLY` or `DESTRUCTIVE` so it
+   gets the right safety annotation.
+5. If it's a new module, register it in `winrdp_mcp/tools/__init__.py`.
+6. Add a unit test (pure logic) and, where practical, a Windows-guarded local test.
+7. Document it in `docs/TOOLS.md`.
+
+## Testing against a real box
+
+Integration tests are opt-in. Point them at a box you own:
+
+```bash
+export WINRDP_TEST_HOST=... WINRDP_TEST_USER=... WINRDP_TEST_PASS=...
+```
+
+Never commit credentials. Use a throwaway VM; a >= 4 GB / 2 vCPU box avoids the
+resource-thrash slowness small boxes exhibit under sustained WinRM load.
+
+## Commit / PR
+
+- Small, focused commits with clear messages.
+- Describe the change, the reasoning, and how you verified it.
+- MIT-licensed contributions only; keep the `NOTICE` attributions intact.

winrdp_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 winrdp-mcp contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

winrdp_mcp-0.1.0/NOTICE

@@ -0,0 +1,22 @@
+winrdp-mcp
+==========
+
+Copyright (c) 2026 winrdp-mcp contributors. MIT License (see LICENSE).
+
+This project's feature set, risk-tier model, and optional interactive-desktop UI agent
+build on prior MIT-licensed work, gratefully credited:
+
+* winremote-mcp — https://github.com/dddabtc/winremote-mcp
+    Copyright (c) 2025 winremote contributors. MIT License.
+    Basis for: the on-box tool surface (desktop/registry/services/process/file/network
+    tools), the tier1/tier2/tier3 risk model, and the optional `deploy_ui_agent` path,
+    which installs and drives winremote-mcp for click/type/OCR desktop control.
+
+* windows-admin-mcp — https://github.com/Cosmicjedi/windows-admin-mcp
+    Copyright (c) 2025 Cosmicjedi. MIT License.
+    Basis for: the WinRM-primary / SSH-fallback remote administration approach and the
+    diagnose/execute/troubleshoot tool shape.
+
+winrdp-mcp's own additions: zero-config provisioning ladder (WinRM -> SSH -> SMB/WMI
+cold-start -> paste-once bootstrap), real UAC/elevation via one-shot Scheduled Tasks,
+on-demand tool staging, encrypted multi-host inventory, and first-class RDP control.