portveil-mcp 0.3.0 → 0.4.1

package/README.md

@@ -24,6 +24,7 @@ Moves are verified: a tool only reports success after the device has switched **
 | `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 |
 

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) {
@@ -35,7 +39,7 @@ async function run(fn) {
 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.
+// 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, 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.",
@@ -60,7 +64,7 @@ server.registerTool("get_device", {
     const [devices, servers] = await Promise.all([pv.devices(), pv.servers()]);
     const d = resolveDevice(device, devices);
     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}.`;
+    return `${describeDevice(d, servers)}\nLast report: ${seen}.${d.status_detail ? `\n${d.status_detail}` : ""}`;
 }));
 server.registerTool("get_account", {
     title: "Get account",
@@ -160,6 +164,46 @@ 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("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("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.",

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.3.0";
+import { generateKeyPairSync } from "node:crypto";
+export const VERSION = "0.4.1";
 /** "↓ 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). */
@@ -28,6 +54,8 @@ export function describeDevice(d, servers) {
         state = "offline";
     else if (d.exit_confirmed && d.quality === "good")
         state = `protected, exiting in ${place}`;
+    else if (d.exit_confirmed && d.quality === "fair")
+        state = `idle: tunnel to ${place} confirmed but no traffic right now (it resumes on the device's next use)`;
     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";
@@ -147,6 +175,13 @@ export class Portveil {
         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)}`));
@@ -157,7 +192,7 @@ export class Portveil {
         }
         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 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;
         }

package/package.json

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