cloudgpu-mcp 0.16.2 → 0.16.3
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 +9 -1
- package/package.json +1 -1
- package/src/api.js +13 -0
- package/src/index.js +5 -3
- package/src/job-batches.js +20 -0
- package/src/job-input.js +2 -0
package/README.md
CHANGED
|
@@ -396,7 +396,7 @@ With `persist_summary=true`, the Job draft explicitly collects only `pipeline-su
|
|
|
396
396
|
|
|
397
397
|
### Funded connection, storage growth and remote MCP
|
|
398
398
|
|
|
399
|
-
Version 0.16.0 was verified on npm and the official Registry on 2026-11-13. The current stdio inventory is
|
|
399
|
+
Version 0.16.0 was verified on npm and the official Registry on 2026-11-13. The current stdio inventory is 57 tools. The remote endpoint at `https://cloudgpu.app/mcp` uses Streamable HTTP JSON responses and OAuth authorization code with S256 PKCE; it exposes 23 tools safe without local filesystem/SSH access. Public discovery needs no login; account and paid operations require scoped owner authorization. Always check live backend capabilities and actual source-specific billing.
|
|
400
400
|
|
|
401
401
|
`connect_account` returns a direct Google link and email alternative. Pending connection state is private, origin-bound and survives restart; the server allows 30 minutes for approval. Browser payment does not approve compute. `request_top_up` creates only a short-lived owner link; `wait_for_funds` requires a real credit signal and sufficient live balance. Neither creates a Job.
|
|
402
402
|
|
|
@@ -411,3 +411,11 @@ The reviewed [Python SDK0.1.0 release](https://github.com/cloudgpu-app/cloudgpu-
|
|
|
411
411
|
### Reproducible paid task cases
|
|
412
412
|
|
|
413
413
|
See [environment check, synthetic causal-LM LoRA and tiny ComfyUI video cases](examples/verified-tasks/README.md) for pinned scripts, observed fees, download checksums and release evidence. They preview locally by default; paid submission needs owner approval. Resume an accepted Job by ID to download results without another GPU. For persistent tasks, `assess_task_fit` accepts `expected_output_bytes`; current direct collection and bounded network fallback limits are returned by the live contract.
|
|
414
|
+
|
|
415
|
+
### Durable server batches and whole-hour Jobs (0.16.3)
|
|
416
|
+
|
|
417
|
+
Use `prepare_job_batch` to review every command, fresh compute quote, deadline and aggregate GPU cap. Pass the exact manifest/hash and explicit user approval to `run_server_job_batch`. The server atomically commits all child Job rows or none; it dispatches from the database after client/server restarts, waiting for account/Key execution slots. `get_server_job_batch(batch_id)` returns bounded states/cost summaries; use individual `get_job` for detailed outputs. `cancel_server_job_batch` requires approval and preserves charges for already-started hours. Failed commands are not automatically rerun, and an uncertain provider result never authorizes another GPU.
|
|
418
|
+
|
|
419
|
+
REST equivalents: `POST /v1/job-batches` with `Idempotency-Key`, `total_budget_usd` and 1–32 `jobs`; `GET /v1/job-batches/{batch_id}`; `POST /v1/job-batches/{batch_id}/cancel`. The MCP reviewed manifest remains capped at eight children. Replaying the identical key/body returns the existing children. Existing `run_job_batch` retains its explicitly non-atomic client submission behavior for compatibility; the server tool never falls back to it.
|
|
420
|
+
|
|
421
|
+
For whole-hour Jobs, call `estimate_cost` for the exact configuration and accept the minimum/billing period. Supply its `billing_quote_id` plus `billing_accepted=true` to `run_job` or each batch child, in addition to the compute `quote_id` and execution approval. Each allocation needs a separate current billing quote. The Job cap must cover the minimum; elapsed portions of a started hour are not voluntarily refunded. Billing quotes last five minutes: an expired queued Job fails without allocation and requires a new reviewed request. It is never silently renewed or routed under different billing terms. Recovery uses durable provider receipts and independent upstream presence checks; ambiguous intents remain `needs_attention`.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "cloudgpu-mcp",
|
|
3
|
-
"version": "0.16.
|
|
3
|
+
"version": "0.16.3",
|
|
4
4
|
"mcpName": "io.github.cloudgpu-app/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 with explicit billing quotes, 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
|
@@ -111,6 +111,19 @@ export class CloudGpuApi {
|
|
|
111
111
|
if (body.model_references?.length) return this.createModelJob(body,idempotencyKey);
|
|
112
112
|
return this.request("POST", "/v1/jobs", body, { idempotencyKey });
|
|
113
113
|
}
|
|
114
|
+
async createServerJobBatch(body,idempotencyKey) {
|
|
115
|
+
if(!idempotencyKey)throw new Error("Server batch requires a stable idempotency key");
|
|
116
|
+
const readiness=await this.request("GET","/v1/public/agent-self-check",undefined,{noAuth:true});
|
|
117
|
+
if(readiness.durable_batch?.enabled!==true)throw new ApiError(503,"durable_batch_unavailable","Durable batch is unavailable; no client-side submission fallback was attempted.");
|
|
118
|
+
if(body.jobs.some(j=>j.outputs||j.model_references?.length)){
|
|
119
|
+
const caps=await this.request("GET","/v1/public/compute-capabilities",undefined,{noAuth:true});
|
|
120
|
+
if(body.jobs.some(j=>j.outputs)&&(caps.automatic_output_collection!==true||caps.storage!==true))throw new ApiError(503,"outputs_unavailable","Output persistence unavailable; no batch submitted.");
|
|
121
|
+
if(body.jobs.some(j=>j.model_references?.length)&&caps.model_references!==true)throw new ApiError(503,"model_references_unavailable","Pinned model loading unavailable; no batch submitted.");
|
|
122
|
+
}
|
|
123
|
+
return this.request("POST","/v1/job-batches",body,{idempotencyKey});
|
|
124
|
+
}
|
|
125
|
+
serverJobBatch(id) {if(!/^[a-f0-9]{32}$/.test(id))throw Error("Invalid server batch id");return this.request("GET",`/v1/job-batches/${id}`);}
|
|
126
|
+
cancelServerJobBatch(id) {if(!/^[a-f0-9]{32}$/.test(id))throw Error("Invalid server batch id");return this.request("POST",`/v1/job-batches/${id}/cancel`,{});}
|
|
114
127
|
async createOutputJob(body,idempotencyKey) {
|
|
115
128
|
const caps=await this.request("GET","/v1/public/compute-capabilities",undefined,{noAuth:true});
|
|
116
129
|
if(caps.automatic_output_collection!==true || caps.storage!==true)
|
package/src/index.js
CHANGED
|
@@ -40,7 +40,7 @@ import {
|
|
|
40
40
|
shq,
|
|
41
41
|
} from "./guards.js";
|
|
42
42
|
|
|
43
|
-
const VERSION = "0.16.
|
|
43
|
+
const VERSION = "0.16.3";
|
|
44
44
|
const HERE = path.dirname(fileURLToPath(import.meta.url));
|
|
45
45
|
const RULES = fs.readFileSync(path.join(HERE, "..", "rules", "cloudgpu.md"), "utf8");
|
|
46
46
|
|
|
@@ -67,7 +67,8 @@ const session = new Map();
|
|
|
67
67
|
|
|
68
68
|
const INSTRUCTIONS = `CloudGPU (cloudgpu.app) provides GPU compute scheduling for AI agents from a prepaid balance. Billing is source-specific: per-minute or minimum one hour with each started hour charged in full. Never infer the period from an hourly price label.
|
|
69
69
|
Planning: compare_compute_costs compares billed GPU cost for explicit candidates and duration; it is not a benchmark or creation approval. Check existing list_instances before renting: multiple approved commands can use the same running rental within its existing budget, time and idle limits. Separate run_job calls each provision and release independently; prepare_job_rerun does not reuse a live GPU. Never extend limits or keep idle GPUs merely to consume prepaid time.
|
|
70
|
-
|
|
70
|
+
Server batches: prepare_job_batch also prepares the exact manifest for run_server_job_batch. The new tool atomically enqueues on the server, persists across client/server restarts, and requires an aggregate cap and individually approved billing. Use get_server_job_batch/cancel_server_job_batch; never substitute client partial submission when unavailable. No automatic failed-command retries.
|
|
71
|
+
Legacy client batches: prepare_job_batch reviews up to eight individually quoted Jobs and their combined GPU budget. run_job_batch requires an exact approved plan hash; partial submission is possible. Retain the manifest and stable batch key to reconcile lost responses. No automatic execution retries; get_job_batch never proves independent supplier release. Storage charges are additional to GPU caps.
|
|
71
72
|
Shared allocation: prepare_task_pipeline prepares 1–8 reviewed sequential commands as a single Job draft, or for an approved existing rental. It creates nothing. Independent run_job calls do not share a GPU. Pipeline summary persistence is explicit and does not save arbitrary results or authorize storage charges.
|
|
72
73
|
Task recipes: list_task_templates and prepare_task_template return local read-only drafts, never a paid submission. Check prerequisites, quote and obtain explicit approval before run_job. Prefer local CPU processing when a GPU is unnecessary.
|
|
73
74
|
Workflow: get_account and list_gpus -> estimate_cost -> show the quote to the user and get an explicit yes -> create_instance -> get_status until running -> upload -> run_command (background for long jobs) -> tail_logs -> download results -> stop_instance -> report the actual cost.
|
|
@@ -539,7 +540,7 @@ if (!cfg.readOnly) {
|
|
|
539
540
|
inputSchema: jobInputShape(cfg),
|
|
540
541
|
annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
|
|
541
542
|
},
|
|
542
|
-
wrap(async ({ command, gpu_model, template, gpu_count = 1, disk_gb, workspace_version_id, model_references, outputs, quote_id, max_spend_usd, max_hours, user_confirmed, idempotency_key }) => {
|
|
543
|
+
wrap(async ({ command, gpu_model, template, gpu_count = 1, disk_gb, workspace_version_id, model_references, outputs, quote_id, billing_quote_id, billing_accepted, max_spend_usd, max_hours, user_confirmed, idempotency_key }) => {
|
|
543
544
|
if (user_confirmed !== true) {
|
|
544
545
|
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.");
|
|
545
546
|
}
|
|
@@ -561,6 +562,7 @@ if (!cfg.readOnly) {
|
|
|
561
562
|
if (outputs) body.outputs = outputs;
|
|
562
563
|
if (model_references?.length) body.model_references = model_references;
|
|
563
564
|
if (quote_id) body.quote_id = quote_id;
|
|
565
|
+
if (billing_quote_id) {if(billing_accepted!==true)return fail("Not started: accept the source-specific minimum charge and billing period first.");body.billing_quote_id=billing_quote_id;body.billing_accepted=true;}
|
|
564
566
|
const job = await api.createJob(body, key);
|
|
565
567
|
return ok({
|
|
566
568
|
...job,
|
package/src/job-batches.js
CHANGED
|
@@ -68,12 +68,32 @@ export async function getJobBatch(api,ids){
|
|
|
68
68
|
for(const id of ids){try{const j=await api.job(id);if(j.id!==id||!['queued','provisioning','running','stopping','needs_attention','succeeded','failed','cancelled'].includes(j.status))throw Error('Unrecognized Job response');items.push({job_id:id,status:j.status,cost_usd:j.cost_usd??null,cost_status:j.cost_status??null,automatic_retry_allowed:false,release_risk:j.status==='needs_attention'||j.status==='stopping'});}catch{items.push({job_id:id,status:'unavailable',automatic_retry_allowed:false,release_risk:true});}}
|
|
69
69
|
return {items,all_terminal:items.every(j=>['succeeded','failed','cancelled'].includes(j.status)),requires_reconciliation:items.some(j=>j.release_risk),automatic_retry_allowed:false,note:'Status and costs come from the existing Job API. Terminal state is not an independent supplier audit; stopping, needs_attention or unavailable must never trigger a new GPU.'};
|
|
70
70
|
}
|
|
71
|
+
export async function submitServerJobBatch(api,raw,cfg){
|
|
72
|
+
if(api instanceof CloudGpuApi)api=new CloudGpuApi({apiKey:api.apiKey,baseUrl:api.baseUrl,fetchImpl:api.fetch,userAgent:api.userAgent});
|
|
73
|
+
const {approved_plan_sha256,user_confirmed,...input}=raw;
|
|
74
|
+
if(user_confirmed!==true)throw Error('Approve every command, billing period and the aggregate budget first');
|
|
75
|
+
const plan=prepareJobBatch(input,cfg);
|
|
76
|
+
if(approved_plan_sha256!==plan.plan_sha256)throw Error('Approved batch manifest changed');
|
|
77
|
+
const quoteIds=new Set();
|
|
78
|
+
for(const item of plan.items)if(item.body.billing_quote_id){
|
|
79
|
+
if(item.body.billing_accepted!==true)throw Error('Accept the exact source billing period and minimum first');
|
|
80
|
+
if(quoteIds.has(item.body.billing_quote_id))throw Error('Each hourly allocation requires its own accepted billing quote');quoteIds.add(item.body.billing_quote_id);
|
|
81
|
+
}
|
|
82
|
+
const result=await api.createServerJobBatch({total_budget_usd:plan.total_budget_usd,jobs:plan.items.map(i=>i.body)},'server-batch:'+plan.batch_key);
|
|
83
|
+
if(!/^[a-f0-9]{32}$/.test(result?.batch_id)||result.durable!==true||!Array.isArray(result.jobs)||result.jobs.length!==plan.items.length||result.jobs.some(j=>!/^job_[a-f0-9]{32}$/.test(j.id)))
|
|
84
|
+
throw Error('Unrecognized batch receipt; reconcile with the identical manifest/key before retrying');
|
|
85
|
+
return {...result,batch_key:plan.batch_key,plan_sha256:plan.plan_sha256,atomic_enqueue:true,automatic_command_retries:false,next:'Use get_server_job_batch. Never replace an uncertain or failed task automatically; the same approved key replays this batch.'};
|
|
86
|
+
}
|
|
87
|
+
|
|
71
88
|
export function registerBatchTools(server,{api,cfg,wrap,ok}){
|
|
72
89
|
const input=schema(cfg);
|
|
73
90
|
const receipts=()=>new BatchReceipts({apiKey:'apiKey' in api?api.apiKey:cfg.apiKey,baseUrl:api.baseUrl||cfg.baseUrl});
|
|
74
91
|
server.registerTool('get_job_batch_receipt',{title:'Read a private local batch receipt',description:'Read only saved accepted Job IDs and uncertain submission intents for the original batch key, API key and endpoint. No API request or GPU creation. Local state is historical, not live release evidence; a missing entry does not prove non-creation. Commands, tokens and signed URLs are never stored.',inputSchema:{batch_key:z.string().min(1).max(80).regex(/^[A-Za-z0-9_-]+$/)},annotations:{readOnlyHint:true,destructiveHint:false,idempotentHint:true,openWorldHint:false}},wrap(async({batch_key})=>ok(await receipts().snapshot(batch_key))));
|
|
75
92
|
server.registerTool('prepare_job_batch',{title:'Review a bounded Job batch',description:'Local, read-only preparation for up to eight Jobs with fresh per-Job quotes and one aggregate cap. No API requests, reservations, installations or automatic execution retries. Retain the immutable plan hash and batch key.',inputSchema:input.shape,annotations:{readOnlyHint:true,destructiveHint:false,idempotentHint:true,openWorldHint:false}},wrap(async p=>ok(prepareJobBatch(p,cfg))));
|
|
76
93
|
server.registerTool('get_job_batch',{title:'Inspect a Job batch',description:'Read-only status and cost summary for explicit Job IDs. Does not retry, cancel, create or claim independent supplier release verification.',inputSchema:{job_ids:z.array(z.string().regex(/^job_[a-f0-9]{32}$/)).min(1).max(8)},annotations:{readOnlyHint:true,destructiveHint:false,idempotentHint:true,openWorldHint:true}},wrap(async({job_ids})=>ok(await getJobBatch(api,job_ids))));
|
|
94
|
+
server.registerTool('get_server_job_batch',{title:'Read a durable server batch',description:'Read persisted child Job states and costs after either client or server restarts. Does not create or retry resources.',inputSchema:{batch_id:z.string().regex(/^[a-f0-9]{32}$/)},annotations:{readOnlyHint:true,destructiveHint:false,idempotentHint:true,openWorldHint:true}},wrap(async({batch_id})=>ok(await api.serverJobBatch(batch_id))));
|
|
77
95
|
if(cfg.readOnly)return;
|
|
96
|
+
server.registerTool('run_server_job_batch',{title:'Atomically enqueue an approved server batch',description:'Paid. Use the exact reviewed prepare_job_batch manifest/hash. Enqueue is atomic and persists on the server; each Job reserves its own budget and waits for account/key concurrency. No automatic command retries and no partial client-side fallback. Whole-hour Jobs require a separate accepted current billing quote per allocation.',inputSchema:{...input.shape,approved_plan_sha256:z.string().regex(/^[a-f0-9]{64}$/),user_confirmed:z.boolean()},annotations:{readOnlyHint:false,destructiveHint:true,idempotentHint:true,openWorldHint:true}},wrap(async p=>ok(await submitServerJobBatch(api,p,cfg))));
|
|
97
|
+
server.registerTool('cancel_server_job_batch',{title:'Cancel a server batch',description:'Cancel queued children without starting a GPU; request safe shutdown of active children. Preserve outputs first. Previously started whole-hour charges remain payable.',inputSchema:{batch_id:z.string().regex(/^[a-f0-9]{32}$/),user_confirmed:z.boolean()},annotations:{readOnlyHint:false,destructiveHint:true,idempotentHint:true,openWorldHint:true}},wrap(async({batch_id,user_confirmed})=>{if(user_confirmed!==true)throw Error('Confirm output preservation and cancellation first');return ok(await api.cancelServerJobBatch(batch_id));}));
|
|
78
98
|
server.registerTool('run_job_batch',{title:'Submit an approved bounded Job batch',description:'Paid: submit an explicitly approved immutable manifest using existing durable Jobs, each with a quote, budget and deadline. Aggregate worst-case budget is capped. Partial success is possible. On lost responses replay the IDENTICAL manifest/key; never create replacement GPUs or retry failed execution automatically. Persist the returned receipt. No transaction rollback or independent batch scheduler.',inputSchema:{...input.shape,approved_plan_sha256:z.string().regex(/^[a-f0-9]{64}$/),user_confirmed:z.boolean()},annotations:{readOnlyHint:false,destructiveHint:true,idempotentHint:true,openWorldHint:true}},wrap(async p=>ok(await submitJobBatch(api,p,cfg,receipts()))));
|
|
79
99
|
}
|
package/src/job-input.js
CHANGED
|
@@ -14,6 +14,8 @@ export function jobInputShape(cfg){return {
|
|
|
14
14
|
accept_storage_charges: z.boolean().optional(),
|
|
15
15
|
}).strict().optional().describe("Explicit relative output files under $CLOUDGPU_OUTPUT_DIR; no globs, symlinks, hidden or credential files. Default total limit 10 MiB, maximum 100 MiB. Only set accept_storage_charges=true after the user agrees to existing paid storage terms. Inspect output_collection after completion; the GPU is released even if saving fails."),
|
|
16
16
|
quote_id: z.string().optional().describe("Server quote from quote_compute, starting quote_; binds configuration and checks price at submission"),
|
|
17
|
+
billing_quote_id: z.string().regex(/^[a-f0-9-]{36}$/).optional().describe("Accepted source-specific billing quote from estimate_cost; expires after five minutes. Required for whole-hour sources."),
|
|
18
|
+
billing_accepted: z.boolean().optional().describe("true only after the user accepts the quoted minimum and billing period; budget must cover that minimum"),
|
|
17
19
|
max_spend_usd: z.number().positive().describe(`Budget for this job in USD (at most ${cfg.maxSpend})`),
|
|
18
20
|
max_hours: z.number().positive().describe(`Hard time limit in hours (at most ${cfg.maxHours})`),
|
|
19
21
|
user_confirmed: z.boolean().describe("true only if the user explicitly approved the GPU, budget and time limit"),
|