@vo1d7bin/remote-mcp-agent 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,42 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# 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

package/bin/vo1d-agent.mjs

@@ -0,0 +1,112 @@
+#!/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.');

package/package.json

@@ -1,6 +1,32 @@
-{
-  "name": "@vo1d7bin/remote-mcp-agent",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "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"
+  }
+}