@portproof/mcp 0.1.0 → 0.2.0

package/README.md

@@ -123,21 +123,27 @@ is `http` or `socks5`. Which countries have devices online changes through the d
 ### Dedicated ports (coming soon, not on sale yet)
 
 `search_inventory`, `quote`, `buy_port`, `list_ports`, `get_port`, `rotate`, `set_rotation_schedule`,
-`get_passport` (port details), `get_receipt` (a rotation record, with its signature checked against the published
-keys) and `get_usage` work on dedicated ports for organisations that already hold one. The server tells the model
-not to offer them.
+`renew_port` (one more term from your account balance), `set_auto_renew`, `get_passport` (port details),
+`get_receipt` (a rotation record, with its signature checked against the published keys) and `get_usage` work on
+dedicated ports for organisations that already hold one. The server tells the model not to offer them.
+
+Every port has a `label` (country, carrier and port id) and a `network`: `own` (Own network) or `partner` (Partner
+network). Partner network ports are bought in the web shop, one SKU per term: `quote` and `buy_port` answer such a
+SKU with its price and `shop_url` and charge nothing. Their HTTP and SOCKS5 connections can differ in host, port,
+login and password, so `get_port` builds `proxy_urls` from each set, and `rotation_url` is the link that rotates the
+IP when fetched.
 
 ## Safety
 
-- `buy_traffic`, `buy_port`, `rotate` and `set_rotation_schedule` are refused, without any request to the API,
-  unless the call carries `confirm: true` and an `idempotency_key`. `buy_traffic` also needs `accept_terms: true`,
+- `buy_traffic`, `buy_port`, `renew_port`, `rotate`, `set_rotation_schedule` and `set_auto_renew` are refused,
+  without any request to the API, unless the call carries `confirm: true` and an `idempotency_key`. `buy_traffic` also needs `accept_terms: true`,
   which records that you accept the terms, the acceptable-use policy and the immediate start of the service. The
   server instructs the model to ask you before setting either.
 - Retrying with the same `idempotency_key` replays the first answer instead of buying twice; a different purchase
   needs a new key.
 - Responses are compact JSON. Errors are `{"error":{"code","status","title","detail"}}` with the API's problem
   codes (`insufficient_funds`, `trial_already_used`, `insufficient_scope`, `rate_limited`, ...) or a local code such
-  as `confirmation_required` or `api_unreachable`.
+  as `confirmation_required`, `not_on_sale` or `api_unreachable`.
 - stdout carries only the MCP protocol; logs go to stderr.
 
 ## Licence

package/dist/index.js

@@ -43,7 +43,11 @@ var ID_PREFIXES = [
   "aud",
   "upp",
   "led",
-  "wl"
+  "wl",
+  "opc",
+  "opm",
+  "opt",
+  "opx"
 ];
 var ULID_RE = /^[0-9A-HJKMNP-TV-Z]{26}$/;
 var prefixSet = /* @__PURE__ */ new Set(ID_PREFIXES);
@@ -91,6 +95,8 @@ var ORDER_STATUSES = [
 var TRAFFIC_TRIAL = { sku: "traffic-trial", gb: 0.5, price_cents: 290 };
 var TRAFFIC_MOBILE_COUNTRIES = ["US", "GB", "FR", "NL", "PL", "GE"];
 var TRAFFIC_PROTOCOLS = ["http", "socks5"];
+var OPS_PRINCIPALS = ["admin-key", "claude", "codex"];
+var OPS_ACTORS = [...OPS_PRINCIPALS, "system"];
 
 import { z } from "zod";
 var IsoDateTime = /* @__PURE__ */ z.string().datetime({ offset: true });
@@ -619,7 +625,8 @@ var ProblemDetails = /* @__PURE__ */ z12.object({
   instance: /* @__PURE__ */ z12.string().optional(),
   code: /* @__PURE__ */ z12.string().min(1),
   retry_after: /* @__PURE__ */ z12.number().int().min(0).optional(),
-  errors: /* @__PURE__ */ z12.array(/* @__PURE__ */ z12.object({ path: /* @__PURE__ */ z12.string(), message: /* @__PURE__ */ z12.string() })).optional()
+  errors: /* @__PURE__ */ z12.array(/* @__PURE__ */ z12.object({ path: /* @__PURE__ */ z12.string(), message: /* @__PURE__ */ z12.string() })).optional(),
+  current_revision: /* @__PURE__ */ z12.number().int().min(1).optional()
 });
 
 import { createPrivateKey, createPublicKey, generateKeyPairSync, sign, verify } from "node:crypto";
@@ -678,16 +685,29 @@ function verifyReceiptWithKeys(receipt, keys) {
 }
 
 var SERVER_NAME = "portproof";
-var SERVER_VERSION = "0.1.0";
+var SERVER_VERSION = "0.2.0";
 var USER_AGENT = `portproof-mcp/${SERVER_VERSION}`;
 var DEFAULT_API_URL = "https://api.portproof.org";
 var DEFAULT_TIMEOUT_MS = 3e4;
 var ROTATE_TIMEOUT_MS = 2e5;
+var ROTATION_POLL_INTERVAL_MS = 5e3;
+var ROTATION_TOTAL_WAIT_MS = 18e4;
 function normaliseBaseUrl(raw) {
   const trimmed = (raw ?? "").trim().replace(/\/+$/, "");
   const origin = trimmed === "" ? DEFAULT_API_URL : trimmed;
   return origin.endsWith("/v1") ? origin : `${origin}/v1`;
 }
+function shopOrigin(baseUrl) {
+  let url;
+  try {
+    url = new URL(baseUrl);
+  } catch {
+    return null;
+  }
+  if (!url.hostname.startsWith("api.")) return null;
+  const port = url.port === "" ? "" : `:${url.port}`;
+  return `${url.protocol}//${url.hostname.slice("api.".length)}${port}`;
+}
 function loadConfig(env = process.env) {
   const key = env.PORTPROOF_API_KEY?.trim();
   return {
@@ -769,6 +789,7 @@ function apiOrigin(baseUrl) {
 var ApiClient = class {
   baseUrl;
   wellKnownKeysUrl;
+  shopOrigin;
   hasApiKey;
   apiKey;
   fetchImpl;
@@ -777,6 +798,7 @@ var ApiClient = class {
   constructor(opts) {
     this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
     this.wellKnownKeysUrl = apiOrigin(this.baseUrl) + WELL_KNOWN_KEYS_PATH;
+    this.shopOrigin = shopOrigin(this.baseUrl);
     this.apiKey = opts.apiKey;
     this.hasApiKey = Boolean(opts.apiKey);
     this.fetchImpl = opts.fetchImpl ?? globalThis.fetch;
@@ -871,13 +893,36 @@ var ApiClient = class {
       idempotencyKey,
       timeoutMs: ROTATE_TIMEOUT_MS
     });
+    return this.rotationOutcome(r, "POST /ports/{id}/rotate");
+  }
+  async getRotationStatus(portId, rotationId) {
+    const r = await this.request(
+      "GET",
+      `/ports/${encodeURIComponent(portId)}/rotation/${encodeURIComponent(rotationId)}`
+    );
+    return this.rotationOutcome(r, "GET /ports/{id}/rotation/{rotation_id}");
+  }
+  rotationOutcome(r, label) {
     if (r.status === 202) {
       return {
         kind: "pending",
-        pending: this.lenient(RotatePendingResponse, r.data, "POST /ports/{id}/rotate 202")
+        pending: this.lenient(RotatePendingResponse, r.data, `${label} 202`)
       };
     }
-    return { kind: "receipt", receipt: this.lenient(Receipt, r.data, "POST /ports/{id}/rotate") };
+    return { kind: "receipt", receipt: this.lenient(Receipt, r.data, label) };
+  }
+  async renewPort(portId, idempotencyKey) {
+    const r = await this.request("POST", `/ports/${encodeURIComponent(portId)}/renew`, {
+      idempotencyKey
+    });
+    return this.lenient(Subscription, r.data, "POST /ports/{id}/renew");
+  }
+  async setAutoRenew(portId, enabled, idempotencyKey) {
+    const r = await this.request("PUT", `/ports/${encodeURIComponent(portId)}/auto-renew`, {
+      body: { enabled },
+      idempotencyKey
+    });
+    return this.lenient(Subscription, r.data, "PUT /ports/{id}/auto-renew");
   }
   async setRotationSchedule(portId, intervalS, idempotencyKey) {
     const r = await this.request("PUT", `/ports/${encodeURIComponent(portId)}/rotation`, {
@@ -947,13 +992,14 @@ var SearchInventoryInput = z13.object({
   country: CountryCode.optional().describe('ISO-3166 alpha-2, e.g. "LT"'),
   carrier: z13.string().min(1).optional().describe("Carrier name filter, exactly as search_inventory returns it")
 });
+var PortSku = ProductSku.describe('SKU from get_pricing (field skus), e.g. "lt-4g"');
 var QuoteInput = z13.object({
-  sku: SkuSchema,
+  sku: PortSku,
   term: Term,
   quantity: z13.number().int().min(1).max(1e3)
 });
 var BuyPortInput = z13.object({
-  sku: SkuSchema.describe('Price table SKU, e.g. "lt-4g" or "trial-24h"'),
+  sku: PortSku,
   term: Term,
   carrier_id: idSchema("car").optional().describe("Pin a carrier (from search_inventory); omit for any"),
   auto_renew: z13.boolean().optional(),
@@ -968,6 +1014,17 @@ var RotateInput = z13.object({
   port_id: idSchema("prt"),
   ...ConfirmFields
 });
+var RenewPortInput = z13.object({
+  port_id: idSchema("prt"),
+  ...ConfirmFields
+});
+var SetAutoRenewInput = z13.object({
+  port_id: idSchema("prt"),
+  enabled: z13.boolean().describe(
+    "true = renew from the account balance before the term ends; false = the port ends at the end of its term"
+  ),
+  ...ConfirmFields
+});
 var SetRotationScheduleInput = z13.object({
   port_id: idSchema("prt"),
   interval_s: z13.number().int().refine((v) => v === 0 || v >= ROTATION_INTERVAL_MIN_S && v <= ROTATION_INTERVAL_MAX_S, {
@@ -1014,8 +1071,10 @@ var BuyTrafficInput = z13.object({
 });
 var PortSummary = z13.object({
   id: idSchema("prt"),
+  label: z13.string(),
+  network: PortNetwork,
   state: z13.string(),
-  site_code: z13.string(),
+  site_code: z13.string().optional(),
   country: z13.string(),
   carrier: z13.string(),
   ip_stack: z13.string(),
@@ -1023,10 +1082,11 @@ var PortSummary = z13.object({
   egress_v6_prefix: z13.string().nullable(),
   rotation_interval_s: z13.number().int(),
   last_rotation_at: z13.string().nullable(),
-  usage_today_bytes: z13.number().int(),
-  daily_cap_bytes: z13.number().int(),
+  usage_today_bytes: z13.number().int().nullable(),
+  daily_cap_bytes: z13.number().int().nullable(),
   uptime_30d_pct: z13.number().nullable(),
   subscription_ends_at: z13.string().nullable(),
+  auto_renew: z13.boolean().nullable(),
   operator: z13.enum(["owned", "partner"]),
   evidence: z13.enum(["signed", "observed"]),
   attestation: z13.enum(["signed", "observed"])
@@ -1056,6 +1116,8 @@ var TOOL_NAMES = [
   "get_port",
   "rotate",
   "set_rotation_schedule",
+  "renew_port",
+  "set_auto_renew",
   "get_passport",
   "get_receipt",
   "get_usage",
@@ -1067,6 +1129,122 @@ var TOOL_NAMES = [
   "test_connection"
 ];
 
+var regionNames = new Intl.DisplayNames(["en"], { type: "region" });
+function countryName(code) {
+  const cc = code.toUpperCase();
+  if (cc === "GE") return "Georgia (country)";
+  try {
+    const name = regionNames.of(cc);
+    if (name === void 0 || name === cc || /^unknown/i.test(name)) return cc;
+    return name;
+  } catch {
+    return cc;
+  }
+}
+function networkOf(port) {
+  if (port.network !== void 0) return port.network;
+  if (port.evidence === "observed") return "partner";
+  return "own";
+}
+function neutralPortLabel(port) {
+  const parts = [countryName(port.country)];
+  if (port.carrierName) parts.push(port.carrierName);
+  parts.push(port.id);
+  return parts.join(" \xB7 ");
+}
+function urlHost(host) {
+  if (host.includes(":") && !host.startsWith("[")) return `[${host}]`;
+  return host;
+}
+function proxyUrl(scheme, credential) {
+  const auth = `${encodeURIComponent(credential.username)}:${encodeURIComponent(credential.password)}`;
+  return `${scheme}://${auth}@${urlHost(credential.host)}:${credential.port}`;
+}
+function proxyUrls(port) {
+  const credentials = port.credentials;
+  if (!credentials) return null;
+  const shared = { username: credentials.username, password: credentials.password };
+  const http = credentials.http ?? {
+    host: port.listeners.host,
+    port: port.listeners.http_port,
+    ...shared
+  };
+  const socks5 = credentials.socks5 ?? {
+    host: port.listeners.host,
+    port: port.listeners.socks_port,
+    ...shared
+  };
+  return { http: proxyUrl("http", http), socks5: proxyUrl("socks5", socks5) };
+}
+function carrierView(carrier, network) {
+  if (network === "own") return carrier;
+  const { mcc_mnc: _placeholder, ...rest } = carrier;
+  return rest;
+}
+function portView(port) {
+  const { site_code: siteCode, usage_today: usageToday, carrier, ...rest } = port;
+  const network = networkOf(port);
+  const label = neutralPortLabel({ id: port.id, country: port.country, carrierName: carrier.name });
+  const view = { label, ...rest, carrier: carrierView(carrier, network), network };
+  if (network === "own") {
+    view.site_code = siteCode;
+    view.usage_today = usageToday;
+  }
+  return view;
+}
+function summarisePort(port) {
+  const network = networkOf(port);
+  const summary = {
+    id: port.id,
+    label: neutralPortLabel({ id: port.id, country: port.country, carrierName: port.carrier.name }),
+    network,
+    state: port.state,
+    country: port.country,
+    carrier: port.carrier.name,
+    ip_stack: port.carrier.ip_stack,
+    egress_v4: port.egress_v4,
+    egress_v6_prefix: port.egress_v6_prefix,
+    rotation_interval_s: port.rotation_interval_s,
+    last_rotation_at: port.last_rotation_at,
+    usage_today_bytes: network === "own" ? port.usage_today.bytes : null,
+    daily_cap_bytes: network === "own" ? port.usage_today.cap_bytes : null,
+    uptime_30d_pct: port.uptime_30d_pct,
+    subscription_ends_at: port.subscription?.ends_at ?? null,
+    auto_renew: port.subscription?.auto_renew ?? null,
+    operator: port.operator,
+    evidence: port.evidence,
+    attestation: port.attestation
+  };
+  if (network === "own") summary.site_code = port.site_code;
+  return summary;
+}
+function passportView(passport) {
+  const {
+    site_code: siteCode,
+    usage: usage2,
+    sessions,
+    sim_contract_class: simClass,
+    ip_shared_with_own_ports: sharedWithOwn,
+    carrier,
+    ...rest
+  } = passport;
+  const network = networkOf(passport);
+  const label = neutralPortLabel({
+    id: passport.port_id,
+    country: passport.country,
+    carrierName: carrier.name
+  });
+  const view = { label, ...rest, carrier: carrierView(carrier, network), network };
+  if (network === "own") {
+    view.site_code = siteCode;
+    view.usage = usage2;
+    view.sessions = sessions;
+    view.sim_contract_class = simClass;
+    view.ip_shared_with_own_ports = sharedWithOwn;
+  }
+  return view;
+}
+
 function defineTool(def) {
   return def;
 }
@@ -1086,10 +1264,10 @@ var MUTATING = {
 var getPassport = defineTool({
   name: "get_passport",
   title: "Get port details",
-  description: "Port details (API object: passport): carrier, SIM contract class, egress IPs, geo consensus, reputation, rotation and uptime statistics, throughput, usage, concurrent sessions (proof the port is not shared) and exclusivity. Credentials are never included.",
+  description: "Port details (API object: passport): label (country, carrier, port id), network (own = Own network, partner = Partner network), carrier, egress IPs, geo consensus, reputation, rotation and uptime statistics, throughput and exclusivity. Own network ports add the SIM contract class, usage against the daily cap and concurrent sessions (proof the port is not shared); a Partner network port has none of these, because nothing of ours runs on its device. Credentials are never included.",
   inputSchema: PortIdInput,
   annotations: READ_ONLY,
-  run: async (args, ctx) => jsonResult(await ctx.api.getPassport(args.port_id))
+  run: async (args, ctx) => jsonResult(passportView(await ctx.api.getPassport(args.port_id)))
 });
 async function verifySignature(receipt, ctx) {
   try {
@@ -1143,35 +1321,42 @@ function checkConfirmation(args, action) {
   return null;
 }
 
-function summarisePort(p) {
-  return {
-    id: p.id,
-    state: p.state,
-    site_code: p.site_code,
-    country: p.country,
-    carrier: p.carrier.name,
-    ip_stack: p.carrier.ip_stack,
-    egress_v4: p.egress_v4,
-    egress_v6_prefix: p.egress_v6_prefix,
-    rotation_interval_s: p.rotation_interval_s,
-    last_rotation_at: p.last_rotation_at,
-    usage_today_bytes: p.usage_today.bytes,
-    daily_cap_bytes: p.usage_today.cap_bytes,
-    uptime_30d_pct: p.uptime_30d_pct,
-    subscription_ends_at: p.subscription?.ends_at ?? null,
-    operator: p.operator,
-    evidence: p.evidence,
-    attestation: p.attestation
-  };
+var PRICE_TABLE_SKUS = new Set(SkuSchema.options);
+function isPriceTableSku(sku) {
+  return PRICE_TABLE_SKUS.has(sku);
+}
+async function findCatalogueListing(sku, ctx) {
+  const pricing = await ctx.api.getPricing();
+  return pricing.skus.find((row) => row.sku === sku && row.buy_via === "cart") ?? null;
 }
-function proxyUrls(p) {
-  if (!p.credentials) return null;
-  const auth = `${encodeURIComponent(p.credentials.username)}:${encodeURIComponent(p.credentials.password)}`;
+function shopAnswer(listing, requestedTerm, ctx) {
+  const shopPath = `/shop/${encodeURIComponent(listing.sku)}`;
+  const shopUrl = ctx.api.shopOrigin === null ? null : `${ctx.api.shopOrigin}${shopPath}`;
+  const steps = [
+    "This port is bought in the Portproof web shop, not through buy_port: open shop_url, add it to the cart and check out.",
+    "The port is delivered after payment and company verification."
+  ];
+  if (listing.term !== requestedTerm) {
+    steps.push(
+      `This SKU is the ${listing.term} term; get_pricing lists the SKUs of the other terms.`
+    );
+  }
   return {
-    http: `http://${auth}@${p.listeners.host}:${p.listeners.http_port}`,
-    socks5: `socks5://${auth}@${p.listeners.host}:${p.listeners.socks_port}`
+    buy_via: "cart",
+    sku: listing.sku,
+    term: listing.term,
+    price_cents: listing.price_cents,
+    currency: listing.currency,
+    shop_path: shopPath,
+    shop_url: shopUrl,
+    next_step: steps.join(" ")
   };
 }
+var NOT_ON_SALE_DETAIL = "This SKU is not on sale for your organisation right now. get_pricing (field skus) lists what can be bought; dedicated ports are coming soon.";
+function notOnSale() {
+  return localError("not_on_sale", "Not on sale", NOT_ON_SALE_DETAIL);
+}
+
 async function costOf(port, input, ctx) {
   if (port.subscription) {
     return {
@@ -1187,27 +1372,33 @@ async function costOf(port, input, ctx) {
     return { cost_cents: null, currency: null, cost_source: "unknown" };
   }
 }
+async function answerCatalogueBuy(args, ctx) {
+  const listing = await findCatalogueListing(args.sku, ctx);
+  if (listing === null) return notOnSale();
+  return jsonResult({ purchased: false, charged: false, ...shopAnswer(listing, args.term, ctx) });
+}
 var buyPort = defineTool({
   name: "buy_port",
   title: "Buy a port",
-  description: "Dedicated ports (coming soon, not on sale yet; do not offer them): buy one dedicated mobile port (one modem, one SIM, one customer) for a SKU and term; check search_inventory first. For proxies by the GB use buy_traffic instead. CHARGES MONEY: requires confirm: true and an idempotency_key; refused otherwise. Fails with kyb_required (402) until the org has passed KYB tier t1, and no_inventory (409) when the SKU is sold out. Returns the Port with credentials and cost_cents.",
+  description: 'Dedicated ports (coming soon, not on sale yet; do not offer them): buy one dedicated mobile port (one modem, one SIM, one customer) for a SKU and term; check search_inventory first. For proxies by the GB use buy_traffic instead. CHARGES MONEY: requires confirm: true and an idempotency_key; refused otherwise. Fails with kyb_required (402) until the org has passed KYB tier t1, and no_inventory (409) when the SKU is sold out. Returns the Port with credentials and cost_cents. Partner network SKUs (buy_via "cart" in get_pricing) are bought in the web shop: for them nothing is charged and the answer is purchased: false with shop_url, or not_on_sale when they are not on sale for your organisation.',
   inputSchema: BuyPortInput,
   annotations: MUTATING,
   run: async (args, ctx) => {
     const refusal = checkConfirmation(args, "buy_port");
     if (refusal) return refusal;
+    if (!isPriceTableSku(args.sku)) return answerCatalogueBuy(args, ctx);
     const body = { sku: args.sku, term: args.term, quantity: 1 };
     if (args.carrier_id !== void 0) body.carrier_id = args.carrier_id;
     if (args.auto_renew !== void 0) body.auto_renew = args.auto_renew;
     const { data: port } = await ctx.api.createPort(body, args.idempotency_key);
     const cost = await costOf(port, args, ctx);
-    return jsonResult({ ...cost, port, proxy_urls: proxyUrls(port) });
+    return jsonResult({ ...cost, port: portView(port), proxy_urls: proxyUrls(port) });
   }
 });
 var listPorts = defineTool({
   name: "list_ports",
   title: "List ports",
-  description: "List the ports owned by this API key (compact summaries; use get_port for credentials and full detail). Paginated: pass next_cursor as cursor to continue.",
+  description: "List the ports owned by this API key as compact summaries: label (country, carrier, port id), network (own = Own network, partner = Partner network), state, egress IPs, rotation, usage, subscription end and auto_renew. No credentials: use get_port for those. Paginated: pass next_cursor as cursor to continue.",
   inputSchema: ListPortsInput,
   annotations: READ_ONLY,
   run: async (args, ctx) => {
@@ -1221,47 +1412,65 @@ var listPorts = defineTool({
 var getPort = defineTool({
   name: "get_port",
   title: "Get port",
-  description: "Full detail for one port: state, carrier, listeners, credentials (only if you own it), allowlist, egress IPs, rotation settings, usage today, uptime and subscription. Also returns ready-to-use proxy_urls.",
+  description: "Full detail for one port: label, network, state, carrier, listeners, credentials (only if you own it), allowlist, egress IPs, rotation settings, usage today, uptime and subscription. Partner network ports also carry credentials.http and credentials.socks5 (each with its own host, port, login and password), capabilities (controls the port supports), renewal (price_cents, ends_at, auto_renew, can_renew) and rotation_url: the Portproof link that rotates the IP when fetched (60 s cooldown). proxy_urls gives ready-to-use http and socks5 URLs, each built from its own credential set.",
   inputSchema: PortIdInput,
   annotations: READ_ONLY,
   run: async (args, ctx) => {
     const port = await ctx.api.getPort(args.port_id);
-    return jsonResult({ port, proxy_urls: proxyUrls(port) });
+    return jsonResult({ port: portView(port), proxy_urls: proxyUrls(port) });
   }
 });
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function awaitRotation(portId, rotationId, startedAt, ctx) {
+  const intervalMs = ctx.rotationPoll?.intervalMs ?? ROTATION_POLL_INTERVAL_MS;
+  const deadline = startedAt + (ctx.rotationPoll?.totalWaitMs ?? ROTATION_TOTAL_WAIT_MS);
+  while (Date.now() + intervalMs <= deadline) {
+    await sleep(intervalMs);
+    const status = await ctx.api.getRotationStatus(portId, rotationId);
+    if (status.kind === "receipt") return status.receipt;
+  }
+  return null;
+}
+function rotationDone(receipt) {
+  return jsonResult({
+    status: "done",
+    rotated: receipt.rotated,
+    reason: receipt.reason,
+    old_ip4: receipt.old_ip4,
+    new_ip4: receipt.new_ip4,
+    elapsed_ms: receipt.elapsed_ms,
+    receipt
+  });
+}
 var rotate = defineTool({
   name: "rotate",
   title: "Rotate IP",
-  description: "Rotate IP: request a new egress IP for a port and wait (up to 180 s) for the rotation record, signed on the device for Own network ports (evidence: signed) or recorded by our monitoring for Partner network ports (evidence: observed). Changes live proxy state: requires confirm: true and an idempotency_key; refused otherwise. Carriers sometimes return the same IP (rotated: false, reason carrier_sticky); a rotation record is written either way. 429 port_cooldown (with retry_after seconds) inside the 60 s cooldown. Included in the subscription: no charge.",
+  description: "Rotate IP: request a new egress IP for a port and wait (up to 180 s in all) for the rotation record, signed on the device for Own network ports (evidence: signed) or recorded by our monitoring for Partner network ports (evidence: observed). A rotation still running after the API's first answer is followed on its status link. Changes live proxy state: requires confirm: true and an idempotency_key; refused otherwise. Carriers sometimes return the same IP (rotated: false, reason carrier_sticky); a rotation record is written either way. 429 port_cooldown (with retry_after seconds) inside the 60 s cooldown. Included in the subscription: no charge.",
   inputSchema: RotateInput,
   annotations: MUTATING,
   run: async (args, ctx) => {
     const refusal = checkConfirmation(args, "rotate");
     if (refusal) return refusal;
+    const startedAt = Date.now();
     const result = await ctx.api.rotatePort(args.port_id, args.idempotency_key);
-    if (result.kind === "pending") {
-      return jsonResult({
-        status: "pending",
-        rotation_id: result.pending.rotation_id,
-        port_id: args.port_id
-      });
-    }
-    const r = result.receipt;
+    if (result.kind === "receipt") return rotationDone(result.receipt);
+    const rotationId = result.pending.rotation_id;
+    const receipt = await awaitRotation(args.port_id, rotationId, startedAt, ctx);
+    if (receipt !== null) return rotationDone(receipt);
     return jsonResult({
-      status: "done",
-      rotated: r.rotated,
-      reason: r.reason,
-      old_ip4: r.old_ip4,
-      new_ip4: r.new_ip4,
-      elapsed_ms: r.elapsed_ms,
-      receipt: r
+      status: "pending",
+      rotation_id: rotationId,
+      port_id: args.port_id,
+      detail: "The rotation is still running. Do not rotate again: read get_receipt with this rotation_id in a minute, or get_port for the new egress IP."
     });
   }
 });
 var setRotationSchedule = defineTool({
   name: "set_rotation_schedule",
   title: "Set rotation schedule",
-  description: "Set the automatic rotation interval for a port: 0 = sticky (never rotate on a schedule), otherwise 60..86400 seconds. Schedules run on the device even if the API is unreachable. Changes live proxy state: requires confirm: true and an idempotency_key; refused otherwise. No charge.",
+  description: "Set the automatic rotation interval for a port: 0 = sticky (never rotate on a schedule), otherwise 60..86400 seconds. The schedule keeps running between API calls. When get_port shows capabilities.rotation_interval: false the port has no schedule control. A change the network has not confirmed yet answers conflict (409); try again later. Changes live proxy state: requires confirm: true and an idempotency_key; refused otherwise. No charge.",
   inputSchema: SetRotationScheduleInput,
   annotations: MUTATING,
   run: async (args, ctx) => {
@@ -1281,11 +1490,54 @@ var setRotationSchedule = defineTool({
     });
   }
 });
+var renewPort = defineTool({
+  name: "renew_port",
+  title: "Renew a port",
+  description: "Dedicated ports: renew one port for one more term now, paid from the account balance. Read get_port first: renewal.can_renew says whether it can be renewed now and renewal.price_cents what one more term costs. A Partner network port is renewed on the network first and ends_at is the end it confirmed; there is no grace period after a term ends. CHARGES MONEY: requires confirm: true and an idempotency_key; refused otherwise. Errors: insufficient_funds (402, nothing charged: top up the balance), conflict (409, for example while an earlier renewal is still being confirmed), supply_source_error (502, the renewal was refused and the charge refunded). Returns ends_at and cost_cents.",
+  inputSchema: RenewPortInput,
+  annotations: MUTATING,
+  run: async (args, ctx) => {
+    const refusal = checkConfirmation(args, "renew_port");
+    if (refusal) return refusal;
+    const subscription = await ctx.api.renewPort(args.port_id, args.idempotency_key);
+    return jsonResult({
+      port_id: args.port_id,
+      renewed: true,
+      ends_at: subscription.ends_at,
+      auto_renew: subscription.auto_renew,
+      cost_cents: subscription.price_cents,
+      currency: subscription.currency,
+      subscription
+    });
+  }
+});
+var setAutoRenew = defineTool({
+  name: "set_auto_renew",
+  title: "Set auto-renew",
+  description: "Dedicated ports: switch auto-renew of one port on or off. On: the port is renewed from the account balance shortly before its term ends (a short balance means it ends). Off: the port ends at the end of its current term, with no refund. Changes the subscription: requires confirm: true and an idempotency_key; refused otherwise. No charge now.",
+  inputSchema: SetAutoRenewInput,
+  annotations: MUTATING,
+  run: async (args, ctx) => {
+    const refusal = checkConfirmation(args, "set_auto_renew");
+    if (refusal) return refusal;
+    const subscription = await ctx.api.setAutoRenew(
+      args.port_id,
+      args.enabled,
+      args.idempotency_key
+    );
+    return jsonResult({
+      port_id: args.port_id,
+      auto_renew: subscription.auto_renew,
+      ends_at: subscription.ends_at,
+      subscription
+    });
+  }
+});
 
 var getPricing = defineTool({
   name: "get_pricing",
   title: "Get pricing",
-  description: 'Public price table. Field traffic: proxy traffic by the GB (tier table with the per-GB price by order size in EUR cents ex VAT, package sizes, the 0.5 GB trial, validity days, monthly GB without company verification); buy it with buy_traffic. Field skus: dedicated ports (coming soon, not on sale yet) with monthly price in cents (EUR, USD for us-4g), supply (evidence signed = Own network, observed = Partner network), volume ladder, weekly/daily term ratios and the 24 h trial. Each SKU says how it is bought (buy_via): "ports" SKUs work with quote and buy_port; "cart" SKUs are Partner network ports sold only through the web shop and cannot be quoted or bought here. No API key needed. Prices are quotes only; nothing is charged.',
+  description: 'Public price table. Field traffic: proxy traffic by the GB (tier table with the per-GB price by order size in EUR cents ex VAT, package sizes, the 0.5 GB trial, validity days, monthly GB without company verification); buy it with buy_traffic. Field skus: dedicated ports (coming soon, not on sale yet) with monthly price in cents (EUR, USD for us-4g), supply (evidence signed = Own network, observed = Partner network), volume ladder, weekly/daily term ratios and the 24 h trial. Each SKU says how it is bought (buy_via): "ports" SKUs work with quote and buy_port; "cart" SKUs are Partner network ports, one SKU per term, sold only through the web shop (quote and buy_port answer them with the shop link). Partner network ports are listed only while they are on sale for your organisation, so the list can differ with and without an API key. No API key needed. Prices are quotes only; nothing is charged.',
   inputSchema: EmptyInput,
   annotations: READ_ONLY,
   run: async (_args, ctx) => jsonResult(await ctx.api.getPricing())
@@ -1293,7 +1545,7 @@ var getPricing = defineTool({
 var searchInventory = defineTool({
   name: "search_inventory",
   title: "Search inventory",
-  description: "Dedicated ports (coming soon, not on sale yet): available dedicated mobile ports per country / site / carrier, with the number available and whether new ports are wait-listed. Use the returned carrier_id to pin a carrier in buy_port. No API key needed.",
+  description: "Dedicated ports (coming soon, not on sale yet): available Own network dedicated mobile ports per country / site / carrier, with the number available and whether new ports are wait-listed. Use the returned carrier_id to pin a carrier in buy_port. Partner network ports are not listed here: get_pricing lists the ones on sale for you. No API key needed.",
   inputSchema: SearchInventoryInput,
   annotations: READ_ONLY,
   run: async (args, ctx) => {
@@ -1306,10 +1558,19 @@ var searchInventory = defineTool({
 var quote = defineTool({
   name: "quote",
   title: "Quote a purchase",
-  description: "Price a purchase before buying: unit price, volume discount and total in cents for a SKU, term (monthly | weekly | daily) and quantity. Read-only, nothing is charged.",
+  description: 'Price a purchase before buying: unit price, volume discount and total in cents for a SKU, term (monthly | weekly | daily) and quantity. For a Partner network SKU (buy_via "cart") the answer is its listed price per port and the web shop link, where the cart shows the total; not_on_sale when it is not on sale for your organisation. Read-only, nothing is charged.',
   inputSchema: QuoteInput,
   annotations: READ_ONLY,
   run: async (args, ctx) => {
+    if (!isPriceTableSku(args.sku)) {
+      const listing = await findCatalogueListing(args.sku, ctx);
+      if (listing === null) return notOnSale();
+      return jsonResult({
+        ...shopAnswer(listing, args.term, ctx),
+        quantity: args.quantity,
+        charged: false
+      });
+    }
     const q = await ctx.api.postQuote({ sku: args.sku, term: args.term, quantity: args.quantity });
     return jsonResult({
       ...q,
@@ -1470,6 +1731,8 @@ var TOOLS = [
   getPort,
   rotate,
   setRotationSchedule,
+  renewPort,
+  setAutoRenew,
   getPassport,
   getReceipt,
   getUsage,
@@ -1490,10 +1753,11 @@ if (registered.size !== TOOL_NAMES.length)
 var INSTRUCTIONS = [
   `Portproof sells proxy traffic by the GB: one prepaid GB balance per organisation, usable on two shared pools, mobile 4G/5G (carrier modems in ${MOBILE_COUNTRIES_TEXT}) and residential (opt-in peer devices; the countries online now come from list_countries, so never state a country count from memory). Pool, country, rotation (new IP every 5 / 10 / 20 / 60 minutes, on every connection, or a sticky session) and the session name are chosen in the proxy username, so one credential serves everything. Be precise: the pools are shared, a sticky session keeps the same device and the carrier may still change its IP; never call this traffic dedicated, private, static or unlimited, and never list pool exit addresses. Validity is what get_traffic reports: limits.validity_days 0 (and expires_at null) means GB never expire; a positive number is the days of validity every purchase guarantees for the whole balance.`,
   "Traffic tools: get_traffic (balance, expiry, limits), list_countries (devices online now per pool), build_proxy_url (username, URL and code snippets; the password stays masked unless reveal_password is true), test_connection (one request through the gateway: exit IP and latency; exit_country is normally null because the exit country is not checked; never report the requested country as the exit country), buy_traffic (wallet purchase of whole GB or the one-off 0.5 GB trial; prices come from the tier table in get_pricing, field traffic).",
-  'Dedicated ports are coming soon and not on sale yet: do not offer them. get_pricing (field skus), search_inventory, quote, buy_port, list_ports, get_port, rotate, set_rotation_schedule, get_passport, get_receipt and get_usage work on dedicated mobile ports (one modem, one SIM, one customer per port) for organisations that already have one. Every port states its supply: "signed" evidence means Own network (each rotation record is signed on the device), "observed" evidence means Partner network (recorded by our monitoring and signed by the control plane key); never describe a Partner network port as signed on the device.',
+  'Dedicated ports are coming soon and not on sale yet: do not offer them. get_pricing (field skus), search_inventory, quote, buy_port, list_ports, get_port, rotate, set_rotation_schedule, renew_port, set_auto_renew, get_passport, get_receipt and get_usage work on dedicated mobile ports (one modem, one SIM, one customer per port) for organisations that already have one. Every port states its supply: "signed" evidence means Own network (each rotation record is signed on the device), "observed" evidence means Partner network (recorded by our monitoring and signed by the control plane key); never describe a Partner network port as signed on the device. Name a port by its label (country, carrier, port id) and say only "Partner network" about where a Partner network port runs.',
+  'Partner network ports are bought in the web shop, one SKU per term (buy_via "cart" in get_pricing): quote and buy_port answer them with shop_url and never charge. Their HTTP and SOCKS5 connections may differ in host, port, login and password: give the user proxy_urls from get_port, never a URL assembled from one set. rotation_url is the Portproof link that rotates the IP when fetched. They renew from the account balance: renewal in get_port says what one more term costs and whether it can be renewed now; auto-renew off means the port ends at the end of its term.',
   "Read tools (get_pricing, search_inventory, quote, list_ports, get_port, get_passport, get_receipt, get_usage, get_status, get_traffic, list_countries, build_proxy_url) are safe to call freely; test_connection uses a few kilobytes of the balance and is limited to 6 per minute.",
-  "buy_traffic and buy_port charge money and rotate / set_rotation_schedule change live proxy state: they are refused unless called with confirm: true and an idempotency_key. buy_traffic also needs accept_terms: true, which records that the user accepts the terms, the acceptable-use policy and the immediate start of the service. Ask the user before setting confirm: true or accept_terms: true, and reuse the same idempotency_key only to retry the identical request.",
-  'Every response is compact JSON. Successful purchases include cost_cents. Errors are {"error": {code, status, title, detail}} using the API problem codes (insufficient_funds, kyb_required_for_volume, trial_already_used, traffic_not_purchased, kyb_required, no_inventory, port_cooldown with retry_after, insufficient_scope, not_found, validation_failed, ...).',
+  "buy_traffic, buy_port and renew_port charge money, rotate and set_rotation_schedule change live proxy state and set_auto_renew changes the subscription: they are refused unless called with confirm: true and an idempotency_key. buy_traffic also needs accept_terms: true, which records that the user accepts the terms, the acceptable-use policy and the immediate start of the service. Ask the user before setting confirm: true or accept_terms: true, and reuse the same idempotency_key only to retry the identical request.",
+  'Every response is compact JSON. Successful purchases include cost_cents. Errors are {"error": {code, status, title, detail}} using the API problem codes (insufficient_funds, kyb_required_for_volume, trial_already_used, traffic_not_purchased, kyb_required, no_inventory, use_cart, port_cooldown with retry_after, conflict, insufficient_scope, not_found, validation_failed, ...) plus local codes such as not_on_sale.',
   "get_pricing, search_inventory, quote, get_status and list_countries work without an API key; everything else needs PORTPROOF_API_KEY. Key scopes are enforced: get_traffic needs ports:read (connection details only with ports:write), and build_proxy_url, test_connection and buy_traffic need ports:write; a missing scope answers insufficient_scope."
 ].join(" ");
 function createServer(ctx) {

package/llms.txt

@@ -1,6 +1,6 @@
 # Portproof MCP server
 
-> Proxy traffic by the GB: one prepaid GB balance per organisation, usable on two shared pools, mobile 4G/5G (carrier modems) and residential (opt-in peer devices). Pool, country, rotation and session are chosen in the proxy username, so one credential serves everything. The pools are shared: the traffic is never dedicated, private, static or unlimited, and a sticky session keeps the same device while the carrier may still change its IP. Countries online now come from list_countries; never state a country count from memory. Dedicated ports are coming soon and not on sale yet. Paid in cryptocurrency. This stdio MCP server (npm package @portproof/mcp) exposes the Portproof API (base `PORTPROOF_API_URL` + `/v1`, default https://api.portproof.org; key `PORTPROOF_API_KEY`) as seventeen tools.
+> Proxy traffic by the GB: one prepaid GB balance per organisation, usable on two shared pools, mobile 4G/5G (carrier modems) and residential (opt-in peer devices). Pool, country, rotation and session are chosen in the proxy username, so one credential serves everything. The pools are shared: the traffic is never dedicated, private, static or unlimited, and a sticky session keeps the same device while the carrier may still change its IP. Countries online now come from list_countries; never state a country count from memory. Dedicated ports are coming soon and not on sale yet. Paid in cryptocurrency. This stdio MCP server (npm package @portproof/mcp) exposes the Portproof API (base `PORTPROOF_API_URL` + `/v1`, default https://api.portproof.org; key `PORTPROOF_API_KEY`) as nineteen tools.
 
 ## Traffic tools
 
@@ -12,24 +12,26 @@
 
 ## Port tools (dedicated ports: coming soon, not on sale yet)
 
-- get_pricing {} -> field traffic (per-GB tier table, packages, trial, validity) and field skus (port price table). Public.
-- search_inventory { country?, carrier? } -> available ports per site/carrier with carrier_id. Public.
-- quote { sku, term, quantity } -> unit_cents, discount_pct, total_cents, currency, charged:false. Public.
-- buy_port { sku, term, carrier_id?, auto_renew?, confirm:true, idempotency_key } -> port, proxy_urls, cost_cents, currency. Charges money.
-- list_ports { limit?, cursor? } -> compact port summaries (no credentials), next_cursor.
-- get_port { port_id } -> full Port with credentials (if owned) and proxy_urls.
-- rotate { port_id, confirm:true, idempotency_key } -> rotated, reason, old_ip4, new_ip4, elapsed_ms and the signed rotation record. Waits up to 180 s. No charge.
+- get_pricing {} -> field traffic (per-GB tier table, packages, trial, validity) and field skus (port price table; buy_via ports or cart; Partner network SKUs only while on sale for the caller's organisation). Public.
+- search_inventory { country?, carrier? } -> available Own network ports per site/carrier with carrier_id. Public.
+- quote { sku, term, quantity } -> unit_cents, discount_pct, total_cents, currency, charged:false; for a Partner network SKU price_cents and shop_url instead, or not_on_sale. Public.
+- buy_port { sku, term, carrier_id?, auto_renew?, confirm:true, idempotency_key } -> port, proxy_urls, cost_cents, currency. Charges money. A Partner network SKU (buy_via "cart" in get_pricing) is bought in the web shop: the answer is purchased:false, charged:false, price_cents and shop_url, or not_on_sale.
+- list_ports { limit?, cursor? } -> compact port summaries (label, network, no credentials), next_cursor. A Partner network port has no site_code.
+- get_port { port_id } -> full Port with label, network, credentials (if owned; Partner network ports carry credentials.http and credentials.socks5, which may differ in every field), capabilities, renewal, rotation_url (the Portproof link that rotates the IP) and proxy_urls built from each protocol's own set.
+- rotate { port_id, confirm:true, idempotency_key } -> rotated, reason, old_ip4, new_ip4, elapsed_ms and the signed rotation record. Waits up to 180 s in all, following the status link when the first answer is 202; status pending with rotation_id when still running. No charge.
 - set_rotation_schedule { port_id, interval_s (0 = sticky, else 60..86400), confirm:true, idempotency_key } -> rotation_interval_s, sticky. No charge.
-- get_passport { port_id } -> port details (API object passport). Never credentials.
+- renew_port { port_id, confirm:true, idempotency_key } -> renewed, ends_at, auto_renew, cost_cents, currency. One more term from the account balance. Charges money.
+- set_auto_renew { port_id, enabled, confirm:true, idempotency_key } -> auto_renew, ends_at. Off: the port ends at the end of its term. No charge now.
+- get_passport { port_id } -> port details (API object passport) with label and network. Never credentials.
 - get_receipt { receipt_id } -> rotation record plus signature { verified, key_id, reason, keys_url } checked against <API origin>/.well-known/portproof-keys.json.
 - get_usage { port_id, from?, to?, granularity? } -> buckets, totals, data[]. Default granularity hour.
 - get_status {} -> platform, sites, carriers, public incidents, support. Public.
 
 ## Rules
 
-- buy_traffic, buy_port, rotate and set_rotation_schedule are refused (error code confirmation_required / idempotency_key_required, no API call made) unless confirm is exactly true and idempotency_key is a non-empty printable string; buy_traffic is also refused (terms_acceptance_required) without accept_terms: true. Ask the user before confirming. A refused purchase stays stored under its key for 24 h, so buy with a new key after fixing the cause. Reuse an idempotency_key only to retry the identical request; the API answers idempotency_conflict (409) when a key is reused for a different purchase.
-- cost_cents is present whenever money moved (buy_traffic, buy_port). quote never charges.
-- Every response is compact JSON in one text block. Errors: {"error":{code,status,title,detail,retry_after?,errors?}} using API problem codes: insufficient_funds, kyb_required_for_volume, trial_already_used, traffic_not_purchased, kyb_required, no_inventory, port_cooldown (retry_after seconds), rescore_quota, insufficient_scope, unauthorized, not_found, validation_failed, idempotency_conflict, rate_limited; local codes: confirmation_required, idempotency_key_required, terms_acceptance_required, api_unreachable, timeout, http_error, config_missing (no PORTPROOF_API_KEY), unexpected_response.
+- buy_traffic, buy_port, renew_port, rotate, set_rotation_schedule and set_auto_renew are refused (error code confirmation_required / idempotency_key_required, no API call made) unless confirm is exactly true and idempotency_key is a non-empty printable string; buy_traffic is also refused (terms_acceptance_required) without accept_terms: true. Ask the user before confirming. A refused purchase stays stored under its key for 24 h, so buy with a new key after fixing the cause. Reuse an idempotency_key only to retry the identical request; the API answers idempotency_conflict (409) when a key is reused for a different purchase.
+- cost_cents is present whenever money moved (buy_traffic, buy_port, renew_port). quote never charges.
+- Every response is compact JSON in one text block. Errors: {"error":{code,status,title,detail,retry_after?,errors?}} using API problem codes: insufficient_funds, kyb_required_for_volume, trial_already_used, traffic_not_purchased, kyb_required, no_inventory, use_cart, conflict, port_cooldown (retry_after seconds), rescore_quota, insufficient_scope, unauthorized, not_found, validation_failed, idempotency_conflict, rate_limited; local codes: confirmation_required, idempotency_key_required, terms_acceptance_required, not_on_sale, api_unreachable, timeout, http_error, config_missing (no PORTPROOF_API_KEY), unexpected_response.
 - Ids are prefixed ULIDs: prt_ ports, rot_ rotations (rotation records), car_ carriers, ord_ orders.
 - Money is integer cents in EUR (the us-4g port SKU is USD). Times are ISO 8601 UTC.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@portproof/mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "MCP server for Portproof: proxy traffic by the GB on shared mobile 4G/5G and residential pools, paid in crypto, as tools for AI agents",
   "keywords": [