portveil-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Streetside Films LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# Portveil MCP server
+
+Let an AI assistant see the devices on your [Portveil](https://portveil.com) account and move them between VPN locations.
+
+> "Move my scraper box to Finland."
+> "Rotate every agent to a new location."
+> "Which of my devices aren't protected right now?"
+
+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.
+
+## Tools
+
+| Tool | What it does | Needs |
+|---|---|---|
+| `list_devices` | Every device: protected or not, where it exits, remote control on/off | read |
+| `list_locations` | The locations you can move to | read |
+| `device_status` | One device's current state | read |
+| `account_info` | Plan and devices used | read |
+| `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 |
+| `reconnect_device` | Re-establish a device's tunnel | control |
+| `disconnect_device` | Turn a device's VPN off (marked destructive, so assistants ask first) | control |
+
+Devices can be named loosely ("scraper" finds "Scraper box"); an ambiguous name returns the choices instead of guessing.
+
+## Setup
+
+1. In the [Portveil dashboard](https://portveil.com/dashboard/), create an **API token**. Choose **control** scope to let the assistant move devices, or **read** to let it only look. Don't give it your account key.
+2. Note your account ID (`acct_…`).
+3. Add the server to your assistant:
+
+**Claude Code**
+```bash
+claude mcp add portveil -e PORTVEIL_ACCOUNT_ID=acct_… -e PORTVEIL_TOKEN=clt_… -- npx -y portveil-mcp
+```
+
+**Claude Desktop** (`claude_desktop_config.json`), **Cursor** (`.cursor/mcp.json`) and most other clients:
+```json
+{
+  "mcpServers": {
+    "portveil": {
+      "command": "npx",
+      "args": ["-y", "portveil-mcp"],
+      "env": { "PORTVEIL_ACCOUNT_ID": "acct_…", "PORTVEIL_TOKEN": "clt_…" }
+    }
+  }
+}
+```
+
+Devices must be running the Portveil app or the Portveil agent with remote control on. Devices using the plain WireGuard app are shown but can't be moved.
+
+## Security
+
+- Use a scoped API token. Every action it takes is recorded in your account's activity log with the token that made it, and you can revoke it in the dashboard at any time.
+- The server talks only to `https://api.portveil.com` (override with `PORTVEIL_API`). It stores nothing.
+
+## Development
+
+```bash
+npm install
+npm test        # builds, then runs the tests against a fake Portveil API
+```

package/dist/index.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+// Portveil MCP server (stdio). Lets an AI assistant see the devices on a
+// Portveil account and move them between VPN locations.
+//
+// Configuration (environment):
+//   PORTVEIL_ACCOUNT_ID  acct_…  (dashboard → Settings)
+//   PORTVEIL_TOKEN       an API token from the dashboard. "read" scope can look;
+//                        "control" scope can also move, reconnect and disconnect.
+//   PORTVEIL_API         optional, defaults to https://api.portveil.com
+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";
+const accountId = process.env.PORTVEIL_ACCOUNT_ID?.trim() ?? "";
+const token = process.env.PORTVEIL_TOKEN?.trim() ?? "";
+if (!/^acct_[0-9a-f]{16}$/.test(accountId) || !token) {
+    console.error("portveil-mcp: set PORTVEIL_ACCOUNT_ID (acct_…) and PORTVEIL_TOKEN (an API token from https://portveil.com/dashboard/).");
+    process.exit(1);
+}
+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 server = new McpServer({ name: "portveil", version: VERSION });
+const ok = (text) => ({ content: [{ type: "text", text }] });
+async function run(fn) {
+    try {
+        return ok(await fn());
+    }
+    catch (e) {
+        const msg = e instanceof PortveilError ? e.message : `Unexpected error: ${e.message}`;
+        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_…)');
+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.",
+    annotations: { readOnlyHint: true, openWorldHint: false },
+}, () => run(async () => {
+    const [devices, servers] = await Promise.all([pv.devices(), pv.servers()]);
+    if (devices.length === 0)
+        return "No devices on this account yet. Add one at https://portveil.com/start/";
+    return devices.map((d) => "- " + describeDevice(d, servers)).join("\n");
+}));
+server.registerTool("list_locations", {
+    title: "List locations",
+    description: "List the VPN exit locations (countries) a device can be moved to.",
+    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.",
+    inputSchema: { device: deviceArg },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+}, ({ device }) => run(async () => {
+    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}.`;
+}));
+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.",
+    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)'),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+}, ({ device, location }) => run(async () => {
+    const [devices, servers] = await Promise.all([pv.devices(), pv.servers()]);
+    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.",
+    inputSchema: { device: deviceArg },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+}, ({ device }) => run(async () => {
+    const [devices, servers] = await Promise.all([pv.devices(), pv.servers()]);
+    const d = resolveDevice(device, devices);
+    return pv.move(d, nextLocation(d.server_id, servers));
+}));
+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.",
+    inputSchema: { device: deviceArg },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+}, ({ device }) => run(async () => {
+    const d = resolveDevice(device, await pv.devices());
+    const st = await pv.runCommand(d, "reconnect");
+    if (st.status === "acked")
+        return `${d.name} reconnected.`;
+    if (isWaiting(st.status))
+        return `Sent. ${d.name} hasn't picked it up yet (it may be offline).`;
+    return `${d.name} did not reconnect: ${st.status}${st.result ? ` (${st.result})` : ""}.`;
+}));
+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.",
+    inputSchema: { device: deviceArg },
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+}, ({ device }) => run(async () => {
+    const d = resolveDevice(device, await pv.devices());
+    const st = await pv.runCommand(d, "disconnect");
+    if (st.status === "acked")
+        return `${d.name} is disconnected. Its traffic no longer goes through Portveil.`;
+    if (isWaiting(st.status))
+        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("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}` : ""}.`;
+}));
+await server.connect(new StdioServerTransport());

package/dist/portveil.js

@@ -0,0 +1,172 @@
+// 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.0";
+export class PortveilError extends Error {
+}
+/** A command the device hasn't finished yet: queued (not picked up) or delivered (working on it). */
+export const isWaiting = (status) => status === "queued" || status === "delivered" || status === "pending";
+// Friendly names for the exits we run; anything new falls back to the server's own name.
+const KNOWN = {
+    "srv-us-1": { country: "United States", code: "US", place: "US West", aliases: ["usa", "america", "united states", "us", "us west", "west"] },
+    "srv-eu-1": { country: "Finland", code: "FI", place: "Helsinki", aliases: ["finland", "fi", "helsinki", "eu", "europe"] },
+};
+export function locationLabel(s) {
+    const k = KNOWN[s.id];
+    return k ? `${k.country} (${k.place})` : s.name;
+}
+export function describeDevice(d, servers) {
+    const where = d.server_id ? servers.find((s) => s.id === d.server_id) : undefined;
+    const place = where ? locationLabel(where) : d.server_id ?? "none";
+    let state;
+    if (!d.connected)
+        state = "offline";
+    else if (d.exit_confirmed && d.quality === "good")
+        state = `protected, exiting in ${place}`;
+    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}`;
+}
+/** Match a device by id, exact name, or a unique partial name (case-insensitive). */
+export function resolveDevice(query, devices) {
+    const q = query.trim().toLowerCase();
+    const byId = devices.find((d) => d.device_id.toLowerCase() === q);
+    if (byId)
+        return byId;
+    const exact = devices.filter((d) => d.name.toLowerCase() === q);
+    if (exact.length === 1)
+        return exact[0];
+    const partial = devices.filter((d) => d.name.toLowerCase().includes(q));
+    if (partial.length === 1)
+        return partial[0];
+    const names = devices.map((d) => `"${d.name}"`).join(", ") || "none";
+    if (exact.length > 1 || partial.length > 1) {
+        throw new PortveilError(`"${query}" matches more than one device (${(exact.length > 1 ? exact : partial).map((d) => `"${d.name}" [${d.device_id}]`).join(", ")}). Use the device ID.`);
+    }
+    throw new PortveilError(`No device matches "${query}". Devices on this account: ${names}.`);
+}
+/** Match a location by server id, country, code, city or region (case-insensitive). */
+export function resolveLocation(query, servers) {
+    const q = query.trim().toLowerCase();
+    const hits = servers.filter((s) => {
+        if (s.id.toLowerCase() === q)
+            return true;
+        const k = KNOWN[s.id];
+        const words = [s.name, s.region, ...(k ? [k.country, k.code, k.place, ...k.aliases] : [])].map((w) => w.toLowerCase());
+        return words.some((w) => w === q) || words.some((w) => w.length > 3 && (w.includes(q) || q.includes(w)));
+    });
+    if (hits.length === 1)
+        return hits[0];
+    const all = servers.map((s) => `${locationLabel(s)} [${s.id}]`).join(", ");
+    if (hits.length > 1)
+        throw new PortveilError(`"${query}" matches more than one location: ${hits.map((s) => s.id).join(", ")}. Available: ${all}.`);
+    throw new PortveilError(`No location matches "${query}". Available: ${all}.`);
+}
+/** The next location after the current one, wrapping around. */
+export function nextLocation(current, servers) {
+    if (servers.length === 0)
+        throw new PortveilError("No locations are available.");
+    const i = current ? servers.findIndex((s) => s.id === current) : -1;
+    if (i === -1)
+        return servers[0];
+    if (servers.length === 1)
+        throw new PortveilError("There's only one location, so there's nowhere to rotate to.");
+    return servers[(i + 1) % servers.length];
+}
+export class Portveil {
+    o;
+    constructor(opts) {
+        this.o = { ackTimeoutMs: 45_000, confirmTimeoutMs: 45_000, ...opts, apiBase: opts.apiBase.replace(/\/+$/, "") };
+    }
+    get doFetch() { return this.o.fetch ?? fetch; }
+    sleep(ms) { return this.o.sleep ? this.o.sleep(ms) : new Promise((r) => setTimeout(r, ms)); }
+    async call(method, path, body) {
+        const res = await this.doFetch(this.o.apiBase + path, {
+            method,
+            headers: {
+                Authorization: `Bearer ${this.o.token}`,
+                "Content-Type": "application/json",
+                // Cloudflare in front of the API rejects generic clients (error 1010).
+                "User-Agent": `portveil-mcp/${VERSION} (+https://portveil.com)`,
+            },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        const text = await res.text();
+        let data = {};
+        try {
+            data = text ? JSON.parse(text) : {};
+        }
+        catch { /* non-JSON error page */ }
+        if (res.ok)
+            return data;
+        const detail = typeof data?.detail === "string" ? data.detail : data?.detail?.reason ?? "";
+        switch (res.status) {
+            // The control endpoints answer 401 both for a bad token and for one without enough scope.
+            case 401: throw new PortveilError(method === "GET"
+                ? "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 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.`);
+            default: throw new PortveilError(`Portveil returned HTTP ${res.status}${detail ? `: ${detail}` : ""}.`);
+        }
+    }
+    acct() { return `/v1/accounts/${encodeURIComponent(this.o.accountId)}`; }
+    async devices() { return (await this.call("GET", `${this.acct()}/devices`)).devices; }
+    async servers() { return (await this.call("GET", "/v1/servers")).servers; }
+    async account() { return this.call("GET", this.acct()); }
+    async audit(limit) {
+        return this.call("GET", `${this.acct()}/audit-log?limit=${Math.max(1, Math.min(limit, 100))}`);
+    }
+    async command(deviceId, type, serverId) {
+        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 };
+    }
+    async commandState(id) {
+        return this.call("GET", `${this.acct()}/commands/${encodeURIComponent(id)}`);
+    }
+    /** Send a command and wait for the device to pick it up (it polls about every 10 s). */
+    async runCommand(device, type, server) {
+        if (device.platform === "wireguard-app")
+            throw new PortveilError(`${device.name} uses the WireGuard app, which can't be controlled remotely. Install the Portveil agent or app on it for that.`);
+        let st = await this.command(device.device_id, type, server?.id);
+        const deadline = Date.now() + this.o.ackTimeoutMs;
+        while (isWaiting(st.status) && Date.now() < deadline) {
+            await this.sleep(2500);
+            st = await this.commandState(st.command_id);
+        }
+        return st;
+    }
+    /** After a switch is acknowledged, wait for the new exit to confirm it sees the device. */
+    async waitConfirmed(deviceId, serverId) {
+        const deadline = Date.now() + this.o.confirmTimeoutMs;
+        for (;;) {
+            const d = (await this.devices()).find((x) => x.device_id === deviceId);
+            if (d && d.server_id === serverId && d.exit_confirmed)
+                return d;
+            if (Date.now() >= deadline)
+                return undefined;
+            await this.sleep(3000);
+        }
+    }
+    /** Move a device and report plainly what actually happened. */
+    async move(device, target) {
+        const place = locationLabel(target);
+        if (device.server_id === target.id && device.exit_confirmed)
+            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.`;
+        }
+        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.`;
+        }
+        if (st.status !== "acked")
+            return `${device.name} did not move: ${st.status}${st.result ? ` (${st.result})` : ""}. It is still on its previous location.`;
+        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.`;
+    }
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "portveil-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Portveil: let AI assistants see your devices and move them between VPN locations.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "portveil-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && chmod +x dist/index.js",
+    "test": "npm run build && node --test test/*.test.mjs"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "vpn",
+    "wireguard",
+    "portveil",
+    "ai-agents"
+  ],
+  "homepage": "https://portveil.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/roybogs/portveil-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/roybogs/portveil-mcp/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "@types/node": "^22.0.0"
+  }
+}