@vo1d7bin/remote-mcp-agent 0.1.0 → 0.2.0

package/README.md

@@ -1,42 +1,42 @@
-# vo1d Remote MCP device agent
-
-Independent, open CLI for connecting an authorized Windows, Linux or macOS device to **your own** account at https://mcp.thelinuxserver.cloud. This is **not** the third-party Desktop Commander relay.
-
-Requires Node.js 22.14 or newer.
-
-### Pair this machine
-
-Sign in to https://mcp.thelinuxserver.cloud/dashboard and choose **Pair a device**. Copy the one-time code. Run:
-
-```powershell
-npx -y @vo1d7bin/remote-mcp-agent@latest enroll
-```
-
-Paste the code when prompted. The credentials are saved outside your source tree at `~/.vo1d-remote-mcp/device.json`. Never share this file.
-
-### Start the agent
-
-```powershell
-npx -y @vo1d7bin/remote-mcp-agent@latest remote --allow-root "C:\Users\Public\Documents"
-```
-
-For Linux: `npx -y @vo1d7bin/remote-mcp-agent@latest remote --allow-root /home/user/mcp-share`.
-
-Use `VO1D_ALLOWED_ROOTS` to set multiple allowed paths, separated by your system PATH delimiter (semicolon on Windows, colon on Linux). Without allowed roots the agent only returns basic system information. An allowed root may expose file and directory names within that folder to the account's explicitly approved MCP clients. Only select directories you're comfortable exposing.
-
-### Useful options
-
-```text
-enroll [--server https://mcp.thelinuxserver.cloud] [--name YOUR-PC]
-remote [--allow-root PATH]
-```
-
-For a second agent profile, set `VO1D_CONFIG_DIR` before enrollment and when starting its `remote` process.
-
-The initial release supports only `system_info` and `list_directory`. It cannot read file contents, write files, or run shell commands. It reconnects automatically while its process is running. To revoke credentials, open the vo1d Devices dashboard and select **Revoke**.
-
-### Security
-
-Only install this package from the official npm registry under the `@vo1d7bin` scope. Do not run agents as Administrator/root unless necessary. Do not forward or publish the device token. Use explicit, limited allowlisted roots and review client permissions.
-
-Maintained source: https://github.com/THE-L1NUX-USER/vo1d-remote-mcp/tree/main/agent
+# vo1d Remote MCP device agent
+
+Connect your own Windows, Linux, or macOS computer to your account on **https://mcp.thelinuxserver.cloud** using one command. This agent is independent of Desktop Commander and its hosted relay.
+
+Requires Node.js 22.14 or newer.
+
+## One-command connection
+
+```powershell
+npx -y @vo1d7bin/remote-mcp-agent@latest remote
+```
+
+**First run:** The agent prints a verification code and opens your default browser. Sign in with Google if needed, compare the code shown in the terminal and browser, then select **Approve device**. The agent automatically receives device credentials, stores them securely in your user profile, and connects to our relay.
+
+**Later runs:** Execute the **same command**. Previously saved device credentials are reused, so no browser approval is required. The agent reconnects automatically after temporary connection interruptions while it remains running.
+
+The terminal must remain open for the agent to remain online. We may add an installer/service or desktop tray application in a future version.
+
+By default, the agent permits **system information only**. To additionally expose names of files and directories within a specific, safe folder, use:
+
+```powershell
+npx -y @vo1d7bin/remote-mcp-agent@latest remote --allow-root "$HOME\mcp-share"
+```
+
+The specified directory must already exist. Do not grant access to your full home directory, system drive, or secrets. Only the folder and its descendants are visible. No file contents, writes, or terminal execution are provided in this version.
+
+## Advanced options
+
+```text
+vo1d-agent remote [--allow-root PATH] [--server https://mcp.thelinuxserver.cloud]
+vo1d-agent enroll [--server https://mcp.thelinuxserver.cloud]
+```
+
+For a headless machine, run with `--no-browser`; the printed link can be opened from a browser on any other device. Use `VO1D_ALLOWED_ROOTS` for multiple approved folders, separated by your OS path delimiter (semicolon on Windows, colon on Linux).
+
+For a separate agent identity on the same computer, set `VO1D_CONFIG_DIR` to an independent directory **before** running `remote`. Device credentials are stored at `~/.vo1d-remote-mcp/device.json` by default. Keep this private; never commit it to source control.
+
+The legacy `enroll` command is available for manual one-time pairing codes. Open **Devices → Pair a device → Manual pairing** if the browser-based flow cannot be used.
+
+Device access can be revoked at any time in your vo1d dashboard. If revoked, the stored credentials cannot reconnect and the machine must be authorized again.
+
+Source: https://github.com/THE-L1NUX-USER/vo1d-remote-mcp

package/bin/vo1d-agent.mjs

@@ -1,112 +1,195 @@
-#!/usr/bin/env node
-import WebSocket from 'ws';
-import os from 'node:os';
-import { promises as fs } from 'node:fs';
-import path from 'node:path';
-import readline from 'node:readline/promises';
-
-const folder = process.env.VO1D_CONFIG_DIR ? path.resolve(process.env.VO1D_CONFIG_DIR) : path.join(os.homedir(), '.vo1d-remote-mcp');
-const configFile = path.join(folder, 'device.json');
-const arg = (name) => { const i = process.argv.indexOf(name); return i < 0 ? undefined : process.argv[i + 1]; };
-function normalizedServer(raw) {
-  const u = new URL(raw);
-  if (u.protocol !== 'https:' && !(u.protocol === 'http:' &&
-      ['127.0.0.1', 'localhost'].includes(u.hostname))) {
-    throw new Error('An HTTPS server URL is required outside localhost');
-  }
-  return u.origin;
-}
-async function enroll() {
-  const server = normalizedServer(arg('--server') || process.env.VO1D_SERVER || 'https://mcp.thelinuxserver.cloud');
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  let code;
-  try { code = (await rl.question('Paste the one-time pairing code: ')).trim(); }
-  finally { rl.close(); }
-  const res = await fetch(server + '/api/agent/enroll', {
-    method: 'POST', headers: { 'content-type': 'application/json' },
-    body: JSON.stringify({ code, name: arg('--name') || os.hostname(), platform: process.platform })
-  });
-  if (!res.ok) throw new Error('Device pairing failed (HTTP ' + res.status + ')');
-  const { id, token } = await res.json();
-  await fs.mkdir(folder, { recursive: true, mode: 0o700 });
-  try {
-    await fs.writeFile(configFile, JSON.stringify({ server, id, token }, null, 2), { mode: 0o600, flag: 'wx' });
-  } catch(error) {
-    if (error.code === 'EEXIST') {
-      throw new Error('A device is already enrolled in this profile. Run "remote" or specify VO1D_CONFIG_DIR to use a separate profile.');
-    }
-    throw error;
-  }
-  console.log('Paired successfully. Device ID:', id);
-  console.log('Credentials saved outside the Git repository:', configFile);
-  console.log('Run: node agent/index.mjs remote');
-}
-async function allowedRoots() {
-  const provided = process.env.VO1D_ALLOWED_ROOTS || arg('--allow-root') || '';
-  const paths = provided.split(path.delimiter).map(s => s.trim()).filter(Boolean);
-  const roots = [];
-  for (const p of paths) roots.push(await fs.realpath(path.resolve(p)));
-  return roots;
-}
-function includesRoot(p, root) {
-  const value = process.platform === 'win32' ? p.toLowerCase() : p;
-  const base = process.platform === 'win32' ? root.toLowerCase() : root;
-  return value === base || value.startsWith(base.endsWith(path.sep) ? base : base + path.sep);
-}
-async function directoryListing(requestPath, roots) {
-  if (!roots.length) throw new Error('No allowed roots configured; set VO1D_ALLOWED_ROOTS');
-  if (typeof requestPath !== 'string' || requestPath.length > 2000) throw new Error('Invalid directory path');
-  const resolved = await fs.realpath(path.resolve(requestPath));
-  if (!roots.some(root => includesRoot(resolved, root))) throw new Error('Path outside allowed directories');
-  const entries = await fs.readdir(resolved, { withFileTypes: true });
-  return { path: resolved, truncated: entries.length > 100, items: entries.slice(0, 100)
-    .map(entry => ({ name: entry.name, type: entry.isDirectory() ? 'directory' : entry.isFile() ? 'file' : 'other' })) };
-}
-async function remote() {
-  const cfg = JSON.parse(await fs.readFile(configFile, 'utf8'));
-  const server = normalizedServer(cfg.server);
-  const roots = await allowedRoots();
-  console.log('Device:', cfg.id, '| Allowed filesystem roots:', roots.length ? roots.join(' ; ') : '(none)');
-  const endpoint = server.replace(/^http/, 'ws') + '/agent';
-  let stopped = false;
-  let retry = 1000;
-  process.on('SIGINT', () => { stopped = true; process.exit(0); });
-  async function connect() {
-    if (stopped) return;
-    const ws = new WebSocket(endpoint, { headers: { Authorization: 'Bearer ' + cfg.token }, handshakeTimeout: 12000 });
-    ws.on('open', () => { retry = 1000; console.log('Connected to', server); });
-    ws.on('message', async raw => {
-      let task;
-      try { task = JSON.parse(raw.toString()); } catch { return; }
-      if (typeof task.id !== 'string') return;
-      let reply;
-      try {
-        if (task.action === 'system_info') {
-          reply = { hostname: os.hostname(), platform: process.platform, arch: process.arch,
-            release: os.release(), cpus: os.cpus().length, memoryBytes: os.totalmem(), allowedRoots: roots };
-        } else if (task.action === 'list_directory') {
-          reply = await directoryListing(task.args?.path, roots);
-        } else {
-          throw new Error('Unsupported action');
-        }
-        ws.send(JSON.stringify({ id: task.id, ok: true, result: reply }));
-      } catch (error) {
-        ws.send(JSON.stringify({ id: task.id, ok: false, error: String(error.message).slice(0, 150) }));
-      }
-    });
-    ws.on('error', error => console.error('Connection:', error.message));
-    ws.on('close', (code) => {
-      if (code === 4001) { console.error('Device revoked. Exiting.'); stopped = true; return; }
-      if (stopped) return;
-      const delay = retry;
-      retry = Math.min(retry * 2, 30000);
-      console.log('Disconnected. Retrying in', delay / 1000, 'seconds.');
-      setTimeout(connect, delay);
-    });
-  }
-  await connect();
-}
-const command = process.argv[2];
-if (command === 'enroll') enroll().catch(e => { console.error(e.message); process.exitCode = 1; });
-else if (command === 'remote') remote().catch(e => { console.error(e.message); process.exitCode = 1; });
-else console.log('Usage: vo1d-agent enroll [--server https://mcp.thelinuxserver.cloud] [--name MY-PC]\n       vo1d-agent remote [--allow-root PATH]\nPass VO1D_ALLOWED_ROOTS for multiple roots or VO1D_CONFIG_DIR for separate profiles.');
+#!/usr/bin/env node
+import WebSocket from 'ws';
+import os from 'node:os';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline/promises';
+import { spawn } from 'node:child_process';
+import { setTimeout as sleep } from 'node:timers/promises';
+
+const folder = process.env.VO1D_CONFIG_DIR
+  ? path.resolve(process.env.VO1D_CONFIG_DIR)
+  : path.join(os.homedir(), '.vo1d-remote-mcp');
+const configFile = path.join(folder, 'device.json');
+const arg = name => {
+  const i = process.argv.indexOf(name);
+  return i < 0 ? undefined : process.argv[i + 1];
+};
+function normalizedServer(raw) {
+  const url = new URL(raw);
+  if (url.protocol !== 'https:' &&
+    !(url.protocol === 'http:' && ['127.0.0.1','localhost'].includes(url.hostname))) {
+    throw new Error('HTTPS is required outside localhost');
+  }
+  if (url.username || url.password || url.pathname !== '/' || url.search || url.hash) {
+    throw new Error('Expected a server origin, not a URL with a path or credentials');
+  }
+  return url.origin;
+}
+function defaultServer() {
+  return normalizedServer(arg('--server') || process.env.VO1D_SERVER || 'https://mcp.thelinuxserver.cloud');
+}
+async function saveDevice(cfg) {
+  await fs.mkdir(folder, {recursive:true, mode:0o700});
+  try {
+    await fs.writeFile(configFile, JSON.stringify(cfg,null,2), {mode:0o600,flag:'wx'});
+  } catch(error) {
+    if(error.code==='EEXIST')throw new Error('Device already enrolled in this profile; use remote to reconnect');
+    throw error;
+  }
+}
+async function legacyEnroll() {
+  const server=defaultServer();
+  const rl=readline.createInterface({input:process.stdin,output:process.stdout});
+  let code;
+  try {code=(await rl.question('Paste the one-time pairing code: ')).trim();}
+  finally {rl.close();}
+  const reply=await fetch(server+'/api/agent/enroll',{
+    method:'POST',headers:{'content-type':'application/json'},
+    body:JSON.stringify({code,name:arg('--name')||os.hostname(),platform:process.platform})
+  });
+  if(!reply.ok)throw new Error('Device pairing failed (HTTP '+reply.status+')');
+  const {id,token}=await reply.json();
+  await saveDevice({server,id,token});
+  console.log('Paired successfully. Device ID:',id);
+  console.log('To connect, run: vo1d-agent remote');
+}
+function openBrowser(address) {
+  if (process.argv.includes('--no-browser') || process.env.VO1D_NO_BROWSER==='true') return false;
+  const program=process.platform==='win32'?'explorer.exe':process.platform==='darwin'?'open':'xdg-open';
+  try {
+    const child=spawn(program,[address],{stdio:'ignore',detached:true,windowsHide:true});
+    child.on('error',()=>{}); // Link is always printed for environments without a browser.
+    child.unref();
+    return true;
+  } catch {return false;}
+}
+async function browserEnroll(server) {
+  const response=await fetch(server+'/api/agent/authorization/start',{
+    method:'POST',headers:{'content-type':'application/json'},
+    body:JSON.stringify({name:arg('--name')||os.hostname(),platform:process.platform})
+  });
+  if(!response.ok)throw new Error('Could not start browser authorization (HTTP '+response.status+')');
+  const data=await response.json();
+  if(typeof data.requestId!=='string' || typeof data.pollToken!=='string')throw new Error('Unexpected authorization response');
+  const link=new URL(data.verificationUrl);
+  if(link.origin!==server || link.pathname!=='/device/authorize')throw new Error('Unexpected authorization destination');
+  console.log('\nFirst-time connection: approve this device in your web browser.');
+  console.log('Verification code:',data.userCode);
+  console.log('Open:',link.href);
+  openBrowser(link.href);
+  console.log('Waiting for approval (expires in 10 minutes). Press Ctrl+C to cancel.\n');
+  const deadline=Math.min(Number(data.expiresAt),Date.now()+10*60_000);
+  let failure=0;
+  while(Date.now()<deadline) {
+    await sleep(Math.max(2000,Number(data.intervalSeconds||3)*1000));
+    let poll;
+    try {
+      poll=await fetch(server+'/api/agent/authorization/poll',{
+        method:'POST',headers:{'content-type':'application/json'},
+        body:JSON.stringify({requestId:data.requestId,pollToken:data.pollToken}),
+        signal:AbortSignal.timeout(12000)
+      });
+    } catch(error) {
+      failure++;
+      if(failure>=5)throw new Error('Unable to reach the authorization server: '+error.message);
+      continue;
+    }
+    failure=0;
+    const info=await poll.json().catch(()=>({}));
+    if(info.status==='pending')continue;
+    if(info.status==='approved' && typeof info.id==='string' && typeof info.token==='string') {
+      const cfg={server,id:info.id,token:info.token};
+      await saveDevice(cfg);
+      console.log('Device approved and credentials stored securely for future runs.');
+      return cfg;
+    }
+    if(info.status==='denied')throw new Error('This device authorization was denied');
+    if(info.status==='expired' || poll.status===410)throw new Error('Authorization expired; rerun the command');
+    throw new Error('Authorization failed (HTTP '+poll.status+'). Rerun the command.');
+  }
+  throw new Error('Device authorization expired; rerun the command');
+}
+async function loadOrEnroll() {
+  try {
+    const cfg=JSON.parse(await fs.readFile(configFile,'utf8'));
+    if(typeof cfg.id!=='string' || typeof cfg.token!=='string' || cfg.token.length<30) {
+      throw new Error('Stored device credentials appear corrupted');
+    }
+    return cfg;
+  } catch(error) {
+    if(error.code!=='ENOENT')throw error;
+    return browserEnroll(defaultServer());
+  }
+}
+async function allowedRoots() {
+  const provided=process.env.VO1D_ALLOWED_ROOTS || arg('--allow-root') || '';
+  const paths=provided.split(path.delimiter).map(x=>x.trim()).filter(Boolean);
+  const roots=[];
+  for(const p of paths)roots.push(await fs.realpath(path.resolve(p)));
+  return roots;
+}
+function includesRoot(p,root) {
+  const value=process.platform==='win32'?p.toLowerCase():p;
+  const base=process.platform==='win32'?root.toLowerCase():root;
+  return value===base || value.startsWith(base.endsWith(path.sep)?base:base+path.sep);
+}
+async function directoryListing(requestPath,roots) {
+  if(!roots.length)throw new Error('No allowed roots configured; set VO1D_ALLOWED_ROOTS');
+  if(typeof requestPath!=='string' || requestPath.length>2000)throw new Error('Invalid directory path');
+  const resolved=await fs.realpath(path.resolve(requestPath));
+  if(!roots.some(root=>includesRoot(resolved,root)))throw new Error('Path outside allowed directories');
+  const entries=await fs.readdir(resolved,{withFileTypes:true});
+  return {path:resolved,truncated:entries.length>100,items:entries.slice(0,100).map(entry=>({
+    name:entry.name,type:entry.isDirectory()?'directory':entry.isFile()?'file':'other'
+  }))};
+}
+async function remote() {
+  const roots=await allowedRoots();
+  const cfg=await loadOrEnroll();
+  const server=normalizedServer(cfg.server);
+  console.log('Device:',cfg.id,'| Allowed filesystem roots:',roots.length?roots.join(' ; '):'(none)');
+  const endpoint=server.replace(/^http/,'ws')+'/agent';
+  let stopped=false,retry=1000;
+  process.on('SIGINT',()=>{stopped=true;process.exit(0);});
+  async function connect() {
+    if(stopped)return;
+    const ws=new WebSocket(endpoint,{headers:{Authorization:'Bearer '+cfg.token},handshakeTimeout:12000});
+    ws.on('open',()=>{retry=1000;console.log('Connected to',server);});
+    ws.on('message',async raw=>{
+      let task;
+      try{task=JSON.parse(raw.toString());}catch{return;}
+      if(typeof task.id!=='string')return;
+      try {
+        let result;
+        if(task.action==='system_info'){
+          result={hostname:os.hostname(),platform:process.platform,arch:process.arch,
+            release:os.release(),cpus:os.cpus().length,memoryBytes:os.totalmem(),allowedRoots:roots};
+        }else if(task.action==='list_directory'){
+          result=await directoryListing(task.args?.path,roots);
+        }else throw new Error('Unsupported action');
+        if(ws.readyState===WebSocket.OPEN)ws.send(JSON.stringify({id:task.id,ok:true,result}));
+      }catch(error){
+        if(ws.readyState===WebSocket.OPEN)ws.send(JSON.stringify({
+          id:task.id,ok:false,error:String(error.message).slice(0,150)
+        }));
+      }
+    });
+    ws.on('error',error=>console.error('Connection:',error.message));
+    ws.on('close',code=>{
+      if(code===4000){console.log('Another session for this device has taken over. Exiting this agent.');stopped=true;return;}
+      if(code===4001){console.error('Device revoked. Stop this process and request a new authorization.');stopped=true;return;}
+      if(stopped)return;
+      const delay=retry;retry=Math.min(retry*2,30000);
+      console.log('Disconnected. Retrying in',delay/1000,'seconds.');
+      setTimeout(connect,delay);
+    });
+  }
+  await connect();
+}
+const command=process.argv[2];
+if(command==='enroll')legacyEnroll().catch(error=>{console.error(error.message);process.exitCode=1;});
+else if(command==='remote')remote().catch(error=>{console.error(error.message);process.exitCode=1;});
+else console.log('Usage: vo1d-agent remote [--allow-root PATH] [--server https://mcp.thelinuxserver.cloud]\n' +
+  '       vo1d-agent enroll   (manual pairing for headless environments)\n' +
+  'The remote command opens a browser on first run and reconnects on subsequent runs.');

package/package.json

@@ -1,32 +1,32 @@
-{
-  "name": "@vo1d7bin/remote-mcp-agent",
-  "version": "0.1.0",
-  "description": "Independent vo1d Remote MCP device agent for Windows, Linux and macOS",
-  "type": "module",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/THE-L1NUX-USER/vo1d-remote-mcp.git",
-    "directory": "packages/agent"
-  },
-  "homepage": "https://mcp.thelinuxserver.cloud",
-  "bin": {
-    "vo1d-agent": "bin/vo1d-agent.mjs"
-  },
-  "files": [
-    "bin/",
-    "README.md"
-  ],
-  "engines": {
-    "node": ">=22.14.0"
-  },
-  "dependencies": {
-    "ws": "8.18.3"
-  },
-  "scripts": {
-    "prepack": "node ../../scripts/sync-agent.mjs"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@vo1d7bin/remote-mcp-agent",
+  "version": "0.2.0",
+  "description": "Independent vo1d Remote MCP device agent for Windows, Linux and macOS",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/THE-L1NUX-USER/vo1d-remote-mcp.git",
+    "directory": "packages/agent"
+  },
+  "homepage": "https://mcp.thelinuxserver.cloud",
+  "bin": {
+    "vo1d-agent": "bin/vo1d-agent.mjs"
+  },
+  "files": [
+    "bin/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22.14.0"
+  },
+  "dependencies": {
+    "ws": "8.18.3"
+  },
+  "scripts": {
+    "prepack": "node ../../scripts/sync-agent.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}