cloudgpu-mcp 0.13.1 → 0.14.1
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 +11 -2
- package/package.json +3 -2
- package/rules/cloudgpu.md +8 -3
- package/skills/cloudgpu/SKILL.md +95 -0
- package/skills/cloudgpu-model-api/SKILL.md +56 -0
- package/src/cli-core.js +3 -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
|
|
|
@@ -370,3 +371,11 @@ Upgrade your installed `cloudgpu-mcp` package and restart the MCP client to load
|
|
|
370
371
|
### Registry namespace update (0.13.1)
|
|
371
372
|
|
|
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,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "cloudgpu-mcp",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.14.1",
|
|
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",
|
|
@@ -14,7 +14,8 @@
|
|
|
14
14
|
"rules",
|
|
15
15
|
"README.md",
|
|
16
16
|
"LICENSE",
|
|
17
|
-
"examples"
|
|
17
|
+
"examples",
|
|
18
|
+
"skills"
|
|
18
19
|
],
|
|
19
20
|
"engines": {
|
|
20
21
|
"node": ">=18.3"
|
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,95 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: cloudgpu
|
|
3
|
+
description: Rent and use a cloud GPU on CloudGPU (cloudgpu.app) through the `cloudgpu` MCP tools. Use when the user wants to rent a GPU, run a training, fine-tuning, inference or ComfyUI job on a cloud GPU, or mentions CloudGPU or cloudgpu.app, and the `cloudgpu` MCP tools are available.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# CloudGPU
|
|
7
|
+
|
|
8
|
+
Follow these steps whenever you rent or use a GPU on CloudGPU (cloudgpu.app) through the `cloudgpu` MCP tools.
|
|
9
|
+
|
|
10
|
+
## Before renting
|
|
11
|
+
|
|
12
|
+
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.
|
|
13
|
+
2. Check existing `list_instances` before renting. A compatible running rental can run multiple approved commands inside its original limits. Optionally compare billed task costs with `compare_compute_costs`, then call `estimate_cost` with preparation/download/output time included.
|
|
14
|
+
3. Show the user a short quote before you rent anything:
|
|
15
|
+
- the GPU and how many,
|
|
16
|
+
- the price per hour,
|
|
17
|
+
- the billing increment and minimum charge: some sources charge a minimum one hour and every started hour in full, with no voluntary-stop refund of unused charged time,
|
|
18
|
+
- the estimated hours and cost,
|
|
19
|
+
- the budget and time limit you will set,
|
|
20
|
+
- their balance after the job.
|
|
21
|
+
4. Rent only after the user says yes. Pass `user_confirmed=true` only in that case.
|
|
22
|
+
|
|
23
|
+
## Renting
|
|
24
|
+
|
|
25
|
+
- Always set `max_spend_usd` and `max_hours`. CloudGPU's servers destroy the instance when either is reached, even if you have disconnected.
|
|
26
|
+
- Keep `idle_minutes` on (default 60). Include setup time when agreeing limits before creation. Never silently extend the approved budget, time or idle limits.
|
|
27
|
+
- Call `get_status` at intervals, not in a tight loop, until the instance is `running`.
|
|
28
|
+
- On failure, inspect actual charges and release status; do not promise zero charges or automatic refunds. Do not retry creation while the result or resource release is uncertain.
|
|
29
|
+
|
|
30
|
+
## Working on the instance
|
|
31
|
+
|
|
32
|
+
- Put code and data on the instance with `upload`. Do not upload credentials.
|
|
33
|
+
- Use `run_command` for short steps. For training, long installs or big downloads, use `background=true` and follow progress with `tail_logs`.
|
|
34
|
+
- Instances come with Python and CUDA, but not always PyTorch. Check first: `nvidia-smi -L` and `python -c "import torch; print(torch.__version__, torch.cuda.is_available())"`.
|
|
35
|
+
- If PyTorch is missing, plain `pip install torch` installs a current CUDA build. It is a few GB, so run it with `background=true`. Index URLs for older CUDA versions (for example `.../whl/cu124`) may have no wheel for the machine's Python, which can be very new. Only use them if the project needs that CUDA version, and then create an environment with an older Python first (`conda create -y -n work python=3.12`, then `conda activate work && ...` in each command).
|
|
36
|
+
- If `nvidia-smi` shows no GPU once the instance is running, stop and tell the user. CloudGPU detects such machines and shuts them down automatically.
|
|
37
|
+
- **Do not** change the root password, edit the SSH configuration, change the firewall, or stop the platform's monitoring agent (`cgpu-*` processes). The platform must keep its access to the instance; if that access is lost, the platform shuts the instance down. The MCP server refuses such commands.
|
|
38
|
+
- Never use the GPU for cryptocurrency mining or anything the [acceptable use policy](https://cloudgpu.app/aup) forbids. Instances that do so are shut down.
|
|
39
|
+
|
|
40
|
+
## Finishing (always)
|
|
41
|
+
|
|
42
|
+
1. Download every result: model weights, adapters, checkpoints, logs, metrics. Destroying an instance erases its disk. Workspace persists only files explicitly uploaded and ready, under its quota/retention policy. It is not an automatic disk backup. Storage fees are separate from GPU budgets.
|
|
43
|
+
2. Call `stop_instance`.
|
|
44
|
+
3. Tell the user what ran, where the results are on their computer, and the final cost from `stop_instance`.
|
|
45
|
+
|
|
46
|
+
If anything goes wrong mid-way, do not leave the instance running. Download whatever exists, stop the instance, then explain what happened.
|
|
47
|
+
|
|
48
|
+
## Balance and top-ups
|
|
49
|
+
|
|
50
|
+
- If `get_account` or `estimate_cost` shows the balance would not cover the quoted job, do not call `create_instance`. Tell the user how much is missing and ask them to top up at https://cloudgpu.app/billing (card or USDT). When they say it is done, call `estimate_cost` again before renting.
|
|
51
|
+
- `create_instance` also checks the balance. If it is below the estimate or budget plus 10%, the MCP server does not rent anything and returns an error that starts with `Not rented: balance $... is below $...` and points to https://cloudgpu.app/billing. If the CloudGPU API itself rejects the request with HTTP status 402, the error reads `CloudGPU API error 402 <code>: <message>` followed by the same billing link. Handle both the same way as above: stop, tell the user how much is missing, and do not retry.
|
|
52
|
+
- Never top up, enter card details or move money on the user's behalf. The user does that themselves on the billing page.
|
|
53
|
+
|
|
54
|
+
## Checking prices without the MCP server
|
|
55
|
+
|
|
56
|
+
If the `cloudgpu` tools are not available, read current prices from https://cloudgpu.app/gpu-prices.json (machine-readable, with an `updated_at` field) or https://cloudgpu.app/pricing. Check `updated_at` and tell the user how fresh the data is. Do not quote prices from memory.
|
|
57
|
+
|
|
58
|
+
## Optional persistence
|
|
59
|
+
|
|
60
|
+
Discover tools and `GET /v1/public/compute-capabilities` first. Persistence is
|
|
61
|
+
unavailable when that endpoint is missing or `storage` is false. Never promise
|
|
62
|
+
free storage, a retention period or automatic output collection.
|
|
63
|
+
|
|
64
|
+
When enabled, ask before saving private project files. Use `save_workspace` for
|
|
65
|
+
regular source/config/dependency-manifest files, `upload_artifact` for persistent
|
|
66
|
+
results or datasets/models, and `download_artifact` to retrieve them. Pass the
|
|
67
|
+
saved `workspace_version_id` to `run_job` to restore the files before execution.
|
|
68
|
+
The service does not restore a boot disk and does not automatically save edits;
|
|
69
|
+
the Job command must still save its results before shutdown. Do not upload secrets.
|
|
70
|
+
|
|
71
|
+
For Jobs, prefer `quote_compute` for a server quote and send its `quote_id` with
|
|
72
|
+
the chosen candidate. Its `required_starting_balance` is separate from the task
|
|
73
|
+
estimate. The original `estimate_cost` quote belongs to `create_instance`.
|
|
74
|
+
|
|
75
|
+
## Only need a model, not a GPU?
|
|
76
|
+
|
|
77
|
+
The same API key works for CloudGPU's model API at `https://cloudgpu.app/v1`. Call `list_models` to see the models. If you only need inference on a hosted model, use the API instead of renting a GPU.
|
|
78
|
+
|
|
79
|
+
## If the MCP server is not installed
|
|
80
|
+
|
|
81
|
+
If no `cloudgpu` tools are available, the MCP server needs to be set up first:
|
|
82
|
+
|
|
83
|
+
- Command: `npx -y cloudgpu-mcp`
|
|
84
|
+
- Environment variable: `CLOUDGPU_API_KEY`, with a key created at https://cloudgpu.app.
|
|
85
|
+
- Never paste the key into the chat or into files in the project. Ask the user to put it in their MCP client's configuration or environment themselves.
|
|
86
|
+
|
|
87
|
+
See the [README](https://github.com/cloudgpu-app/cloudgpu-mcp#install) for per-client setup.
|
|
88
|
+
|
|
89
|
+
## Jobs and instance reuse
|
|
90
|
+
|
|
91
|
+
Sequential approved `run_command` calls may reuse a running rental within its original budget, deadline and idle limit. Check ownership, readiness and free memory/disk first. Independent `run_job` calls and `prepare_job_rerun` provision separately, not into that live rental. Job/template support is configuration-specific; inspect `supports_jobs` and obtain a Job quote, never substitute the rental quote. Do not keep an idle GPU merely to consume a prepaid hour. Confirm result persistence and release when finished.
|
|
92
|
+
|
|
93
|
+
## Connect with an approval link
|
|
94
|
+
|
|
95
|
+
In a configured MCP client, call `connect_account`, show the owner its link, then `finish_connect` after approval. No password or API key is pasted in chat. The link grants scoped access; it does not automatically install an MCP server in arbitrary AI products.
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: cloudgpu-model-api
|
|
3
|
+
description: Call a hosted model through CloudGPU's OpenAI-compatible model API at https://cloudgpu.app/v1, without renting a GPU. Use when the user wants to call a hosted model (chat/completions) through CloudGPU, wire CloudGPU into an OpenAI-compatible client or agent framework (OpenAI SDK, LangChain, Cline, Roo Code, Continue, Aider, n8n, Dify), or mentions cloudgpu.app/v1.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# CloudGPU model API
|
|
7
|
+
|
|
8
|
+
CloudGPU (cloudgpu.app) serves hosted models over an OpenAI-compatible API at `https://cloudgpu.app/v1`. No GPU rental is needed.
|
|
9
|
+
|
|
10
|
+
## 1. Pick a model ID
|
|
11
|
+
|
|
12
|
+
- Call the `list_models` tool, or `GET https://cloudgpu.app/v1/models` (public, no key needed).
|
|
13
|
+
- Never guess or hardcode a model ID. Use one the list returns.
|
|
14
|
+
|
|
15
|
+
## 2. Authenticate
|
|
16
|
+
|
|
17
|
+
- Send `Authorization: Bearer $CLOUDGPU_API_KEY`.
|
|
18
|
+
- Read the key from the environment. Never print it, and never write it into files that get committed.
|
|
19
|
+
- If `CLOUDGPU_API_KEY` is not set, ask the user to create a key at https://cloudgpu.app and set it themselves. Do not ask them to paste it into the chat.
|
|
20
|
+
|
|
21
|
+
## 3. Set up a client
|
|
22
|
+
|
|
23
|
+
In any OpenAI-compatible SDK, client or agent framework, set `base_url` to `https://cloudgpu.app/v1` and the API key to the value of `CLOUDGPU_API_KEY`.
|
|
24
|
+
|
|
25
|
+
Python (OpenAI SDK):
|
|
26
|
+
|
|
27
|
+
```python
|
|
28
|
+
import os
|
|
29
|
+
from openai import OpenAI
|
|
30
|
+
|
|
31
|
+
client = OpenAI(base_url="https://cloudgpu.app/v1", api_key=os.environ["CLOUDGPU_API_KEY"])
|
|
32
|
+
resp = client.chat.completions.create(
|
|
33
|
+
model="kimi-k3", # example only: check list_models or /v1/models first
|
|
34
|
+
messages=[{"role": "user", "content": "Say hello."}],
|
|
35
|
+
)
|
|
36
|
+
print(resp.choices[0].message.content)
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
The same request as HTTP. Read the key from the environment; do not paste it into the request text you show the user.
|
|
40
|
+
|
|
41
|
+
- `POST https://cloudgpu.app/v1/chat/completions`
|
|
42
|
+
- `Authorization: Bearer` followed by the value of `CLOUDGPU_API_KEY`
|
|
43
|
+
- `Content-Type: application/json`
|
|
44
|
+
- Body: `{"model":"<id from the model list>","messages":[{"role":"user","content":"Say hello."}]}`
|
|
45
|
+
|
|
46
|
+
The model id in any example is only an example. Check the model list before using it.
|
|
47
|
+
|
|
48
|
+
## Prices and balance
|
|
49
|
+
|
|
50
|
+
Don't quote prices from memory. Current prices are at https://cloudgpu.app/api. The same API key and balance also cover GPU rental (see the `cloudgpu` skill).
|
|
51
|
+
|
|
52
|
+
## Errors
|
|
53
|
+
|
|
54
|
+
- **401:** the key is missing or wrong. Check that `CLOUDGPU_API_KEY` is set and valid.
|
|
55
|
+
- **404 / model not found:** the model ID is not available. Re-run `list_models` and use an ID from the list.
|
|
56
|
+
- **429:** too many requests. Back off, then retry.
|
package/src/cli-core.js
CHANGED
|
@@ -78,7 +78,7 @@ const COMMANDS = {
|
|
|
78
78
|
" output in /root/cloudgpu-setup.log on the instance",
|
|
79
79
|
"--wait poll until the instance is running or failed, then print SSH and URLs",
|
|
80
80
|
"--show-password with --wait, also print the SSH password if the API returns one",
|
|
81
|
-
"Costs money: billing is
|
|
81
|
+
"Costs money: billing is source-specific. Hourly sources require a billing quote and explicit approval through MCP; never infer billing from the hourly price label.",
|
|
82
82
|
],
|
|
83
83
|
options: {
|
|
84
84
|
...JSON_OPT,
|
|
@@ -557,7 +557,7 @@ async function cmdOffers(c) {
|
|
|
557
557
|
offers.map((o) => [o.gpu_model, o.vram_gb != null ? `${o.vram_gb} GB` : null, usd(o.hourly_usd), o.available, o.min_gpu_count]),
|
|
558
558
|
),
|
|
559
559
|
);
|
|
560
|
-
c.out("Prices and availability are live
|
|
560
|
+
c.out("Prices and availability are live and can change; billing periods vary by source. Use MCP estimate_cost for the minimum charge.\n");
|
|
561
561
|
if (tpl && tpl.recommended_gpu) c.out(`Template ${tpl.id} recommends: ${tpl.recommended_gpu}\n`);
|
|
562
562
|
return 0;
|
|
563
563
|
}
|
|
@@ -611,7 +611,7 @@ async function cmdUp(c) {
|
|
|
611
611
|
return 0;
|
|
612
612
|
}
|
|
613
613
|
c.out(`Created ${inst.id} (${gpuLabel(inst)}, status: ${inst.status}).\n`);
|
|
614
|
-
c.out(`Billing
|
|
614
|
+
c.out(`Billing follows the approved source-specific terms until destroyed. Check it with: cloudgpu status ${inst.id}\n`);
|
|
615
615
|
c.out(`Destroy it with: cloudgpu down ${inst.id}\n`);
|
|
616
616
|
return 0;
|
|
617
617
|
}
|
|
@@ -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.1";
|
|
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
|
);
|