cloudgpu-mcp 0.13.0 → 0.14.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 +15 -2
- package/package.json +2 -2
- package/rules/cloudgpu.md +8 -3
- package/src/compute-planning.js +39 -0
- package/src/index.js +6 -3
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# CloudGPU MCP
|
|
2
2
|
|
|
3
|
-
[CloudGPU](https://cloudgpu.app) MCP server: let an AI agent
|
|
3
|
+
[CloudGPU](https://cloudgpu.app) MCP server: let an AI agent compare GPU compute costs, approve source-specific billing, run a job, bring the results back and shut the GPU down. The same API key and balance also cover CloudGPU's OpenAI-compatible model API, so an agent can call a hosted model without renting anything.
|
|
4
4
|
|
|
5
5
|
> "Fine-tune a 7B base model with LoRA on data/train.jsonl and put the adapter in ./outputs."
|
|
6
6
|
|
|
@@ -135,6 +135,7 @@ The same guidance is available as two [Agent Skills](https://agentskills.io):
|
|
|
135
135
|
| `get_account` | Balance, and how many instances the account may run at once |
|
|
136
136
|
| `list_gpus` | GPU models with VRAM, live price per GPU-hour and availability |
|
|
137
137
|
| `list_templates` | Ready-made images: JupyterLab, Ollama, ComfyUI, LLaMA-Factory, … |
|
|
138
|
+
| `compare_compute_costs` | Compare live total billed GPU cost for up to eight compatible candidates; no reservation or creation approval |
|
|
138
139
|
| `estimate_cost` | Live quote for a GPU and a number of hours, plus your balance afterwards; returns a `quote_id` |
|
|
139
140
|
| `create_instance` | Rents from an approved quote, with a budget, a time limit and an idle limit |
|
|
140
141
|
| `get_status` / `list_instances` | Status, minutes run, cost so far, auto-shutdown limits |
|
|
@@ -254,7 +255,7 @@ cloudgpu down <id> # destroys it and stops billing (asks first; --
|
|
|
254
255
|
- Model API and prices: https://cloudgpu.app/api
|
|
255
256
|
- API reference: https://cloudgpu.app/api/docs · OpenAPI: https://cloudgpu.app/openapi.json · For LLMs: https://cloudgpu.app/llms.txt
|
|
256
257
|
|
|
257
|
-
CloudGPU here means cloudgpu.app. Prepaid balance,
|
|
258
|
+
CloudGPU here means cloudgpu.app. Prepaid balance, source-specific minute or started-hour billing; when the balance runs out, running instances are destroyed and their disks erased, so keep enough balance for the job and download results as you go.
|
|
258
259
|
|
|
259
260
|
## Development
|
|
260
261
|
|
|
@@ -366,3 +367,15 @@ Use 0.12.1 or newer for directory-entry durability: newly created config/receipt
|
|
|
366
367
|
`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
|
|
|
368
369
|
Upgrade your installed `cloudgpu-mcp` package and restart the MCP client to load the new tools. This update does not restart existing GPUs.
|
|
370
|
+
|
|
371
|
+
### Registry namespace update (0.13.1)
|
|
372
|
+
|
|
373
|
+
The current MCP Registry listing is `io.github.cloudgpu-app/cloudgpu-mcp`, matching the repository organization. Older entries under `io.github.mrhy7176/cloudgpu-mcp` are historical. The npm package remains `cloudgpu-mcp`; existing stdio configurations and scoped API keys do not change. Upgrade the package and restart your MCP client.
|
|
374
|
+
|
|
375
|
+
### Agent compute planning (0.14.0)
|
|
376
|
+
|
|
377
|
+
Ask your connected Agent: “Compare compatible GPUs for this task, include preparation and download time, and show the minimum charge before creating anything.” `compare_compute_costs` checks live rental quotes and sorts by estimated billed GPU cost, including whole-hour minimums. It does not benchmark speed or prove Job/template support. A fresh `estimate_cost` and explicit billing approval are still required to rent.
|
|
378
|
+
|
|
379
|
+
Can one GPU serve several Agent tasks? Yes: sequential approved `run_command` calls can use the same running rental, within its original budget, deadline and idle limit. Check `list_instances` / `get_status` first. Independent `run_job` calls and “rerun” each provision separately; they do not share an instance. Do not extend limits or keep an idle GPU merely because an hour was charged. Save outputs before stopping; Workspace is explicit persistence, not a disk snapshot.
|
|
380
|
+
|
|
381
|
+
MCP clients must install or upgrade this package and restart their local MCP process. The account connection link authorizes a supported client; it cannot install tools into any arbitrary AI service.
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "cloudgpu-mcp",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"mcpName": "io.github.
|
|
3
|
+
"version": "0.14.0",
|
|
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",
|
|
7
7
|
"bin": {
|
package/rules/cloudgpu.md
CHANGED
|
@@ -6,10 +6,11 @@ Copy this file into your project as `AGENTS.md`, `.cursor/rules/cloudgpu.md` or
|
|
|
6
6
|
## Before renting
|
|
7
7
|
|
|
8
8
|
1. Call `get_account` and `list_gpus`. Pick a GPU with enough VRAM for the job, and don't rent more GPU than the job needs. As a rough guide, LoRA on a 7–8B model fits in 24 GB, and a full fine-tune of the same model needs 80 GB or more.
|
|
9
|
-
2.
|
|
9
|
+
2. Check `list_instances` for an existing approved running rental. If a new rental is needed, optionally use `compare_compute_costs` for up to eight compatible GPUs, then call `estimate_cost` with a realistic duration including preparation, model downloads and result collection. A comparison is not a creation quote or benchmark.
|
|
10
10
|
3. Show the user a short quote before you rent anything:
|
|
11
11
|
- the GPU and how many,
|
|
12
12
|
- the price per hour,
|
|
13
|
+
- the billing increment and minimum charge (some sources charge a minimum one hour and each started hour in full),
|
|
13
14
|
- the estimated hours and cost,
|
|
14
15
|
- the budget and time limit you will set,
|
|
15
16
|
- their balance after the job.
|
|
@@ -37,7 +38,7 @@ Copy this file into your project as `AGENTS.md`, `.cursor/rules/cloudgpu.md` or
|
|
|
37
38
|
For a batch task that is one command (a training script, a render, a batch of inference), `run_job` is simpler than renting an instance: CloudGPU starts the GPU, runs the command, and destroys the GPU when it finishes, even if you disconnect.
|
|
38
39
|
|
|
39
40
|
- Get the user's yes on the GPU, the budget and the time limit first, as for renting.
|
|
40
|
-
- The GPU's disk is erased when the job ends.
|
|
41
|
+
- The GPU's disk is erased when the job ends. When automatic output collection is available, declare explicit outputs under `$CLOUDGPU_OUTPUT_DIR` and inspect collection status and ready file IDs. Otherwise save results explicitly before release. Never print credentials or assume a rental billing quote proves Job/template compatibility. `get_job` returns the last ~4 KB of output.
|
|
41
42
|
- If `run_job` times out or the connection drops, call it again with the same `idempotency_key`. You get the same job back; a second GPU is not started.
|
|
42
43
|
- Check progress with `get_job` every minute or so. `needs_attention` means CloudGPU stopped the job to check something by hand; tell the user and do not resubmit it.
|
|
43
44
|
|
|
@@ -47,7 +48,7 @@ Call `connect_account` with a name for yourself and the spending limit the user
|
|
|
47
48
|
|
|
48
49
|
## Finishing (always)
|
|
49
50
|
|
|
50
|
-
1. Download every result: model weights, adapters, checkpoints, logs, metrics. Destroying an instance erases its disk
|
|
51
|
+
1. Download every result: model weights, adapters, checkpoints, logs, metrics. Destroying an instance erases its disk. Files explicitly uploaded to Workspace persist under its quota and retention policy; an instance disk is not automatically backed up. Confirm uploads completed and files are ready before release. Storage charges are separate from the GPU budget.
|
|
51
52
|
2. Call `stop_instance`.
|
|
52
53
|
3. Tell the user what ran, where the results are on their computer, and the final cost from `stop_instance`.
|
|
53
54
|
|
|
@@ -62,3 +63,7 @@ The same API key works for CloudGPU's OpenAI-compatible model API at `https://cl
|
|
|
62
63
|
Use prepare_job_batch to review all tasks and the sum of their GPU budget caps before any submission. Storage charges are separate. run_job_batch requires explicit approval and the exact plan hash. Preserve the full approved manifest, stable batch key and receipt. A partial or unknown submission never permits a replacement key: replay the identical manifest to recover original Jobs. Never automatically retry failed execution or create a replacement GPU while release is uncertain. Batch preparation is not a reservation, and accepted Jobs are independent, not an atomic transaction. Unsubmitted members do not survive a client exit.
|
|
63
64
|
|
|
64
65
|
Application recipes reuse prepared environments. ComfyUI protocol fixtures and LoRA orchestration fixtures are not real GPU or model-quality acceptance. No image/SDXL LoRA recipe is supplied. Never tell a user a template is production-validated based on these fixtures, or ask for credentials in workflow files.
|
|
66
|
+
|
|
67
|
+
## Reuse a GPU across tasks
|
|
68
|
+
|
|
69
|
+
A running rental can execute multiple approved commands sequentially using its instance ID and `run_command`; check status, ownership, available memory/disk and remaining original budget/deadline first. Do not use another team or personal account's resource. This does not extend its existing limits. Separate `run_job` calls and `prepare_job_rerun` do not reuse that rental. Persist results, stop when finished and reconcile release; do not retain idle GPUs just because an hour was charged. Crossing the next started hour incurs a further full-hour charge. No warm pool is promised.
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
import {z} from 'zod';
|
|
2
|
+
import {rentalBilling} from './rental-billing.js';
|
|
3
|
+
|
|
4
|
+
// Quotes do not reserve capacity. Compare charged periods, never hourly labels.
|
|
5
|
+
export async function compareComputeQuotes(api,{gpu_models,gpu_count=1,hours,max_spend_usd,template},now=Date.now()) {
|
|
6
|
+
const offers=await api.offers(), candidates=[],unavailable=[];
|
|
7
|
+
for(const name of [...new Set(gpu_models)]) {
|
|
8
|
+
const offer=offers.find(o=>o.gpu_model===name);
|
|
9
|
+
if(!offer||offer.available==='none'||gpu_count<(offer.min_gpu_count||1)) {
|
|
10
|
+
unavailable.push({gpu_model:name,reason:'No compatible live offer'});continue;
|
|
11
|
+
}
|
|
12
|
+
try {
|
|
13
|
+
const quote=await api.rentalBillingQuote({gpuModel:name,gpuCount:gpu_count,...(template?{templateId:template}:{})});
|
|
14
|
+
const b=rentalBilling(quote,hours,now);
|
|
15
|
+
candidates.push({gpu_model:name,gpu_count,estimated_cost_usd:b.estimate,
|
|
16
|
+
minimum_charge_usd:b.minimum,preauthorized_usd:b.prepaid,
|
|
17
|
+
billing_increment_seconds:b.increment,expires_at:quote.expiresAt,
|
|
18
|
+
within_gpu_budget:b.estimate<=max_spend_usd&&b.prepaid<=max_spend_usd,
|
|
19
|
+
billing_description:b.increment===3600?'Minimum one hour; each started hour charged in full. Unused charged time is not refunded on voluntary stop.':'Per-minute billing; one-minute minimum.'});
|
|
20
|
+
} catch {
|
|
21
|
+
// Provider errors may contain secrets: expose a fixed reason only.
|
|
22
|
+
unavailable.push({gpu_model:name,reason:'A valid current billing quote could not be obtained'});
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
candidates.sort((a,b)=>Number(b.within_gpu_budget)-Number(a.within_gpu_budget)||a.estimated_cost_usd-b.estimated_cost_usd||a.gpu_model.localeCompare(b.gpu_model));
|
|
26
|
+
return {candidates,unavailable,selection_basis:'Estimated billed GPU cost for the supplied duration only',
|
|
27
|
+
performance_verified:false,capacity_reserved:false,creates_gpu:false,
|
|
28
|
+
next:'Check VRAM, image and task compatibility. For the selected rental call estimate_cost again and obtain explicit approval of its billing period, minimum charge, budget and time limit before create_instance. This comparison is not a creation quote or Job compatibility proof.',
|
|
29
|
+
limitations:['Include environment preparation, downloads and result collection in the expected duration.','Execution speed, startup latency, storage, transfer and other ancillary costs are not measured here.','Hourly billing is not supported by every Job or template path; do not substitute a rental quote for a Job quote.']};
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
export function registerComputePlanningTools(server,{api,wrap,ok}) {
|
|
33
|
+
server.registerTool('compare_compute_costs',{
|
|
34
|
+
title:'Compare GPU billing periods and estimated task costs',
|
|
35
|
+
description:'Read-only live quote comparison for up to eight explicit compatible GPU candidates. Accounts for minimum one-hour versus per-minute billing. No capacity reservation, GPU creation, benchmark, automatic selection or approval. Run estimate_cost for the selected rental afterward.',
|
|
36
|
+
inputSchema:{gpu_models:z.array(z.string().min(1).max(120)).min(1).max(8),gpu_count:z.number().int().min(1).max(8).default(1),hours:z.number().positive().max(168),max_spend_usd:z.number().positive(),template:z.string().optional()},
|
|
37
|
+
annotations:{readOnlyHint:true,destructiveHint:false,idempotentHint:true,openWorldHint:true}
|
|
38
|
+
},wrap(async p=>ok(await compareComputeQuotes(api,p))));
|
|
39
|
+
}
|
package/src/index.js
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
import {rentalBilling} from "./rental-billing.js";
|
|
3
|
+
import {registerComputePlanningTools} from './compute-planning.js';
|
|
3
4
|
import {registerBatchTools} from './job-batches.js';
|
|
4
5
|
import {jobInputShape} from './job-input.js';
|
|
5
6
|
import {registerTaskTemplateTools} from './task-templates.js';
|
|
@@ -36,7 +37,7 @@ import {
|
|
|
36
37
|
shq,
|
|
37
38
|
} from "./guards.js";
|
|
38
39
|
|
|
39
|
-
const VERSION = "0.
|
|
40
|
+
const VERSION = "0.14.0";
|
|
40
41
|
const HERE = path.dirname(fileURLToPath(import.meta.url));
|
|
41
42
|
const RULES = fs.readFileSync(path.join(HERE, "..", "rules", "cloudgpu.md"), "utf8");
|
|
42
43
|
|
|
@@ -61,7 +62,8 @@ const quotes = new Quotes();
|
|
|
61
62
|
// Instances this session touched: did we run anything, did we download anything.
|
|
62
63
|
const session = new Map();
|
|
63
64
|
|
|
64
|
-
const INSTRUCTIONS = `CloudGPU (cloudgpu.app)
|
|
65
|
+
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.
|
|
66
|
+
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.
|
|
65
67
|
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.
|
|
66
68
|
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.
|
|
67
69
|
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.
|
|
@@ -72,6 +74,7 @@ The same API key also works for the OpenAI-compatible model API at ${cfg.baseUrl
|
|
|
72
74
|
|
|
73
75
|
const server = new McpServer({ name: "cloudgpu", version: VERSION }, { instructions: INSTRUCTIONS });
|
|
74
76
|
registerTaskTemplateTools(server, {wrap, ok});
|
|
77
|
+
registerComputePlanningTools(server,{api,wrap,ok});
|
|
75
78
|
registerBatchTools(server,{api,cfg,wrap,ok});
|
|
76
79
|
registerStorageTools(server, { api, wrap, ok, fail, readOnly: cfg.readOnly, expandHome });
|
|
77
80
|
registerJobResultTools(server, { api, wrap, ok, readOnly: cfg.readOnly });
|
|
@@ -191,7 +194,7 @@ server.registerTool(
|
|
|
191
194
|
available: r.available,
|
|
192
195
|
min_gpu_count: r.min_gpu_count,
|
|
193
196
|
})),
|
|
194
|
-
note: "
|
|
197
|
+
note: "Billing periods vary by allocated source. Call estimate_cost for the minimum charge and billing increment. 'available' is live and can change before you rent.",
|
|
195
198
|
});
|
|
196
199
|
}),
|
|
197
200
|
);
|