@hcu-lab.me/mcp-device 1.0.2 → 1.0.4

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2024-2025 Eduard Ruzga and Desktop Commander Contributors
-
-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
+MIT License
+
+Copyright (c) 2024-2025 Eduard Ruzga and Desktop Commander Contributors
+
+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

@@ -1,51 +1,84 @@
-# MCP Device
-
-`@hcu-lab.me/mcp-device` securely connects a user-owned computer to an authenticated Model Context Protocol gateway. The device makes the outbound connection; no inbound device port is required.
-
-The gateway owns accounts, OAuth, device ownership, MCP tool contracts, routing, and usage aggregation. MCP Device owns local device identity, pairing, reconnect lifecycle, bounded execution, background registration, and local status.
-
-## Commands
-
-```text
-mcp-device              start in the foreground
-mcp-device start        start in the foreground
-mcp-device login        explicitly link or switch the gateway account
-mcp-device logout       unlink the gateway account from this device
-mcp-device status       show runtime, manager, connection, security, proxy, usage, and schema state
-mcp-device install      pair if needed, then install and start a background runtime
-mcp-device stop         stop the current runtime without deleting identity/account state
-mcp-device uninstall    remove background registration while preserving identity/account state
-mcp-device --help       show command help
-```
-
-`md` is an alias of `mcp-device` on POSIX shells. On Windows, use `mcp-device`; bare `md` has a shell collision with built-in directory-creation commands/aliases and is not the supported invocation.
-
-On Windows, `install` uses the current-user background registration. On Linux, every `install` asks whether to use `systemd --user` or an already configured PM2 installation. MCP Device does not install PM2, run `pm2 startup`, or use `sudo` automatically.
-
-## First run and trust
-
-The official gateway is `https://mcp-v2.hcu-lab.me/mcp`. The official package is designed to pin an independently distributed application CA and require protocol v2 before the first network connection. If that CA is absent, MCP Device fails closed rather than learning trust from the gateway it is about to contact or falling back to protocol v1.
-
-For a custom gateway, configure the gateway URL and provision its application CA through an independent trusted channel before enabling protocol v2. Proxy selection is captured during interactive provisioning and reused by the background runtime; proxy credentials are protected with Windows DPAPI on Windows.
-
-## Local state and migration
-
-Canonical state is stored under `~/.mcp-device/`. Existing `~/.hcu-device/` identity/config/status state is migrated non-destructively under serialized runtime ownership. A conflicting canonical and legacy identity fails closed rather than creating a second device identity.
-
-The device identity is Ed25519. On Windows, the private key is protected with DPAPI for the current user. The gateway stores the public identity and account ownership.
-
-## Development
-
-```powershell
-git clone https://github.com/Hiroshimeow/agent-mcp-device.git
-cd agent-mcp-device
-npm ci
-npm run build
-node dist/mcp-device.js --help
-```
-
-For a custom development gateway, set `MCP_GATEWAY_URL`. Supply `MCP_GATEWAY_APP_CA_PATH` from an independent trusted source when using protocol v2. Non-loopback plaintext gateway URLs are rejected.
-
-## Upstream execution engine
-
-The local execution engine is derived from [Desktop Commander MCP](https://github.com/wonderwhy-er/DesktopCommanderMCP). Desktop Commander is MIT licensed; its copyright and MIT license are preserved in this repository's `LICENSE`. The MCP Device product identity, gateway protocol, account/device lifecycle, security layer, and packaging are maintained separately in this repository.
+# MCP Device
+
+`@hcu-lab.me/mcp-device` connects a user-owned computer to the authenticated MCP Gateway. The device opens the outbound connection; no inbound device port is required.
+
+The gateway owns accounts, OAuth, device ownership, MCP tool contracts, routing, and usage aggregation. MCP Device owns local device identity, pairing, reconnect lifecycle, bounded execution, background registration, and local status.
+
+## Quick start
+
+Canonical production gateway: https://device.hcu-lab.me
+
+- Dashboard: https://device.hcu-lab.me/dashboard
+- Pair device: https://device.hcu-lab.me/pair
+- Live setup/help: https://device.hcu-lab.me/help
+
+Install the current release:
+
+```powershell
+npm install -g @hcu-lab.me/mcp-device
+mcp-device login
+mcp-device install
+mcp-device status
+```
+
+`mcp-device login` stays terminal-only: it prints the pairing URL, user code, and QR code, and never opens a browser automatically.
+
+## Limited hosted access
+
+The public source package remains MIT licensed, but access to the hosted `device.hcu-lab.me` gateway is intentionally limited. New hosted accounts are admitted through a small, controlled supply of invite codes rather than open registration. Invite availability may be capped, paused, expired, or revoked as the service capacity and security policy change. Installing the package does not by itself grant a hosted-service account or guarantee that an invite code will be available.
+
+The hosted Pair/Help pages render their gateway URL and navigation from the deployment that served the page, so staging or custom deployments do not need a production-host rewrite. For the canonical package, `https://device.hcu-lab.me` is the default gateway; `MCP_GATEWAY_URL` is only needed when intentionally using another gateway.
+
+## Commands
+
+```text
+mcp-device              start in the foreground
+mcp-device start        start in the foreground
+mcp-device login        explicitly link or switch the gateway account
+mcp-device logout       unlink the gateway account from this device
+mcp-device status       show runtime, manager, connection, security, proxy, usage, and schema state
+mcp-device install      pair if needed, then install and start a background runtime
+mcp-device stop         stop the current runtime without deleting identity/account state
+mcp-device uninstall    remove background registration while preserving identity/account state
+mcp-device --help       show command help
+```
+
+`md` is an alias of `mcp-device` on POSIX shells. On Windows, use `mcp-device`; bare `md` has a shell collision with built-in directory-creation commands/aliases and is not the supported invocation.
+
+On Windows, `install` uses current-user background registration. On Linux, every `install` asks whether to use `systemd --user` or an already configured PM2 installation. MCP Device does not install PM2, run `pm2 startup`, or use `sudo` automatically.
+
+## First run and trust
+
+The official gateway base URL is `https://device.hcu-lab.me`. The official package pins the independently distributed application CA and requires protocol v2 before the first network connection. If that CA is absent or invalid, MCP Device fails closed instead of learning trust from the gateway it is about to contact or falling back to protocol v1.
+
+For a custom gateway, set `MCP_GATEWAY_URL` and provision its application CA through an independent trusted channel before enabling protocol v2. Proxy selection is captured during interactive provisioning and reused by the background runtime.
+
+## Local state and 1.0.2 migration
+
+Canonical state is stored under `~/.mcp-device/`. Existing `~/.hcu-device/` identity/config/status state is migrated non-destructively under serialized runtime ownership. A conflicting canonical and legacy identity fails closed rather than creating a second device identity.
+
+The device identity is Ed25519. MCP Device 1.0.2 does not use Windows DPAPI for the device private key or proxy configuration. A legacy protected 1.0.1 identity is archived without decrypting it, a fresh local identity is generated, and the device must be paired once again. A legacy protected proxy configuration must be supplied again during `mcp-device login`. The gateway stores only the public device identity and account ownership.
+
+## Development
+
+```powershell
+git clone https://github.com/Hiroshimeow/agent-mcp-device.git
+cd agent-mcp-device
+npm ci
+npm run build
+node dist/mcp-device.js --help
+```
+
+Normal development pushes do not publish npm. After reviewed development work is committed on a clean `main`, a release is intentionally created with:
+
+```powershell
+npm run release
+```
+
+That command runs the test suite, bumps the patch version, synchronizes project version files, creates the release commit and `vX.Y.Z` tag, then atomically pushes `main` and the tag. The tag-triggered GitHub Actions workflow performs the npm publish through trusted OIDC publishing. Use `npm run release:minor` or `npm run release:major` only when that version change is intentional.
+
+For a custom development gateway, set `MCP_GATEWAY_URL`. Supply `MCP_GATEWAY_APP_CA_PATH` from an independent trusted source when using protocol v2. Non-loopback plaintext gateway URLs are rejected.
+
+## Upstream execution engine
+
+The local execution engine is derived from [Desktop Commander MCP](https://github.com/wonderwhy-er/DesktopCommanderMCP). Desktop Commander is MIT licensed; its copyright and MIT license are preserved in this repository's `LICENSE`. The MCP Device product identity, gateway protocol, account/device lifecycle, security layer, and packaging are maintained separately in this repository.

package/dist/data/official-app-ca.pem

@@ -1,12 +1,12 @@
------BEGIN CERTIFICATE-----
-MIIBrzCCAVagAwIBAgIUJT4N8vTRvyxp9rlhfHuY8OOJvB4wCgYIKoZIzj0EAwIw
-JDEiMCAGA1UEAwwZTUNQIERldmljZSBBcHBsaWNhdGlvbiBDQTAeFw0yNjA5MTYx
-NDMyNDVaFw0zNjA5MTMxNDMyNDVaMCQxIjAgBgNVBAMMGU1DUCBEZXZpY2UgQXBw
-bGljYXRpb24gQ0EwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAARFvReUGN6fAVYg
-FF4UTn6F7KQ78b9yhkBU9qBy1XEMnCJqpn07rxKQszaB/ABb0awH0kIQuOUt+NA/
-7iUVeyA4o2YwZDASBgNVHRMBAf8ECDAGAQH/AgEAMA4GA1UdDwEB/wQEAwIBBjAd
-BgNVHQ4EFgQUMtlUKf+st0jgEdxhESpzROwRDW0wHwYDVR0jBBgwFoAUMtlUKf+s
-t0jgEdxhESpzROwRDW0wCgYIKoZIzj0EAwIDRwAwRAIgbjQRULWIJp+zuwOEQgVo
-9Y+3UygTogcwDkylzlR21lwCIDwbk3Vp07JVK7qBCLL9JplP8j4UWTTXVe5Oi+xJ
-japd
------END CERTIFICATE-----
+-----BEGIN CERTIFICATE-----
+MIIBrzCCAVagAwIBAgIUJT4N8vTRvyxp9rlhfHuY8OOJvB4wCgYIKoZIzj0EAwIw
+JDEiMCAGA1UEAwwZTUNQIERldmljZSBBcHBsaWNhdGlvbiBDQTAeFw0yNjA5MTYx
+NDMyNDVaFw0zNjA5MTMxNDMyNDVaMCQxIjAgBgNVBAMMGU1DUCBEZXZpY2UgQXBw
+bGljYXRpb24gQ0EwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAARFvReUGN6fAVYg
+FF4UTn6F7KQ78b9yhkBU9qBy1XEMnCJqpn07rxKQszaB/ABb0awH0kIQuOUt+NA/
+7iUVeyA4o2YwZDASBgNVHRMBAf8ECDAGAQH/AgEAMA4GA1UdDwEB/wQEAwIBBjAd
+BgNVHQ4EFgQUMtlUKf+st0jgEdxhESpzROwRDW0wHwYDVR0jBBgwFoAUMtlUKf+s
+t0jgEdxhESpzROwRDW0wCgYIKoZIzj0EAwIDRwAwRAIgbjQRULWIJp+zuwOEQgVo
+9Y+3UygTogcwDkylzlR21lwCIDwbk3Vp07JVK7qBCLL9JplP8j4UWTTXVe5Oi+xJ
+japd
+-----END CERTIFICATE-----

package/dist/data/onboarding-prompts.json

@@ -1,70 +1,70 @@
-{
-  "version": "2.0.0",
-  "description": "Desktop Commander onboarding prompts - V2 simplified (5 prompts only)",
-  "prompts": [
-    {
-      "id": "onb2_01",
-      "title": "Organize my Downloads folder",
-      "description": "Clean up and organize your messy Downloads folder into relevant subfolders automatically.",
-      "prompt": "Let's organize your Downloads folder! \n\nFirst, let me check what we're working with. I'll look at your Downloads folder to see how many files are there and what types.\n\nShould I start by analyzing your Downloads folder?",
-      "categories": ["onboarding"],
-      "secondaryTag": "Quick Start",
-      "votes": 0,
-      "gaClicks": 0,
-      "icon": "FolderOpen",
-      "author": "DC team",
-      "verified": true
-    },
-    {
-      "id": "onb2_02",
-      "title": "Explain codebase or repository to me",
-      "description": "Analyze and explain any codebase - local project or GitHub repository - including architecture, dependencies, and how it works.",
-      "prompt": "I'll analyze and explain any codebase for you! 🔍\n\n**What should I analyze?**\n\n*Local project:* `~/work/my-project` (replace with your path)\n*GitHub repo:* `https://github.com/user/repo`\n\nI'll break down the architecture, dependencies, and how everything works together!",
-      "categories": ["onboarding"],      "secondaryTag": "Code Analysis",
-      "votes": 0,
-      "gaClicks": 0,
-      "icon": "Code",
-      "author": "DC team",
-      "verified": true
-    },
-    {
-      "id": "onb2_03",
-      "title": "Create organized knowledge/documents folder",
-      "description": "Set up a well-structured knowledge base or document organization system with templates and suggested categories.",
-      "prompt": "Let's create an organized knowledge base! 📚\n\n**Where should I set it up?**\n\n*I suggest: `~/Documents/Knowledge-Base` (replace with your path) or give me a different location.*\n\nI'll create a clean folder structure with templates and organize any existing documents you have!",
-      "categories": ["onboarding"],
-      "secondaryTag": "Quick Start",
-      "votes": 0,
-      "gaClicks": 0,
-      "icon": "BookOpen",
-      "author": "DC team",
-      "verified": true
-    },
-    {
-      "id": "onb2_04",
-      "title": "Analyze my data file",
-      "description": "Upload or point to any data file (CSV, JSON, Excel, etc.) and get comprehensive analysis including patterns, insights, and summary reports.",
-      "prompt": "I'll help you analyze your data file! \n\nWhat's the path to your data file? (e.g., `/Users/yourname/data.csv`)\n\nOnce you give me the path, I'll start by checking what type of file it is and show you a quick preview, then we can dive deeper step by step.",
-      "categories": ["onboarding"],
-      "secondaryTag": "Quick Start",
-      "votes": 0,
-      "gaClicks": 0,
-      "icon": "BarChart3",
-      "author": "DC team",
-      "verified": true
-    },
-    {
-      "id": "onb2_05",
-      "title": "Check system health and resources",
-      "description": "Analyze your system's health, resource usage, running processes, and generate a comprehensive system status report.",
-      "prompt": "Let me check your system health and resources!\n\nI'll start by looking at your CPU, memory, and disk usage, then check for any performance issues.\n\nShould I begin the system analysis?",
-      "categories": ["onboarding"],
-      "secondaryTag": "Quick Start",
-      "votes": 0,
-      "gaClicks": 0,
-      "icon": "Activity",
-      "author": "DC team",
-      "verified": true
-    }
-  ]
-}
+{
+  "version": "2.0.0",
+  "description": "Desktop Commander onboarding prompts - V2 simplified (5 prompts only)",
+  "prompts": [
+    {
+      "id": "onb2_01",
+      "title": "Organize my Downloads folder",
+      "description": "Clean up and organize your messy Downloads folder into relevant subfolders automatically.",
+      "prompt": "Let's organize your Downloads folder! \n\nFirst, let me check what we're working with. I'll look at your Downloads folder to see how many files are there and what types.\n\nShould I start by analyzing your Downloads folder?",
+      "categories": ["onboarding"],
+      "secondaryTag": "Quick Start",
+      "votes": 0,
+      "gaClicks": 0,
+      "icon": "FolderOpen",
+      "author": "DC team",
+      "verified": true
+    },
+    {
+      "id": "onb2_02",
+      "title": "Explain codebase or repository to me",
+      "description": "Analyze and explain any codebase - local project or GitHub repository - including architecture, dependencies, and how it works.",
+      "prompt": "I'll analyze and explain any codebase for you! 🔍\n\n**What should I analyze?**\n\n*Local project:* `~/work/my-project` (replace with your path)\n*GitHub repo:* `https://github.com/user/repo`\n\nI'll break down the architecture, dependencies, and how everything works together!",
+      "categories": ["onboarding"],      "secondaryTag": "Code Analysis",
+      "votes": 0,
+      "gaClicks": 0,
+      "icon": "Code",
+      "author": "DC team",
+      "verified": true
+    },
+    {
+      "id": "onb2_03",
+      "title": "Create organized knowledge/documents folder",
+      "description": "Set up a well-structured knowledge base or document organization system with templates and suggested categories.",
+      "prompt": "Let's create an organized knowledge base! 📚\n\n**Where should I set it up?**\n\n*I suggest: `~/Documents/Knowledge-Base` (replace with your path) or give me a different location.*\n\nI'll create a clean folder structure with templates and organize any existing documents you have!",
+      "categories": ["onboarding"],
+      "secondaryTag": "Quick Start",
+      "votes": 0,
+      "gaClicks": 0,
+      "icon": "BookOpen",
+      "author": "DC team",
+      "verified": true
+    },
+    {
+      "id": "onb2_04",
+      "title": "Analyze my data file",
+      "description": "Upload or point to any data file (CSV, JSON, Excel, etc.) and get comprehensive analysis including patterns, insights, and summary reports.",
+      "prompt": "I'll help you analyze your data file! \n\nWhat's the path to your data file? (e.g., `/Users/yourname/data.csv`)\n\nOnce you give me the path, I'll start by checking what type of file it is and show you a quick preview, then we can dive deeper step by step.",
+      "categories": ["onboarding"],
+      "secondaryTag": "Quick Start",
+      "votes": 0,
+      "gaClicks": 0,
+      "icon": "BarChart3",
+      "author": "DC team",
+      "verified": true
+    },
+    {
+      "id": "onb2_05",
+      "title": "Check system health and resources",
+      "description": "Analyze your system's health, resource usage, running processes, and generate a comprehensive system status report.",
+      "prompt": "Let me check your system health and resources!\n\nI'll start by looking at your CPU, memory, and disk usage, then check for any performance issues.\n\nShould I begin the system analysis?",
+      "categories": ["onboarding"],
+      "secondaryTag": "Quick Start",
+      "votes": 0,
+      "gaClicks": 0,
+      "icon": "Activity",
+      "author": "DC team",
+      "verified": true
+    }
+  ]
+}

package/dist/device/gateway-pairing.d.ts

@@ -16,6 +16,7 @@ export interface GatewayPairingOptions {
     deviceName?: string;
     fetchFn?: typeof fetch;
     proxyAgent?: Agent;
+    /** @deprecated Pairing is intentionally terminal-only; this hook is ignored. */
     openBrowser?: (url: string) => Promise<unknown>;
     renderQr?: (value: string) => void;
     sleep?: (ms: number) => Promise<void>;

package/dist/device/gateway-pairing.js

@@ -1,7 +1,6 @@
 import { createHash, randomBytes } from 'crypto';
 import { createRequire } from 'module';
 import os from 'os';
-import open from 'open';
 import fetch from 'cross-fetch';
 import { gatewayHttpBase } from './gateway-url-policy.js';
 const CLIENT_ID = 'mcp-device';
@@ -34,7 +33,6 @@ async function jsonResponse(response) {
 export async function pairGatewayDevice(options) {
     const baseUrl = gatewayHttpBase(options.gatewayUrl);
     const fetchFn = options.fetchFn || fetch;
-    const openBrowser = options.openBrowser || (url => open(url));
     const renderQr = options.renderQr || defaultQrRenderer;
     const sleep = options.sleep || (ms => new Promise(resolve => setTimeout(resolve, ms)));
     const log = options.log || (value => console.log(value));
@@ -62,10 +60,6 @@ export async function pairGatewayDevice(options) {
     log(`Pair this device: ${verificationUrl}`);
     log(`Code: ${start.user_code}`);
     renderQr(verificationUrl);
-    try {
-        await openBrowser(verificationUrl);
-    }
-    catch { /* URL + QR remain usable */ }
     const intervalMs = Math.max(1000, Math.min(30000, Number(start.interval || 2) * 1000));
     const deadline = Date.now() + Math.max(1, Number(start.expires_in || 600)) * 1000;
     while (Date.now() < deadline) {

package/dist/handlers/filesystem-handlers.js

@@ -289,8 +289,8 @@ export async function handleWriteFile(args) {
         const lineCount = lines.length;
         let errorMessage = "";
         if (lineCount > MAX_LINES) {
-            errorMessage = `✅ File written successfully! (${lineCount} lines)
-            
+            errorMessage = `✅ File written successfully! (${lineCount} lines)
+            
 💡 Performance tip: For optimal speed, consider chunking files into ≤30 line pieces in future operations.`;
         }
         // Pass the mode parameter to writeFile