portveil-mcp 0.2.1 → 0.4.0

package/README.md

@@ -15,15 +15,20 @@ 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 |
+| `add_device` | Add a device. Phones and laptops (WireGuard app): creates it and saves its tunnel files locally, key never shown in chat. Linux servers and agent machines: gives the exact commands to run on that machine, which makes its own key and registers itself | admin (phones/laptops) |
+| `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

@@ -10,7 +10,10 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { Portveil, PortveilError, VERSION, describeDevice, isWaiting, locationLabel, nextLocation, resolveDevice, resolveLocation, } from "./portveil.js";
+import { mkdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { Portveil, PortveilError, VERSION, agentSetup, describeDevice, wgConfig, wgKeypair, isWaiting, locationLabel, nextLocation, resolveDevice, resolveLocation, } from "./portveil.js";
 const accountId = process.env.PORTVEIL_ACCOUNT_ID?.trim() ?? "";
 const token = process.env.PORTVEIL_TOKEN?.trim() ?? "";
 if (!/^acct_[0-9a-f]{16}$/.test(accountId) || !token) {
@@ -20,7 +23,8 @@ if (!/^acct_[0-9a-f]{16}$/.test(accountId) || !token) {
 if (token.startsWith("cla_")) {
     console.error("portveil-mcp: warning: that's your account key. Create a scoped API token in the dashboard instead, so an assistant never holds full access.");
 }
-const pv = new Portveil({ apiBase: process.env.PORTVEIL_API || "https://api.portveil.com", accountId, token });
+const apiBase = (process.env.PORTVEIL_API || "https://api.portveil.com").replace(/\/+$/, "");
+const pv = new Portveil({ apiBase, accountId, token });
 const server = new McpServer({ name: "portveil", version: VERSION });
 const ok = (text) => ({ content: [{ type: "text", text }] });
 async function run(fn) {
@@ -32,10 +36,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 adding, 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 +52,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 +66,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 +99,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 +108,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 +127,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 +138,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 +152,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 +164,71 @@ 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("add_device", {
+    title: "Add device",
+    description: "Add a new device to the account. kind \"phone_or_computer\" (iPhone, Android, Mac, Windows using the WireGuard app): creates the device now and saves one WireGuard tunnel file per location, with a private key made locally, into a folder on the machine running this MCP server; the key is never shown in the reply. Import a file in the WireGuard app to connect. These devices are view-only: they can't be moved remotely. kind \"linux_machine\" (a server or the machine an agent runs on): returns the exact commands to run as root on that machine; it makes its own key and registers itself, and can then be moved, rotated and switched with the other tools. Uses one device slot (see get_account). Needs an admin-scope token for phone_or_computer.",
+    inputSchema: {
+        name: z.string().trim().min(1).max(64).describe('Display name for the new device, e.g. "Miguel iPhone" or "scraper-box"'),
+        kind: z.enum(["phone_or_computer", "linux_machine"]).describe("phone_or_computer: WireGuard app on a phone or laptop. linux_machine: a Linux server or agent machine running the Portveil agent"),
+        temporary_minutes: z.number().int().min(5).max(43200).optional().describe("phone_or_computer only: delete the device automatically after this many minutes (5 to 43200, i.e. 30 days). Omit for a permanent device"),
+        folder: z.string().min(1).optional().describe("phone_or_computer only: folder to save the tunnel files in. Default ~/Portveil/<name>"),
+        split_tunnel: z.boolean().optional().describe("linux_machine only: default true, so a remote server keeps its SSH session. false sends all of its traffic through Portveil"),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+}, ({ name, kind, temporary_minutes, folder, split_tunnel }) => run(async () => {
+    const acct = await pv.account();
+    const slots = acct.device_limit === null ? "" : ` (${acct.device_count} of ${acct.device_limit} devices used)`;
+    if (acct.device_limit !== null && acct.device_count >= acct.device_limit) {
+        throw new PortveilError(`The plan's device limit is reached${slots}. Remove a device or upgrade first.`);
+    }
+    if (kind === "linux_machine") {
+        return `Run these as root on the machine you're adding. It makes its own VPN key, so this can't be done from here. The token prompt doesn't echo; use an admin-scope API token or the account key, and never paste it into a chat.\n\n` +
+            agentSetup(apiBase, accountId, name, split_tunnel ?? true) +
+            `\n\nThe daemon keeps running; install it as a service to survive reboots. "${name}" then appears in list_devices, and can be moved once its exit confirms it${slots}.`;
+    }
+    const dir = resolve(folder?.replace(/^~(?=$|\/)/, homedir()) ?? join(homedir(), "Portveil", name.replace(/[^\w .-]+/g, "_")));
+    const k = wgKeypair();
+    const d = await pv.addDevice(name, "wireguard-app", k.pub, false, temporary_minutes);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    const files = [];
+    for (const s of d.servers) {
+        const addr = d.addresses[s.id];
+        if (!addr)
+            continue;
+        const file = join(dir, `Portveil-${locationLabel(s).replace(/[^\w .()-]+/g, "_")}.conf`);
+        await writeFile(file, wgConfig(k.priv, addr, s), { mode: 0o600 });
+        files.push(file);
+    }
+    const expires = d.expires_at ? ` It deletes itself at ${new Date(d.expires_at * 1000).toISOString().replace(".000Z", "Z")}.` : "";
+    return `Added "${name}" [${d.device_id}].${expires} Its tunnel files are saved on the machine running this MCP server, one per location:\n` +
+        files.map((f) => `- ${f}`).join("\n") +
+        `\n\nOn a Mac or PC: WireGuard → Import tunnel(s) from file. On a phone: send the files to it (AirDrop, or save to Files) and open them with WireGuard. The files hold the device's private key: keep them private and delete copies once imported. Switch countries by turning on a different tunnel in the app.`;
 }));
-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("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("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,12 +1,38 @@
 // 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";
+import { generateKeyPairSync } from "node:crypto";
+export const VERSION = "0.4.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)
         return "idle";
     return `↓ ${speed.down_mbps.toFixed(1)} Mbps ↑ ${speed.up_mbps.toFixed(1)} Mbps`;
 }
+/** A fresh WireGuard keypair (base64), made locally: the private key never leaves this machine. */
+export function wgKeypair() {
+    const { publicKey, privateKey } = generateKeyPairSync("x25519");
+    const raw = (der) => der.subarray(der.length - 32).toString("base64");
+    return { priv: raw(privateKey.export({ format: "der", type: "pkcs8" })), pub: raw(publicKey.export({ format: "der", type: "spki" })) };
+}
+/** The WireGuard app tunnel file for one exit, the same as the setup page makes. */
+export function wgConfig(priv, address, s) {
+    return `[Interface]\nPrivateKey = ${priv}\nAddress = ${address.split("/")[0]}/32\nDNS = 1.1.1.1, 9.9.9.9\nMTU = 1420\n\n` +
+        `[Peer]\nPublicKey = ${s.pubkey}\nEndpoint = ${s.endpoint_host}:${s.endpoint_port}\n` +
+        `AllowedIPs = 0.0.0.0/0, ::/0\nPersistentKeepalive = 25\n`;
+}
+/** Commands that set up a Linux machine as a Portveil device. It makes its own key, so they run on that machine. */
+export function agentSetup(apiBase, accountId, name, splitTunnel) {
+    const q = (v) => `'${v.replace(/'/g, `'\\''`)}'`;
+    return [
+        "apt install -y wireguard-tools curl",
+        "curl -fsSLO https://portveil.com/downloads/portveil-agent",
+        "curl -fsSL https://portveil.com/downloads/portveil-agent.sha256 | sha256sum -c -",
+        "chmod +x portveil-agent",
+        "read -rsp 'Admin API token or account key: ' PORTVEIL_ACCOUNT_TOKEN && export PORTVEIL_ACCOUNT_TOKEN && echo",
+        `./portveil-agent register --control ${apiBase} --account-id ${accountId} --name ${q(name)}${splitTunnel ? " --split-tunnel" : ""}`,
+        "./portveil-agent daemon",
+    ].join("\n");
+}
 export class PortveilError extends Error {
 }
 /** A command the device hasn't finished yet: queued (not picked up) or delivered (working on it). */
@@ -142,6 +168,33 @@ 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));
+    }
+    /** Register a device with a public key made elsewhere. Needs an admin-scope token. */
+    async addDevice(name, platform, pubkey, allowRemote, ttlMinutes) {
+        const body = { name, platform, peer_pubkey: pubkey, allow_remote: allowRemote };
+        if (ttlMinutes !== undefined)
+            body.ttl_minutes = ttlMinutes;
+        return this.adminOnly(() => this.call("POST", `${this.acct()}/devices`, 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('Adding, 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 +229,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 +239,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.4.0",
   "description": "MCP server for Portveil: let AI assistants see your devices and move them between VPN locations.",
   "license": "MIT",
   "type": "module",