cloudgpu-mcp 0.12.0 → 0.13.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
@@ -25,7 +25,7 @@ For another stdio client, use `command: "npx"` and `args: ["-y", "cloudgpu-mcp"]
25
25
  <summary><b>Claude Code</b></summary>
26
26
 
27
27
  ```bash
28
- claude mcp add cloudgpu --env CLOUDGPU_API_KEY=cgw-sk-... -- npx -y cloudgpu-mcp
28
+ claude mcp add cloudgpu --env CLOUDGPU_API_KEY='<YOUR_API_KEY>' -- npx -y cloudgpu-mcp
29
29
  ```
30
30
  </details>
31
31
 
@@ -38,7 +38,7 @@ claude mcp add cloudgpu --env CLOUDGPU_API_KEY=cgw-sk-... -- npx -y cloudgpu-mcp
38
38
  "cloudgpu": {
39
39
  "command": "npx",
40
40
  "args": ["-y", "cloudgpu-mcp"],
41
- "env": { "CLOUDGPU_API_KEY": "cgw-sk-..." }
41
+ "env": { "CLOUDGPU_API_KEY": "<YOUR_API_KEY>" }
42
42
  }
43
43
  }
44
44
  }
@@ -54,7 +54,7 @@ claude mcp add cloudgpu --env CLOUDGPU_API_KEY=cgw-sk-... -- npx -y cloudgpu-mcp
54
54
  "cloudgpu": {
55
55
  "command": "npx",
56
56
  "args": ["-y", "cloudgpu-mcp"],
57
- "env": { "CLOUDGPU_API_KEY": "cgw-sk-..." }
57
+ "env": { "CLOUDGPU_API_KEY": "<YOUR_API_KEY>" }
58
58
  }
59
59
  }
60
60
  }
@@ -71,7 +71,7 @@ claude mcp add cloudgpu --env CLOUDGPU_API_KEY=cgw-sk-... -- npx -y cloudgpu-mcp
71
71
  "cloudgpu": {
72
72
  "type": "local",
73
73
  "command": ["npx", "-y", "cloudgpu-mcp"],
74
- "environment": { "CLOUDGPU_API_KEY": "cgw-sk-..." },
74
+ "environment": { "CLOUDGPU_API_KEY": "<YOUR_API_KEY>" },
75
75
  "enabled": true
76
76
  }
77
77
  }
@@ -90,7 +90,7 @@ extensions:
90
90
  cmd: npx
91
91
  args: ["-y", "cloudgpu-mcp"]
92
92
  envs:
93
- CLOUDGPU_API_KEY: "cgw-sk-..."
93
+ CLOUDGPU_API_KEY: "<YOUR_API_KEY>"
94
94
  enabled: true
95
95
  timeout: 300
96
96
  ```
@@ -110,16 +110,22 @@ The same guidance is available as two [Agent Skills](https://agentskills.io):
110
110
  - **Claude plugin:** both skills are included automatically when you install the CloudGPU Claude plugin from this repo's marketplace:
111
111
 
112
112
  ```
113
- /plugin marketplace add mrhy7176/cloudgpu-mcp
113
+ /plugin marketplace add cloudgpu-app/cloudgpu-mcp
114
114
  /plugin install cloudgpu@cloudgpu
115
115
  ```
116
116
 
117
+ - **Codex plugin:** the same repository is an Agent Plugins package (`plugin.json`, `mcp.json`, and `skills/`). Codex shows it as CloudGPU. The server reads `CLOUDGPU_API_KEY` from the environment.
118
+
119
+ ```
120
+ codex plugin marketplace add cloudgpu-app/cloudgpu-mcp
121
+ ```
122
+
117
123
  - **Claude Code, personal install:** copy `skills/cloudgpu/` and `skills/cloudgpu-model-api/` to `~/.claude/skills/`.
118
124
  - **Claude Code, project install:** copy `skills/cloudgpu/` and `skills/cloudgpu-model-api/` to `.claude/skills/` in your project.
119
125
  - **Cursor, Codex, Cline, Amp and other agents that read Agent Skills:** install both skills with the [skills CLI](https://skills.sh):
120
126
 
121
127
  ```
122
- npx skills add mrhy7176/cloudgpu-mcp
128
+ npx skills add cloudgpu-app/cloudgpu-mcp
123
129
  ```
124
130
 
125
131
  ## Tools
@@ -352,3 +358,11 @@ This is client-local receipt durability, not a server-side batch coordinator. Un
352
358
  Keep the exact original manifest outside the receipt store. Expired quotes for unsubmitted members may require reconciliation followed by a newly reviewed plan for the remaining work; do not overwrite the old ledger or regenerate keys merely to bypass expiry. Terminal status without final cost evidence also stops a journaled resume.
353
359
 
354
360
  One in-flight batch retains its original API credential and endpoint even if another tool connects a different account concurrently. `not_submitted` in a returned call receipt means unvisited **in that invocation only**; those entries may have accepted Jobs from an earlier call. Inspect the saved receipt and live Job IDs before deciding what remains.
361
+
362
+ Use 0.12.1 or newer for directory-entry durability: newly created config/receipt directories and their parent entries are synced before paid submission. A parent-directory sync failure refuses new batch work. Existing 0.12.0 receipt records remain readable; preserve their IDs and original keys rather than deleting them. Process-exit tests alone do not constitute physical power-loss testing.
363
+
364
+ ### Rental billing quotes (0.13.0)
365
+
366
+ `estimate_cost` obtains a short-lived server billing quote and reports the minimum charge, billing increment and preauthorization. Most sources charge by the minute. A whole-hour source starts billing at resource allocation, has a one-hour minimum and charges each started hour in full; voluntary stop does not refund unused time inside that hour. Show these terms and the estimate before requesting the user’s approval. `rent_gpu` submits the same approved billing quote; expired quotes require a new estimate and approval. Do not infer billing periods from the GPU model or hourly price.
367
+
368
+ Upgrade your installed `cloudgpu-mcp` package and restart the MCP client to load the new tools. This update does not restart existing GPUs.
package/package.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "name": "cloudgpu-mcp",
3
- "version": "0.12.0",
3
+ "version": "0.13.0",
4
4
  "mcpName": "io.github.mrhy7176/cloudgpu-mcp",
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.",
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 with explicit billing quotes, run a job, fetch the results and shut it down, with spending limits the platform enforces.",
6
6
  "type": "module",
7
7
  "bin": {
8
8
  "cloudgpu-mcp": "src/index.js",
@@ -42,10 +42,10 @@
42
42
  "homepage": "https://cloudgpu.app/docs/mcp",
43
43
  "repository": {
44
44
  "type": "git",
45
- "url": "git+https://github.com/mrhy7176/cloudgpu-mcp.git"
45
+ "url": "git+https://github.com/cloudgpu-app/cloudgpu-mcp.git"
46
46
  },
47
47
  "bugs": {
48
- "url": "https://github.com/mrhy7176/cloudgpu-mcp/issues"
48
+ "url": "https://github.com/cloudgpu-app/cloudgpu-mcp/issues"
49
49
  },
50
50
  "license": "MIT",
51
51
  "author": "CloudGPU <support@cloudgpu.app>",
package/src/api.js CHANGED
@@ -91,6 +91,7 @@ export class CloudGpuApi {
91
91
  instance(id) {
92
92
  return this.request("GET", `/v1/gpu/instances/${encodeURIComponent(id)}`);
93
93
  }
94
+ rentalBillingQuote(body) { return this.request("POST", "/v1/gpu/billing-quote", body); }
94
95
  create(body) {
95
96
  return this.request("POST", "/v1/gpu/instances", body);
96
97
  }
@@ -12,10 +12,31 @@ const meta=z.object({version:z.literal(1),plan_sha256:z.string().regex(/^[a-f0-9
12
12
  const intent=z.object({version:z.literal(1),index:z.number().int().min(0).max(7),idempotency_key:key}).strict();
13
13
  const accepted=intent.extend({job_id:z.string().regex(/^job_[a-f0-9]{32}$/),status_at_acceptance:states}).strict();
14
14
  const safeError=()=>new Error('Local batch receipt is unavailable or inconsistent. No replacement key or GPU may be created; retain the original manifest and reconcile existing Jobs.');
15
+ async function syncDirectory(p){
16
+ const f=await fs.open(p,constants.O_RDONLY|constants.O_DIRECTORY|constants.O_NOFOLLOW);
17
+ try{await f.sync();}finally{await f.close();}
18
+ }
19
+ // 目录项属于父目录;先同步父目录,才能在付费提交前确认新树已持久化。
15
20
  async function directory(p,create=false){
16
- try{const s=await fs.lstat(p);if(s.isSymbolicLink()||!s.isDirectory()||(s.mode&0o077)!==0||(process.getuid&&s.uid!==process.getuid()))throw safeError();}
17
- catch(e){if(e.code!=='ENOENT'||!create)throw e;await fs.mkdir(p,{mode:0o700}).catch(e=>{if(e.code!=='EEXIST')throw e;});return directory(p);}
21
+ try{
22
+ const s=await fs.lstat(p);if(s.isSymbolicLink()||!s.isDirectory()||(s.mode&0o077)!==0||(process.getuid&&s.uid!==process.getuid()))throw safeError();
23
+ }catch(e){
24
+ if(e.code!=='ENOENT'||!create)throw e;
25
+ await fs.mkdir(p,{mode:0o700}).catch(e=>{if(e.code!=='EEXIST')throw e;});
26
+ await directory(p,false);
27
+ }
28
+ if(create)await syncDirectory(path.dirname(p));
18
29
  }
30
+ async function configRoot(p){
31
+ try{if(!(await fs.stat(p)).isDirectory())throw safeError();}
32
+ catch(e){
33
+ if(e.code!=='ENOENT')throw e;
34
+ const parent=path.dirname(p);if(parent===p)throw safeError();await configRoot(parent);
35
+ await fs.mkdir(p,{mode:0o700}).catch(e=>{if(e.code!=='EEXIST')throw e;});
36
+ }
37
+ await syncDirectory(path.dirname(p));
38
+ }
39
+
19
40
  async function read(p,schema){
20
41
  let f;try{f=await fs.open(p,constants.O_RDONLY|constants.O_NOFOLLOW);const s=await f.stat();if(!s.isFile()||s.size>8192||(s.mode&0o077)!==0||(process.getuid&&s.uid!==process.getuid()))throw safeError();return schema.parse(JSON.parse(await f.readFile('utf8')));}
21
42
  catch(e){if(e.code==='ENOENT')return null;throw safeError();}finally{await f?.close();}
@@ -38,7 +59,7 @@ export class BatchReceipts{
38
59
  if(!this.apiKey)throw Error('Connect the original scoped account before reading or submitting a batch receipt. Never paste the key into chat.');
39
60
  if(!/^[A-Za-z0-9_-]{1,80}$/.test(batchKey))throw Error('Invalid batch key');
40
61
  // 配置目录由用户选择;回执树及下级目录必须为当前用户私有,拒绝符号链接。
41
- if(create)await fs.mkdir(this.root,{recursive:true,mode:0o700}).catch(()=>{throw safeError();});
62
+ if(create)await configRoot(path.resolve(this.root)).catch(()=>{throw safeError();});
42
63
  const base=path.join(this.root,'batch-receipts-v1');
43
64
  try{await directory(base,create);}catch(e){if(e.code==='ENOENT')return null;throw safeError();}
44
65
  const scope=path.join(base,this.scope);
package/src/cli-core.js CHANGED
@@ -333,6 +333,7 @@ function limitsText(l) {
333
333
  }
334
334
 
335
335
  export function instanceDetails(inst, { showPassword = false } = {}) {
336
+ const concealed = "(hidden; add --show-password to print it)";
336
337
  const rows = [
337
338
  ["ID", inst.id],
338
339
  ["Status", inst.status],
@@ -350,7 +351,7 @@ export function instanceDetails(inst, { showPassword = false } = {}) {
350
351
  inst.status === "running" && inst.ssh && inst.ssh.password
351
352
  ? showPassword
352
353
  ? inst.ssh.password
353
- : "(hidden; add --show-password to print it)"
354
+ : concealed
354
355
  : null,
355
356
  ],
356
357
  ["URL", inst.api_url || null],
package/src/index.js CHANGED
@@ -1,4 +1,5 @@
1
1
  #!/usr/bin/env node
2
+ import {rentalBilling} from "./rental-billing.js";
2
3
  import {registerBatchTools} from './job-batches.js';
3
4
  import {jobInputShape} from './job-input.js';
4
5
  import {registerTaskTemplateTools} from './task-templates.js';
@@ -35,7 +36,7 @@ import {
35
36
  shq,
36
37
  } from "./guards.js";
37
38
 
38
- const VERSION = "0.12.0";
39
+ const VERSION = "0.13.0";
39
40
  const HERE = path.dirname(fileURLToPath(import.meta.url));
40
41
  const RULES = fs.readFileSync(path.join(HERE, "..", "rules", "cloudgpu.md"), "utf8");
41
42
 
@@ -230,8 +231,8 @@ server.registerTool(
230
231
  if (gpu_count < (offer.min_gpu_count || 1)) {
231
232
  return fail(`${offer.gpu_model} is rented in groups of at least ${offer.min_gpu_count} GPUs.`);
232
233
  }
233
- const hourly = round2(Number(offer.hourly_usd) * gpu_count);
234
- const estimate = round2(hourly * hours);
234
+ const billing = await api.rentalBillingQuote({gpuModel:offer.gpu_model,gpuCount:gpu_count,...(template?{templateId:template}:{})});
235
+ const {hourly,increment,estimate}=rentalBilling(billing,hours);
235
236
  const balance = account ? Number(account.balance_usd) : null;
236
237
  const warnings = [];
237
238
  if (offer.available === "none") warnings.push("This GPU is out of stock right now; renting will likely fail. Pick another.");
@@ -241,13 +242,17 @@ server.registerTool(
241
242
  `Balance $${balance} does not cover the estimate plus a 10% buffer. When the balance runs out the instance is destroyed and its disk erased. Top up at https://cloudgpu.app/billing.`,
242
243
  );
243
244
  }
244
- const quote_id = quotes.put({ gpu_model: offer.gpu_model, gpu_count, template, hourly, hours, estimate });
245
+ const quote_id = quotes.put({ gpu_model: offer.gpu_model, gpu_count, template, hourly, hours, estimate, billingQuoteId:billing.billingQuoteId, billingExpiresAt:billing.expiresAt, minimumChargeUsd:Number(billing.minimumChargeUsd), billingIncrementSeconds:increment });
245
246
  return ok({
246
247
  quote_id,
247
248
  gpu_model: offer.gpu_model,
248
249
  gpu_count,
249
250
  template: template || null,
250
251
  usd_per_hour: hourly,
252
+ billing_increment_seconds:increment,
253
+ minimum_charge_usd:Number(billing.minimumChargeUsd),
254
+ preauthorized_usd:Number(billing.preauthorizedUsd),
255
+ billing_description:increment===3600?"Billing starts at resource allocation. Minimum one hour; each started hour is charged in full. Unused time within a charged hour is not refunded on voluntary stop.":"Billed per minute, one-minute minimum; unused prepaid minutes are refunded on destroy.",
251
256
  hours,
252
257
  estimated_cost_usd: estimate,
253
258
  balance_usd: balance,
@@ -464,6 +469,8 @@ if (!cfg.readOnly) {
464
469
  if (idle_minutes > 0 && idle_minutes < 10) return fail("idle_minutes must be 0 (off) or at least 10.");
465
470
  const { quote, error } = quotes.take(quote_id);
466
471
  if (error) return fail(error);
472
+ if(!quote.billingQuoteId || quote.billingExpiresAt<=Date.now())return fail("Billing quote expired. Request estimate_cost again and ask the user to approve it.");
473
+ if(max_spend_usd<quote.minimumChargeUsd)return fail("Budget is below the minimum charge shown in the approved quote.");
467
474
  const account = await api.account();
468
475
  const balance = Number(account.balance_usd);
469
476
  const needed = round2(Math.min(max_spend_usd, quote.estimate) * 1.1);
@@ -473,6 +480,8 @@ if (!cfg.readOnly) {
473
480
  );
474
481
  }
475
482
  const body = {
483
+ billing_quote_id:quote.billingQuoteId,
484
+ billing_accepted:true,
476
485
  gpu_model: quote.gpu_model,
477
486
  gpu_count: quote.gpu_count,
478
487
  max_minutes: Math.ceil(max_hours * 60),
@@ -0,0 +1,8 @@
1
+ // 验证服务端的计费契约,不从小时单价猜测最低收费。
2
+ export function rentalBilling(b,hours,now=Date.now()){
3
+ if(!b||!['number','string'].includes(typeof b.hourlyTotalUsd)||![60,3600].includes(b.incrementSeconds)||b.minimumSeconds!==b.incrementSeconds||b.currency!=='USD'||typeof b.billingQuoteId!=='string'||!b.billingQuoteId||!Number.isFinite(b.expiresAt)||b.expiresAt<=now||!Number.isFinite(hours)||hours<=0)throw new Error('A current server billing quote is required before renting.');
4
+ const rate=Number(b.hourlyTotalUsd),minimum=Number(b.minimumChargeUsd),prepaid=Number(b.preauthorizedUsd);
5
+ if(!Number.isFinite(rate)||rate<=0||!Number.isFinite(minimum)||minimum<=0||!Number.isFinite(prepaid)||prepaid<minimum||Math.abs(minimum-rate*b.incrementSeconds/3600)>0.0000001)throw new Error('Invalid rental billing amounts.');
6
+ const billedSeconds=Math.max(b.incrementSeconds,Math.ceil(hours*3600/b.incrementSeconds)*b.incrementSeconds);
7
+ return {hourly:rate,increment:b.incrementSeconds,estimate:Math.ceil(rate*billedSeconds/3600*10000-1e-9)/10000,minimum,prepaid};
8
+ }