cloudgpu-mcp 0.16.3 → 0.16.4

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
@@ -6,7 +6,7 @@
6
6
 
7
7
  The agent checks live prices and quotes you, rents the GPU once you say yes, uploads your code and data, starts training in the background, watches the logs, downloads the adapter and destroys the instance. You get the files and the final cost.
8
8
 
9
- It is a local (stdio) MCP server. It works with any MCP client that can start one: Claude Code, Cursor, Cline, opencode, goose, VS Code, Windsurf and others.
9
+ It is a local (stdio) MCP server. It works with any MCP client that can start one: Codex, Claude Code, Cursor, Cline, opencode, goose, VS Code, Windsurf and others. Remote Streamable HTTP with OAuth is also available at `https://cloudgpu.app/mcp`; see [remote MCP setup](https://cloudgpu.app/docs/mcp).
10
10
 
11
11
  ## Install
12
12
 
@@ -100,6 +100,26 @@ extensions:
100
100
 
101
101
  To check the install, ask your agent: "List the GPUs available, then estimate the cost for a 24 GB GPU for one hour. Do not create anything." You should see `list_gpus` and `estimate_cost` calls and a quote, and nothing is rented.
102
102
 
103
+ ## Codex MCP
104
+
105
+ Add the local stdio server without putting a key in your command history:
106
+
107
+ ```bash
108
+ codex mcp add cloudgpu -- npx -y cloudgpu-mcp
109
+ codex mcp list
110
+ ```
111
+
112
+ In Codex, ask CloudGPU to call `connect_account`, open the returned link yourself, sign in, review the limits and approve, then ask it to call `finish_connect`. If needed, use `request_top_up` for an owner payment link and `wait_for_funds` to check the resulting balance. Never paste credentials into the conversation. Account connection does not approve paid compute; review a fresh quote and its billing terms before each allocation.
113
+
114
+ For a Codex client that supports remote MCP and OAuth, use this instead of the local entry:
115
+
116
+ ```bash
117
+ codex mcp add cloudgpu --url https://cloudgpu.app/mcp
118
+ codex mcp login cloudgpu
119
+ ```
120
+
121
+ The remote and local transports expose different tool sets; consult the [current MCP documentation](https://cloudgpu.app/docs/mcp). Start with a read-only capability or GPU-price check and explicitly ask it not to create resources. This is direct MCP configuration, separate from the optional Codex plugin below.
122
+
103
123
  ## Agent Skill
104
124
 
105
125
  The same guidance is available as two [Agent Skills](https://agentskills.io):
@@ -133,7 +153,7 @@ The same guidance is available as two [Agent Skills](https://agentskills.io):
133
153
  | Tool | What it does |
134
154
  |---|---|
135
155
  | `get_account` | Balance, and how many instances the account may run at once |
136
- | `list_gpus` | GPU models with VRAM, live price per GPU-hour and availability |
156
+ | `list_gpus` | GPU models, live starting rates, availability and detailed native configurations (GPU count, CPU, RAM, disks, region, interconnect and total hourly price) when available |
137
157
  | `list_templates` | Ready-made images: JupyterLab, Ollama, ComfyUI, LLaMA-Factory, … |
138
158
  | `compare_compute_costs` | Compare live total billed GPU cost for up to eight compatible candidates; no reservation or creation approval |
139
159
  | `estimate_cost` | Live quote for a GPU and a number of hours, plus your balance afterwards; returns a `quote_id` |
@@ -148,6 +168,8 @@ The same guidance is available as two [Agent Skills](https://agentskills.io):
148
168
  | `get_job` / `list_jobs` | Job status, exit code, cost, the last ~4 KB of output and the job's history |
149
169
  | `cancel_job` | Stops a job and destroys its GPU |
150
170
  | `get_agent_readiness` / `assess_task_fit` | Anonymous capability, billing, task suitability and evidence checks; no GPU is created |
171
+ | `list_rental_regions` | Anonymous qualified continent catalog; use its enabled flag, then a continent-bound rental quote |
172
+ | `list_regional_offers` | Anonymous native regional inventory observations and independent price evidence; explicit owner country, freshness, unknowns and overlapping capacity; planning only |
151
173
  | `request_top_up` / `wait_for_funds` | Human-only payment link and bounded polling for actual credit; no automatic charge or Job |
152
174
  | `quote_storage_budget` / `confirm_storage_budget` | Quote and explicitly approve an earmarked storage transfer; backend rollout and owner permissions apply |
153
175
  | `resume_artifact_upload` | Resume the same owned multipart reservation with the original local file and checksum |
@@ -419,3 +441,37 @@ Use `prepare_job_batch` to review every command, fresh compute quote, deadline a
419
441
  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
442
 
421
443
  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`.
444
+
445
+ ### Regional facts before a compute decision
446
+
447
+ `list_regional_offers` calls anonymous `GET /v1/public/compute-offers`. Give the
448
+ human owner country explicitly as `user_country`; an Agent's hosting location
449
+ is not its owner's location. Optional filters are `country_code`, `gpu_model`,
450
+ `gpu_count`, `include_unavailable`, `limit` and the returned `after_id` cursor.
451
+ Stock and source-price evidence have separate ages. Failed, stale, unsupported
452
+ or missing observations do not prove zero stock. Counts are not reservations
453
+ or proof that multiple cards can be allocated on one host. Capacity groups are
454
+ known aliases only; do not sum them into an independent global total.
455
+
456
+ Native regional observations do not authorize execution or change retail
457
+ pricing. A published SKU reference is not an executable quote. For a hard
458
+ continent constraint, use the separately advertised rental capability below.
459
+ Country/datacenter constraints remain unsupported and must not be dropped. MCP also
460
+ rejects unknown argument fields instead of silently stripping them. Tasks that
461
+ do not require a location continue to use fresh standard quotes and their
462
+ source-specific billing/approval rules. No native mounted-volume product is
463
+ offered; Workspace still uses explicit file snapshots and restore.
464
+
465
+
466
+ ## Continent-constrained rentals
467
+
468
+ Check anonymous `GET /v1/public/rental-regions` (MCP `list_rental_regions`) first. This staged capability is available only when its response says `enabled: true`. Select one of `asia`, `europe`, `north_america`, `oceania`, `south_america`, `africa`; country and datacenter selection are not supported. With no qualified supply, do not infer a region from the unfiltered legacy catalogue or the Agent's IP.
469
+
470
+ For a rental, pass the same `continent` to `estimate_cost` / `POST /v1/gpu/billing-quote`, then obtain explicit approval and pass it with the exact `billing_quote_id` and `billing_accepted: true` to `POST /v1/gpu/instances`. The stdio client's `create_instance` carries the approved continent automatically. Changes or missing continent bindings require a new quote. Minimum billing periods are unchanged; there is no automatic cross-continent fallback.
471
+
472
+ The generic `POST /v1/quotes`, Jobs and batches do not yet accept a hard continent constraint. Do not drop that constraint or substitute an unconstrained Job. Dynamic aggregate pricing remains an internal calculation module pending qualified supplier cost feeds and end-to-end billing activation; these endpoints do not promise an active global market.
473
+ ### Detailed GPU configurations
474
+
475
+ `list_gpus` preserves the REST `/v1/gpu/offers` configuration data. `usd_per_gpu_hour` is a starting per-card rate; each `configurations[].hourlyPrice` is the **whole instance** price for `gpuCount` cards. Each entry includes per-card VRAM, CPU/RAM, system/local disk, interconnect, continent, current availability, billing minimum/increment in seconds and observation time in Unix milliseconds where supplied. Missing fields mean unknown.
476
+
477
+ `inventory_count_exact: false` means the source reports configuration availability, not a count of machines. Do not add overlapping 1/2/4/8-card alternatives or treat them as reserved stock. A catalog entry can be unavailable while retained for discovery. `estimate_cost` for the chosen card count remains required; GPU catalog membership does not imply Job or template compatibility.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "cloudgpu-mcp",
3
- "version": "0.16.3",
3
+ "version": "0.16.4",
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",
@@ -97,3 +97,7 @@ In a configured MCP client, call `connect_account`, show the owner its link, the
97
97
  ## Several steps on one allocation
98
98
 
99
99
  If installed, `prepare_task_pipeline` prepares up to eight reviewed sequential commands for one Job, or for `run_command` on an approved existing rental. It creates nothing. Commands share the filesystem and GPU but use separate shells; they do not share exported shell variables or a resident model process. Failure stops later steps. Python 3, bash and prepared dependencies are required. Review the returned command, obtain a compatible quote and explicit total budget/deadline approval, then submit one Job with a stable idempotency key. Preserve the original request on a lost response. The fingerprint is informational, not approval. Optional collection saves only pipeline-summary.json, never arbitrary results or logs; approve actual result persistence separately. Existing user instance limits and lifecycle remain unchanged.
100
+
101
+ ## Regional discovery
102
+
103
+ Use `list_regional_offers` for recent native regional observations and independent price evidence. Ask for the human owner's country only when useful; do not infer it from the Agent server IP. Respect unknown/expired facts and shared pools. These are planning observations, not reservations, region-bound quotes or verified multi-card allocations. Exact-region execution and dynamic regional retail are not enabled in this release. If the task has a hard location requirement, explain the unsupported capability and do not submit an ordinary rental or Job in its place. Existing R2 Workspace is explicit file save/restore, not a mounted volume.
package/src/index.js CHANGED
@@ -1,6 +1,8 @@
1
1
  #!/usr/bin/env node
2
2
  import {registerFundingTools} from "./funding-tools.js";
3
3
  import {registerAgentReadinessTools} from "./agent-readiness.js";
4
+ import {registerRegionalOfferTools,CONTINENTS} from "./regional-offers.js";
5
+ import {useStrictToolInputs} from "./strict-tools.js";
4
6
  import {rentalBilling} from "./rental-billing.js";
5
7
  import {registerComputePlanningTools} from './compute-planning.js';
6
8
  import {registerTaskPipelineTools} from './task-pipelines.js';
@@ -40,7 +42,7 @@ import {
40
42
  shq,
41
43
  } from "./guards.js";
42
44
 
43
- const VERSION = "0.16.3";
45
+ const VERSION = "0.16.4";
44
46
  const HERE = path.dirname(fileURLToPath(import.meta.url));
45
47
  const RULES = fs.readFileSync(path.join(HERE, "..", "rules", "cloudgpu.md"), "utf8");
46
48
 
@@ -66,6 +68,7 @@ const quotes = new Quotes();
66
68
  const session = new Map();
67
69
 
68
70
  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.
71
+ Regional discovery: list_regional_offers reads native observations with separate stock/price ages and explicit unknowns. Supply the owner country explicitly, never the Agent egress IP. Native observations are planning only. For continent-constrained rentals, first call list_rental_regions and require enabled=true, then estimate_cost with the chosen continent. create_instance carries that approved constraint. Countries/datacenters and continent-constrained Jobs are not supported; never drop a hard constraint. Dynamic aggregate retail is not activated.
69
72
  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
73
  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
74
  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.
@@ -78,8 +81,10 @@ No API key yet? connect_account gives the user a link to approve this assistant
78
81
  The same API key also works for the OpenAI-compatible model API at ${cfg.baseUrl}/v1 (see list_models).`;
79
82
 
80
83
  const server = new McpServer({ name: "cloudgpu", version: VERSION }, { instructions: INSTRUCTIONS });
84
+ useStrictToolInputs(server);
81
85
  registerFundingTools(server,{api,wrap,ok,readOnly:cfg.readOnly});
82
86
  registerAgentReadinessTools(server,{api,wrap,ok});
87
+ registerRegionalOfferTools(server,{api,wrap,ok});
83
88
  registerTaskTemplateTools(server, {wrap, ok});
84
89
  registerComputePlanningTools(server,{api,wrap,ok});
85
90
  registerTaskPipelineTools(server,{cfg,wrap,ok});
@@ -180,7 +185,7 @@ server.registerTool(
180
185
  {
181
186
  title: "List GPUs",
182
187
  description:
183
- "GPU models you can rent now, with VRAM, live price per GPU-hour in USD and availability (ok / low / none). Prices are live; never assume them.",
188
+ "GPU catalog with per-card VRAM, live starting price in USD, availability, and native configurations (GPU count, CPU, RAM, disks, region, interconnect and whole-instance price) when provided. Unavailable models remain discoverable. Request an exact quote before renting.",
184
189
  inputSchema: {
185
190
  min_vram_gb: z.number().optional().describe("Only GPUs with at least this much VRAM per card"),
186
191
  gpu_model: z.string().optional().describe("Filter by name, e.g. 4090, A100, H20"),
@@ -201,8 +206,10 @@ server.registerTool(
201
206
  usd_per_gpu_hour: r.hourly_usd,
202
207
  available: r.available,
203
208
  min_gpu_count: r.min_gpu_count,
209
+ inventory_count_exact: r.inventory_count_exact ?? null,
210
+ configurations: r.configurations ?? [],
204
211
  })),
205
- 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.",
212
+ note: "usd_per_gpu_hour is a starting per-card rate; configurations[].hourlyPrice is the total for that single-host GPU count, not a per-card rate. Configuration availability is not a fleet count or reservation. Billing periods vary by allocated source; call estimate_cost for the selected count and current minimum charge, billing increment and exact total. Availability can change before you rent. Configuration fields are absent when the source has not supplied verified metadata.",
206
213
  });
207
214
  }),
208
215
  );
@@ -226,6 +233,7 @@ server.registerTool(
226
233
  description:
227
234
  "Live price and estimated cost for a GPU, plus your balance after it. Returns a quote_id that create_instance needs. Show the quote to the user and get an explicit yes before renting.",
228
235
  inputSchema: {
236
+ continent: z.enum(CONTINENTS).optional().describe("Hard continent constraint, from list_rental_regions"),
229
237
  gpu_model: z.string().describe("GPU model exactly as list_gpus returns it"),
230
238
  gpu_count: z.number().int().min(1).max(8).default(1),
231
239
  hours: z.number().positive().describe("Expected run time in hours"),
@@ -233,7 +241,7 @@ server.registerTool(
233
241
  },
234
242
  annotations: { readOnlyHint: true, openWorldHint: true },
235
243
  },
236
- wrap(async ({ gpu_model, gpu_count = 1, hours, template }) => {
244
+ wrap(async ({ gpu_model, gpu_count = 1, hours, template, continent }) => {
237
245
  const [offers, account] = await Promise.all([api.offers(), api.account().catch(() => null)]);
238
246
  const offer = offers.find((o) => String(o.gpu_model).toLowerCase() === gpu_model.toLowerCase());
239
247
  if (!offer) {
@@ -242,7 +250,8 @@ server.registerTool(
242
250
  if (gpu_count < (offer.min_gpu_count || 1)) {
243
251
  return fail(`${offer.gpu_model} is rented in groups of at least ${offer.min_gpu_count} GPUs.`);
244
252
  }
245
- const billing = await api.rentalBillingQuote({gpuModel:offer.gpu_model,gpuCount:gpu_count,...(template?{templateId:template}:{})});
253
+ const billing = await api.rentalBillingQuote({gpuModel:offer.gpu_model,gpuCount:gpu_count,...(continent?{continent}:{}),...(template?{templateId:template}:{})});
254
+ if(continent&&billing.continent!==continent)return fail("The billing quote did not bind the requested continent. No rental was started.");
246
255
  const {hourly,increment,estimate}=rentalBilling(billing,hours);
247
256
  const balance = account ? Number(account.balance_usd) : null;
248
257
  const warnings = [];
@@ -253,9 +262,10 @@ server.registerTool(
253
262
  `Balance $${balance} does not cover the estimate plus a 10% buffer. When the balance runs out the instance is destroyed and its disk erased. Call request_top_up and wait_for_funds; obtain approval before continuing.`,
254
263
  );
255
264
  }
256
- 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 });
265
+ const quote_id = quotes.put({ continent, gpu_model: offer.gpu_model, gpu_count, template, hourly, hours, estimate, billingQuoteId:billing.billingQuoteId, billingExpiresAt:billing.expiresAt, minimumChargeUsd:Number(billing.minimumChargeUsd), billingIncrementSeconds:increment });
257
266
  return ok({
258
267
  quote_id,
268
+ continent:continent||null,
259
269
  gpu_model: offer.gpu_model,
260
270
  gpu_count,
261
271
  template: template || null,
@@ -494,6 +504,7 @@ if (!cfg.readOnly) {
494
504
  );
495
505
  }
496
506
  const body = {
507
+ ...(quote.continent?{continent:quote.continent}:{}),
497
508
  billing_quote_id:quote.billingQuoteId,
498
509
  billing_accepted:true,
499
510
  gpu_model: quote.gpu_model,
@@ -0,0 +1,25 @@
1
+ import {z} from "zod";
2
+
3
+ /** Discovery only; no implicit owner geolocation, quote, procurement or data migration. */
4
+ export const CONTINENTS=["asia","europe","north_america","oceania","south_america","africa"];
5
+ export function registerRegionalOfferTools(server,{api,wrap,ok}){
6
+ server.registerTool("list_rental_regions",{
7
+ title:"List rentable GPUs by continent",
8
+ description:"Read-only qualified continent catalog shared with the rental UI. Use enabled and inventory/capability/count constraints. Request estimate_cost with the same continent before renting. Countries and individual datacenters are not selectable. Empty inventory does not authorize renting in another continent.",
9
+ inputSchema:{continent:z.enum(CONTINENTS).optional()},
10
+ annotations:{readOnlyHint:true,destructiveHint:false,idempotentHint:true,openWorldHint:true},
11
+ },wrap(async ({continent})=>ok(await api.request("GET","/v1/public/rental-regions"+(continent?"?continent="+encodeURIComponent(continent):""),undefined,{noAuth:true}))));
12
+
13
+ server.registerTool("list_regional_offers",{
14
+ title:"Inspect regional compute observations",
15
+ description:"Anonymous, read-only native regional stock observations, independent price evidence ages, billing references and known/unknown limits. Supply the human owner's country explicitly; the Agent server IP is not its owner's location. Counts are not reservations or verified single-host multi-GPU allocations. Published SKU references are not region-bound executable quotes; dynamic regional pricing and exact-region execution are not activated. Unsupported, stale or failed observations do not prove global stockout. Follow has_more/next_after_id; pagination is a live view, not a frozen snapshot.",
16
+ inputSchema:{user_country:z.string().regex(/^[A-Za-z]{2}$/).optional(),country_code:z.string().regex(/^[A-Za-z]{2}$/).optional(),gpu_model:z.string().max(100).optional(),gpu_count:z.number().int().min(1).max(8).default(1),include_unavailable:z.boolean().default(false),limit:z.number().int().min(1).max(200).default(100),after_id:z.string().regex(/^offer_[a-f0-9]{32}$/).optional()},
17
+ annotations:{readOnlyHint:true,destructiveHint:false,idempotentHint:true,openWorldHint:true},
18
+ },wrap(async input=>{
19
+ const query=new URLSearchParams();
20
+ for(const field of ["user_country","country_code","gpu_model","gpu_count","include_unavailable","limit","after_id"])
21
+ if(input[field]!==undefined)query.set(field,String(input[field]));
22
+ const encoded=query.toString();
23
+ return ok(await api.request("GET","/v1/public/compute-offers"+(encoded?"?"+encoded:""),undefined,{noAuth:true}));
24
+ }));
25
+ }
@@ -0,0 +1,13 @@
1
+ import {z} from "zod";
2
+
3
+ /** JSON tool contracts already advertise no extra fields; enforce that instead of stripping constraints. */
4
+ export function useStrictToolInputs(server){
5
+ const register=server.registerTool.bind(server);
6
+ server.registerTool=(name,config,...rest)=>{
7
+ if(config.inputSchema){
8
+ const schema=typeof config.inputSchema.safeParse==="function"?config.inputSchema:z.object(config.inputSchema);
9
+ config={...config,inputSchema:typeof schema.strict==="function"?schema.strict():schema};
10
+ }
11
+ return register(name,config,...rest);
12
+ };
13
+ }