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 +21 -7
- package/package.json +4 -4
- package/src/api.js +1 -0
- package/src/batch-receipts.js +24 -3
- package/src/cli-core.js +2 -1
- package/src/index.js +13 -4
- package/src/rental-billing.js +8 -0
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=
|
|
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": "
|
|
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": "
|
|
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": "
|
|
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: "
|
|
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
|
|
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
|
|
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.
|
|
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
|
|
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/
|
|
45
|
+
"url": "git+https://github.com/cloudgpu-app/cloudgpu-mcp.git"
|
|
46
46
|
},
|
|
47
47
|
"bugs": {
|
|
48
|
-
"url": "https://github.com/
|
|
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
|
}
|
package/src/batch-receipts.js
CHANGED
|
@@ -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{
|
|
17
|
-
|
|
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
|
|
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
|
-
:
|
|
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.
|
|
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
|
|
234
|
-
const estimate
|
|
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
|
+
}
|