@hcu-lab.me/mcp-device 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +51 -51
  2. package/dist/device/official-trust.d.ts +1 -1
  3. package/dist/device/official-trust.js +11 -4
  4. package/package.json +131 -131
package/README.md CHANGED
@@ -1,51 +1,51 @@
1
- # MCP Device
2
-
3
- `@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.
4
-
5
- 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.
6
-
7
- ## Commands
8
-
9
- ```text
10
- mcp-device start in the foreground
11
- mcp-device start start in the foreground
12
- mcp-device login explicitly link or switch the gateway account
13
- mcp-device logout unlink the gateway account from this device
14
- mcp-device status show runtime, manager, connection, security, proxy, usage, and schema state
15
- mcp-device install pair if needed, then install and start a background runtime
16
- mcp-device stop stop the current runtime without deleting identity/account state
17
- mcp-device uninstall remove background registration while preserving identity/account state
18
- mcp-device --help show command help
19
- ```
20
-
21
- `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.
22
-
23
- 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.
24
-
25
- ## First run and trust
26
-
27
- 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.
28
-
29
- 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.
30
-
31
- ## Local state and migration
32
-
33
- 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.
34
-
35
- 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.
36
-
37
- ## Development
38
-
39
- ```powershell
40
- git clone https://github.com/Hiroshimeow/agent-mcp-device.git
41
- cd agent-mcp-device
42
- npm ci
43
- npm run build
44
- node dist/mcp-device.js --help
45
- ```
46
-
47
- 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.
48
-
49
- ## Upstream execution engine
50
-
51
- 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.
1
+ # MCP Device
2
+
3
+ `@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.
4
+
5
+ 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.
6
+
7
+ ## Commands
8
+
9
+ ```text
10
+ mcp-device start in the foreground
11
+ mcp-device start start in the foreground
12
+ mcp-device login explicitly link or switch the gateway account
13
+ mcp-device logout unlink the gateway account from this device
14
+ mcp-device status show runtime, manager, connection, security, proxy, usage, and schema state
15
+ mcp-device install pair if needed, then install and start a background runtime
16
+ mcp-device stop stop the current runtime without deleting identity/account state
17
+ mcp-device uninstall remove background registration while preserving identity/account state
18
+ mcp-device --help show command help
19
+ ```
20
+
21
+ `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.
22
+
23
+ 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.
24
+
25
+ ## First run and trust
26
+
27
+ 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.
28
+
29
+ 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.
30
+
31
+ ## Local state and migration
32
+
33
+ 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.
34
+
35
+ 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.
36
+
37
+ ## Development
38
+
39
+ ```powershell
40
+ git clone https://github.com/Hiroshimeow/agent-mcp-device.git
41
+ cd agent-mcp-device
42
+ npm ci
43
+ npm run build
44
+ node dist/mcp-device.js --help
45
+ ```
46
+
47
+ 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.
48
+
49
+ ## Upstream execution engine
50
+
51
+ 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/device/official-trust.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { GatewayDeviceConfigStore, type GatewayDeviceConfig } from './gateway-config.js';
2
- export declare const OFFICIAL_GATEWAY_URL = "https://mcp-v2.hcu-lab.me/mcp";
2
+ export declare const OFFICIAL_GATEWAY_URL = "https://device.hcu-lab.me";
3
3
  export declare function isOfficialGatewayUrl(value: string | null | undefined): boolean;
4
4
  export declare function bootstrapOfficialGatewayTrust(store: GatewayDeviceConfigStore, options?: {
5
5
  gatewayUrl?: string | null;
package/dist/device/official-trust.js CHANGED
@@ -1,10 +1,14 @@
1
1
  import { X509Certificate } from 'crypto';
2
2
  import fs from 'fs/promises';
3
3
  import { fileURLToPath } from 'url';
4
- export const OFFICIAL_GATEWAY_URL = 'https://mcp-v2.hcu-lab.me/mcp';
4
+ export const OFFICIAL_GATEWAY_URL = 'https://device.hcu-lab.me';
5
5
  function normalizedUrl(value) {
6
6
  return new URL(value).toString();
7
7
  }
8
+ function isOfficialGatewayHost(hostname) {
9
+ const host = hostname.toLowerCase();
10
+ return host === 'hcu-lab.me' || host.endsWith('.hcu-lab.me');
11
+ }
8
12
  function defaultOfficialCaPath() {
9
13
  return fileURLToPath(new URL('../data/official-app-ca.pem', import.meta.url));
10
14
  }
@@ -12,7 +16,8 @@ export function isOfficialGatewayUrl(value) {
12
16
  if (!value)
13
17
  return false;
14
18
  try {
15
- return normalizedUrl(value) === normalizedUrl(OFFICIAL_GATEWAY_URL);
19
+ const url = new URL(value);
20
+ return url.protocol === 'https:' && isOfficialGatewayHost(url.hostname);
16
21
  }
17
22
  catch {
18
23
  return false;
@@ -28,7 +33,9 @@ export async function bootstrapOfficialGatewayTrust(store, options = {}) {
28
33
  return await store.update({ gatewayUrl });
29
34
  }
30
35
  if (current.appCaPem && current.securityProtocolFloor >= 2 && isOfficialGatewayUrl(current.gatewayUrl || gatewayUrl)) {
31
- return current;
36
+ if (current.gatewayUrl && normalizedUrl(current.gatewayUrl) === normalizedUrl(gatewayUrl))
37
+ return current;
38
+ return await store.update({ gatewayUrl });
32
39
  }
33
40
  const caPath = options.caPath || defaultOfficialCaPath();
34
41
  let appCaPem;
@@ -42,7 +49,7 @@ export async function bootstrapOfficialGatewayTrust(store, options = {}) {
42
49
  throw new Error(`Official MCP Device application CA is not provisioned in this package; refusing network bootstrap: ${error?.message || error}`);
43
50
  }
44
51
  return await store.update({
45
- gatewayUrl: OFFICIAL_GATEWAY_URL,
52
+ gatewayUrl,
46
53
  appCaPem,
47
54
  securityProtocolFloor: 2
48
55
  });
package/package.json CHANGED
@@ -1,131 +1,131 @@
1
- {
2
- "name": "@hcu-lab.me/mcp-device",
3
- "version": "1.0.0",
4
- "description": "MCP Device securely connects a user-owned computer to an authenticated Model Context Protocol gateway.",
5
- "license": "MIT",
6
- "author": "Hirohimeow",
7
- "homepage": "https://github.com/Hiroshimeow/agent-mcp-device",
8
- "repository": {
9
- "type": "git",
10
- "url": "https://github.com/Hiroshimeow/agent-mcp-device.git"
11
- },
12
- "bugs": "https://github.com/Hiroshimeow/agent-mcp-device/issues",
13
- "type": "module",
14
- "engines": {
15
- "node": ">=18.0.0"
16
- },
17
- "bin": {
18
- "mcp-device": "dist/mcp-device.js",
19
- "md": "dist/mcp-device.js"
20
- },
21
- "files": [
22
- "dist"
23
- ],
24
- "scripts": {
25
- "device:install": "cd src/device && npm install",
26
- "device:start": "tsx src/device/device.ts",
27
- "device:start:dev": "nodemon --watch src/device --exec tsx src/device/device.ts",
28
- "sync-version": "node scripts/sync-version.js",
29
- "bump": "node scripts/sync-version.js --bump",
30
- "bump:minor": "node scripts/sync-version.js --bump --minor",
31
- "bump:major": "node scripts/sync-version.js --bump --major",
32
- "build": "shx rm -rf dist/remote-device && shx rm -f dist/device/desktop-commander-integration.js dist/device/desktop-commander-integration.d.ts && tsc && shx chmod +x dist/*.js && shx mkdir -p dist/data && shx cp src/data/onboarding-prompts.json dist/data/ && node scripts/copy-official-ca.cjs && node scripts/build-ui-runtime.cjs",
33
- "watch": "tsc --watch",
34
- "start": "node dist/mcp-device.js",
35
- "start:debug": "node --inspect-brk=9229 dist/mcp-device.js",
36
- "prepack": "node scripts/verify-production-trust.cjs && shx rm -rf dist/remote-device && shx rm -f dist/device/desktop-commander-integration.js dist/device/desktop-commander-integration.d.ts dist/hcu-device.js dist/hcu-device.d.ts dist/track-installation.js dist/setup-claude-server.js dist/uninstall-claude-server.js dist/npm-scripts/setup.js dist/npm-scripts/setup.d.ts dist/npm-scripts/uninstall.js dist/npm-scripts/uninstall.d.ts dist/npm-scripts/verify-ripgrep.js dist/npm-scripts/verify-ripgrep.d.ts",
37
- "prepare": "npm run build",
38
- "clean": "shx rm -rf dist",
39
- "test": "npm run build && node test/run-all-tests.js",
40
- "test:integration": "npm run build && node test/integration/run-all-integration-tests.js",
41
- "test:debug": "node --inspect test/run-all-tests.js",
42
- "link:local": "npm run build && npm link",
43
- "unlink:local": "npm unlink",
44
- "inspector": "npx @modelcontextprotocol/inspector dist/index.js",
45
- "logs:view": "npm run build && node scripts/view-fuzzy-logs.js",
46
- "logs:analyze": "npm run build && node scripts/analyze-fuzzy-logs.js",
47
- "logs:clear": "npm run build && node scripts/clear-fuzzy-logs.js",
48
- "logs:export": "npm run build && node scripts/export-fuzzy-logs.js",
49
- "count-tokens": "npm run build && node scripts/count-tokens.js",
50
- "count-tokens:json": "npm run build && node scripts/count-tokens.js --json"
51
- },
52
- "keywords": [
53
- "mcp",
54
- "model-context-protocol",
55
- "terminal",
56
- "claude",
57
- "ai",
58
- "command-line",
59
- "process-management",
60
- "file-editing",
61
- "code-editing",
62
- "diff",
63
- "patch",
64
- "block-editing",
65
- "file-system",
66
- "text-manipulation",
67
- "code-modification",
68
- "surgical-edits",
69
- "file-operations"
70
- ],
71
- "dependencies": {
72
- "@modelcontextprotocol/sdk": "^1.9.0",
73
- "@opendocsg/pdf2md": "^0.2.2",
74
- "@tiptap/core": "^3.31.3",
75
- "@tiptap/extension-image": "^3.31.3",
76
- "@tiptap/extension-table": "^3.31.3",
77
- "@tiptap/extension-table-cell": "^3.31.3",
78
- "@tiptap/extension-table-header": "^3.31.3",
79
- "@tiptap/extension-table-row": "^3.31.3",
80
- "@tiptap/pm": "^3.31.3",
81
- "@tiptap/starter-kit": "^3.31.3",
82
- "@vscode/ripgrep": "^1.15.9",
83
- "cross-fetch": "^4.1.0",
84
- "exceljs": "^4.4.0",
85
- "fastest-levenshtein": "^1.0.16",
86
- "file-type": "^21.1.1",
87
- "highlight.js": "^11.11.1",
88
- "isbinaryfile": "^5.0.4",
89
- "markdown-it": "^14.1.0",
90
- "md-to-pdf": "^5.2.5",
91
- "open": "^10.2.0",
92
- "pdf-lib": "^1.17.1",
93
- "pizzip": "^3.2.0",
94
- "proxy-agent": "6.5.0",
95
- "proxy-from-env": "2.1.0",
96
- "qrcode-terminal": "^0.12.0",
97
- "remark": "^15.0.1",
98
- "remark-gfm": "^4.0.1",
99
- "remark-parse": "^11.0.0",
100
- "sharp": "^0.35.4",
101
- "tiptap-markdown": "^0.9.0",
102
- "unified": "^11.0.5",
103
- "unpdf": "^1.4.0",
104
- "ws": "^8.18.3",
105
- "zod": "^3.24.1",
106
- "zod-to-json-schema": "^3.23.5"
107
- },
108
- "optionalDependencies": {
109
- "caffeinate": "^1.0.1"
110
- },
111
- "devDependencies": {
112
- "@modelcontextprotocol/ext-apps": "^1.0.1",
113
- "@types/node": "^20.17.24",
114
- "@types/ws": "^8.18.1",
115
- "commander": "^13.1.0",
116
- "esbuild": "^0.27.2",
117
- "js-tiktoken": "^1.0.21",
118
- "jsdom": "^24.1.3",
119
- "nodemon": "^3.0.2",
120
- "shx": "^0.3.4",
121
- "ts-node": "^10.9.2",
122
- "tsx": "^4.21.0",
123
- "typescript": "^5.3.3"
124
- },
125
- "overrides": {
126
- "@mapbox/node-pre-gyp": "^2.0.3",
127
- "exceljs": {
128
- "uuid": "^11.1.1"
129
- }
130
- }
131
- }
1
+ {
2
+ "name": "@hcu-lab.me/mcp-device",
3
+ "version": "1.0.1",
4
+ "description": "MCP Device securely connects a user-owned computer to an authenticated Model Context Protocol gateway.",
5
+ "license": "MIT",
6
+ "author": "Hirohimeow",
7
+ "homepage": "https://github.com/Hiroshimeow/agent-mcp-device",
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "https://github.com/Hiroshimeow/agent-mcp-device.git"
11
+ },
12
+ "bugs": "https://github.com/Hiroshimeow/agent-mcp-device/issues",
13
+ "type": "module",
14
+ "engines": {
15
+ "node": ">=18.0.0"
16
+ },
17
+ "bin": {
18
+ "mcp-device": "dist/mcp-device.js",
19
+ "md": "dist/mcp-device.js"
20
+ },
21
+ "files": [
22
+ "dist"
23
+ ],
24
+ "scripts": {
25
+ "device:install": "cd src/device && npm install",
26
+ "device:start": "tsx src/device/device.ts",
27
+ "device:start:dev": "nodemon --watch src/device --exec tsx src/device/device.ts",
28
+ "sync-version": "node scripts/sync-version.js",
29
+ "bump": "node scripts/sync-version.js --bump",
30
+ "bump:minor": "node scripts/sync-version.js --bump --minor",
31
+ "bump:major": "node scripts/sync-version.js --bump --major",
32
+ "build": "shx rm -rf dist/remote-device && shx rm -f dist/device/desktop-commander-integration.js dist/device/desktop-commander-integration.d.ts && tsc && shx chmod +x dist/*.js && shx mkdir -p dist/data && shx cp src/data/onboarding-prompts.json dist/data/ && node scripts/copy-official-ca.cjs && node scripts/build-ui-runtime.cjs",
33
+ "watch": "tsc --watch",
34
+ "start": "node dist/mcp-device.js",
35
+ "start:debug": "node --inspect-brk=9229 dist/mcp-device.js",
36
+ "prepack": "node scripts/verify-production-trust.cjs && shx rm -rf dist/remote-device && shx rm -f dist/device/desktop-commander-integration.js dist/device/desktop-commander-integration.d.ts dist/hcu-device.js dist/hcu-device.d.ts dist/track-installation.js dist/setup-claude-server.js dist/uninstall-claude-server.js dist/npm-scripts/setup.js dist/npm-scripts/setup.d.ts dist/npm-scripts/uninstall.js dist/npm-scripts/uninstall.d.ts dist/npm-scripts/verify-ripgrep.js dist/npm-scripts/verify-ripgrep.d.ts",
37
+ "prepare": "npm run build",
38
+ "clean": "shx rm -rf dist",
39
+ "test": "npm run build && node test/run-all-tests.js",
40
+ "test:integration": "npm run build && node test/integration/run-all-integration-tests.js",
41
+ "test:debug": "node --inspect test/run-all-tests.js",
42
+ "link:local": "npm run build && npm link",
43
+ "unlink:local": "npm unlink",
44
+ "inspector": "npx @modelcontextprotocol/inspector dist/index.js",
45
+ "logs:view": "npm run build && node scripts/view-fuzzy-logs.js",
46
+ "logs:analyze": "npm run build && node scripts/analyze-fuzzy-logs.js",
47
+ "logs:clear": "npm run build && node scripts/clear-fuzzy-logs.js",
48
+ "logs:export": "npm run build && node scripts/export-fuzzy-logs.js",
49
+ "count-tokens": "npm run build && node scripts/count-tokens.js",
50
+ "count-tokens:json": "npm run build && node scripts/count-tokens.js --json"
51
+ },
52
+ "keywords": [
53
+ "mcp",
54
+ "model-context-protocol",
55
+ "terminal",
56
+ "claude",
57
+ "ai",
58
+ "command-line",
59
+ "process-management",
60
+ "file-editing",
61
+ "code-editing",
62
+ "diff",
63
+ "patch",
64
+ "block-editing",
65
+ "file-system",
66
+ "text-manipulation",
67
+ "code-modification",
68
+ "surgical-edits",
69
+ "file-operations"
70
+ ],
71
+ "dependencies": {
72
+ "@modelcontextprotocol/sdk": "^1.9.0",
73
+ "@opendocsg/pdf2md": "^0.2.2",
74
+ "@tiptap/core": "^3.31.3",
75
+ "@tiptap/extension-image": "^3.31.3",
76
+ "@tiptap/extension-table": "^3.31.3",
77
+ "@tiptap/extension-table-cell": "^3.31.3",
78
+ "@tiptap/extension-table-header": "^3.31.3",
79
+ "@tiptap/extension-table-row": "^3.31.3",
80
+ "@tiptap/pm": "^3.31.3",
81
+ "@tiptap/starter-kit": "^3.31.3",
82
+ "@vscode/ripgrep": "^1.15.9",
83
+ "cross-fetch": "^4.1.0",
84
+ "exceljs": "^4.4.0",
85
+ "fastest-levenshtein": "^1.0.16",
86
+ "file-type": "^21.1.1",
87
+ "highlight.js": "^11.11.1",
88
+ "isbinaryfile": "^5.0.4",
89
+ "markdown-it": "^14.1.0",
90
+ "md-to-pdf": "^5.2.5",
91
+ "open": "^10.2.0",
92
+ "pdf-lib": "^1.17.1",
93
+ "pizzip": "^3.2.0",
94
+ "proxy-agent": "6.5.0",
95
+ "proxy-from-env": "2.1.0",
96
+ "qrcode-terminal": "^0.12.0",
97
+ "remark": "^15.0.1",
98
+ "remark-gfm": "^4.0.1",
99
+ "remark-parse": "^11.0.0",
100
+ "sharp": "^0.35.4",
101
+ "tiptap-markdown": "^0.9.0",
102
+ "unified": "^11.0.5",
103
+ "unpdf": "^1.4.0",
104
+ "ws": "^8.18.3",
105
+ "zod": "^3.24.1",
106
+ "zod-to-json-schema": "^3.23.5"
107
+ },
108
+ "optionalDependencies": {
109
+ "caffeinate": "^1.0.1"
110
+ },
111
+ "devDependencies": {
112
+ "@modelcontextprotocol/ext-apps": "^1.0.1",
113
+ "@types/node": "^20.17.24",
114
+ "@types/ws": "^8.18.1",
115
+ "commander": "^13.1.0",
116
+ "esbuild": "^0.27.2",
117
+ "js-tiktoken": "^1.0.21",
118
+ "jsdom": "^24.1.3",
119
+ "nodemon": "^3.0.2",
120
+ "shx": "^0.3.4",
121
+ "ts-node": "^10.9.2",
122
+ "tsx": "^4.21.0",
123
+ "typescript": "^5.3.3"
124
+ },
125
+ "overrides": {
126
+ "@mapbox/node-pre-gyp": "^2.0.3",
127
+ "exceljs": {
128
+ "uuid": "^11.1.1"
129
+ }
130
+ }
131
+ }