cloudgpu-mcp 0.4.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -162,6 +162,43 @@ The server also provides a `train_on_cloudgpu` prompt.
162
162
 
163
163
  The key also works with the OpenAI-compatible API at `https://cloudgpu.app/v1`. Call `list_models` (or `GET /v1/models`) to see the available model IDs. Model prices are on [cloudgpu.app/api](https://cloudgpu.app/api).
164
164
 
165
+ ## Optional persistent files and Workspaces (development)
166
+
167
+ These tools require persistent storage to be explicitly enabled on the server;
168
+ they return `storage_not_enabled` until it is ready. Discover server capabilities
169
+ at `/v1/public/compute-capabilities`. Read `get_storage` for current included allowance, quota, prices and retention. Storage fees are separate from GPU Job budgets. Uploads above the included allowance require `accept_storage_charges=true` after user agreement; the default is false. Budget-limited connect-link keys cannot enable paid storage. Files expose `expires_at`; downloading does not renew retention. Versions containing expired files become unavailable, while active Jobs defer deletion.
170
+
171
+ - `get_compute_catalog` and `quote_compute` use public discovery and server quotes,
172
+ including required starting balance and `supports_jobs`. Pass the server quote to
173
+ `run_job` as `quote_id`; the original `estimate_cost` remains a local quote for
174
+ interactive instance rentals.
175
+ - `get_storage`, `list_files`, `list_workspaces`, `list_workspace_versions` and
176
+ `get_workspace_version` show saved files, versions and usage.
177
+ - `upload_artifact` and `download_artifact` transfer persistent files, including
178
+ datasets/models, without returning storage credentials to the assistant.
179
+ - `save_workspace` saves regular project files as an immutable version. It refuses
180
+ known credential paths and symlinks, and skips `.git`, `node_modules`,
181
+ `__pycache__` and `.venv`. Save dependency manifests so the next GPU can rebuild
182
+ its environment. The returned `workspace_version_id` can be passed to `run_job`.
183
+ - `delete_file` and `delete_workspace_version` require explicit user confirmation
184
+ and refuse active references.
185
+
186
+ This restores project files into a fresh directory before the Job command. It is
187
+ not full-disk restore and does not automatically save edits or collect outputs.
188
+ Continue saving results from the command itself. Large-model restore speed and
189
+ cross-supplier cache behavior must be measured before relying on them. Backend restore plans travel via SSH stdin, never in
190
+ Job command arguments or saved scripts; the user command starts after restoration.
191
+ This does not protect transfer-time memory from root on the GPU. Failed deletions
192
+ or expired uploads may remain pending while the server verifies cleanup; quota is
193
+ released only after confirmed removal. With storage disabled, normal catalog,
194
+ account, instance and Job tools keep working without a storage provider.
195
+
196
+
197
+ The developer acceptance script `node scripts/acceptance.mjs` is read-only by
198
+ default. Its `--paid` mode is for an explicitly authorized internal test account
199
+ only; it can create two Jobs capped at $0.03 each. Do not run paid mode as part of
200
+ ordinary package tests.
201
+
165
202
  ## Without MCP
166
203
 
167
204
  The server wraps CloudGPU's public REST API, which any agent or script can call with the same key:
@@ -217,3 +254,10 @@ node src/cli.js --help
217
254
  ## License
218
255
 
219
256
  MIT, see [LICENSE](LICENSE).
257
+
258
+
259
+ ### Apply a Workspace to a GPU you already rent
260
+
261
+ Use `list_workspace_instances`, then `get_workspace_application` with the saved `version_id` and the selected `instance_id`. After the user agrees, call `apply_workspace` with `user_confirmed: true`, then poll status. The files appear in a new private project directory; existing files are never overwritten. This does not install dependencies, execute project code or start, stop, or restart a GPU. Rental billing continues during transfer. Budgeted Agent keys can only target instances created with the same key. Workspace requires a funded account.
262
+
263
+ Repeated application of the same version to the same instance returns the existing result, including user edits after success. On `needs_attention`, `failed` or `conflict`, inspect the result rather than automatically retrying. A new saved version creates a separate directory. The feature must be enabled by the server; unavailable storage does not disable ordinary GPU rental or Job tools.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "cloudgpu-mcp",
3
- "version": "0.4.0",
3
+ "version": "0.6.0",
4
4
  "mcpName": "io.github.mrhy7176/cloudgpu-mcp",
5
5
  "description": "MCP server and command-line tool for cloudgpu.app: let Claude Code, Cursor, Cline, opencode, goose and other MCP clients (or you, from a terminal) rent a GPU per minute, run a job, fetch the results and shut it down, with spending limits the platform enforces.",
6
6
  "type": "module",
package/src/api.js CHANGED
@@ -100,6 +100,8 @@ export class CloudGpuApi {
100
100
  models() {
101
101
  return this.request("GET", "/v1/models").then((r) => r.data || []);
102
102
  }
103
+ catalog() { return this.request("GET", "/v1/public/gpu-catalog", undefined, { noAuth: !this.apiKey }); }
104
+ quote(body) { return this.request("POST", "/v1/quotes", body, { noAuth: !this.apiKey }); }
103
105
 
104
106
  // ── jobs: start a GPU, run one command, destroy the GPU (server-side) ──
105
107
  createJob(body, idempotencyKey) {
package/src/index.js CHANGED
@@ -18,6 +18,7 @@ import { CloudGpuApi, ApiError } from "./api.js";
18
18
  import { SshPool, exec, upload, download, writeFile } from "./ssh.js";
19
19
  import { loadStoredKey, saveStoredKey } from "./credentials.js";
20
20
  import crypto from "node:crypto";
21
+ import { registerStorageTools } from "./storage.js";
21
22
  import {
22
23
  checkCommand,
23
24
  sensitiveReason,
@@ -29,7 +30,7 @@ import {
29
30
  shq,
30
31
  } from "./guards.js";
31
32
 
32
- const VERSION = "0.4.0";
33
+ const VERSION = "0.6.0";
33
34
  const HERE = path.dirname(fileURLToPath(import.meta.url));
34
35
  const RULES = fs.readFileSync(path.join(HERE, "..", "rules", "cloudgpu.md"), "utf8");
35
36
 
@@ -62,6 +63,7 @@ No API key yet? connect_account gives the user a link to approve this assistant
62
63
  The same API key also works for the OpenAI-compatible model API at ${cfg.baseUrl}/v1 (see list_models).`;
63
64
 
64
65
  const server = new McpServer({ name: "cloudgpu", version: VERSION }, { instructions: INSTRUCTIONS });
66
+ registerStorageTools(server, { api, wrap, ok, fail, readOnly: cfg.readOnly, expandHome });
65
67
 
66
68
  // ── helpers ──────────────────────────────────────────────────────────────
67
69
 
@@ -126,6 +128,20 @@ function cleanOut(s, secrets) {
126
128
 
127
129
  // ── account and catalogue ────────────────────────────────────────────────
128
130
 
131
+ server.registerTool("get_compute_catalog", {
132
+ title: "Public GPU catalog", description: "GPU catalog, templates and billing without an API key. Does not rent anything.",
133
+ inputSchema: {}, annotations: { readOnlyHint: true, openWorldHint: true },
134
+ }, wrap(async () => ok(await api.catalog())));
135
+ server.registerTool("quote_compute", {
136
+ title: "Server-side compute quote", description: "Five-minute server quote: separates estimated task cost from required starting balance and marks supports_jobs. No GPU is started. Pass its quote_id to run_job.",
137
+ inputSchema: { min_vram_gb: z.number().int().min(0).default(0), gpu_model: z.string().optional(), gpu_count: z.number().int().min(1).max(8).default(1),
138
+ template: z.string().optional(), disk_gb: z.number().int().optional(), estimated_duration_seconds: z.number().int().positive(), max_budget_usd: z.number().positive() },
139
+ annotations: { readOnlyHint: true, openWorldHint: true },
140
+ }, wrap(async ({ estimated_duration_seconds, max_budget_usd, ...requirements }) => {
141
+ const q = await api.quote({ requirements, estimated_duration_seconds, max_budget_usd });
142
+ return ok({ ...q, quote_id: q.id });
143
+ }));
144
+
129
145
  server.registerTool(
130
146
  "get_account",
131
147
  {
@@ -479,6 +495,8 @@ if (!cfg.readOnly) {
479
495
  template: z.string().optional().describe("Template id from list_templates"),
480
496
  gpu_count: z.number().int().min(1).max(8).default(1),
481
497
  disk_gb: z.number().int().optional().describe("Larger system disk: 100, 200 or 500; omit for the standard disk"),
498
+ workspace_version_id: z.string().optional().describe("Immutable Workspace version to restore before the command; requires enabled persistent storage"),
499
+ quote_id: z.string().optional().describe("Server quote from quote_compute, starting quote_; binds configuration and checks price at submission"),
482
500
  max_spend_usd: z.number().positive().describe(`Budget for this job in USD (at most ${cfg.maxSpend})`),
483
501
  max_hours: z.number().positive().describe(`Hard time limit in hours (at most ${cfg.maxHours})`),
484
502
  user_confirmed: z.boolean().describe("true only if the user explicitly approved the GPU, budget and time limit"),
@@ -486,11 +504,11 @@ if (!cfg.readOnly) {
486
504
  },
487
505
  annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
488
506
  },
489
- wrap(async ({ command, gpu_model, template, gpu_count = 1, disk_gb, max_spend_usd, max_hours, user_confirmed, idempotency_key }) => {
507
+ wrap(async ({ command, gpu_model, template, gpu_count = 1, disk_gb, workspace_version_id, quote_id, max_spend_usd, max_hours, user_confirmed, idempotency_key }) => {
490
508
  if (user_confirmed !== true) {
491
509
  return fail("Not started: tell the user the GPU, budget and time limit, wait for an explicit yes, then call again with user_confirmed=true.");
492
510
  }
493
- if (!gpu_model && !template) return fail("Give gpu_model or template.");
511
+ if (!gpu_model && !template && !quote_id) return fail("Give gpu_model, template or a server quote_id from quote_compute.");
494
512
  if (max_spend_usd > cfg.maxSpend) {
495
513
  return fail(`max_spend_usd ${max_spend_usd} is above this server's cap of ${cfg.maxSpend} (CLOUDGPU_MAX_SPEND_USD).`);
496
514
  }
@@ -504,6 +522,8 @@ if (!cfg.readOnly) {
504
522
  if (gpu_model) body.gpu_model = gpu_model;
505
523
  if (template) body.template = template;
506
524
  if (disk_gb) body.disk_gb = disk_gb;
525
+ if (workspace_version_id) body.workspace_version_id = workspace_version_id;
526
+ if (quote_id) body.quote_id = quote_id;
507
527
  const job = await api.createJob(body, key);
508
528
  return ok({
509
529
  ...job,
package/src/storage.js ADDED
@@ -0,0 +1,135 @@
1
+ // 持久文件直接流向对象存储;长期 key 只发给 CloudGPU,不发给签名 URL 的主机。
2
+ import fs from "node:fs";
3
+ import fsp from "node:fs/promises";
4
+ import path from "node:path";
5
+ import { pipeline } from "node:stream/promises";
6
+ import { Readable, Transform } from "node:stream";
7
+ import { sensitiveReason } from "./guards.js";
8
+ import { z } from "zod";
9
+
10
+ export class PersistentStorage {
11
+ constructor(api, fetchImpl = globalThis.fetch) { this.api = api; this.fetch = fetchImpl; }
12
+ async upload(local, purpose = "artifact", name = path.basename(local), acceptStorageCharges = false) {
13
+ const stat = await fsp.stat(local);
14
+ if (!stat.isFile()) throw new Error("Upload needs a regular file.");
15
+ const file = await this.api.request("POST", "/v1/files", { name, purpose, size_bytes: stat.size, accept_storage_charges: acceptStorageCharges === true });
16
+ try {
17
+ for (let i = 1, offset = 0; i <= file.part_count; i++) {
18
+ const part = await this.api.request("POST", `/v1/files/${file.file_id}/parts/${i}`, {});
19
+ if (!String(part.url).startsWith("https://")) throw new Error("Storage must use HTTPS.");
20
+ const len = Number(part.content_length);
21
+ if (!Number.isSafeInteger(len) || len < 0 || offset + len > stat.size || (len === 0 && stat.size !== 0)) throw new Error("Invalid upload reservation.");
22
+ const stream = len === 0 ? Buffer.alloc(0) : fs.createReadStream(local, { start: offset, end: offset + len - 1 });
23
+ try {
24
+ const res = await this.fetch(part.url, { method: "PUT", headers: { "Content-Length": String(len) }, body: stream, duplex: "half", redirect: "error" });
25
+ if (!res.ok) throw new Error("Part upload failed.");
26
+ if (res.body) await res.body.cancel();
27
+ } catch { throw new Error("Storage part upload failed; no credentials were sent to the API response."); }
28
+ finally { if (stream.destroy) stream.destroy(); }
29
+ offset += len;
30
+ }
31
+ const after = await fsp.stat(local);
32
+ if (after.size !== stat.size || after.mtimeMs !== stat.mtimeMs) throw new Error("File changed during upload; snapshot was not saved.");
33
+ return await this.api.request("POST", `/v1/files/${file.file_id}/complete`, {});
34
+ } catch (e) {
35
+ await this.api.request("DELETE", `/v1/files/${file.file_id}`).catch(() => {});
36
+ throw e;
37
+ }
38
+ }
39
+ async download(id, local) {
40
+ const transfer = await this.api.request("POST", `/v1/files/${encodeURIComponent(id)}/download`, {});
41
+ if (!String(transfer.url).startsWith("https://")) throw new Error("Storage must use HTTPS.");
42
+ const expected = Number(transfer.size_bytes);
43
+ if (!Number.isSafeInteger(expected) || expected < 0) throw new Error("Invalid file size.");
44
+ await fsp.mkdir(path.dirname(local), { recursive: true });
45
+ const handle = await fsp.open(local, "wx", 0o600); // 不覆盖已有结果。
46
+ try {
47
+ const res = await this.fetch(transfer.url, { redirect: "error" });
48
+ if (!res.ok || !res.body) throw new Error("Download failed.");
49
+ let received = 0;
50
+ const bounded = new Transform({ transform(chunk, _encoding, done) {
51
+ received += chunk.length;
52
+ done(received > expected ? new Error("Storage returned excess bytes.") : null, received > expected ? undefined : chunk);
53
+ } });
54
+ await pipeline(Readable.fromWeb(res.body), bounded, handle.createWriteStream());
55
+ if ((await fsp.stat(local)).size !== Number(transfer.size_bytes)) throw new Error("Downloaded size mismatch.");
56
+ return { local_path: local, bytes: transfer.size_bytes };
57
+ } catch {
58
+ await handle.close().catch(() => {}); await fsp.unlink(local).catch(() => {});
59
+ throw new Error("Storage download failed; the partial file was removed.");
60
+ }
61
+ }
62
+ async saveWorkspace(localDir, name, workspaceId, acceptStorageCharges = false) {
63
+ const root = path.resolve(localDir), selected = [];
64
+ const walk = async dir => {
65
+ for (const e of await fsp.readdir(dir, { withFileTypes: true })) {
66
+ if ([".git", "node_modules", "__pycache__", ".venv"].includes(e.name)) continue;
67
+ const full = path.join(dir, e.name);
68
+ if (e.isSymbolicLink()) throw new Error("Workspace contains a symlink; choose regular project files.");
69
+ if (sensitiveReason(full)) throw new Error("Workspace contains a credential file. Remove it before saving.");
70
+ if (e.isDirectory()) await walk(full);
71
+ else if (e.isFile()) selected.push({ full, rel: path.relative(root, full).split(path.sep).join("/") });
72
+ }
73
+ };
74
+ await walk(root);
75
+ // Job runner 当前一次恢复最多 100 个文件;不悄悄保存一个不能用的工作区。
76
+ if (selected.length < 1 || selected.length > 100) throw new Error("Workspace must contain 1–100 regular files; binary environments and full disk images are not supported.");
77
+ const created = [], manifest = {};
78
+ try {
79
+ for (const file of selected) {
80
+ const saved = await this.upload(file.full, "workspace", file.rel, acceptStorageCharges);
81
+ created.push(saved.file_id); manifest[file.rel] = saved.file_id;
82
+ }
83
+ const ws = workspaceId ? { workspace_id: workspaceId } : await this.api.request("POST", "/v1/workspaces", { name });
84
+ const version = await this.api.request("POST", `/v1/workspaces/${encodeURIComponent(ws.workspace_id)}/versions`, manifest);
85
+ return { ...version, workspace_version_id: version.version_id };
86
+ } catch (e) {
87
+ for (const id of created) await this.api.request("DELETE", `/v1/files/${id}`).catch(() => {});
88
+ throw e;
89
+ }
90
+ }
91
+ }
92
+
93
+ export function registerStorageTools(server, { api, wrap, ok, fail, readOnly, expandHome }) {
94
+ const client = new PersistentStorage(api);
95
+ server.registerTool("get_storage", { title: "Persistent storage quota", description: "Storage availability, used bytes, reserved uploads and account quota. No money is spent.", inputSchema: {}, annotations: { readOnlyHint: true, openWorldHint: true } }, wrap(async () => ok(await api.request("GET", "/v1/storage"))));
96
+ server.registerTool("list_files", { title: "List persistent files", description: "Persistent artifacts, model/data files and Workspace files. Availability depends on storage being enabled.", inputSchema: {}, annotations: { readOnlyHint: true, openWorldHint: true } }, wrap(async () => ok(await api.request("GET", "/v1/files"))));
97
+ server.registerTool("list_workspaces", { title: "List Workspaces", description: "Saved project Workspaces; versions are immutable file manifests.", inputSchema: {}, annotations: { readOnlyHint: true, openWorldHint: true } }, wrap(async () => ok(await api.request("GET", "/v1/workspaces"))));
98
+ server.registerTool("list_workspace_versions", { title: "List Workspace versions", description: "List saved immutable versions of an owned Workspace.", inputSchema: { workspace_id: z.string() }, annotations: { readOnlyHint: true } }, wrap(async ({ workspace_id }) => ok(await api.request("GET", `/v1/workspaces/${encodeURIComponent(workspace_id)}/versions`))));
99
+ server.registerTool("get_workspace_version", { title: "Read Workspace version", description: "Read the path-to-file manifest for an owned version.", inputSchema: { version_id: z.string() }, annotations: { readOnlyHint: true } }, wrap(async ({ version_id }) => ok(await api.request("GET", `/v1/workspace-versions/${encodeURIComponent(version_id)}`))));
100
+ server.registerTool("list_workspace_instances", { title: "Running GPUs for Workspace restore", description: "Lists your running GPUs that this key may access. Budgeted Agent keys only see instances created by the same key.", inputSchema: {}, annotations: { readOnlyHint: true } }, wrap(async () => ok(await api.request("GET", "/v1/workspace-instances"))));
101
+ server.registerTool("get_workspace_application", { title: "Workspace application status", description: "Check file restoration on an existing GPU. This does not create, stop or restart a GPU. An uncertain result must be checked, never automatically resubmitted.", inputSchema: { version_id: z.string(), instance_id: z.string().regex(/^[0-9]{1,32}$/) }, annotations: { readOnlyHint: true } }, wrap(async ({ version_id, instance_id }) => ok(await api.request("GET", `/v1/workspace-versions/${encodeURIComponent(version_id)}/applications/${encodeURIComponent(instance_id)}`))));
102
+ if (readOnly) return;
103
+ server.registerTool("apply_workspace", {
104
+ title: "Apply Workspace to running GPU", description: "Restore project files to a new private directory on your existing running GPU. Does not install dependencies, execute code, overwrite existing files, rent, restart or stop a GPU. GPU rental billing continues; transfer consumes its network and disk. Ask the user before applying. Repeat requests for the same version and instance return the existing result; failures require inspection, not automatic retries.",
105
+ inputSchema: { version_id: z.string(), instance_id: z.string().regex(/^[0-9]{1,32}$/), user_confirmed: z.boolean() }, annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
106
+ }, wrap(async ({ version_id, instance_id, user_confirmed }) => user_confirmed === true ? ok(await api.request("POST", `/v1/workspace-versions/${encodeURIComponent(version_id)}/applications/${encodeURIComponent(instance_id)}`, {})) : fail("Ask the user before applying files to their running GPU.")));
107
+ server.registerTool("delete_workspace_version", {
108
+ title: "Delete Workspace version", description: "Deletes a saved version, releasing its file references. Refuses versions pinned by active Jobs. Ask the user first.",
109
+ inputSchema: { version_id: z.string(), user_confirmed: z.boolean() }, annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
110
+ }, wrap(async ({ version_id, user_confirmed }) => user_confirmed === true ? ok(await api.request("DELETE", `/v1/workspace-versions/${encodeURIComponent(version_id)}`)) : fail("Ask the user before deleting the Workspace version.")));
111
+
112
+ server.registerTool("upload_artifact", {
113
+ title: "Save a persistent artifact", description: "Uploads a local regular file in resumable-sized parts. Consumes storage quota; retention and pricing depend on the account policy. Credential files are refused.",
114
+ inputSchema: { local_path: z.string(), purpose: z.enum(["artifact", "model", "dataset"]).default("artifact"), accept_storage_charges: z.boolean().default(false).describe("Read get_storage pricing first. Set true only after the user agrees to paid storage above the included allowance.") },
115
+ annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
116
+ }, wrap(async ({ local_path, purpose = "artifact", accept_storage_charges = false }) => {
117
+ const local = path.resolve(expandHome(local_path));
118
+ if (sensitiveReason(local)) return fail("Credential files cannot be saved as artifacts.");
119
+ if ((await fsp.lstat(local)).isSymbolicLink()) return fail("Choose a regular file, not a symlink.");
120
+ return ok(await client.upload(local, purpose, path.basename(local), accept_storage_charges));
121
+ }));
122
+ server.registerTool("download_artifact", {
123
+ title: "Download a persistent file", description: "Streams a persistent file to this computer. Never overwrites an existing local file.",
124
+ inputSchema: { file_id: z.string(), local_path: z.string() }, annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
125
+ }, wrap(async ({ file_id, local_path }) => ok(await client.download(file_id, path.resolve(expandHome(local_path))))));
126
+ server.registerTool("save_workspace", {
127
+ title: "Save a project Workspace", description: "Saves 1–100 regular project files as an immutable version. Refuses secrets and symlinks; skips .git, node_modules, __pycache__ and .venv. Save dependency manifests, not the operating system. Pass the returned workspace_version_id to run_job.",
128
+ inputSchema: { local_dir: z.string(), name: z.string().min(1).max(120), workspace_id: z.string().optional(), accept_storage_charges: z.boolean().default(false).describe("Read get_storage pricing and obtain user agreement before enabling paid storage.") },
129
+ annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
130
+ }, wrap(async ({ local_dir, name, workspace_id, accept_storage_charges = false }) => ok(await client.saveWorkspace(expandHome(local_dir), name, workspace_id, accept_storage_charges))));
131
+ server.registerTool("delete_file", {
132
+ title: "Delete a persistent file", description: "Permanently deletes a persistent file or cancels an unfinished upload. Files pinned by a Workspace version cannot be deleted.",
133
+ inputSchema: { file_id: z.string(), user_confirmed: z.boolean() }, annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
134
+ }, wrap(async ({ file_id, user_confirmed }) => user_confirmed === true ? ok(await api.request("DELETE", `/v1/files/${encodeURIComponent(file_id)}`)) : fail("Ask the user before deleting the file.")));
135
+ }