portveil-mcp 0.4.1 → 0.4.3

package/README.md

@@ -34,6 +34,8 @@ Devices can be named loosely ("scraper" finds "Scraper box"); an ambiguous name
 
 ## Setup
 
+No account yet? [Start free](https://portveil.com/free/) with just an email, no card.
+
 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:
@@ -56,6 +58,20 @@ claude mcp add portveil -e PORTVEIL_ACCOUNT_ID=acct_… -e PORTVEIL_TOKEN=clt_
 }
 ```
 
+**Hermes Agent**: Hermes only installs npm packages older than 14 days, so install into its own folder and run it with node:
+```bash
+cd ~ && npm install --prefix ~/.hermes/mcp-servers/portveil portveil-mcp@0.4.3
+echo 'PORTVEIL_TOKEN=clt_…' >> ~/.hermes/.env
+hermes mcp add portveil --command node \
+  --env PORTVEIL_ACCOUNT_ID=acct_… 'PORTVEIL_TOKEN=${PORTVEIL_TOKEN}' \
+  --args ~/.hermes/mcp-servers/portveil/node_modules/portveil-mcp/dist/index.js
+```
+For Hermes to use it well (when to act, what to confirm first, how to add devices), also install the Portveil skill from [ClawHub](https://clawhub.ai/roybogs/portveil):
+```bash
+hermes skills install roybogs/portveil
+```
+(Source: [`skills/portveil/SKILL.md`](skills/portveil/SKILL.md).)
+
 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

package/dist/index.js

@@ -13,7 +13,7 @@ import { z } from "zod";
 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";
+import { Portveil, PortveilError, VERSION, agentSetup, describeDevice, wgConfig, wgKeypair, isWaiting, localHint, 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) {
@@ -52,12 +52,15 @@ server.registerTool("list_devices", {
 }));
 server.registerTool("list_locations", {
     title: "List locations",
-    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.",
+    description: "List the exit locations (country, city and location ID) that devices can be moved to, with each one's timezone and language settings. Use it before move_device or start_rotation when you're unsure what's available, or to make a browser on a moved machine match its exit (sites compare the browser's timezone with its IP's country). 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")));
+}, () => run(async () => (await pv.servers()).map((s) => {
+    const hint = localHint(s);
+    return `- ${locationLabel(s)} [${s.id}]${hint ? `: ${hint}` : ""}`;
+}).join("\n")));
 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.",
+    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, whether an agent machine's clock matches its exit's timezone, 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 () => {
@@ -172,7 +175,7 @@ server.registerTool("add_device", {
         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"),
+        split_tunnel: z.boolean().optional().describe("linux_machine only, advanced: default false (full tunnel), which sends everything the machine connects to through Portveil and keeps SSH and other incoming connections on their normal route, so remote servers stay reachable. true only reaches Portveil's own network: the machine's internet traffic would NOT go through Portveil"),
     },
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
 }, ({ name, kind, temporary_minutes, folder, split_tunnel }) => run(async () => {
@@ -183,8 +186,8 @@ server.registerTool("add_device", {
     }
     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}.`;
+            agentSetup(apiBase, accountId, name, split_tunnel ?? false) +
+            `\n\nIts own traffic then goes through Portveil, while SSH and other incoming connections keep their normal route, so a remote session stays up. The 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();

package/dist/portveil.js

@@ -1,7 +1,7 @@
 // Portveil API client and the logic behind the MCP tools. No MCP types here,
 // so it can be tested against a fake API.
 import { generateKeyPairSync } from "node:crypto";
-export const VERSION = "0.4.1";
+export const VERSION = "0.4.3";
 /** "↓ 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)
@@ -24,7 +24,7 @@ export function wgConfig(priv, address, s) {
 export function agentSetup(apiBase, accountId, name, splitTunnel) {
     const q = (v) => `'${v.replace(/'/g, `'\\''`)}'`;
     return [
-        "apt install -y wireguard-tools curl",
+        "apt install -y wireguard-tools curl nftables",
         "curl -fsSLO https://portveil.com/downloads/portveil-agent",
         "curl -fsSL https://portveil.com/downloads/portveil-agent.sha256 | sha256sum -c -",
         "chmod +x portveil-agent",
@@ -39,9 +39,40 @@ export class PortveilError extends Error {
 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"] },
+    "srv-us-1": { country: "United States", code: "US", place: "US West", aliases: ["usa", "america", "united states", "us", "us west", "west"],
+        timezone: "America/Los_Angeles", locale: "en-US", accept_language: "en-US,en;q=0.9" },
+    "srv-eu-1": { country: "Finland", code: "FI", place: "Helsinki", aliases: ["finland", "fi", "helsinki", "eu", "europe"],
+        timezone: "Europe/Helsinki", locale: "fi-FI", accept_language: "en-US,en;q=0.9,fi;q=0.8" },
 };
+/** What a local browser at this exit looks like: the API's values, else the built-in ones. */
+export function localProfile(s) {
+    const k = KNOWN[s.id];
+    const timezone = s.timezone ?? k?.timezone;
+    if (!timezone)
+        return undefined;
+    return { timezone, locale: s.locale ?? k?.locale ?? "", accept_language: s.accept_language ?? k?.accept_language ?? "" };
+}
+/** One line an agent can act on so its browser matches the exit. Match the timezone;
+ *  keep the language English-first so pages stay readable. */
+export function localHint(s) {
+    const p = localProfile(s);
+    if (!p)
+        return "";
+    const lang = p.accept_language ? `; keep the browser's language English-first (Accept-Language: ${p.accept_language})` : "";
+    const local = p.locale && !p.locale.startsWith("en") ? `; the local language is ${p.locale}, only for pages that should be in it` : "";
+    return `timezone ${p.timezone}${lang}${local}`;
+}
+/** Whether the machine's own clock matches its exit (agent machines only). */
+export function clockNote(d, where) {
+    if (!d.connected || !d.timezone || !where)
+        return "";
+    const want = localProfile(where)?.timezone;
+    if (!want)
+        return "";
+    return d.timezone === want
+        ? `clock ${d.timezone}, matching the exit`
+        : `clock set to ${d.timezone}, not the exit's ${want}: sites can see the mismatch, so set a browser on it to ${want}`;
+}
 export function locationLabel(s) {
     const k = KNOWN[s.id];
     return k ? `${k.country} (${k.place})` : s.name;
@@ -64,6 +95,9 @@ export function describeDevice(d, servers) {
         extras.push(`speed ${describeSpeed(d.speed)}`);
     if (d.rotation)
         extras.push(`rotates every ${d.rotation.every_minutes} min`);
+    const clock = clockNote(d, where);
+    if (clock)
+        extras.push(clock);
     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("; ")}` : ""}`;
@@ -240,7 +274,7 @@ export class Portveil {
             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.`
+            ? `Done. ${device.name} now exits in ${place}, confirmed by the ${place} exit server.${localHint(target) ? ` If a browser on it should look local, use ${localHint(target)}.` : ""}`
             : `${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.4.1",
+  "version": "0.4.3",
   "description": "MCP server for Portveil: let AI assistants see your devices and move them between VPN locations.",
   "license": "MIT",
   "type": "module",