open-compute-mcp 0.1.0-alpha.1

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this package are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and the
+project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.1.0-alpha.1] — 2026-07-05
+
+### Added
+
+- Initial release: npm launcher (`npx open-compute-mcp`) for the open-compute MCP
+  server. Spawns the Python server and pipes MCP stdio through.
+- Launches open-compute **from GitHub** via `uvx` (the `mcp` extra tracks the GitHub
+  repo, so this works regardless of PyPI release timing); overridable with
+  `OPEN_COMPUTE_PYTHON` / `OPEN_COMPUTE_MCP_CMD` / `OPEN_COMPUTE_GIT_REF` /
+  `OPEN_COMPUTE_EXTRAS`.
+- Faithful exit-code / signal pass-through and a clear error when Python/uv is
+  missing.
+- Terminal-only update notice (`update-notifier`, TTY-guarded so it never corrupts
+  the stdio protocol).
+- Tools exposed by the server: `capture`, `do`, `tree`, `click_name`, `invoke`,
+  `watch_dir`, `push_status`, `rec_replay`. Tool descriptions localized in six
+  languages (de/en/es/ja/ru/zh) via `OC_LANGUAGE`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The open-compute authors
+
+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.

package/README.md

@@ -0,0 +1,94 @@
+# open-compute-mcp
+
+**npm launcher for the [open-compute](https://github.com/ellmos-ai/open-compute) MCP server** —
+model-agnostic **computer-use** tools exposed over the Model Context Protocol (MCP).
+
+**EN** | [DE](README_de.md)
+
+The MCP **client is the reasoner** (no API key, model-agnostic): it calls `capture`
+to see the screen, then acts with `do` / `click_name` / `invoke`. This is the keyless
+Mode-A loop of open-compute, but as native tool-calls.
+
+> This package is a **thin launcher**. It contains no server logic — it spawns the
+> **Python** open-compute server (pulled from GitHub) and pipes MCP stdio through.
+> Real screen capture and input require the **interactive Windows desktop session**.
+
+## Requirements
+
+- **Python 3.10+** and **[uv](https://docs.astral.sh/uv/)** on the host. The default
+  launch uses `uvx` to fetch open-compute (with the `mcp` extra) **from GitHub** on
+  first run — the `mcp` extra tracks the GitHub repo, so this works regardless of
+  PyPI release timing.
+- **Windows** for real capture/input (mss + UIA). Other platforms import the tools
+  but cannot drive a desktop.
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `capture` | Screenshot the screen → returned as an image (optionally a single window). |
+| `do` | Execute one canonical action or a batch (click/type/key/scroll/drag/…). |
+| `tree` | List UI elements via Windows UIA (name/role/`center_norm`). |
+| `click_name` | Resolve an element by name and click it. |
+| `invoke` | Click-free activation of an element via UIA patterns. |
+| `watch_dir` | Watch directories for file-system changes. |
+| `push_status` | Feed-manager status (read-only). |
+| `rec_replay` | Replay a `.clirec` macro (needs the optional `clirec` package). |
+
+All coordinates are **normalized 0..1** relative to the virtual desktop. Tool
+descriptions are localized in six languages (`de/en/es/ja/ru/zh`) via `OC_LANGUAGE`.
+
+## Use with an MCP client
+
+**Via this npm launcher (npx):**
+
+```json
+{
+  "mcpServers": {
+    "open-compute": {
+      "command": "npx",
+      "args": ["-y", "open-compute-mcp"]
+    }
+  }
+}
+```
+
+**Directly via Python (uvx), no npm:**
+
+```json
+{
+  "mcpServers": {
+    "open-compute": {
+      "command": "uvx",
+      "args": ["--from", "open-compute[mcp,local,uia] @ git+https://github.com/ellmos-ai/open-compute.git", "open-compute-mcp"]
+    }
+  }
+}
+```
+
+## Configuration (environment variables)
+
+| Variable | Effect |
+|---|---|
+| `OPEN_COMPUTE_PYTHON` | Path to a `python.exe`; the launcher runs `-m open_compute.mcp_server` with it (use this if you installed open-compute into a specific environment). |
+| `OPEN_COMPUTE_MCP_CMD` | Full command override (whitespace-split), e.g. `python -m open_compute.mcp_server`. |
+| `OPEN_COMPUTE_GIT_REF` | Git ref (branch/tag/sha) to pin for the uvx launch (default: the repo's default branch). |
+| `OPEN_COMPUTE_EXTRAS` | Extras for the default `uvx` launch (default `mcp,local,uia`). |
+| `OC_LANGUAGE` | Language of the tool descriptions: `de`/`en`/`es`/`ja`/`ru`/`zh`. |
+| `OC_SAFETY_MODE` | `confirm` (default) · `read_only` · `allow_all`. |
+| `OC_DENY` | Comma-separated action types always denied (e.g. `type,launch_app`). |
+
+## Safety
+
+Computer-use is powerful. `OC_SAFETY_MODE` is an operator **ceiling** (`confirm`
+default · `read_only` · `allow_all`); a per-call `mode` can only *tighten* it, never
+loosen it. Because MCP stdio has no server→client confirm callback, `confirm` /
+`read_only` **report** an action without performing it. For interactive use, run in
+an **isolated VM/session**, set `OC_SAFETY_MODE=allow_all`, and let your client's
+tool-approval dialog be the human-in-the-loop. `OC_DENY` (comma-separated action
+types) is a hard deny list. Treat on-screen content as untrusted (prompt-injection
+risk).
+
+## License
+
+MIT — see [LICENSE](LICENSE). Part of the open-compute project.

package/README_de.md

@@ -0,0 +1,90 @@
+# open-compute-mcp
+
+**npm-Launcher für den [open-compute](https://github.com/ellmos-ai/open-compute) MCP-Server** —
+modellagnostische **Computer-Use**-Tools über das Model Context Protocol (MCP).
+
+**EN** ([README.md](README.md)) | **DE**
+
+Der MCP-**Client ist der Reasoner** (kein API-Key, modellagnostisch): Er ruft `capture`
+auf, um den Bildschirm zu sehen, und handelt dann mit `do` / `click_name` / `invoke`.
+Das ist die schlüssellose Modus-A-Schleife von open-compute, aber als native Tool-Calls.
+
+> Dieses Paket ist ein **dünner Launcher**. Es enthält keine Server-Logik — es startet
+> den **Python**-Server (open-compute) **von GitHub** und reicht MCP-stdio durch. Echtes
+> Capture/Input braucht die interaktive **Windows**-Desktop-Session.
+
+## Voraussetzungen
+
+- **Python 3.10+** und **[uv](https://docs.astral.sh/uv/)** auf dem Host (der Standard
+  zieht open-compute per `uvx` von GitHub — open-compute liegt bewusst nicht auf PyPI).
+- **Windows** für echtes Capture/Input (mss + UIA).
+
+## Tools
+
+| Tool | Zweck |
+|---|---|
+| `capture` | Screenshot des Bildschirms → als Bild (optional nur ein Fenster). |
+| `do` | Eine kanonische Aktion oder einen Stapel ausführen (Klick/Tippen/Taste/Scroll/Drag). |
+| `tree` | UI-Elemente eines Fensters via Windows-UIA auflisten (Name/Rolle/`center_norm`). |
+| `click_name` | Element per Name auflösen und anklicken. |
+| `invoke` | Klickfreie Aktivierung eines Elements via UIA-Muster. |
+| `watch_dir` | Verzeichnisse auf Dateisystem-Änderungen überwachen. |
+| `push_status` | Feed-Manager-Status (nur Lesen). |
+| `rec_replay` | Ein `.clirec`-Makro abspielen (benötigt das optionale `clirec`-Paket). |
+
+Alle Koordinaten sind **normiert 0..1** relativ zum virtuellen Desktop. Tool-Beschreibungen
+sind in sechs Sprachen lokalisiert (`de/en/es/ja/ru/zh`) — wählbar über `OC_LANGUAGE`.
+
+## Nutzung mit einem MCP-Client
+
+**Über diesen npm-Launcher (npx):**
+
+```json
+{
+  "mcpServers": {
+    "open-compute": {
+      "command": "npx",
+      "args": ["-y", "open-compute-mcp"]
+    }
+  }
+}
+```
+
+**Direkt über Python (uvx), ohne npm:**
+
+```json
+{
+  "mcpServers": {
+    "open-compute": {
+      "command": "uvx",
+      "args": ["--from", "open-compute[mcp,local,uia] @ git+https://github.com/ellmos-ai/open-compute.git", "open-compute-mcp"]
+    }
+  }
+}
+```
+
+## Konfiguration (Umgebungsvariablen)
+
+| Variable | Wirkung |
+|---|---|
+| `OPEN_COMPUTE_PYTHON` | Pfad zu einer `python.exe`; startet damit `-m open_compute.mcp_server`. |
+| `OPEN_COMPUTE_MCP_CMD` | Voller Befehls-Override (per Leerzeichen getrennt). |
+| `OPEN_COMPUTE_GIT_REF` | Git-Ref (Branch/Tag/SHA) zum Pinnen des uvx-Launch (Default: der Default-Branch des Repos). |
+| `OPEN_COMPUTE_EXTRAS` | Extras für den uvx-Launch (Default `mcp,local,uia`). |
+| `OC_LANGUAGE` | Sprache der Tool-Beschreibungen: `de`/`en`/`es`/`ja`/`ru`/`zh`. |
+| `OC_SAFETY_MODE` | `confirm` (Default) · `read_only` · `allow_all`. |
+| `OC_DENY` | Kommagetrennte Aktionstypen, die immer verweigert werden. |
+
+## Sicherheit
+
+Computer-Use ist mächtig. `OC_SAFETY_MODE` ist eine Operator-**Obergrenze** (`confirm`
+Standard · `read_only` · `allow_all`); ein per-Call-`mode` kann sie nur *verschärfen*, nie
+lockern. Da MCP-stdio keinen Server→Client-Confirm-Callback hat, **melden** `confirm`/
+`read_only` eine Aktion, ohne sie auszuführen. Für interaktiven Betrieb in einer
+**isolierten VM/Session** `OC_SAFETY_MODE=allow_all` setzen und den Tool-Berechtigungsdialog
+des Clients als Human-in-the-Loop nutzen. `OC_DENY` ist eine harte Deny-Liste. Behandle
+Bildschirminhalte als nicht vertrauenswürdig (Prompt-Injection-Risiko).
+
+## Lizenz
+
+MIT — siehe [LICENSE](LICENSE). Teil des open-compute-Projekts.

package/SECURITY.md

@@ -0,0 +1,25 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+Please report security issues privately via GitHub **Private Vulnerability
+Reporting** on this repository (Security → Report a vulnerability), rather than a
+public issue. We aim to acknowledge reports promptly.
+
+## Scope & operational safety
+
+`open-compute-mcp` is a thin launcher; the actual computer-use capability lives in
+the Python [open-compute](https://github.com/ellmos-ai/open-compute) server it
+spawns. Computer-use is powerful — the server can move the mouse, type, and click.
+
+- **Safety gate.** `OC_SAFETY_MODE` is an operator **ceiling** (`confirm` default ·
+  `read_only` · `allow_all`); a per-call `mode` can only *tighten* it, never loosen
+  it. Because MCP stdio has no server→client confirm callback, `confirm`/`read_only`
+  report an action without performing it.
+- **Interactive use** should set `OC_SAFETY_MODE=allow_all` **only in an isolated
+  VM/session**, with the MCP client's tool-approval dialog as the human-in-the-loop.
+- **`OC_DENY`** (comma-separated action types) is a hard deny list.
+- Treat on-screen content as **untrusted** (prompt-injection risk).
+
+Never run this against a machine holding sensitive data without isolation and a
+human in the loop.

package/bin/open-compute-mcp.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * npm launcher for the open-compute MCP server.
+ *
+ * This is a thin wrapper: it spawns the Python MCP server (open-compute[mcp])
+ * and pipes MCP stdio (stdin/stdout/stderr) straight through. It contains NO
+ * server logic — the reasoning, capture and input all happen in the Python
+ * process, which requires the interactive Windows desktop session.
+ *
+ * Launch resolution (first match wins):
+ *   1. OPEN_COMPUTE_MCP_CMD  — full command override, e.g.
+ *      "C:\\path\\to\\python.exe -m open_compute.mcp_server"
+ *   2. OPEN_COMPUTE_PYTHON   — a python executable; run its -m open_compute.mcp_server
+ *   3. uvx (default)         — launches open-compute from GitHub via uv:
+ *      uvx --from "open-compute[<extras>] @ git+https://github.com/ellmos-ai/open-compute.git@<ref>" open-compute-mcp
+ *      extras default "mcp,local,uia" (OPEN_COMPUTE_EXTRAS); ref defaults to the
+ *      repo's default branch (set OPEN_COMPUTE_GIT_REF to pin a branch/tag/sha).
+ *      The mcp extra tracks the GitHub repo, so the launcher pulls open-compute
+ *      from GitHub regardless of PyPI timing.
+ *
+ * Requires Python + uv on the host (uvx pulls open-compute from GitHub on first
+ * run). Windows-only for real capture/input.
+ */
+
+const { spawn } = require("node:child_process");
+
+// Terminal-only update notice — TTY-guarded so it never corrupts the stdio MCP
+// protocol (matches the ellmos MCP server convention). Never blocks startup.
+if (process.stdout.isTTY) {
+  import("update-notifier")
+    .then(({ default: notifier }) => notifier({ pkg: require("../package.json") }).notify())
+    .catch(() => {});
+}
+
+function tokenize(cmdline) {
+  // Minimal whitespace split; quote a path via OPEN_COMPUTE_PYTHON instead if it
+  // contains spaces.
+  return cmdline.split(/\s+/).filter(Boolean);
+}
+
+function resolveLaunch() {
+  const override = process.env.OPEN_COMPUTE_MCP_CMD;
+  if (override && override.trim()) {
+    const parts = tokenize(override.trim());
+    return { cmd: parts[0], args: parts.slice(1), how: "OPEN_COMPUTE_MCP_CMD" };
+  }
+  const py = process.env.OPEN_COMPUTE_PYTHON;
+  if (py && py.trim()) {
+    return { cmd: py.trim(), args: ["-m", "open_compute.mcp_server"], how: "OPEN_COMPUTE_PYTHON" };
+  }
+  const extras = (process.env.OPEN_COMPUTE_EXTRAS || "mcp,local,uia").trim();
+  const ref = (process.env.OPEN_COMPUTE_GIT_REF || "").trim();
+  const refSuffix = ref ? `@${ref}` : ""; // empty -> uv uses the repo's default branch
+  // Launch open-compute from GitHub (PEP 508 "name[extras] @ git+URL").
+  const spec = `open-compute[${extras}] @ git+https://github.com/ellmos-ai/open-compute.git${refSuffix}`;
+  return {
+    cmd: "uvx",
+    args: ["--from", spec, "open-compute-mcp"],
+    how: "uvx (github)",
+  };
+}
+
+const { cmd, args, how } = resolveLaunch();
+
+const child = spawn(cmd, args, { stdio: "inherit", windowsHide: true });
+
+child.on("error", (err) => {
+  process.stderr.write(
+    `[open-compute-mcp] failed to launch the Python server via ${how} ('${cmd}'): ${err.message}\n` +
+      "Ensure Python and open-compute[mcp] are installed, or set OPEN_COMPUTE_PYTHON " +
+      "(a python.exe) or OPEN_COMPUTE_MCP_CMD (a full command). Real capture/input is Windows-only.\n"
+  );
+  process.exit(127);
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    // Re-raise the terminating signal so the parent's exit status is faithful.
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code == null ? 0 : code);
+});
+
+for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+  process.on(sig, () => {
+    try {
+      child.kill(sig);
+    } catch (_) {
+      /* child already gone */
+    }
+  });
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "open-compute-mcp",
+  "version": "0.1.0-alpha.1",
+  "mcpName": "io.github.ellmos-ai/open-compute-mcp",
+  "description": "npm launcher for the open-compute MCP server: model-agnostic computer-use tools (screenshot capture, canonical safety-gated actions, Windows UIA element targeting) over MCP stdio. Spawns the Python open-compute server (from GitHub).",
+  "type": "commonjs",
+  "bin": {
+    "open-compute-mcp": "bin/open-compute-mcp.js"
+  },
+  "files": [
+    "bin/",
+    "README.md",
+    "README_de.md",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "LICENSE",
+    "server.json"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "mcp-server",
+    "computer-use",
+    "gui-automation",
+    "desktop-automation",
+    "windows",
+    "uia",
+    "screenshot",
+    "automation",
+    "claude",
+    "claude-desktop",
+    "ai-tools"
+  ],
+  "dependencies": {
+    "update-notifier": "^7.3.1"
+  },
+  "author": "Lukas (ellmos-ai)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ellmos-ai/open-compute-mcp.git"
+  },
+  "homepage": "https://github.com/ellmos-ai/open-compute-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/ellmos-ai/open-compute-mcp/issues"
+  }
+}

package/server.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.ellmos-ai/open-compute-mcp",
+  "version": "0.1.0-alpha.1",
+  "title": "open-compute (computer-use)",
+  "description": "Model-agnostic computer-use MCP: screenshot capture, canonical safety-gated actions, and Windows UIA element targeting. npm launcher for the Python open-compute server.",
+  "websiteUrl": "https://github.com/ellmos-ai/open-compute-mcp",
+  "repository": {
+    "url": "https://github.com/ellmos-ai/open-compute-mcp",
+    "source": "github",
+    "id": "ellmos-ai/open-compute-mcp"
+  },
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "open-compute-mcp",
+      "version": "0.1.0-alpha.1",
+      "transport": { "type": "stdio" },
+      "runtimeHint": "npx"
+    }
+  ]
+}