portveil-mcp 0.2.1 → 0.3.0

package/README.md

@@ -15,15 +15,19 @@ Moves are verified: a tool only reports success after the device has switched **
 |---|---|---|
 | `list_devices` | Every device: protected or not, where it exits, live speed (↓/↑ Mbps), remote control on/off | read |
 | `list_locations` | The locations you can move to | read |
-| `device_status` | One device's current state, including live speed | read |
-| `account_info` | Plan and devices used | read |
-| `recent_activity` | Recent moves, reconnects and changes, and who made them | read |
+| `get_device` | One device's current state, including live speed and any rotation | read |
+| `get_account` | Plan and devices used | read |
+| `list_activity` | Recent moves, reconnects and changes, and which token 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 |
+| `rotate_device` | Move a device once to the next location | control |
+| `start_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 (flagged destructive: a hint that tells well-behaved assistants to check with you first) | control |
+| `update_device` | Rename a device and/or turn its remote control on or off | admin |
+| `remove_device` | Remove a device for good (flagged destructive) | admin |
+
+Tool names changed in 0.3.0 to one verb_noun pattern: `device_status` → `get_device`, `account_info` → `get_account`, `recent_activity` → `list_activity`, `set_rotation` → `start_rotation`.
 
 Devices can be named loosely ("scraper" finds "Scraper box"); an ambiguous name returns the choices instead of guessing.
 

package/dist/index.js

@@ -32,10 +32,13 @@ async function run(fn) {
         return { content: [{ type: "text", text: msg }], isError: true };
     }
 }
-const deviceArg = z.string().min(1).describe('Device name (or part of it, e.g. "scraper") or its device ID (dev_…)');
+const deviceArg = z.string().min(1).describe('Which device: its name, a unique part of its name (e.g. "scraper"), or its device ID (dev_…). Case-insensitive. Get names and IDs from list_devices.');
+// Tool names follow one verb_noun pattern: list_*, get_*, and an action verb + device/rotation.
+// Scopes: "read" tokens can use the list_/get_ tools; "control" adds moving, rotating, reconnecting
+// and disconnecting; "admin" adds renaming, remote-control settings and removal.
 server.registerTool("list_devices", {
     title: "List devices",
-    description: "List every device on the Portveil account: whether each is protected, which country its traffic exits from, and whether it accepts remote control.",
+    description: "List every device on the Portveil account, one line each: whether it's protected (connected AND confirmed by the exit server), which country it exits from, its live download/upload speed while connected, and whether it accepts remote control. Use this first to see what's there or to find a device's exact name; use get_device for one device. Read-only.",
     annotations: { readOnlyHint: true, openWorldHint: false },
 }, () => run(async () => {
     const [devices, servers] = await Promise.all([pv.devices(), pv.servers()]);
@@ -45,12 +48,12 @@ server.registerTool("list_devices", {
 }));
 server.registerTool("list_locations", {
     title: "List locations",
-    description: "List the VPN exit locations (countries) a device can be moved to.",
+    description: "List the exit locations (country, city and location ID) that devices can be moved to. Use it before move_device or start_rotation when you're unsure what's available. Every plan can use every location. Read-only.",
     annotations: { readOnlyHint: true, openWorldHint: false },
 }, () => run(async () => (await pv.servers()).map((s) => `- ${locationLabel(s)} [${s.id}]`).join("\n")));
-server.registerTool("device_status", {
-    title: "Device status",
-    description: "Show one device's current state: connected or not, the location it exits from, and whether the exit server confirms it.",
+server.registerTool("get_device", {
+    title: "Get device",
+    description: "Get one device's current state: online or offline, the location it exits from, whether that exit server confirms the tunnel, its live speed, any rotation schedule, and when it last reported. Use it to check a device before or after an action. Read-only.",
     inputSchema: { device: deviceArg },
     annotations: { readOnlyHint: true, openWorldHint: false },
 }, ({ device }) => run(async () => {
@@ -59,12 +62,32 @@ server.registerTool("device_status", {
     const seen = d.last_seen_s_ago == null ? "never" : `${Math.round(d.last_seen_s_ago)}s ago`;
     return `${describeDevice(d, servers)}\nLast report: ${seen}.`;
 }));
+server.registerTool("get_account", {
+    title: "Get account",
+    description: "Get the account's plan and how many devices it uses out of its limit. Use it when asked about the plan or before suggesting adding devices. Read-only.",
+    annotations: { readOnlyHint: true, openWorldHint: false },
+}, () => run(async () => {
+    const a = await pv.account();
+    return `Plan: ${a.plan ?? "none"}. Devices: ${a.device_count}${a.device_limit ? ` of ${a.device_limit}` : ""}.`;
+}));
+server.registerTool("list_activity", {
+    title: "List activity",
+    description: "List recent actions on the account (moves, reconnects, rotations, renames, tokens created), newest first, with the token that made each. Use it to answer \"what changed?\" or to audit an assistant's actions. Read-only.",
+    inputSchema: { limit: z.number().int().min(1).max(100).default(20).describe("How many entries to return, newest first (1–100, default 20)") },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+}, ({ limit }) => run(async () => {
+    const [{ entries }, devices] = await Promise.all([pv.audit(limit), pv.devices()]);
+    if (entries.length === 0)
+        return "No activity yet.";
+    const name = (id) => (id ? devices.find((d) => d.device_id === id)?.name ?? id : "account");
+    return entries.map((e) => `- ${new Date(e.created_at * 1000).toISOString().replace(".000Z", "Z")}  ${e.action}  ${name(e.device_id)}  (by ${e.issued_by})`).join("\n");
+}));
 server.registerTool("move_device", {
-    title: "Move device to a location",
-    description: "Move a device's VPN traffic to exit from another country. Waits until the device switches and the new exit server confirms it (usually 10–30 s). Needs a token with control scope and remote control enabled on the device.",
+    title: "Move device",
+    description: "Move a device's traffic to exit from a chosen location. Waits until the device switches and the new exit server confirms it (usually 10–30 s), and says plainly if that didn't happen. Safe to repeat: moving to where it already is does nothing. Only works on machines running the Portveil agent with remote control on (phones using the WireGuard app switch on the device itself). Needs a control-scope token. To just go somewhere different, use rotate_device.",
     inputSchema: {
         device: deviceArg,
-        location: z.string().min(1).describe('Where to exit: a country or city ("Finland", "US", "Helsinki") or a location ID (srv-eu-1)'),
+        location: z.string().min(1).describe('Where to exit: a country, city or region ("Finland", "US", "Helsinki") or a location ID from list_locations (e.g. srv-eu-1)'),
     },
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
 }, ({ device, location }) => run(async () => {
@@ -72,8 +95,8 @@ server.registerTool("move_device", {
     return pv.move(resolveDevice(device, devices), resolveLocation(location, servers));
 }));
 server.registerTool("rotate_device", {
-    title: "Rotate device to the next location",
-    description: "Move a device to the next available location, so its traffic exits from somewhere new. Waits for the move to be confirmed.",
+    title: "Rotate device",
+    description: "Move a device once to the next location in the list, so its traffic exits from somewhere new. Same checks and waiting as move_device. Each call moves again, so it isn't idempotent. For repeated automatic moves use start_rotation instead. Needs a control-scope token.",
     inputSchema: { device: deviceArg },
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
 }, ({ device }) => run(async () => {
@@ -81,13 +104,13 @@ 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.",
+server.registerTool("start_rotation", {
+    title: "Start rotation",
+    description: "Make Portveil move a device to the next location automatically every N minutes, optionally cycling through chosen locations only. Portveil runs the schedule itself, so the assistant doesn't need to stay running. Calling it again replaces the schedule. Stop it with stop_rotation. Needs a control-scope token and a Portveil-agent device.",
     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.'),
+        every_minutes: z.number().int().min(5).max(10080).describe("Minutes between moves: 5 to 10080 (one week)"),
+        locations: z.array(z.string().min(1)).optional().describe('Locations to cycle through, e.g. ["US", "Finland"]; at least two. Omit to cycle through every location.'),
     },
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
 }, ({ device, every_minutes, locations }) => run(async () => {
@@ -100,8 +123,8 @@ server.registerTool("set_rotation", {
     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.",
+    title: "Stop rotation",
+    description: "Turn off a device's automatic rotation. The device stays at its current location. Safe to call when no rotation is set. Needs a control-scope token.",
     inputSchema: { device: deviceArg },
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
 }, ({ device }) => run(async () => {
@@ -111,7 +134,7 @@ server.registerTool("stop_rotation", {
 }));
 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.",
+    description: "Tell a device to re-establish its VPN tunnel at its current location, without moving it. Use when it shows connected but not confirmed, or traffic seems stuck. Traffic may pause for a few seconds. Needs a control-scope token and a Portveil-agent device.",
     inputSchema: { device: deviceArg },
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
 }, ({ device }) => run(async () => {
@@ -125,7 +148,7 @@ server.registerTool("reconnect_device", {
 }));
 server.registerTool("disconnect_device", {
     title: "Disconnect device",
-    description: "Turn off a device's VPN tunnel. Its traffic stops going through Portveil until it reconnects. Confirm with the user before using this.",
+    description: "Turn off a device's VPN tunnel. Its traffic stops going through Portveil (and loses VPN protection) until it reconnects. The device stays on the account. Confirm with the user first. Needs a control-scope token and a Portveil-agent device.",
     inputSchema: { device: deviceArg },
     annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
 }, ({ device }) => run(async () => {
@@ -137,24 +160,31 @@ server.registerTool("disconnect_device", {
         return `Sent. ${d.name} hasn't picked it up yet (it may be offline).`;
     return `${d.name} did not disconnect: ${st.status}${st.result ? ` (${st.result})` : ""}.`;
 }));
-server.registerTool("recent_activity", {
-    title: "Recent activity",
-    description: "Show recent actions on the account (moves, reconnects, renames, tokens created), newest first, with who issued each.",
-    inputSchema: { limit: z.number().int().min(1).max(100).default(20).describe("How many entries (1–100)") },
-    annotations: { readOnlyHint: true, openWorldHint: false },
-}, ({ limit }) => run(async () => {
-    const [{ entries }, devices] = await Promise.all([pv.audit(limit), pv.devices()]);
-    if (entries.length === 0)
-        return "No activity yet.";
-    const name = (id) => (id ? devices.find((d) => d.device_id === id)?.name ?? id : "account");
-    return entries.map((e) => `- ${new Date(e.created_at * 1000).toISOString().replace(".000Z", "Z")}  ${e.action}  ${name(e.device_id)}  (by ${e.issued_by})`).join("\n");
+server.registerTool("update_device", {
+    title: "Update device",
+    description: "Rename a device and/or turn remote control on or off for it. Turning remote control off stops move, rotate, reconnect and disconnect for that device until it's turned back on. Change only what's given; safe to repeat. Needs an admin-scope token.",
+    inputSchema: {
+        device: deviceArg,
+        name: z.string().min(1).max(64).optional().describe("New display name, 1–64 characters"),
+        remote_control: z.boolean().optional().describe("true lets tokens move and control this device; false blocks it"),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+}, ({ device, name, remote_control }) => run(async () => {
+    if (name === undefined && remote_control === undefined)
+        throw new PortveilError("Nothing to change: give a new name, remote_control, or both.");
+    const d = resolveDevice(device, await pv.devices());
+    const u = await pv.updateDevice(d.device_id, { name, allow_remote: remote_control });
+    const parts = [name !== undefined ? `renamed to "${u.name ?? name}"` : "", remote_control !== undefined ? `remote control ${remote_control ? "on" : "off"}` : ""].filter(Boolean);
+    return `${d.name}: ${parts.join(", ")}.`;
 }));
-server.registerTool("account_info", {
-    title: "Account info",
-    description: "Show the account's plan and how many devices it uses out of its limit.",
-    annotations: { readOnlyHint: true, openWorldHint: false },
-}, () => run(async () => {
-    const a = await pv.account();
-    return `Plan: ${a.plan ?? "none"}. Devices: ${a.device_count}${a.device_limit ? ` of ${a.device_limit}` : ""}.`;
+server.registerTool("remove_device", {
+    title: "Remove device",
+    description: "Permanently remove a device from the account: its VPN key stops working at every exit and its slot is freed. It can't be undone; the device would have to be set up again. Confirm with the user first, naming the device. Needs an admin-scope token.",
+    inputSchema: { device: deviceArg },
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
+}, ({ device }) => run(async () => {
+    const d = resolveDevice(device, await pv.devices());
+    await pv.removeDevice(d.device_id);
+    return `${d.name} was removed from the account. Its VPN key no longer works.`;
 }));
 await server.connect(new StdioServerTransport());

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.2.1";
+export const VERSION = "0.3.0";
 /** "↓ 42.3 Mbps ↑ 6.1 Mbps", or "idle" when nothing is moving. */
 export function describeSpeed(speed) {
     if (speed.down_mbps < 0.1 && speed.up_mbps < 0.1)
@@ -142,6 +142,26 @@ export class Portveil {
         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);
     }
+    /** Rename a device and/or switch remote control. Needs an admin-scope token. */
+    async updateDevice(deviceId, change) {
+        const body = Object.fromEntries(Object.entries(change).filter(([, v]) => v !== undefined));
+        return this.adminOnly(() => this.call("PATCH", `${this.acct()}/devices/${encodeURIComponent(deviceId)}`, body));
+    }
+    /** Remove a device for good (its key stops working everywhere). Needs an admin-scope token. */
+    async removeDevice(deviceId) {
+        await this.adminOnly(() => this.call("DELETE", `${this.acct()}/devices/${encodeURIComponent(deviceId)}`));
+    }
+    async adminOnly(fn) {
+        try {
+            return await fn();
+        }
+        catch (e) {
+            if (e instanceof PortveilError && /refused this with your token|isn't allowed to do that/.test(e.message)) {
+                throw new PortveilError('Renaming, changing remote control or removing devices needs an API token with "admin" scope. Create one in the dashboard, or make the change there.');
+            }
+            throw e;
+        }
+    }
     async commandState(id) {
         return this.call("GET", `${this.acct()}/commands/${encodeURIComponent(id)}`);
     }
@@ -176,7 +196,7 @@ export class Portveil {
             return `${device.name} is already exiting in ${place}; nothing to do.`;
         const st = await this.runCommand(device, "switch_server", target);
         if (st.status === "delivered") {
-            return `${device.name} is switching to ${place} but hasn't reported back yet. Check with device_status in a minute.`;
+            return `${device.name} is switching to ${place} but hasn't reported back yet. Check with get_device in a minute.`;
         }
         if (isWaiting(st.status)) {
             return `Sent. ${device.name} hasn't picked up the move to ${place} yet (it may be offline); it will when it's next online, until the command expires.`;
@@ -186,6 +206,6 @@ export class Portveil {
         const confirmed = await this.waitConfirmed(device.device_id, target.id);
         return confirmed
             ? `Done. ${device.name} now exits in ${place}, confirmed by the ${place} exit server.`
-            : `${device.name} switched to ${place}, but that exit hasn't confirmed the connection yet. Check again with device_status in a minute.`;
+            : `${device.name} switched to ${place}, but that exit hasn't confirmed the connection yet. Check again with get_device in a minute.`;
     }
 }

package/package.json

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