@harperfast/harper 5.0.30 → 5.1.0-beta.2

package/server/middlewareChain.ts

@@ -0,0 +1,270 @@
+export type HttpEntry = {
+	listener: Function;
+	port: number | string;
+	name?: string;
+	before?: string;
+	after?: string;
+	urlPath?: string;
+	host?: string;
+};
+
+/**
+ * Topological sort of middleware entries respecting `before`/`after` constraints.
+ * Uses the original registration index as a tiebreaker so config order is preserved
+ * when there are no constraints between two entries.
+ *
+ * `before: 'X'` → this entry must run before the FIRST entry named X.
+ * `after: 'X'`  → this entry must run after the LAST entry named X.
+ *
+ * @param onCycle - called when a cycle is detected; entries are returned unsorted.
+ */
+export function topoSort(entries: HttpEntry[], onCycle?: () => void): HttpEntry[] {
+	const n = entries.length;
+	if (n <= 1) return entries;
+
+	// Map name → first and last index (for before/after semantics)
+	const nameToFirst = new Map<string, number>();
+	const nameToLast = new Map<string, number>();
+	for (let i = 0; i < n; i++) {
+		const name = entries[i].name;
+		if (name) {
+			if (!nameToFirst.has(name)) nameToFirst.set(name, i);
+			nameToLast.set(name, i);
+		}
+	}
+
+	// successors[i] = list of indices that must come after i
+	const successors: number[][] = Array.from({ length: n }, () => []);
+	const inDegree = new Int32Array(n);
+	const addEdge = (from: number, to: number) => {
+		successors[from].push(to);
+		inDegree[to]++;
+	};
+
+	for (let i = 0; i < n; i++) {
+		const { before, after } = entries[i];
+		if (before) {
+			const j = nameToFirst.get(before);
+			if (j !== undefined && j !== i) addEdge(i, j);
+		}
+		if (after) {
+			const j = nameToLast.get(after);
+			if (j !== undefined && j !== i) addEdge(j, i);
+		}
+	}
+
+	// Kahn's algorithm; use original index as tiebreaker to preserve registration/config order
+	const ready: number[] = [];
+	for (let i = 0; i < n; i++) {
+		if (inDegree[i] === 0) ready.push(i);
+	}
+
+	const sorted: HttpEntry[] = [];
+	while (ready.length > 0) {
+		const i = ready.shift()!;
+		sorted.push(entries[i]);
+		for (const j of successors[i]) {
+			if (--inDegree[j] === 0) {
+				// Binary-insert to keep ready sorted by original index
+				let lo = 0,
+					hi = ready.length;
+				while (lo < hi) {
+					const mid = (lo + hi) >> 1;
+					if (ready[mid] < j) lo = mid + 1;
+					else hi = mid;
+				}
+				ready.splice(lo, 0, j);
+			}
+		}
+	}
+
+	if (sorted.length !== n) {
+		onCycle?.();
+		return entries;
+	}
+	return sorted;
+}
+
+/**
+ * Builds a linear middleware chain from a sorted array of entries.
+ * The first entry in `sorted` is the outermost (called first).
+ * `fallback` is invoked when all entries call next() without handling the request.
+ */
+export function buildLinearChain(sorted: HttpEntry[], fallback: Function): Function {
+	let next = fallback;
+	for (let i = sorted.length; i > 0; ) {
+		const { listener } = sorted[--i];
+		const callback = next;
+		next = (...args: any[]) => listener(...args, callback);
+	}
+	return next;
+}
+
+/**
+ * Resolves transitive `after` dependencies for a set of entries.
+ * If entry A says `after: 'auth'` and auth is in `nameToEntry` but not in `entries`,
+ * auth is pulled into the result so that the ordering constraint can be satisfied.
+ * `before` constraints do NOT pull in entries — they only affect ordering.
+ */
+export function resolveDeps(entries: HttpEntry[], nameToEntry: Map<string, HttpEntry>): HttpEntry[] {
+	const included = new Set(entries);
+	let changed = true;
+	while (changed) {
+		changed = false;
+		for (const entry of [...included]) {
+			if (entry.after) {
+				const dep = nameToEntry.get(entry.after);
+				if (dep && !included.has(dep)) {
+					included.add(dep);
+					changed = true;
+				}
+			}
+		}
+	}
+	return [...included];
+}
+
+/**
+ * Normalizes a urlPath by stripping a single trailing slash (except for the root '/').
+ * '/api' and '/api/' are treated equivalently for routing/matching.
+ */
+export function normalizeUrlPath(urlPath: string | undefined): string | undefined {
+	if (!urlPath || urlPath.length <= 1) return urlPath;
+	return urlPath.endsWith('/') ? urlPath.slice(0, -1) : urlPath;
+}
+
+/**
+ * Returns true when `request` satisfies the route's host and urlPath constraints.
+ * urlPath matching is prefix-based and segment-boundary-aware:
+ *   '/api' matches '/api' and '/api/foo' but NOT '/api2'.
+ * Trailing slashes on `route.urlPath` are ignored.
+ */
+export function matchesRoute(request: any, route: { host?: string; urlPath?: string }): boolean {
+	if (route.host) {
+		const hostHeader: string = request.headers?.asObject?.host ?? '';
+		const requestHost = hostHeader.split(':')[0];
+		if (requestHost !== route.host) return false;
+	}
+	const urlPath = normalizeUrlPath(route.urlPath);
+	if (urlPath) {
+		const pathname: string = request.pathname ?? '/';
+		if (pathname !== urlPath && !pathname.startsWith(urlPath + '/')) return false;
+	}
+	return true;
+}
+
+/**
+ * Returns a proxy of `request` with `pathname` and `url` rewritten so that
+ * `prefix` is stripped from the path. e.g. prefix='/foo', pathname='/foo/bar' → '/bar'.
+ * Trailing slashes on `prefix` are ignored. The strip is computed lazily on each
+ * access so that downstream mutations to `request.pathname` remain reflected.
+ * The original request object is not mutated.
+ */
+export function stripPrefix(request: any, prefix: string): any {
+	const normalizedPrefix = normalizeUrlPath(prefix) ?? '';
+	return new Proxy(request, {
+		get(target, prop) {
+			if (prop === 'pathname') {
+				const origPathname: string = target.pathname ?? '/';
+				return origPathname === normalizedPrefix ? '/' : origPathname.slice(normalizedPrefix.length);
+			}
+			if (prop === 'url') {
+				const origPathname: string = target.pathname ?? '/';
+				const origUrl: string = target.url ?? '';
+				const stripped = origPathname === normalizedPrefix ? '/' : origPathname.slice(normalizedPrefix.length);
+				return stripped + origUrl.slice(origPathname.length);
+			}
+			return Reflect.get(target, prop);
+		},
+	});
+}
+
+/**
+ * Builds a dispatching chain when sub-routes (urlPath/host) are present.
+ *
+ * Each sub-route gets its own complete chain. If a sub-route entry declares
+ * `after: 'X'`, entry X is pulled in from any route's registry so that the
+ * constraint can be satisfied without requiring X to be explicitly registered
+ * in the sub-route. This is how auth on the default route propagates into
+ * sub-route chains that depend on it.
+ *
+ * Dispatch priority: host+path > host-only > path-only; longer paths win ties.
+ *
+ * `requestArgIndex` tells the dispatcher which positional argument carries the request
+ * object used for host/path matching. HTTP and upgrade chains pass it at index 0;
+ * WebSocket chains pass `(ws, request, chainCompletion)` so request is at index 1.
+ * The matched (and prefix-stripped) request is substituted back into the same
+ * position before forwarding to the inner chain.
+ */
+export function buildRoutedChain(
+	portEntries: HttpEntry[],
+	fallback: Function,
+	onCycle?: () => void,
+	requestArgIndex: number = 0
+): Function {
+	// Global name registry across all routes (first registration wins)
+	const nameToEntry = new Map<string, HttpEntry>();
+	for (const entry of portEntries) {
+		if (entry.name && !nameToEntry.has(entry.name)) nameToEntry.set(entry.name, entry);
+	}
+
+	// Group entries by (host, normalized urlPath) so that '/api' and '/api/' coalesce.
+	type RouteGroup = { host?: string; urlPath?: string; entries: HttpEntry[] };
+	const routeGroups: RouteGroup[] = [];
+	for (const entry of portEntries) {
+		const urlPath = normalizeUrlPath(entry.urlPath);
+		const group = routeGroups.find((g) => g.host === entry.host && g.urlPath === urlPath);
+		if (group) group.entries.push(entry);
+		else routeGroups.push({ host: entry.host, urlPath, entries: [entry] });
+	}
+
+	const defaultGroup = routeGroups.find((g) => !g.host && !g.urlPath);
+	const subRouteGroups = routeGroups.filter((g) => g.host || g.urlPath);
+
+	const subRouteChains = subRouteGroups.map((group) => {
+		const resolved = resolveDeps(group.entries, nameToEntry);
+		return { host: group.host, urlPath: group.urlPath, chain: buildLinearChain(topoSort(resolved, onCycle), fallback) };
+	});
+
+	subRouteChains.sort((a, b) => {
+		const aSpec = (a.host ? 2 : 0) + (a.urlPath ? 1 : 0);
+		const bSpec = (b.host ? 2 : 0) + (b.urlPath ? 1 : 0);
+		if (aSpec !== bSpec) return bSpec - aSpec;
+		return (b.urlPath?.length ?? 0) - (a.urlPath?.length ?? 0);
+	});
+
+	const defaultChain = buildLinearChain(topoSort(defaultGroup?.entries ?? [], onCycle), fallback);
+
+	return function dispatch(...args: any[]) {
+		const request = args[requestArgIndex];
+		for (const route of subRouteChains) {
+			if (matchesRoute(request, route)) {
+				if (route.urlPath) {
+					const newArgs = args.slice();
+					newArgs[requestArgIndex] = stripPrefix(request, route.urlPath);
+					return route.chain(...newArgs);
+				}
+				return route.chain(...args);
+			}
+		}
+		return defaultChain(...args);
+	};
+}
+
+/**
+ * Builds the complete middleware chain for a given port from the full responders list.
+ * Uses a flat linear chain when no sub-routes are present (fast path),
+ * or a route-dispatching chain when any entry has urlPath or host.
+ */
+export function makeCallbackChain(
+	responders: HttpEntry[],
+	portNum: number | string,
+	fallback: Function,
+	onCycle?: () => void,
+	requestArgIndex: number = 0
+): Function {
+	const portEntries = responders.filter(({ port }) => port === portNum || port === 'all');
+	if (portEntries.some((e) => e.urlPath || e.host))
+		return buildRoutedChain(portEntries, fallback, onCycle, requestArgIndex);
+	return buildLinearChain(topoSort(portEntries, onCycle), fallback);
+}

package/server/mqtt.ts

@@ -6,10 +6,10 @@ import { getSuperUser } from '../security/user.ts';
 import { serializeMessage, getDeserializer } from './serverHelpers/contentTypes.ts';
 import { recordAction, addAnalyticsListener, recordActionBinary } from '../resources/analytics/write.ts';
 import { server } from '../server/Server.ts';
-import { get } from '../utility/environment/environmentManager.js';
+import { get } from '../utility/environment/environmentManager.ts';
 import { CONFIG_PARAMS, AUTH_AUDIT_STATUS, AUTH_AUDIT_TYPES } from '../utility/hdbTerms.ts';
 import { loggerWithTag } from '../utility/logging/logger.ts';
-import { forComponent as loggerForComponent } from '../utility/logging/harper_logger.js';
+import { forComponent as loggerForComponent } from '../utility/logging/harper_logger.ts';
 import { EventEmitter } from 'events';
 import { verifyCertificate } from '../security/certificateVerification/index.ts';
 const authEventLog = loggerWithTag('auth-event');
@@ -23,18 +23,25 @@ export function bypassAuth() {
 const authorizeLocal = (remoteAddress: string) =>
 	AUTHORIZE_LOCAL && (remoteAddress.includes('127.0.0.') || remoteAddress === '::1');
 
-export function start({ server, port, network, webSocket, securePort, requireAuthentication }) {
+export function handleApplication(scope: import('../components/Scope.ts').Scope) {
+	const { network, webSocket, requireAuthentication } = scope.options.getAll() as {
+		network?: any;
+		webSocket?: any;
+		requireAuthentication?: boolean;
+	};
+	const server = scope.server;
+	const { port, securePort } = network ?? {};
 	// here we basically normalize the different types of sockets to pass to our socket/message handler
-	if (!server.mqtt) {
-		server.mqtt = {
+	if (!(server as any).mqtt) {
+		(server as any).mqtt = {
 			requireAuthentication,
 			sessions: new Set(),
 			events: new EventEmitter(),
 		};
 		// a no-op error handler to prevent unhandled error events from being rethrown
-		server.mqtt.events.on('error', () => {});
+		(server as any).mqtt.events.on('error', () => {});
 	}
-	const mqttSettings = server.mqtt;
+	const mqttSettings = (server as any).mqtt;
 	function emitEvent(type: string, ...args: any[]) {
 		try {
 			mqttSettings.events.emit(type, ...args);
@@ -45,8 +52,8 @@ export function start({ server, port, network, webSocket, securePort, requireAut
 	let serverInstances = [];
 	const mtls = network?.mtls;
 	if (webSocket)
-		serverInstances = server.ws(
-			(ws, request, chainCompletion, next) => {
+		serverInstances = (server as any).ws(
+			(ws, request, chainCompletion, next: any) => {
 				if (request.headers.get('sec-websocket-protocol') !== 'mqtt') {
 					return next(ws, request, chainCompletion);
 				}
@@ -68,7 +75,7 @@ export function start({ server, port, network, webSocket, securePort, requireAut
 					mqttLog.info?.('WebSocket error', error);
 				});
 			},
-			{ ...webSocket }
+			{ ...webSocket, after: 'authentication' }
 		); // if there is no port, we are piggy-backing off of default app http server
 	// standard TCP socket
 	if (port || securePort) {
@@ -78,13 +85,13 @@ export function start({ server, port, network, webSocket, securePort, requireAut
 					let user;
 					emitEvent('connection', socket);
 					mqttLog.debug?.(
-						`Received ${socket.getCertificate ? 'SSL' : 'TCP'} connection for MQTT from ${socket.remoteAddress}`
+						`Received ${(socket as any).getCertificate ? 'SSL' : 'TCP'} connection for MQTT from ${socket.remoteAddress}`
 					);
 					if (mtls) {
-						if (socket.authorized) {
+						if ((socket as any).authorized) {
 							try {
 								// Perform certificate verification
-								const peerCertificate = socket.getPeerCertificate(true);
+								const peerCertificate = (socket as any).getPeerCertificate(true);
 								if (peerCertificate?.subject) {
 									const verificationResult = await verifyCertificate(peerCertificate, mtls);
 									if (!verificationResult.valid) {
@@ -102,7 +109,7 @@ export function start({ server, port, network, webSocket, securePort, requireAut
 								if (username !== null) {
 									// null means no user is defined from certificate, need regular authentication as well
 									if (username === undefined || username === 'Common Name' || username === 'CN')
-										username = socket.getPeerCertificate().subject.CN;
+										username = (socket as any).getPeerCertificate().subject.CN;
 									try {
 										user = await server.getUser(username, null, null);
 										if (get(CONFIG_PARAMS.LOGGING_AUDITAUTHEVENTS_LOGSUCCESSFUL)) {
@@ -139,7 +146,7 @@ export function start({ server, port, network, webSocket, securePort, requireAut
 							}
 						} else if (mtls.required) {
 							mqttLog.info?.(
-								`Unauthorized connection attempt, no authorized client certificate provided, error: ${socket.authorizationError}`
+								`Unauthorized connection attempt, no authorized client certificate provided, error: ${(socket as any).authorizationError}`
 							);
 							return socket.end();
 						}
@@ -160,7 +167,6 @@ export function start({ server, port, network, webSocket, securePort, requireAut
 			)
 		);
 	}
-	return serverInstances;
 }
 let addingMetrics,
 	numberOfConnections = 0;
@@ -195,7 +201,7 @@ function onSocket(socket, send, request, user, mqttSettings) {
 		numberOfConnections--;
 		if (!disconnected) {
 			disconnected = true;
-			session?.disconnect?.();
+			session?.disconnect?.(false);
 			emitEvent('disconnected', session, socket);
 			mqttSettings.sessions.delete(session);
 			recordActionBinary(false, 'connection', 'mqtt', 'disconnect');
@@ -203,7 +209,7 @@ function onSocket(socket, send, request, user, mqttSettings) {
 		}
 	}
 
-	parser.on('packet', async (packet) => {
+	parser.on('packet', async (packet: any) => {
 		try {
 			if (user?.then) user = await user;
 		} catch (error) {
@@ -213,14 +219,14 @@ function onSocket(socket, send, request, user, mqttSettings) {
 		}
 		const command = packet.cmd;
 		if (session) {
-			if (session.then) await session;
+			if ((session as any).then) await session;
 		} else if (command !== 'connect') {
 			mqttLog.info?.('Received packet before connection was established, closing connection');
 			if (socket?.destroy) socket.destroy();
 			else socket?.terminate();
 			return;
 		}
-		const topic = packet.topic;
+		const topic = (packet as any).topic;
 		const slashIndex = topic?.indexOf('/', 1);
 		const generalTopic = slashIndex > 0 ? topic.slice(0, slashIndex) : topic;
 		recordAction(packet.length, 'bytes-received', generalTopic, packetMethodName(packet), 'mqtt');
@@ -279,14 +285,16 @@ function onSocket(socket, send, request, user, mqttSettings) {
 						// TODO: Handle the will & testament, and possibly use the will's content type as a hint for expected content
 						if (packet.will) {
 							const deserialize =
-								socket.deserialize || (socket.deserialize = getDeserializer(request?.headers.get?.('content-type')));
-							packet.will.data = packet.will.payload?.length > 0 ? deserialize(packet.will.payload) : undefined;
+								socket.deserialize ||
+								(socket.deserialize = getDeserializer(request?.headers.get?.('content-type') as string, false));
+							(packet.will as any).data =
+								packet.will.payload?.length > 0 ? deserialize(packet.will.payload) : undefined;
 							delete packet.will.payload;
 						}
 						session = getSession({
 							user,
 							...packet,
-						});
+						} as any) as any;
 						session = await session;
 						// the session is used in the context, and we want to make sure we can access this
 						session.socket = socket;
@@ -338,12 +346,12 @@ function onSocket(socket, send, request, user, mqttSettings) {
 							return !rawSocket.closed;
 						} catch (error) {
 							mqttLog.error?.(error);
-							session?.disconnect();
+							session?.disconnect(false);
 							mqttSettings.sessions.delete(session);
 							return false;
 						}
 					};
-					session.setListener(listener);
+					session.setListener(listener as any);
 					if (session.sessionWasPresent) await session.resume();
 					break;
 				case 'subscribe':
@@ -407,7 +415,8 @@ function onSocket(socket, send, request, user, mqttSettings) {
 					const responseCmd = packet.qos === 2 ? 'pubrec' : 'puback';
 					// deserialize
 					const deserialize =
-						socket.deserialize || (socket.deserialize = getDeserializer(request?.headers.get?.('content-type')));
+						socket.deserialize ||
+						(socket.deserialize = getDeserializer(request?.headers.get?.('content-type') as string, false));
 					const messageLength = packet.payload?.length || 0;
 					const data = messageLength > 0 ? deserialize(packet.payload) : undefined; // zero payload length maps to a delete
 					let published;

package/server/nodeName.ts

@@ -1,8 +1,9 @@
 import { readFileSync } from 'node:fs';
 import { X509Certificate } from 'node:crypto';
 import { CONFIG_PARAMS } from '../utility/hdbTerms.ts';
-import env from '../utility/environment/environmentManager.js';
+import * as env from '../utility/environment/environmentManager.ts';
 import { logger } from '../utility/logging/logger.ts';
+import { server } from './Server.ts';
 
 Object.defineProperty(server, 'hostname', {
 	get() {
@@ -64,6 +65,7 @@ function getPortFromListeningPort(key: string) {
 }
 
 export function hostnameToUrl(hostname) {
+	if (!hostname) return undefined;
 	let port = getPortFromListeningPort('replication_port');
 	if (port) return `ws://${hostname}:${port}`;
 	port = getPortFromListeningPort('replication_secureport');

package/server/operationsServer.ts

@@ -1,9 +1,11 @@
+// @ts-nocheck
 import cluster from 'cluster';
 import zlib from 'node:zlib';
-import env from '../utility/environment/environmentManager.js';
+import * as env from '../utility/environment/environmentManager.ts';
 env.initSync();
 import * as terms from '../utility/hdbTerms.ts';
-import harperLogger from '../utility/logging/harper_logger.js';
+import harperLogger from '../utility/logging/harper_logger.ts';
+import { realExit } from './threads/workerProcessGuard.ts';
 import fastify, { FastifyInstance, FastifyReply, FastifyRequest, FastifyServerOptions } from 'fastify';
 import fastifyCors, { type FastifyCorsOptions } from '@fastify/cors';
 import fastifyCompress from '@fastify/compress';
@@ -11,8 +13,8 @@ import fastifyStatic from '@fastify/static';
 import requestTimePlugin from './serverHelpers/requestTimePlugin.js';
 import guidePath from 'path';
 import { PACKAGE_ROOT } from '../utility/packageUtils.js';
-import globalSchema from '../utility/globalSchema.js';
-import commonUtils from '../utility/common_utils.js';
+import * as globalSchema from '../utility/globalSchema.ts';
+import * as commonUtils from '../utility/common_utils.ts';
 import * as userSchema from '../security/user.ts';
 import { server as serverRegistration, type ServerOptions } from '../server/Server.ts';
 import {
@@ -22,12 +24,17 @@ import {
 	serverErrorHandler,
 	reqBodyValidationHandler,
 } from './serverHelpers/serverHandlers.js';
+import { registerBunFastifyInstance } from './http.ts';
 import { registerContentHandlers } from './serverHelpers/contentTypes.ts';
+import { getConfigObj } from '../config/configUtils.js';
+import { registerMcpProfile } from '../components/mcp/index.ts';
 import type { OperationFunctionName } from './serverHelpers/serverUtilities.ts';
-import type { ParsedSqlObject } from '../sqlTranslator/index.js';
+type ParsedSqlObject = any;
 import { generateJsonApi } from '../resources/openApi.ts';
 import { Resources } from '../resources/Resources.ts';
-import { ServerError } from '../utility/errors/hdbError.js';
+import { ServerError } from '../utility/errors/hdbError.ts';
+import { sendItcEvent } from './threads/itc.js';
+import { onMessageByType } from './threads/manageThreads.js';
 
 const DEFAULT_HEADERS_TIMEOUT = 60000;
 const REQ_MAX_BODY_SIZE = env.get(terms.CONFIG_PARAMS.OPERATIONSAPI_NETWORK_MAXREQUESTBODYSIZE) ?? 1024 * 1024 * 1024; //this defaults to 1GB in bytes
@@ -37,7 +44,7 @@ const { CONFIG_PARAMS } = terms;
 let server;
 
 export { operationsServer as hdbServer };
-export { operationsServer as start };
+export { operationsServer as startOnMainThread };
 
 /**
  * Builds a Harper server.
@@ -67,6 +74,11 @@ async function operationsServer(options: ServerOptions & { resources?: Resources
 			// now that server is fully loaded/ready, start listening on port provided in config settings or just use
 			// zero to wait for sockets from the main thread
 			serverRegistration.http(server.server, options);
+			// On Bun, register the Fastify instance so requests can be delegated via inject()
+			if (typeof globalThis.Bun !== 'undefined') {
+				const port = options.port || options.securePort || env.get(CONFIG_PARAMS.OPERATIONSAPI_NETWORK_PORT);
+				if (port) registerBunFastifyInstance(port, server);
+			}
 			if (!server.server.closeIdleConnections) {
 				// before Node v18, closeIdleConnections is not available, and we have to setup a listener for fastify
 				// to handle closing by setting up the dynamic port
@@ -81,7 +93,9 @@ async function operationsServer(options: ServerOptions & { resources?: Resources
 	} catch (err) {
 		console.error(`Failed to build server on ${process.pid}`, err);
 		harperLogger.fatal(err);
-		process.exit(1);
+		// Use realExit so this fatal worker bootstrap failure still terminates
+		// the worker even with the worker process guard installed.
+		realExit(1);
 	}
 }
 
@@ -174,6 +188,24 @@ function buildServer(isHttps: boolean, resources: Resources): FastifyInstance {
 	});
 	registerContentHandlers(app);
 
+	// Presence-based enablement (matches Harper's `replication` convention):
+	// register iff `mcp.operations` is present in the merged config. The
+	// nested config tree from `getConfigObj()` is used directly here because
+	// Joi defaults under `mcp` are not propagated to env.get's flat map —
+	// only six hardcoded defaults are re-applied in configUtils.validateConfig.
+	const fullConfig = getConfigObj() ?? {};
+	if (fullConfig.mcp?.operations) {
+		registerMcpProfile({
+			profile: 'operations',
+			host: app,
+			config: fullConfig,
+			// Use authAndEnsureUserOnRequest (sets `req.hdb_user`) instead of
+			// authHandler (which mutates `req.body.hdb_user` — that would
+			// contaminate the JSON-RPC envelope the MCP handler reads).
+			routeOptions: { preValidation: [authAndEnsureUserOnRequest] },
+		});
+	}
+
 	// Add a simple health check
 	app.get('/health', () => 'Harper is running.');
 
@@ -204,12 +236,55 @@ function buildServer(isHttps: boolean, resources: Resources): FastifyInstance {
 	return app;
 }
 
+let nextOpenApiRequestId = 1;
+let openApiResponseListenerAttached = false;
+const pendingOpenApiRequests = new Map<number, (openapi: unknown) => void>();
+
+function attachOpenApiResponseListener() {
+	if (openApiResponseListenerAttached) return;
+	onMessageByType(terms.ITC_EVENT_TYPES.RESOURCE_OPENAPI_RESPONSE, ({ message }: any) => {
+		const resolve = pendingOpenApiRequests.get(message.requestId);
+		if (resolve) {
+			pendingOpenApiRequests.delete(message.requestId);
+			resolve(message.openapi);
+		}
+	});
+	openApiResponseListenerAttached = true;
+}
+
+function queryWorkerForOpenApi(serverHttpURL: string): Promise<unknown> {
+	attachOpenApiResponseListener();
+	const requestId = nextOpenApiRequestId++;
+	return new Promise<unknown>((resolve, reject) => {
+		const timeoutHandle = setTimeout(() => {
+			pendingOpenApiRequests.delete(requestId);
+			reject(new ServerError('Timeout fetching OpenAPI spec from worker thread', 503));
+		}, 5000);
+		pendingOpenApiRequests.set(requestId, (openapi) => {
+			clearTimeout(timeoutHandle);
+			resolve(openapi);
+		});
+		sendItcEvent({
+			type: terms.ITC_EVENT_TYPES.RESOURCE_OPENAPI_REQUEST,
+			message: { requestId, serverHttpURL },
+		}).catch((err: unknown) => {
+			clearTimeout(timeoutHandle);
+			pendingOpenApiRequests.delete(requestId);
+			reject(err);
+		});
+	});
+}
+
 function restOpenAPIHandler(resources: Resources) {
 	const httpPort = env.get(terms.CONFIG_PARAMS.HTTP_PORT);
 	const httpSecurePort = env.get(terms.CONFIG_PARAMS.HTTP_SECUREPORT);
-	return (req: FastifyRequest & { hdb_user?: { role?: { permission?: { super_user: boolean } } } }) => {
+	return async (req: FastifyRequest & { hdb_user?: { role?: { permission?: { super_user: boolean } } } }) => {
 		if (req.hdb_user?.role?.permission?.super_user) {
-			return generateJsonApi(resources, calculateRestHttpURL(httpPort, httpSecurePort, req));
+			const serverHttpURL = calculateRestHttpURL(httpPort, httpSecurePort, req);
+			if (resources.size > 0) {
+				return generateJsonApi(resources, serverHttpURL);
+			}
+			return queryWorkerForOpenApi(serverHttpURL);
 		} else {
 			harperLogger.warn(
 				`{"ip":"${req.socket.remoteAddress}", "error":"attempt to access /api/openapi/rest without being super_user"`