@vo1d7bin/remote-mcp-agent 0.2.0 → 0.3.0

package/README.md

@@ -1,42 +1,66 @@
 # 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.
+Connect Windows, Linux or macOS to your account at **https://mcp.thelinuxserver.cloud**. Independent of Desktop Commander.
 
-Requires Node.js 22.14 or newer.
+Node.js 22.14+ required.
 
-## One-command connection
+## Connect in one command
 
 ```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.
+First run opens a browser to approve your device through your existing Google account. Compare the verification code in the browser and terminal, then approve. The agent stores its credentials under your user profile and connects automatically. Subsequent runs restore that authorization; you do not need to pair every time.
 
-**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.
+A compact connection screen confirms the device name, account, unique device ID and connection status, with a short reminder to keep the terminal open.
 
-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.
+### Commands
 
-By default, the agent permits **system information only**. To additionally expose names of files and directories within a specific, safe folder, use:
+| Command | Purpose |
+| --- | --- |
+| `remote` | Connect, or authorize in browser the first time |
+| `status` | Check the server-recorded online/offline state, account and device ID |
+| `logout` | Revoke this device in the server and remove saved local credentials |
+| `open` | Open the dashboard in your browser |
+| `help` / `--help` | Show available commands and examples |
+| `--version` | Display the agent version |
+| `enroll` | Manual code-based pairing for advanced/headless setups |
+
+Use the same `npx -y @vo1d7bin/remote-mcp-agent@latest` prefix for each command. For example:
 
 ```powershell
-npx -y @vo1d7bin/remote-mcp-agent@latest remote --allow-root "$HOME\mcp-share"
+npx -y @vo1d7bin/remote-mcp-agent@latest status
+npx -y @vo1d7bin/remote-mcp-agent@latest open
+npx -y @vo1d7bin/remote-mcp-agent@latest logout
 ```
 
-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.
+`remote --help` and `remote --logout` are accepted as convenience aliases.
 
-## Advanced options
+**Logout revokes the device credential on the server**, disconnecting a running agent. For safety, if the relay is unreachable, the CLI preserves local credentials and tells you how to revoke through the dashboard. `logout --local` is a last-resort local cleanup only: it does **not** revoke server authorization, and you must also revoke the device in the dashboard.
+
+## Share a specific folder (optional)
+
+By default, the agent exposes basic system information only. To allow a client to list names in a safe directory:
 
-```text
-vo1d-agent remote [--allow-root PATH] [--server https://mcp.thelinuxserver.cloud]
-vo1d-agent enroll [--server https://mcp.thelinuxserver.cloud]
+```powershell
+mkdir "$HOME\mcp-share" -Force
+npx -y @vo1d7bin/remote-mcp-agent@latest remote --allow-root "$HOME\mcp-share"
 ```
 
-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).
+Never use a secrets directory or the entire system drive as an allowed root. File contents, file modifications and terminal commands are **not** enabled in this version. The public MCP endpoint also remains gated until the end-to-end OAuth integration is ready.
 
-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 process needs to keep running to remain online. Closing the terminal makes the device offline but does not log it out.
+
+## Advanced options
 
-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.
+- `--server URL`: use a custom HTTPS server (local HTTP development is allowed only for localhost)
+- `--name NAME`: set a name during first-time authorization
+- `--no-browser`: print the verification link for another computer instead of attempting to open a local browser
+- `--allow-root PATH`: allow directory listing inside the specified safe path
+- `VO1D_ALLOWED_ROOTS`: additional allowed paths separated by the system path delimiter
+- `VO1D_CONFIG_DIR`: isolate a second authorized device profile
+- `NO_COLOR=1`: suppress terminal ANSI colors
 
-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.
+Future installers can run the same background agent without requiring users to install Node themselves.
 
 Source: https://github.com/THE-L1NUX-USER/vo1d-remote-mcp

package/bin/cli-ux.mjs

@@ -0,0 +1,70 @@
+const colors=Boolean(process.stdout.isTTY && !process.env.NO_COLOR && process.env.TERM!=='dumb');
+const tint=(s,c)=>colors?'['+c+'m'+s+'':s;
+const cyan=s=>tint(s,'96'), green=s=>tint(s,'92'), dim=s=>tint(s,'90');
+export const version='0.3.0';
+export function banner() {
+  console.log('');
+  console.log(cyan('  __   __   ___   _   ____'));
+  console.log(cyan('  \\ \\ / /  / _ \\ / | |  _ \\'));
+  console.log(cyan('   \\ V /  | (_) || | | | | |'));
+  console.log(cyan('    \\_/    \\___/ |_| |____/'));
+  console.log('');
+  console.log('  '+cyan('REMOTE MCP')+dim('  ·  v'+version));
+  console.log('  '+dim('Your machines. Your control.'));
+  console.log('');
+}
+export function heading(title) {console.log(cyan('◆ '+title));}
+export function info(label,value){console.log('  '+dim(label.padEnd(15))+String(value||'—'));}
+export function success(message){console.log(green('  ✓  '+message));}
+export function note(message){console.log(dim('  '+message));}
+export function divider(){console.log(dim('  ───────────────────────────────────────────────────'));}
+export function help() {
+  banner();
+  heading('Commands');
+  console.log('  remote       Connect this device (default; browser approval on first run)');
+  console.log('  status       Show this device, account and current relay status');
+  console.log('  logout       Revoke device authorization and delete local credentials');
+  console.log('  open         Open the online device dashboard in your browser');
+  console.log('  enroll       Manual pairing code for headless or advanced setups');
+  console.log('  help         Show these commands');
+  console.log('  --version    Show CLI version');
+  console.log('');
+  heading('Useful options');
+  console.log('  remote --allow-root PATH     Share directory names from an approved folder');
+  console.log('  remote --no-browser          Print approval link instead of opening it');
+  console.log('  remote --server URL          Use a custom vo1d server');
+  console.log('  logout --local               Forget credentials without remote revocation');
+  console.log('  --name DEVICE_NAME           Choose name when first pairing');
+  console.log('');
+  heading('Examples');
+  console.log('  npx -y @vo1d7bin/remote-mcp-agent@latest remote');
+  console.log('  npx -y @vo1d7bin/remote-mcp-agent@latest remote --allow-root ./mcp-share');
+  console.log('  npx -y @vo1d7bin/remote-mcp-agent@latest status');
+  console.log('  npx -y @vo1d7bin/remote-mcp-agent@latest logout');
+  console.log('');
+  note('Tip: keep the terminal open while you want this device online.');
+  note('Only system information is shared unless you specify an allowed folder.');
+}
+export function ready(details) {
+  console.log('');
+  divider();
+  success('Secure connection established');
+  success('Device is online');
+  console.log('');
+  info('Device',details.name);
+  info('Account',details.account||'Your vo1d workspace');
+  info('Device ID',details.id);
+  info('Server',details.server);
+  info('Status','Online');
+  info('Allowed roots',details.roots?.length?details.roots.join(' ; '):'None (system info only)');
+  console.log('');
+  heading('Next');
+  note('Return to your MCP-compatible assistant when the connection is enabled.');
+  note('Keep this terminal open, or minimize it.');
+  note('Press Ctrl+C to disconnect (not to log out).');
+  console.log('');
+  heading('Manage this device (in another terminal)');
+  note('Status: npx -y @vo1d7bin/remote-mcp-agent@latest status');
+  note('Log out: npx -y @vo1d7bin/remote-mcp-agent@latest logout');
+  console.log('');
+}

package/bin/management.mjs

@@ -0,0 +1,104 @@
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { banner, heading, info, success, note } from './cli-ux.mjs';
+
+const profile = process.env.VO1D_CONFIG_DIR
+  ? path.resolve(process.env.VO1D_CONFIG_DIR)
+  : path.join(os.homedir(), '.vo1d-remote-mcp');
+const file=path.join(profile,'device.json');
+const publicServer=process.env.VO1D_SERVER || 'https://mcp.thelinuxserver.cloud';
+
+async function readProfile(){
+  let cfg;
+  try {cfg=JSON.parse(await fs.readFile(file,'utf8'));}
+  catch(error) {
+    if(error.code==='ENOENT')return null;
+    throw new Error('Unable to read device credentials: '+error.message);
+  }
+  if(typeof cfg.id!=='string' || typeof cfg.token!=='string' || cfg.token.length<30 ||
+    typeof cfg.server!=='string')throw new Error('Saved device credentials appear corrupted.');
+  const server=new URL(cfg.server);
+  if(server.protocol!=='https:' &&
+    !(server.protocol==='http:' && ['localhost','127.0.0.1'].includes(server.hostname)))
+    throw new Error('Saved profile has an invalid server address.');
+  return cfg;
+}
+async function call(cfg,endpoint,method='GET') {
+  const url=new URL(endpoint,cfg.server).href;
+  const response=await fetch(url,{method,headers:{Authorization:'Bearer '+cfg.token},signal:AbortSignal.timeout(12000)});
+  if(response.status===401)return {invalid:true};
+  if(!response.ok)throw new Error('Server responded HTTP '+response.status);
+  return response.json();
+}
+export async function showStatus(){
+  banner();
+  heading('Device status');
+  const cfg=await readProfile();
+  if(!cfg){
+    note('No saved device authorization for this profile.');
+    note('Start with: npx -y @vo1d7bin/remote-mcp-agent@latest remote');
+    return;
+  }
+  info('Device ID',cfg.id);
+  info('Server',cfg.server);
+  try {
+    const remote=await call(cfg,'/api/agent/me');
+    if(remote.invalid){
+      info('Status','Authorization invalid or revoked');
+      note('Use logout --local to clear this profile, then remote to reauthorize.');
+      process.exitCode=1;
+      return;
+    }
+    info('Device',remote.name);
+    info('Account',remote.account || 'vo1d account');
+    info('Status',remote.online?'Online':'Offline');
+    if(!remote.online)note('Run remote to bring this device online.');
+  }catch(error){
+    info('Status','Unknown (server unavailable)');
+    note(error.message);
+    process.exitCode=1;
+  }
+}
+export async function logOut(){
+  banner();
+  heading('Log out this device');
+  const cfg=await readProfile();
+  if(!cfg){note('Already logged out. No device credentials found.');return;}
+  if(process.argv.includes('--local')){
+    await fs.unlink(file);
+    note('Local credentials deleted, but server authorization was NOT revoked.');
+    note('Revoke this device in the online dashboard if it is still authorized.');
+    return;
+  }
+  try {
+    const result=await call(cfg,'/api/agent/revoke-self','POST');
+    if(!result.revoked && !result.invalid)throw new Error('Server did not confirm revocation');
+  }catch(error){
+    console.error('Could not revoke device: '+error.message);
+    note('Credentials have been kept so you can retry safely.');
+    note('Alternatively, revoke from the dashboard. --local only deletes locally.');
+    process.exitCode=1;
+    return;
+  }
+  await fs.unlink(file);
+  success('Server authorization revoked');
+  success('Local device credentials removed');
+  note('Run remote whenever you want to authorize this machine again.');
+}
+export async function openDashboard(){
+  banner();
+  const cfg=await readProfile();
+  const origin=cfg?.server || publicServer;
+  const url=new URL(origin);
+  if(url.protocol!=='https:' && !(url.protocol==='http:'&&['localhost','127.0.0.1'].includes(url.hostname)))
+    throw new Error('Dashboard URL must be HTTPS');
+  const address=url.origin+'/dashboard';
+  console.log('Dashboard:',address);
+  if(process.argv.includes('--no-browser') || process.env.VO1D_NO_BROWSER==='true')return;
+  const command=process.platform==='win32'?'explorer.exe':process.platform==='darwin'?'open':'xdg-open';
+  const child=spawn(command,[address],{stdio:'ignore',detached:true,windowsHide:true});
+  child.on('error',()=>note('Could not open browser; use the URL above.'));
+  child.unref();
+}

package/bin/vo1d-agent.mjs

@@ -6,6 +6,8 @@ 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';
+import { banner, heading, info, success, note, divider, help, ready, version } from './cli-ux.mjs';
+import { showStatus, logOut, openDashboard } from './management.mjs';
 
 const folder = process.env.VO1D_CONFIG_DIR
   ? path.resolve(process.env.VO1D_CONFIG_DIR)
@@ -145,6 +147,8 @@ async function directoryListing(requestPath,roots) {
   }))};
 }
 async function remote() {
+  banner();
+  heading('Remote connection');
   const roots=await allowedRoots();
   const cfg=await loadOrEnroll();
   const server=normalizedServer(cfg.server);
@@ -155,7 +159,22 @@ async function remote() {
   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('open',async()=>{
+      retry=1000;
+      console.log('Connected to',server);
+      let details={id:cfg.id,name:os.hostname(),account:null,server,roots};
+      try {
+        const response=await fetch(server+'/api/agent/me',{
+          headers:{Authorization:'Bearer '+cfg.token},
+          signal:AbortSignal.timeout(9000)
+        });
+        if(response.ok){
+          const remote=await response.json();
+          details={...details,name:remote.name||details.name,account:remote.account};
+        }
+      }catch{note('Account details unavailable; relay connection is still active.');}
+      if(ws.readyState===WebSocket.OPEN)ready(details);
+    });
     ws.on('message',async raw=>{
       let task;
       try{task=JSON.parse(raw.toString());}catch{return;}
@@ -188,8 +207,12 @@ async function remote() {
   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.');
+const run = fn => fn().catch(error=>{console.error('Error:',error.message);process.exitCode=1;});
+if(command==='--version' || command==='-v' || command==='version') console.log('vo1d-agent v'+version);
+else if(command==='--help' || command==='-h' || command==='help' || command==='remote' && process.argv.includes('--help')) help();
+else if(command==='logout' || command==='remote' && process.argv.includes('--logout')) run(logOut);
+else if(command==='status' || command==='whoami') run(showStatus);
+else if(command==='open' || command==='dashboard') run(openDashboard);
+else if(command==='enroll') run(legacyEnroll);
+else if(!command || command==='remote') run(remote);
+else {console.error('Unknown command:',command);help();process.exitCode=1;}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vo1d7bin/remote-mcp-agent",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Independent vo1d Remote MCP device agent for Windows, Linux and macOS",
   "type": "module",
   "license": "MIT",