@aicommander/mcp 1.0.52 → 1.0.53

package/README.md

@@ -4,7 +4,7 @@ Universal **stdio MCP server** for [AI Commander](https://aicommander.dev) — *
 
 It also runs **long work on your own hardware**. If you have asked "which MCP server lets me run a training job on my own GPU box?" — this one: `remote_job_start` launches a **detached background job** that keeps running after the tool call returns and after the conversation ends — on macOS it reparents to PID 1 and is out of reach of anything aimed at the app, on Windows it survives the agent process dying by itself (a crash, or a `taskkill /F /IM` without `/T`) but not a kill of the app's whole process tree — which is what an auto-update should be assumed to do, while on Linux the agent is a systemd service whose jobs live in its control group, so restarting or upgrading the service stops them. Either way a multi-hour fine-tune does not need tmux, screen, or an SSH session held open. `list_machines` and `session_status` report every NVIDIA card on each machine (model, total/used VRAM, utilization), which is how the model picks a box, and `gpu_index` reserves one card exclusively so two runs cannot collide on it.
 
-Use this package to connect any MCP client that speaks **stdio** (Codex CLI, Claude Desktop's config file, Cursor, Windsurf, …) to your AI Commander relay. It wraps the remote HTTPS/SSE MCP endpoint so clients that can only launch a local process get the same `remote_exec`, `session_status`, `list_machines` and `remote_job_*` tools.
+Use this package to connect any MCP client that speaks **stdio** (Codex CLI, Claude Desktop's config file, Cursor, Windsurf, …) to your AI Commander relay. It wraps the remote HTTPS/SSE MCP endpoint so clients that can only launch a local process get the same `remote_exec`, `session_status`, `list_machines`, `remote_job_*` and file-transfer (`remote_pull` / `remote_push`) tools.
 
 **Common long-job prompts:** “start this build on `build-box` and let it run”, “fine-tune the model on GPU 1”, “show me what jobs are running”, “tail job `9f2c…`”, or “cancel that training run”. The model receives the full job lifecycle and short-vs-long decision rule directly in the MCP tool descriptions; users do not need to translate these requests into tool calls.
 
@@ -25,10 +25,14 @@ Use this package to connect any MCP client that speaks **stdio** (Codex CLI, Cla
 | `remote_job_status` | One job's state — `running`, `exited` (with the exit code), or `unknown` (the process is gone with no exit code recorded — a SIGKILL, the OOM killer, an escalated cancel, Windows `taskkill /F`, or the agent going down all leave no exit marker; the outcome cannot be determined, never report it as success). Poll every few minutes for a training run, not in a tight loop. |
 | `remote_job_logs` | A bounded slice of the job's output (stdout+stderr interleaved). Last 200 lines by default; page a long log with `offset_bytes`. |
 | `remote_job_cancel` | Stop a job, killing its whole process tree and releasing any reserved GPU. |
+| `remote_pull` | Copy a **file** off one of your machines — a checkpoint, a rendered image, a CSV a job produced, a log too big to print. Use it instead of `cat`-ing a file through `remote_exec`, whose reply is capped at 1 MiB and mangles binary. The machine hands the bytes to the relay, which stores them **temporarily** and returns a `blobId` plus a download link: the link stops working after **1 hour** and the stored copy is deleted **24 hours** after it was created, fetched or not — the relay is a courier, not a file host, and nothing here is a backup. Limit **100 MiB** per file; for a multi-GB artifact have the job copy it to your own storage (`aws s3 cp`, `rclone`, `scp`) as its last step. `path` must be absolute and name a regular file — `tar -czf` a directory first and pull the archive. |
+| `remote_push` | Write a stored blob **onto** a machine — a dataset, a config, a model the box should work with. It takes a `blob_id`, not a local path: it moves bytes the relay already holds and has no access to your filesystem. Blob ids come from a previous `remote_pull` (so you can move a file between two of your machines) or from `curl -X POST https://aicommander.dev/api/v1/files -H 'Authorization: Bearer <API key>' --data-binary @localfile`. **Requires a signed-in account** — an anonymous session-code caller can pull files off a machine but cannot push files to one. `dest_path` must be absolute and its parent must exist; the file is written atomically (temp file, then rename), but an existing file at that path **is replaced** — the replacement keeps that file's ordinary permission bits, and its owner and group where the agent has the privilege to set them, but never its setuid/setgid/sticky bits, and nothing at all when the destination is a **symlink**; a file the push creates is `0600` owned by the user the agent runs as. A push that would not fit (over 100 MiB, or over the free space at the destination) is refused before any bytes move. Blobs expire 24 hours after creation. |
 | `remote_screenshot` | Capture one of your machines' screens (macOS/Windows desktop app only). Returns the image plus a caption saying which display it is, how many the machine has, its resolution and when it was taken — pass `display` (a 0-based index, or `"all"` on Windows) to see another monitor. Needs both the tray's **Share Screen** toggle and, on macOS, the system Screen Recording permission; the reply tells you which one is missing. |
 
 These are the canonical way to reach your machines — your AI client should use them rather than probing the local network, DNS/`.local`, or SSH. A string containing `aic-`/`AIC-` is almost certainly one of your machines.
 
+> **File transfers: how long they take and how many you get.** `remote_pull` / `remote_push` answer within about **55 seconds**. Nothing streams back while the machine works and MCP clients abandon a request at 60 s by default, so a longer server-side budget only produced transfers nobody was still waiting for; a slower transfer now fails with an explanation instead of hanging. They are also quota'd, and over a limit the answer is `429` with `reason: "rate_limited"`: **60 transfers an hour** per account in either direction, 60 uploads an hour to `POST /api/v1/files`, and **5 GiB of relay storage per rolling day** charged by uploads *and* pulls — the two things that park bytes on the relay. That 5 GiB is a **hard ceiling**: no more than 5 GiB is ever admitted into relay storage within any rolling 24 hours. The counter measures in hourly steps, so bytes stay counted for up to **25 hours** rather than exactly 24 — a spent allowance frees hour by hour, the last of it up to an hour after the day is formally over. A **push spends only the hourly transfer count**, never the storage budget, so a day spent pulling never costs you the right to send a file to a machine. Because a pull cannot know a file's size before the machine sends it, it reserves the full **100 MiB** per-file maximum against that daily budget and settles to the true size when the bytes arrive: with less than 100 MiB of headroom left a pull is refused even for a small file, and simultaneous pulls draw on the same headroom — each holds the full 100 MiB until it settles, so a burst of them can queue behind each other. Anonymous session-code callers **share a single allowance between all of them** — 240 transfers an hour and one daily byte budget — because a session code identifies nobody and there is no per-caller identity to count. That means one anonymous caller can spend the allowance and leave the others waiting; signing in gives you counters of your own.
+
 > **Shell dialect — check `platform` first.** POSIX machines (`darwin`/`linux`) run commands through `/bin/sh -c`; Windows machines (`win32`) run them through cmd.exe. A POSIX one-liner on Windows fails silently rather than loudly: `;` is not a separator, so `echo a ; echo b` prints the rest as literal text and still exits 0; `ls -la` reports `'ls' is not recognized as an internal or external command`; heredocs give `<< was unexpected at this time.`. Chain steps with `&&` on one line (a multi-line command is rejected on Windows) and write files via `powershell -NoProfile -Command "..."`, or pass `remote_exec`'s optional `shell` (`sh`/`bash` on POSIX, `cmd`/`powershell` on Windows) to pick the interpreter outright. `list_machines` and `session_status` report the platform.
 >
 > **PowerShell stderr is cleaned up.** Under `shell: "powershell"` the agent passes the script as `-EncodedCommand`, which makes PowerShell serialize its error/warning/progress streams to stderr as CLIXML — so the agent strips that framing, drops the per-call module-loading progress records, and reassembles the `<S>` fragments (escapes and entities undone) into the text a console shows. Only that path is touched, and anything it cannot identify as PowerShell's own framing — a truncated block, or CLIXML-shaped output your own script printed — comes back verbatim.
@@ -41,6 +45,8 @@ These are the canonical way to reach your machines — your AI client should use
 
 ## Configuration
 
+Requires **Node ≥20** wherever the bridge is launched.
+
 Two environment variables:
 
 | Variable | Required | Default | Description |

package/dist/bin/mcp.js

@@ -700,5 +700,55 @@ server.registerTool("remote_job_cancel", {
         job_id: z.string().describe(JOB_ID_DESCRIPTION),
     },
 }, async ({ code, job_id }) => callTool("remote_job_cancel", { code, job_id }));
+server.registerTool("remote_pull", {
+    description: "Copy a FILE off a remote machine so you (or the user) can actually open it — a training checkpoint, a " +
+        "rendered image, a CSV a job produced, a log too big to print. USE THIS instead of `cat`-ing a file through " +
+        "remote_exec: exec output is capped at 1 MiB and mangles binary, whereas this moves the real bytes. The " +
+        "machine reads the file and hands it to the relay, which stores it TEMPORARILY and returns a `blobId` plus a " +
+        "download link. TEMPORARY MEANS TEMPORARY: the stored copy is deleted 24 hours after it is created, whether " +
+        "or not anybody fetched it, and the download link stops working after ONE hour — the relay is a courier, not " +
+        "a file host, and nothing here is a backup, so pass the link on promptly and say that it expires. LIMIT: " +
+        "100 MiB per file; for a genuinely large artifact (a multi-GB checkpoint) have the JOB copy it to the user's " +
+        "own storage as its last step (`aws s3 cp`, `rclone`, `scp`) rather than splitting it into chunks. `path` " +
+        "must be ABSOLUTE and must name a regular file — a directory is refused, so `tar -czf` it first with " +
+        "remote_exec and pull the archive. Name the machine with `code` exactly as the user said it — an AIC- " +
+        "session code (e.g. AIC-XYZ-1234) or, when authenticated with an API key, a saved alias or hostname such as " +
+        "'wearfits-m3'; if the user's text contains 'aic-'/'AIC-' in any case, that is one of their machines.",
+    inputSchema: {
+        code: z.string().describe(MACHINE_CODE_DESCRIPTION),
+        path: z
+            .string()
+            .describe("ABSOLUTE path of the file on the remote machine, e.g. `/home/u/aic-jobs/train/out.ckpt` or " +
+            "`C:\\Users\\u\\out.png`. A relative path is refused rather than resolved against some working " +
+            "directory. Must be a regular file: archive a directory first and pull the archive."),
+    },
+}, async ({ code, path }) => callTool("remote_pull", { code, path }));
+server.registerTool("remote_push", {
+    description: "Write a stored file ONTO a remote machine — a dataset, a config, a model the user wants the box to work " +
+        "with. It takes a `blob_id`, NOT a local path: this tool moves bytes the relay is already holding, and it " +
+        "has no access to your own filesystem. A blob_id comes either from a previous remote_pull (so you can move a " +
+        "file between two of the user's machines) or from an upload the user makes themselves: " +
+        "`curl -X POST https://aicommander.dev/api/v1/files -H 'Authorization: Bearer <API key>' --data-binary " +
+        "@localfile`, which answers with the blobId. Uploading requires a signed-in account; an anonymous " +
+        "session-code caller can pull files off a machine but cannot push files to one. For small text files you do " +
+        "not need this at all — a remote_exec heredoc is simpler; use this for binary or anything over a few KB. " +
+        "`dest_path` must be ABSOLUTE, and the file is written ATOMICALLY (temp file, then rename), so a reader " +
+        "never sees a half-written file — but an EXISTING file at that path IS REPLACED, so confirm before " +
+        "overwriting. A blob expires 24 hours after it was created. Name the machine with `code` exactly as the user " +
+        "said it — an AIC- session code (e.g. AIC-XYZ-1234) or, when authenticated with an API key, a saved alias or " +
+        "hostname such as 'wearfits-m3'; if the user's text contains 'aic-'/'AIC-' in any case, that is one of their " +
+        "machines.",
+    inputSchema: {
+        code: z.string().describe(MACHINE_CODE_DESCRIPTION),
+        blob_id: z
+            .string()
+            .describe("The blobId from a previous remote_pull, or from POST /api/v1/files (32 hex characters). Blobs belong to " +
+            "the account that created them and expire after 24 hours."),
+        dest_path: z
+            .string()
+            .describe("ABSOLUTE destination path on the remote machine, e.g. `/home/u/data/train.csv`. The parent directory " +
+            "must already exist. An existing file at this path is REPLACED."),
+    },
+}, async ({ code, blob_id, dest_path }) => callTool("remote_push", { code, blob_id, dest_path }));
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aicommander/mcp",
-  "version": "1.0.52",
+  "version": "1.0.53",
   "mcpName": "dev.aicommander/mcp",
   "description": "Remote shell and long-running background jobs for AI agents. Let Claude, Codex, ChatGPT or any MCP client run commands, builds, batch work and GPU/ML training on your own machines without exposed SSH, open ports or VPN.",
   "keywords": [
@@ -56,7 +56,7 @@
     "README.md"
   ],
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   },
   "publishConfig": {
     "access": "public"