Migrate MCP setup from the desktop into the server

I think desktop inclusion is going to be very short lived, moving instead
to the server gives us more control, and makes it usable standalone
which is helpful especially for testing & local dev.

Author: pimterry

bin/run

@@ -1,4 +1,17 @@
 #!/usr/bin/env node
 
+// The ctl and mcp commands handle --help themselves with dynamic content.
+// Oclif's Main class intercepts --help before dispatching to any command,
+// so we remap it to --show-help to bypass that interception.
+const cmd = process.argv[2];
+if (cmd === 'ctl' || cmd === 'mcp') {
+  for (let i = 3; i < process.argv.length; i++) {
+    if (process.argv[i] === '--help' || process.argv[i] === '-h') {
+      process.argv[i] = '--show-help';
+    }
+    if (process.argv[i] === '--') break;
+  }
+}
+
 require('@oclif/command').run()
-.catch(require('@oclif/errors/handle'))
+.catch(require('@oclif/errors/handle'))

package.json

@@ -98,7 +98,8 @@
     "tmp": "0.2.4",
     "tslib": "^1.9.3",
     "usbmux-client": "^0.2.1",
-    "win-version-info": "^5.0.1"
+    "win-version-info": "^5.0.1",
+    "ws": "^8.18.0"
   },
   "devDependencies": {
     "@oclif/dev-cli": "^1.19.4",
@@ -119,7 +120,7 @@
     "@types/node-forge": "^0.9.9",
     "@types/request-promise-native": "^1.0.15",
     "@types/rimraf": "^2.0.2",
-    "@types/ws": "^6.0.1",
+    "@types/ws": "^8.5.0",
     "axios": "^1.8.2",
     "bent": "^1.5.13",
     "chai": "^4.2.0",

src/api/api-model.ts

@@ -1,11 +1,15 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
 import * as _ from 'lodash';
 import * as os from 'os';
+import * as semver from 'semver';
 
 import { ErrorLike, delay } from '@httptoolkit/util';
 import { generateSPKIFingerprint } from 'mockttp';
 import { getSystemProxy } from 'os-proxy-config';
 
-import { SERVER_VERSION } from "../constants";
+import { APP_ROOT, SERVER_VERSION } from "../constants";
 import { logError, addBreadcrumb } from '../error-tracking';
 
 import { HtkConfig } from "../config";
@@ -18,6 +22,50 @@ import { HttpClient } from '../client/http-client';
 
 const INTERCEPTOR_TIMEOUT = 1000;
 
+/**
+ * Returns the command + args needed to invoke the ctl and mcp tools.
+ *
+ * If HTK_TOOLS_PATH is set (by the desktop app), wrapper scripts in that
+ * directory are used. Otherwise the server's own binary is used with ctl/mcp
+ * subcommands, stabilized via the oclif 'current' symlink when available.
+ */
+function getToolPaths(): { ctl: string[]; mcp: string[] } {
+    // If we're running via a modern desktop app, we can use the path provided directly:
+    const toolsPath = process.env.HTK_TOOLS_PATH;
+    if (toolsPath) {
+        const ext = process.platform === 'win32' ? '.cmd' : '';
+        return {
+            ctl: [path.join(toolsPath, `httptoolkit-ctl${ext}`)],
+            mcp: [path.join(toolsPath, `httptoolkit-mcp${ext}`)]
+        };
+    }
+
+    // If not (old desktop, local dev) we need to use our own path directly:
+    const serverBin = stabilizeServerBinPath();
+    return {
+        ctl: [serverBin, 'ctl'],
+        mcp: [serverBin, 'mcp']
+    };
+}
+
+function stabilizeServerBinPath(): string {
+    const binPath = process.env.HTTPTOOLKIT_SERVER_BINPATH
+        ?? path.join(APP_ROOT, 'bin', process.platform === 'win32' ? 'run.cmd' : 'run');
+
+    // If the server is running from a versioned oclif directory (e.g. .../client/1.25.0/...),
+    // replace the version segment with 'current' for a path that survives updates.
+    const appRootBase = path.basename(APP_ROOT);
+    if (semver.valid(appRootBase) && binPath.startsWith(APP_ROOT)) {
+        const currentDir = path.join(path.dirname(APP_ROOT), 'current');
+        try {
+            fs.accessSync(currentDir);
+            return currentDir + binPath.slice(APP_ROOT.length);
+        } catch {}
+    }
+
+    return binPath;
+}
+
 export class ApiModel {
 
     constructor(
@@ -83,7 +131,9 @@ export class ApiModel {
             systemProxy,
             dnsServers,
 
-            ruleParameterKeys: this.getRuleParamKeys()
+            ruleParameterKeys: this.getRuleParamKeys(),
+
+            toolPaths: getToolPaths()
         };
     }
 

src/api/api-server.ts

@@ -1,8 +1,10 @@
+import * as http from 'http';
 import _ from 'lodash';
 import * as events from 'events';
 import express from 'express';
 import cors from 'cors';
 import corsGate from 'cors-gate';
+import * as WebSocket from 'ws';
 
 import { HtkConfig } from '../config';
 import { buildInterceptors } from '../interceptors';
@@ -13,6 +15,7 @@ import { ApiModel } from './api-model';
 import { exposeGraphQLAPI } from './graphql-api';
 import { exposeRestAPI } from './rest-api';
 import { HttpClient } from '../client/http-client';
+import { UiOperationBridge, getSocketPath } from './ui-operation-bridge';
 
 /**
  * This file contains the core server API, used by the UI to query
@@ -39,6 +42,8 @@ import { HttpClient } from '../client/http-client';
 export class HttpToolkitServerApi extends events.EventEmitter {
 
     private server: express.Application;
+    private bridge: UiOperationBridge;
+    private authToken: string | undefined;
 
     constructor(
         config: HtkConfig,
@@ -47,6 +52,9 @@ export class HttpToolkitServerApi extends events.EventEmitter {
     ) {
         super();
 
+        this.bridge = new UiOperationBridge();
+        this.authToken = config.authToken;
+
         const interceptors = buildInterceptors(config);
 
         this.server = express();
@@ -134,8 +142,64 @@ export class HttpToolkitServerApi extends events.EventEmitter {
 
     start() {
         return new Promise<void>((resolve, reject) => {
-            this.server.listen(45457, '127.0.0.1', resolve); // Localhost only
-            this.server.once('error', reject);
+            const httpServer: http.Server = this.server.listen(45457, '127.0.0.1', resolve);
+            httpServer.once('error', reject);
+
+            this.attachWebSocketBridge(httpServer);
+            this.startBridgeApiServer();
+        });
+    }
+
+    private attachWebSocketBridge(httpServer: http.Server) {
+        const wss = new WebSocket.Server({ noServer: true });
+
+        httpServer.on('upgrade', (req: http.IncomingMessage, socket, head) => {
+            const url = new URL(req.url!, `http://localhost`);
+
+            if (url.pathname !== '/ui-operations') {
+                socket.destroy();
+                return;
+            }
+
+            // Enforce the same origin restrictions as the REST/GraphQL API
+            const origin = req.headers['origin'] || '';
+            if (!ALLOWED_ORIGINS.some(pattern => pattern.test(origin))) {
+                socket.write('HTTP/1.1 403 Forbidden\r\n\r\n');
+                socket.destroy();
+                return;
+            }
+
+            // Check auth token if configured. Browser WebSocket can't send
+            // headers, so accept token via query param or Authorization header.
+            if (this.authToken) {
+                const authHeader = req.headers['authorization'] || '';
+                const tokenMatch = authHeader.match(/Bearer (\S+)/) || [];
+                const headerToken = tokenMatch[1];
+                const queryToken = url.searchParams.get('token');
+
+                if (headerToken !== this.authToken && queryToken !== this.authToken) {
+                    socket.write('HTTP/1.1 403 Forbidden\r\n\r\n');
+                    socket.destroy();
+                    return;
+                }
+            }
+
+            wss.handleUpgrade(req, socket as any, head, (ws) => {
+                this.bridge.setWebSocket(ws as any);
+            });
         });
     }
+
+    private startBridgeApiServer() {
+        try {
+            const socketPath = getSocketPath();
+            this.bridge.startApiServer(socketPath);
+        } catch (err: any) {
+            console.warn(
+                `Failed to start UI Bridge socket server: ${err.message}. ` +
+                `MCP & remote control will not be available.`
+            );
+        }
+    }
+
 };

src/api/bridge-client.ts

@@ -0,0 +1,58 @@
+import * as http from 'http';
+
+import { getDeferred } from '@httptoolkit/util';
+
+import { getSocketPath } from './ui-operation-bridge';
+
+export function apiRequest(
+    method: 'GET' | 'POST',
+    urlPath: string,
+    body?: any
+): Promise<any> {
+    const result = getDeferred<any>();
+
+    const req = http.request({
+        method,
+        path: urlPath,
+        socketPath: getSocketPath(),
+        headers: {
+            'Content-Type': 'application/json'
+        }
+    }, (res) => {
+        const chunks: Buffer[] = [];
+        res.on('error', (err) => result.reject(err));
+        res.on('data', (chunk: Buffer) => chunks.push(chunk));
+        res.on('end', () => {
+            const raw = Buffer.concat(chunks).toString('utf-8');
+            if (res.statusCode && res.statusCode >= 400) {
+                try {
+                    const err = JSON.parse(raw);
+                    result.reject(new Error(err.message || err.error || `HTTP ${res.statusCode}`));
+                } catch {
+                    result.reject(new Error(`HTTP ${res.statusCode}: ${raw}`));
+                }
+                return;
+            }
+            try {
+                result.resolve(JSON.parse(raw));
+            } catch {
+                result.reject(new Error(`Unparseable response: ${raw}`));
+            }
+        });
+    });
+
+    req.on('error', (err: any) => {
+        if (err.code === 'ECONNREFUSED' || err.code === 'ENOENT') {
+            result.reject(new Error('HTTP Toolkit is not running. Start HTTP Toolkit first.'));
+        } else {
+            result.reject(err);
+        }
+    });
+
+    if (body) {
+        req.write(JSON.stringify(body));
+    }
+    req.end();
+
+    return result;
+}