dsh-windows-mcp 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -4,7 +4,49 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.1.0] - 2026-10-10
+## [0.2.0] - 2026-10-24
+
+### Added
+
+- **Windows-MCP version management** (`lib/updater.js`, `lib/installs.js`): the
+  plugin checks the mirrors for the newest stable `windows-mcp`, installs a
+  version **side by side** under `$DSH_HOME/dsh-windows-mcp/toolchain/<version>`
+  (each version its own `UV_TOOL_DIR`, so nothing is overwritten), rewrites the
+  bridge row to the freshly installed executable, and keeps the replaced version
+  so **Roll back** switches back to it without downloading anything. The check
+  result, active/previous version and the install history are persisted in
+  `$DSH_HOME/dsh-windows-mcp.versions.json`. Checks run on boot and are cached
+  for six hours.
+- **Fast-mirror selection for the Python dependency** (`lib/mirrors.js`,
+  `lib/pypi.js`): PyPI plus the USTC, Aliyun, Tencent Cloud, Huawei Cloud,
+  Nanjing University and TUNA mirrors are probed with a 96 KiB ranged read and
+  ranked by measured throughput; the install uses the fastest working mirror and
+  falls back to the next candidate on failure.
+- On the plugin page: running version, newest version, kept versions, the
+  measured mirror speed, and **Check for updates** / **Update to vX** / **Roll
+  back to vPrev** actions, with the streamed `uv` log.
+- `tools/update-e2e.mjs`, a maintainer harness that runs the real check, install,
+  activation and rollback against this machine's profile (never published).
+
+### Changed
+
+- `createPrepare` / the prepare route now install into the managed tool root
+  through `UV_TOOL_DIR`, support a chosen `--default-index` mirror, and resolve
+  the executable from the version that was installed.
+- `uv` installs set `UV_CONCURRENT_DOWNLOADS=4`, `UV_HTTP_RETRIES=3` and
+  `UV_HTTP_TIMEOUT=600`: at uv's default of eight parallel downloads the mirrors
+  answer HTTP 429 and the install fails.
+- The bridge-row writer, the doctor report and the `/state` payload all report
+  which side is live (`managed` vs the global `uv-tool` install).
+
+### Fixed
+
+- The PyPI index parser dropped files whose link carried a `#sha256=…` fragment
+  (every wheel on a real mirror), so the newest version looked missing.
+- The version pin regex stopped at YAML punctuation but not at the backtick used
+  in the written block's prose comment.
+
+## [0.1.0] - 2026-10-11
 
 ### Added
 

package/LICENSE

@@ -19,9 +19,3 @@ 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.
-
----
-
-This plugin does not bundle Windows-MCP: at runtime it launches the upstream
-package `windows-mcp` (CursorTouch/Windows-MCP, MIT) and mounts the MCP client
-bridge that ships with DeepSeek Harness. Both remain under their own licenses.

package/README.md

@@ -1,5 +1,10 @@
 # dsh-windows-mcp
 
+**English** · [中文](https://github.com/helloHub1212/dsh-windows-mcp/blob/main/README.zh.md)
+
+[![npm version](https://img.shields.io/npm/v/dsh-windows-mcp.svg)](https://www.npmjs.com/package/dsh-windows-mcp)
+[![CI](https://github.com/helloHub1212/dsh-windows-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/helloHub1212/dsh-windows-mcp/actions/workflows/ci.yml)
+
 **Windows desktop automation for [DeepSeek Harness](https://github.com/sandbaseai/deepseek-harness-handbook)** — lets the DSH agent see your screen and drive your PC.
 
 This plugin connects [CursorTouch/Windows-MCP](https://github.com/CursorTouch/Windows-MCP) to DSH by mounting one loader row against the **MCP client bridge that already ships inside DeepSeek Harness**. There is no reimplemented protocol client and no second copy of the MCP SDK: the plugin is a *carrier bundle*, and everything you can do comes from the official bridge.
@@ -98,6 +103,21 @@ The block it writes is exactly the row documented under [Pin a local interpreter
 
 The page also shows the **Patch target**: the `cordis.patch.yml` a manual write would touch, which is the profile this host booted — including a `dsh --profile web` host. If this package sits in more than one profile and the host does not report which one it started, the plugin writes nothing and says so instead of guessing: set `DSH_WINDOWS_MCP_PROFILE=<profile name>` (or an absolute profile directory) for the process that runs DSH and retry.
 
+### Update Windows-MCP, and roll back
+
+The same page manages the upstream version, so an upgrade never means reinstalling the dependency by hand:
+
+- **It checks by itself.** On boot, and whenever the page asks, the plugin probes the PyPI mirrors, takes the fastest one that answers and reads its `windows-mcp` index. The result is cached for six hours in `$DSH_HOME/dsh-windows-mcp.versions.json`, so restarts do not hammer the network.
+- **Versions live side by side.** Every version is installed into its own tool root, `$DSH_HOME/dsh-windows-mcp/toolchain/<version>/windows-mcp`, through `UV_TOOL_DIR`. Activating a version only rewrites the bridge row (backed up, as above): no reinstall, and the previous version stays on disk.
+- **Update in one click.** **Update to vX** downloads that version from the fastest mirror that works, verifies the executable and its `dist-info`, then activates it — the panel names the running version and the mirror it came from.
+- **Roll back the same way.** **Roll back to vPrev** points the bridge back at the version the active one replaced; nothing is downloaded.
+
+Only the managed installs are touched: until you install one, the bridge keeps using the global `uv tool` installation, and the panel says which side is live (`uv-tool` vs `managed`).
+
+### Fast mirrors for the Python dependency
+
+The check measures all seven candidates — PyPI plus the USTC, Aliyun, Tencent Cloud, Huawei Cloud, Nanjing University and TUNA mirrors — with a 96 KiB ranged read, and ranks them by throughput. An install uses the fastest mirror that works and falls back to the next one when a mirror fails, with `UV_CONCURRENT_DOWNLOADS=4`, `UV_HTTP_RETRIES=3` and `UV_HTTP_TIMEOUT=600`, because mirrors rate-limit uv's default of eight parallel downloads (HTTP 429). A mirror that has blocked this network is ranked out instead of failing the install; the measured speed is shown per mirror in the panel.
+
 ## Verify
 
 ```text
@@ -293,12 +313,28 @@ Layout:
 
 ```text
 cordis.patch.yml      the integration: two insert rows
-lib/index.js          host half: windows_mcp_doctor + startup audit (no dependencies)
-test/plugin.test.mjs  patch composition + hostile-context tests
+lib/index.js          host half: routes + windows_mcp_doctor + startup audit (no dependencies)
+lib/dependency.js     dependency state, uv invocation, profile bridge-row writer
+lib/pypi.js           PyPI index parsing and version maths (pure functions)
+lib/mirrors.js        mirror candidates, ranged speed probe, ranking
+lib/installs.js       per-version tool roots and the versions state file
+lib/updater.js        version manager: check / install / activate / roll back
+lib/client.js         web half: composer switch + plugin panel
+test/plugin.test.mjs  patch composition + hostile-context + panel tests
+test/update.test.mjs  version maths, mirror ranking, isolation and rollback state machine
 scripts/dump-config.mjs  dev helper for composing against a scratch profile
 tools/                zero-dependency debug probes (not published to npm)
 ```
 
+To exercise the update path for real — real mirrors, real `uv`, real profile
+write — use the e2e harness:
+
+```powershell
+node tools/update-e2e.mjs --check          # probe the mirrors, read the newest stable version
+node tools/update-e2e.mjs --install 0.8.8  # download, activate, rewrite the bridge row
+node tools/update-e2e.mjs --rollback
+```
+
 Contributions are welcome; keep `lib/index.js` free of runtime dependencies and
 keep `apply()` throw-proof.
 

package/README.zh.md

@@ -1,5 +1,10 @@
 # dsh-windows-mcp
 
+[English](https://github.com/helloHub1212/dsh-windows-mcp/blob/main/README.md) · **中文**
+
+[![npm version](https://img.shields.io/npm/v/dsh-windows-mcp.svg)](https://www.npmjs.com/package/dsh-windows-mcp)
+[![CI](https://github.com/helloHub1212/dsh-windows-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/helloHub1212/dsh-windows-mcp/actions/workflows/ci.yml)
+
 **给 [DeepSeek Harness](https://github.com/sandbaseai/deepseek-harness-handbook) 接上 Windows 桌面自动化** —— 让 DSH 的 agent 能"看见"你的屏幕并操作你的电脑。
 
 本插件把 [CursorTouch/Windows-MCP](https://github.com/CursorTouch/Windows-MCP) 接到 DSH 上，做法是**挂载 DSH 本体自带的那座 MCP 客户端桥**：不重新实现协议客户端，也不重复打包 MCP SDK。插件本身是一个 *carrier bundle*（只有补丁、没有自己的服务），agent 能用的一切能力都来自官方那座桥。
@@ -94,6 +99,21 @@ Windows-MCP 本身是个 Python 程序，所以 **设置 → 插件 → dsh-wind
 
 面板上还会显示 **写入目标**：手动写入会落到哪个 `cordis.patch.yml`，也就是这个宿主启动的那个 profile（`dsh --profile web` 启动的 web 宿主同样适用）。如果本插件装在多个 profile 里、而宿主没有报告自己启动的是哪一个，插件**不会猜**：它什么都不写并直接说明——给运行 DSH 的进程设 `DSH_WINDOWS_MCP_PROFILE=<profile 名>`（或 profile 的绝对路径）再重试。
 
+### 更新 Windows-MCP，以及回退
+
+同一个面板也管上游版本，所以升级不用再手动重装依赖：
+
+- **自己检查。** 宿主启动时（以及页面要求时）插件会探测各 PyPI 镜像，取响应最快的那个读它的 `windows-mcp` 索引；结果在 `$DSH_HOME/dsh-windows-mcp.versions.json` 里缓存 6 小时，重启不会反复打网络。
+- **版本各装各的。** 每个版本通过 `UV_TOOL_DIR` 装进自己的目录：`$DSH_HOME/dsh-windows-mcp/toolchain/<版本>/windows-mcp`。激活一个版本只是重写桥那一行（同样先备份），**不需要重装**，上一版原样留在磁盘上。
+- **一键更新。** **更新到 vX** 会从能用的最快镜像下载该版本（失败自动换下一个镜像），校验可执行文件和 `dist-info` 之后再激活；面板会显示当前运行版本和它来自哪个镜像。
+- **回退同样一键。** **回退到 vPrev** 把桥指回“当前版本替换掉的那个版本”，不下载任何东西。
+
+只动插件自己管理的安装：在你安装第一个托管版本之前，桥仍然用全局 `uv tool` 装的那份；面板会标明当前生效的是 `uv-tool` 还是 `managed`。
+
+### Python 依赖的镜像加速
+
+检查阶段会用 96 KiB 的 range 读取量一遍七个候选——PyPI 官方，加上中科大、阿里云、腾讯云、华为云、南京大学、清华 TUNA——按实测吞吐量排序。安装时用最快且能用的镜像，失败就回退到下一个；同时固定 `UV_CONCURRENT_DOWNLOADS=4`、`UV_HTTP_RETRIES=3`、`UV_HTTP_TIMEOUT=600`，因为镜像会限流 uv 默认的 8 并发（HTTP 429）。对当前网络直接封锁的镜像（本机 TUNA 现在返回 403）会被排到后面而不是让安装失败；每个镜像的实测速度都显示在面板上。
+
 ## 验证
 
 ```text
@@ -243,12 +263,27 @@ npm run dump
 
 ```text
 cordis.patch.yml      集成本体：两行 insert
-lib/index.js          宿主半边：windows_mcp_doctor + 启动审计（零依赖）
-test/plugin.test.mjs  补丁合成测试 + 恶意 ctx 测试
+lib/index.js          宿主半边：路由 + windows_mcp_doctor + 启动审计（零依赖）
+lib/dependency.js     依赖状态、uv 调用封装、profile 桥行写入
+lib/pypi.js           PyPI 索引解析与版本比较（纯函数）
+lib/mirrors.js        镜像候选、限速探测与排序
+lib/installs.js       按版本隔离的工具目录 + 版本状态文件
+lib/updater.js        版本管理：检查 / 安装 / 激活 / 回退
+lib/client.js         网页半边：输入框开关 + 插件面板
+test/plugin.test.mjs  补丁合成测试 + 恶意 ctx 测试 + 面板测试
+test/update.test.mjs  版本解析、镜像排序、版本隔离与回退状态机测试
 scripts/dump-config.mjs  面向影子 profile 的合成调试脚本
 tools/                零依赖调试探针（不发布到 npm）
 ```
 
+要对着真实网络和本机 profile 验证升级链路，用 `tools/update-e2e.mjs`：
+
+```powershell
+node tools/update-e2e.mjs --check          # 探测镜像并读出最新稳定版
+node tools/update-e2e.mjs --install 0.8.8  # 真下载、真激活、真改桥行
+node tools/update-e2e.mjs --rollback
+```
+
 欢迎贡献；请保持 `lib/index.js` 无运行时依赖，并保持 `apply()` 永不抛错。
 
 ## 致谢与许可

package/lib/client.js

@@ -31,6 +31,7 @@ window.__ModuleLoader__.load({
     var PREPARE_PATH = "/dsh-windows-mcp/prepare";
     var PREPARE_CANCEL_PATH = "/dsh-windows-mcp/prepare/cancel";
     var BRIDGE_PATH = "/dsh-windows-mcp/bridge";
+    var UPDATE_PATH = "/dsh-windows-mcp/update";
     var STYLE_ID = PACKAGE_ID + "-computer-use-styles";
     var LABEL = "Computer Use";
     /** Only `slots` is injected: it is certainly provided, and a declaration for
@@ -300,6 +301,22 @@ window.__ModuleLoader__.load({
         ready: "依赖已就绪，桌面工具可用（记得把 Computer Use 开关打开）。",
         restart: "已把桥指向新安装的版本，重启 DSH 后生效。",
         hostDown: "连不上宿主",
+        version: "运行版本",
+        latest: "最新版本",
+        previous: "可回退",
+        kept: "已保留版本",
+        mirror: "镜像",
+        updateAvailable: "有新版本",
+        upToDate: "已是最新",
+        notChecked: "还没检查",
+        check: "检查更新",
+        checking: "正在测速…",
+        updateTo: "更新到",
+        rollback: "回退到",
+        installVersion: "安装版本",
+        versionInstalled: "版本已切换，重启 DSH 生效。",
+        noPrevious: "没有可回退的版本",
+        updateHint: "更新只下载新版本、旧版本原样保留；出问题一键回退，不需要重装依赖。",
       },
       en: {
         title: "Windows desktop automation (Windows-MCP)",
@@ -327,6 +344,22 @@ window.__ModuleLoader__.load({
         ready: "Dependency ready — the desktop tools are available (turn the Computer Use switch on).",
         restart: "The bridge now points at the freshly installed build; restart DSH to apply it.",
         hostDown: "Host unreachable",
+        version: "Running version",
+        latest: "Latest version",
+        previous: "Rollback to",
+        kept: "Kept versions",
+        mirror: "Mirror",
+        updateAvailable: "update available",
+        upToDate: "up to date",
+        notChecked: "not checked yet",
+        check: "Check for updates",
+        checking: "Probing mirrors…",
+        updateTo: "Update to",
+        rollback: "Roll back to",
+        installVersion: "Install version",
+        versionInstalled: "Version switched — restart DSH to apply it.",
+        noPrevious: "no previous version to roll back to",
+        updateHint: "An update only downloads the new build; the old one is kept as-is. Roll back with one click — no reinstall.",
       },
     };
 
@@ -381,6 +414,19 @@ window.__ModuleLoader__.load({
       });
     }
 
+    /** POST JSON — used by the version manager (check / install / activate / rollback). */
+    function postJson(path, payload) {
+      return fetch(apiUrl(path), {
+        method: "POST",
+        headers: { accept: "application/json", "content-type": "application/json" },
+        body: JSON.stringify(payload || {}),
+      }).then(function (response) {
+        return response.json().then(function (body) {
+          return { ok: response.ok, status: response.status, body: body };
+        });
+      });
+    }
+
     function statusDot(tone) {
       return React.createElement("span", { className: "dwmc-dot", "data-tone": tone });
     }
@@ -419,6 +465,19 @@ window.__ModuleLoader__.load({
       var installed = dependency.installed === true;
       var bridged = typeof state.bridged === "number" ? state.bridged : null;
       var log = Array.isArray(prepare.log) ? prepare.log : [];
+      var update = state.update || {};
+      var versions = update.versions || {};
+      var check = update.check || {};
+      var install = update.install || {};
+      var updateAvailable = versions.updateAvailable === true && typeof check.latest === "string";
+      var mirrors = Array.isArray(check.mirrors) ? check.mirrors : [];
+      var bestMirror = null;
+      for (var mirrorIndex = 0; mirrorIndex < mirrors.length; mirrorIndex += 1) {
+        if (mirrors[mirrorIndex] && mirrors[mirrorIndex].id === check.best) {
+          bestMirror = mirrors[mirrorIndex];
+          break;
+        }
+      }
       var profile = dependency.profile && typeof dependency.profile === "object" ? dependency.profile : null;
       var profileTarget =
         profile === null
@@ -441,10 +500,28 @@ window.__ModuleLoader__.load({
           });
       };
 
+      var actUpdate = function (payload) {
+        setBusy(true);
+        postJson(UPDATE_PATH, payload)
+          .catch(function () {
+            /* the next poll reports the truth */
+          })
+          .then(function () {
+            setBusy(false);
+            reload();
+          });
+      };
+
+      var speedText = function (bytesPerSecond) {
+        var value = Number(bytesPerSecond);
+        if (!isFinite(value) || value <= 0) return "—";
+        return value >= 1048576 ? (value / 1048576).toFixed(1) + " MB/s" : Math.max(1, Math.round(value / 1024)) + " KB/s";
+      };
+
       var head = React.createElement(
         "div",
         { className: "dwmc-panel__head", key: "head" },
-        statusDot(running ? "warn" : installed ? "on" : "warn"),
+        statusDot(running ? "warn" : updateAvailable ? "warn" : installed ? "on" : "warn"),
         React.createElement("span", null, t.title),
       );
 
@@ -452,11 +529,23 @@ window.__ModuleLoader__.load({
       if (!compact) {
         var rows = [
           [t.dependency, installed ? t.installed + (dependency.version ? " " + dependency.version : "") : dependency.uv === null ? t.uvMissing : t.missing],
-          [t.tool, dependency.executable || "—"],
-          [t.bridge, bridged === null ? "—" : bridged + " " + t.bridgedTools],
-          [t.profile, profileTarget],
-          [t.toggle, state.enabled === true ? t.on : t.off],
+          [t.version, versions.active ? "v" + versions.active : dependency.version ? "v" + dependency.version : "—"],
+          [
+            t.latest,
+            typeof check.latest === "string"
+              ? "v" + check.latest + " · " + (updateAvailable ? t.updateAvailable : t.upToDate)
+              : t.notChecked,
+          ],
         ];
+        if (typeof versions.previous === "string") rows.push([t.previous, "v" + versions.previous]);
+        if (Array.isArray(versions.available) && versions.available.length > 0) {
+          rows.push([t.kept, versions.available.map(function (version) { return "v" + version; }).join(", ")]);
+        }
+        if (bestMirror !== null) rows.push([t.mirror, bestMirror.label + " · " + speedText(bestMirror.speedBps)]);
+        rows.push([t.tool, dependency.executable || "—"]);
+        rows.push([t.bridge, bridged === null ? "—" : bridged + " " + t.bridgedTools]);
+        rows.push([t.profile, profileTarget]);
+        rows.push([t.toggle, state.enabled === true ? t.on : t.off]);
         children.push(
           React.createElement(
             "dl",
@@ -473,7 +562,13 @@ window.__ModuleLoader__.load({
 
       if (running) {
         children.push(React.createElement("div", { className: "dwmc-progress", key: "progress" }, React.createElement("i")));
-        children.push(React.createElement("p", { className: "dwmc-note", key: "running" }, t.running));
+        children.push(
+          React.createElement(
+            "p",
+            { className: "dwmc-note", key: "running" },
+            (install.version ? t.installVersion + " v" + install.version + "… " : "") + t.running,
+          ),
+        );
         var tail = log.slice(-3).join("\n");
         if (tail) children.push(React.createElement("pre", { className: "dwmc-log", key: "log" }, tail));
       } else if (prepare.phase === "failed") {
@@ -492,17 +587,46 @@ window.__ModuleLoader__.load({
       } else if (!installed && !running) {
         children.push(React.createElement("p", { className: "dwmc-note", key: "estimate" }, t.estimate));
       }
+      if (!compact && (running || updateAvailable)) {
+        children.push(React.createElement("p", { className: "dwmc-note", key: "updateHint" }, t.updateHint));
+      }
       if (view.phase === "error") {
         children.push(React.createElement("p", { className: "dwmc-error", key: "offline" }, t.hostDown + ": " + view.error));
       }
 
       var actions = [];
       if (running) {
-        actions.push(actionButton(t.cancel, function () { act(PREPARE_CANCEL_PATH); }, busy, true));
-      } else if (!installed) {
-        actions.push(actionButton(t.install, function () { act(PREPARE_PATH); }, busy));
+        actions.push(actionButton(t.cancel, function () { actUpdate({ action: "cancel" }); }, busy, true));
       } else {
-        actions.push(actionButton(t.reinstall, function () { act(PREPARE_PATH); }, busy, true));
+        actions.push(
+          actionButton(
+            check.phase === "checking" ? t.checking : t.check,
+            function () { actUpdate({ action: "check" }); },
+            busy,
+            true,
+          ),
+        );
+        if (updateAvailable) {
+          actions.push(
+            actionButton(
+              t.updateTo + " v" + check.latest,
+              function () { actUpdate({ action: "install", version: check.latest }); },
+              busy,
+            ),
+          );
+        }
+        if (typeof versions.previous === "string") {
+          actions.push(
+            actionButton(
+              t.rollback + " v" + versions.previous,
+              function () { actUpdate({ action: "rollback" }); },
+              busy,
+              true,
+            ),
+          );
+        }
+        if (!installed) actions.push(actionButton(t.install, function () { act(PREPARE_PATH); }, busy));
+        else actions.push(actionButton(t.reinstall, function () { act(PREPARE_PATH); }, busy, true));
         if (prepare.bridge && prepare.bridge.ok !== true) {
           actions.push(actionButton(t.pointBridge, function () { act(BRIDGE_PATH); }, busy, true));
         }
@@ -601,7 +725,7 @@ window.__ModuleLoader__.load({
 
     exports.apply = apply;
     exports.inject = inject;
-    exports.__internals = { CSS: CSS, apiUrl: apiUrl, tooltipFor: tooltipFor, LABEL: LABEL, STATE_PATH: STATE_PATH };
+    exports.__internals = { CSS: CSS, apiUrl: apiUrl, tooltipFor: tooltipFor, LABEL: LABEL, STATE_PATH: STATE_PATH, UPDATE_PATH: UPDATE_PATH };
     return module.exports;
   },
 });

package/lib/dependency.js

@@ -80,10 +80,15 @@ export function windowsMcpExecutable() {
   return null;
 }
 
-/** Version of the installed tool, read from its dist-info directory. */
-export function windowsMcpVersion(executable = windowsMcpExecutable()) {
-  if (executable === null) return null;
-  const directory = windowsMcpToolDirectory();
+/**
+ * Version of a `uv tool` installation, read from the dist-info directory inside
+ * the tool's environment. Works for the global tool root and for the managed
+ * per-version directories this plugin keeps (see `installs.js`).
+ * @param toolDirectory - the directory that contains `Scripts/` and `Lib/`,
+ *   i.e. `…/tools/windows-mcp` or `…/tools/<version>/windows-mcp`.
+ */
+export function toolVersionIn(toolDirectory) {
+  if (typeof toolDirectory !== "string" || toolDirectory === "") return null;
   const packages = [];
   const collect = (sitePackages) => {
     try {
@@ -94,10 +99,10 @@ export function windowsMcpVersion(executable = windowsMcpExecutable()) {
       /* layout absent */
     }
   };
-  collect(join(directory, "Lib", "site-packages"));
+  collect(join(toolDirectory, "Lib", "site-packages"));
   try {
-    for (const entry of readdirSync(join(directory, "lib"), { withFileTypes: true })) {
-      if (entry.isDirectory() && /^python\d/u.test(entry.name)) collect(join(directory, "lib", entry.name, "site-packages"));
+    for (const entry of readdirSync(join(toolDirectory, "lib"), { withFileTypes: true })) {
+      if (entry.isDirectory() && /^python\d/u.test(entry.name)) collect(join(toolDirectory, "lib", entry.name, "site-packages"));
     }
   } catch {
     /* POSIX layout absent */
@@ -109,9 +114,17 @@ export function windowsMcpVersion(executable = windowsMcpExecutable()) {
   return null;
 }
 
+/** Version of the globally installed tool, read from its dist-info directory. */
+export function windowsMcpVersion(executable = windowsMcpExecutable()) {
+  if (executable === null) return null;
+  return toolVersionIn(windowsMcpToolDirectory());
+}
+
 /** The pinned upstream version our patch mounts, e.g. `0.8.8`, or null. */
 export function windowsMcpVersionPin(patchText) {
-  const match = /windows-mcp@([0-9][^\s,'"\]]*)/u.exec(String(patchText ?? ""));
+  // Stop at anything that ends a version in YAML or prose: whitespace, quotes,
+  // commas, closing brackets, and the backtick/paren used in comments.
+  const match = /windows-mcp@([0-9][^\s,'"\]`);]*)/u.exec(String(patchText ?? ""));
   return match === null ? null : match[1];
 }
 
@@ -143,11 +156,67 @@ export function dependencySnapshot(resolver, pinned, env = process.env) {
  * install
  * ------------------------------------------------------------------ */
 
+/**
+ * Environment for `uv tool install`.
+ *
+ * `UV_CONCURRENT_DOWNLOADS` is deliberately below uv's default of 8: the
+ * mainland mirrors rate-limit aggressive parallelism (measured: USTC answered
+ * HTTP 429 while unzipping a dependency when uv fetched 8 files at once), and a
+ * slow-but-successful install beats a fast-but-failing one.
+ *
+ * @param toolDirectory - when set, the install is redirected into that tool
+ *   root (`UV_TOOL_DIR`) instead of the global one, which is how this plugin
+ *   keeps several upstream versions side by side.
+ */
+export function uvInstallEnvironment(toolDirectory = null) {
+  const environment = {
+    ...process.env,
+    UV_HTTP_TIMEOUT: "600",
+    UV_CONCURRENT_DOWNLOADS: "4",
+    UV_HTTP_RETRIES: "3",
+  };
+  if (typeof toolDirectory === "string" && toolDirectory !== "") environment.UV_TOOL_DIR = toolDirectory;
+  return environment;
+}
+
+/**
+ * Start one `uv tool install` and stream its output to `onLine`.
+ * @returns `{ child, args }` — the caller owns the child's lifecycle.
+ */
+export function spawnUvInstall(options = {}) {
+  const uv = options.uv;
+  const spec = options.spec;
+  const indexUrl = typeof options.indexUrl === "string" && options.indexUrl !== "" ? options.indexUrl : null;
+  const toolDirectory = typeof options.toolDirectory === "string" && options.toolDirectory !== "" ? options.toolDirectory : null;
+  const onLine = typeof options.onLine === "function" ? options.onLine : () => {};
+  const args = ["tool", "install", "--force"];
+  if (indexUrl !== null) args.push("--default-index", indexUrl);
+  args.push(spec);
+  const child = spawn(uv, args, {
+    cwd: typeof options.cwd === "string" ? options.cwd : homedir(),
+    env: { ...uvInstallEnvironment(toolDirectory), ...(options.env ?? {}) },
+    windowsHide: true,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  try {
+    child.stdout?.on("data", onLine);
+    child.stderr?.on("data", onLine);
+  } catch {
+    /* a child without pipes still closes */
+  }
+  return { child, args };
+}
+
 /**
  * One `uv tool install` at a time, with a bounded log the page can follow.
  * @param options.warn - warning sink.
  * @param options.resolver - PATH lookup used to find `uv`.
  * @param options.pinned - upstream version pin.
+ * @param options.indexUrl - PyPI index to install from (a mirror), or null.
+ * @param options.toolDirectory - `UV_TOOL_DIR` for an isolated install, or null
+ *   for the global tool root.
+ * @param options.resolveExecutable - where to look for the installed executable
+ *   afterwards; defaults to the global `uv tool` installation.
  * @param options.afterInstall - called with the installed executable, returns
  *   the bridge-write outcome that `snapshot()` then reports.
  */
@@ -202,22 +271,19 @@ export function createPrepare(options = {}) {
         return { started: false, reason: state.error, state: this.snapshot() };
       }
       const spec = options.pinned === null || options.pinned === undefined ? WINDOWS_MCP_TOOL : `${WINDOWS_MCP_TOOL}@${options.pinned}`;
+      const indexUrl = typeof options.indexUrl === "string" && options.indexUrl !== "" ? options.indexUrl : null;
+      const toolDirectory = typeof options.toolDirectory === "string" && options.toolDirectory !== "" ? options.toolDirectory : null;
+      const resolveExecutable = typeof options.resolveExecutable === "function" ? options.resolveExecutable : windowsMcpExecutable;
       state.phase = "running";
       state.startedAt = new Date().toISOString();
       state.finishedAt = null;
       state.error = null;
       state.bridge = null;
-      state.log = [`$ ${uv} tool install --force ${spec}`];
+      const command = [uv, "tool", "install", "--force", ...(indexUrl === null ? [] : ["--default-index", indexUrl]), spec].join(" ");
+      state.log = [`$ ${command}${toolDirectory === null ? "" : `  (UV_TOOL_DIR=${toolDirectory})`}`];
       try {
-        const running = spawn(uv, ["tool", "install", "--force", spec], {
-          cwd: homedir(),
-          env: { ...process.env, UV_HTTP_TIMEOUT: "600", UV_CONCURRENT_DOWNLOADS: "8" },
-          windowsHide: true,
-          stdio: ["ignore", "pipe", "pipe"],
-        });
+        const { child: running } = spawnUvInstall({ uv, spec, indexUrl, toolDirectory, onLine: append });
         child = running;
-        running.stdout?.on("data", append);
-        running.stderr?.on("data", append);
         running.on("error", (error) => settle("failed", String(error)));
         running.on("close", (code) => {
           if (state.phase === "cancelled") return;
@@ -225,7 +291,7 @@ export function createPrepare(options = {}) {
             settle("failed", `uv exited with code ${code}`);
             return;
           }
-          const executable = windowsMcpExecutable();
+          const executable = resolveExecutable();
           if (executable === null) {
             settle("failed", "uv reported success, but no windows-mcp executable appeared in the tool directory.");
             return;