portveil-mcp 0.1.1 → 0.2.0

package/README.md

@@ -5,6 +5,7 @@ Let an AI assistant see the devices on your [Portveil](https://portveil.com) acc
 > "Move my scraper box to Finland."
 > "Rotate every agent to a new location."
 > "Which of my devices aren't protected right now?"
+> "Rotate the scraper between the US and Finland every 15 minutes."
 
 Moves are verified: a tool only reports success after the device has switched **and** the exit server in the new location confirms it sees that device.
 
@@ -19,8 +20,10 @@ Moves are verified: a tool only reports success after the device has switched **
 | `recent_activity` | Recent moves, reconnects and changes, and who made them | read |
 | `move_device` | Move a device to a country or city ("Finland", "US", "Helsinki") | control |
 | `rotate_device` | Move a device to the next location | control |
+| `set_rotation` | Move a device automatically every N minutes (5–10080), optionally among chosen locations. Portveil runs the schedule, so the assistant can close | control |
+| `stop_rotation` | Turn scheduled rotation off | control |
 | `reconnect_device` | Re-establish a device's tunnel | control |
-| `disconnect_device` | Turn a device's VPN off (marked destructive, so assistants ask first) | control |
+| `disconnect_device` | Turn a device's VPN off (flagged destructive: a hint that tells well-behaved assistants to check with you first) | control |
 
 Devices can be named loosely ("scraper" finds "Scraper box"); an ambiguous name returns the choices instead of guessing.
 

package/dist/index.js

@@ -81,6 +81,34 @@ server.registerTool("rotate_device", {
     const d = resolveDevice(device, devices);
     return pv.move(d, nextLocation(d.server_id, servers));
 }));
+server.registerTool("set_rotation", {
+    title: "Rotate a device on a schedule",
+    description: "Make Portveil move a device to the next location automatically every N minutes (5 to 10080), optionally cycling only through some locations. Portveil does the moves itself, so the assistant doesn't need to stay running. Needs control scope.",
+    inputSchema: {
+        device: deviceArg,
+        every_minutes: z.number().int().min(5).max(10080).describe("Minutes between moves (5 to 10080)"),
+        locations: z.array(z.string().min(1)).optional().describe('Locations to cycle through, e.g. ["US", "Finland"]. Omit for every location.'),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+}, ({ device, every_minutes, locations }) => run(async () => {
+    const [devices, servers] = await Promise.all([pv.devices(), pv.servers()]);
+    const d = resolveDevice(device, devices);
+    const chosen = locations?.map((l) => resolveLocation(l, servers));
+    const r = await pv.setRotation(d.device_id, every_minutes, chosen?.map((s) => s.id));
+    const where = chosen ? chosen.map(locationLabel).join(" → ") : "every location";
+    const next = r.next_rotation_at ? ` First move around ${new Date(r.next_rotation_at * 1000).toISOString().replace(".000Z", "Z")}.` : "";
+    return `${d.name} will now move every ${every_minutes} minutes, cycling through ${where}.${next}`;
+}));
+server.registerTool("stop_rotation", {
+    title: "Stop scheduled rotation",
+    description: "Turn off automatic rotation for a device. It stays at its current location.",
+    inputSchema: { device: deviceArg },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+}, ({ device }) => run(async () => {
+    const d = resolveDevice(device, await pv.devices());
+    await pv.setRotation(d.device_id, null);
+    return `${d.name} will no longer rotate automatically. It stays where it is.`;
+}));
 server.registerTool("reconnect_device", {
     title: "Reconnect device",
     description: "Tell a device to re-establish its VPN tunnel at its current location. Useful when it shows as connected but not confirmed.",

package/dist/portveil.js

@@ -1,6 +1,6 @@
 // Portveil API client and the logic behind the MCP tools. No MCP types here,
 // so it can be tested against a fake API.
-export const VERSION = "0.1.1";
+export const VERSION = "0.2.0";
 export class PortveilError extends Error {
 }
 /** A command the device hasn't finished yet: queued (not picked up) or delivered (working on it). */
@@ -25,7 +25,12 @@ export function describeDevice(d, servers) {
     else
         state = `connected to ${place}, not yet confirmed by the exit`;
     const remote = d.platform === "wireguard-app" ? "view only (WireGuard app)" : d.allow_remote ? "remote control on" : "remote control off";
-    return `${d.name} [${d.device_id}] (${d.platform}): ${state}; ${remote}`;
+    const extras = [];
+    if (d.rotation)
+        extras.push(`rotates every ${d.rotation.every_minutes} min`);
+    if (d.expires_at)
+        extras.push(`temporary, deleted ${new Date(d.expires_at * 1000).toISOString().replace(".000Z", "Z")}`);
+    return `${d.name} [${d.device_id}] (${d.platform}): ${state}; ${remote}${extras.length ? `; ${extras.join("; ")}` : ""}`;
 }
 /** Match a device by id, exact name, or a unique partial name (case-insensitive). */
 export function resolveDevice(query, devices) {
@@ -106,6 +111,7 @@ export class Portveil {
                 ? "Portveil rejected the token. Check PORTVEIL_TOKEN (an API token from the dashboard)."
                 : 'Portveil refused this with your token. Moving, reconnecting or disconnecting devices needs an API token with "control" scope; a "read" token can only look.');
             case 403: throw new PortveilError(`This token isn't allowed to do that${detail ? ` (${detail})` : ""}. Moving or reconnecting devices needs a token with "control" scope.`);
+            case 400: throw new PortveilError(detail || "Portveil rejected the request.");
             case 404: throw new PortveilError("Not found. Check PORTVEIL_ACCOUNT_ID matches the token's account.");
             case 409: throw new PortveilError(detail === "remote_disabled" ? "That device has remote control turned off, so it can't be controlled from here." : `Conflict: ${detail || text}`);
             case 429: throw new PortveilError(`Portveil is rate limiting requests; try again in ${res.headers.get("retry-after") ?? "a few"} seconds.`);
@@ -123,6 +129,11 @@ export class Portveil {
         const c = await this.call("POST", `${this.acct()}/devices/${encodeURIComponent(deviceId)}/commands`, serverId ? { type, server_id: serverId } : { type });
         return { command_id: c.command_id, status: c.status, result: null };
     }
+    /** Turn scheduled rotation on (every N minutes, optionally among some locations) or off (null). */
+    async setRotation(deviceId, everyMinutes, servers) {
+        const body = everyMinutes === null ? { every_minutes: null } : servers?.length ? { every_minutes: everyMinutes, servers } : { every_minutes: everyMinutes };
+        return this.call("PUT", `${this.acct()}/devices/${encodeURIComponent(deviceId)}/rotation`, body);
+    }
     async commandState(id) {
         return this.call("GET", `${this.acct()}/commands/${encodeURIComponent(id)}`);
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "portveil-mcp",
   "mcpName": "io.github.roybogs/portveil-mcp",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "MCP server for Portveil: let AI assistants see your devices and move them between VPN locations.",
   "license": "MIT",
   "type": "module",