@loop_ouroboros/mcp-hub-lite 1.0.0

package/dist/server/src/api/web/sessions.d.ts

@@ -0,0 +1,29 @@
+import { FastifyInstance } from 'fastify';
+/**
+ * Session Management API Routes
+ *
+ * Provides comprehensive session management endpoints for the MCP Hub Lite system's persistent session storage.
+ * This module enables administrators and clients to monitor, inspect, and manage active and persisted sessions
+ * that maintain client connection state across service restarts.
+ *
+ * Sessions store critical client context including connection metadata, working directories, project information,
+ * and other state that enables seamless reconnection and continuity of operations. The session persistence
+ * feature ensures that client connections can be restored even after service interruptions.
+ *
+ * Key features include:
+ * - Listing all persisted sessions with metadata
+ * - Detailed session inspection by session ID
+ * - Session deletion for cleanup and maintenance
+ * - Integration with the MCP session manager for consistency
+ *
+ * @param fastify - The Fastify instance to register routes on
+ * @returns Promise that resolves when all routes are registered
+ *
+ * @example
+ * ```typescript
+ * // Register session management routes
+ * await webSessionRoutes(app);
+ * ```
+ */
+export declare function webSessionRoutes(fastify: FastifyInstance): Promise<void>;
+//# sourceMappingURL=sessions.d.ts.map

package/dist/server/src/api/web/sessions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.d.ts","sourceRoot":"","sources":["../../../../../src/api/web/sessions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAI1C;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,eAAe,iBAsF9D"}

package/dist/server/src/api/web/sessions.js

@@ -0,0 +1,104 @@
+import { mcpSessionManager } from '../../services/mcp-session-manager.js';
+import { logger, LOG_MODULES } from '../../utils/logger.js';
+/**
+ * Session Management API Routes
+ *
+ * Provides comprehensive session management endpoints for the MCP Hub Lite system's persistent session storage.
+ * This module enables administrators and clients to monitor, inspect, and manage active and persisted sessions
+ * that maintain client connection state across service restarts.
+ *
+ * Sessions store critical client context including connection metadata, working directories, project information,
+ * and other state that enables seamless reconnection and continuity of operations. The session persistence
+ * feature ensures that client connections can be restored even after service interruptions.
+ *
+ * Key features include:
+ * - Listing all persisted sessions with metadata
+ * - Detailed session inspection by session ID
+ * - Session deletion for cleanup and maintenance
+ * - Integration with the MCP session manager for consistency
+ *
+ * @param fastify - The Fastify instance to register routes on
+ * @returns Promise that resolves when all routes are registered
+ *
+ * @example
+ * ```typescript
+ * // Register session management routes
+ * await webSessionRoutes(app);
+ * ```
+ */
+export async function webSessionRoutes(fastify) {
+    /**
+     * List all persisted sessions
+     */
+    fastify.get('/web/sessions', async (_request, reply) => {
+        try {
+            const sessions = mcpSessionManager.getAllSessionStates();
+            return reply.send({
+                success: true,
+                data: sessions,
+                count: sessions.length
+            });
+        }
+        catch (error) {
+            logger.error('Failed to get sessions:', error, LOG_MODULES.SESSION_API);
+            return reply.code(500).send({
+                success: false,
+                error: 'Failed to get sessions'
+            });
+        }
+    });
+    /**
+     * Get a specific session by ID
+     */
+    fastify.get('/web/sessions/:sessionId', async (request, reply) => {
+        try {
+            const { sessionId } = request.params;
+            const session = mcpSessionManager.getSessionState(sessionId);
+            if (!session) {
+                return reply.code(404).send({
+                    success: false,
+                    error: 'Session not found'
+                });
+            }
+            return reply.send({
+                success: true,
+                data: session
+            });
+        }
+        catch (error) {
+            logger.error('Failed to get session:', error, LOG_MODULES.SESSION_API);
+            return reply.code(500).send({
+                success: false,
+                error: 'Failed to get session'
+            });
+        }
+    });
+    /**
+     * Delete a session
+     */
+    fastify.delete('/web/sessions/:sessionId', async (request, reply) => {
+        try {
+            const { sessionId } = request.params;
+            logger.info(`Deleting session: ${sessionId}`, LOG_MODULES.SESSION_API);
+            const existed = await mcpSessionManager.deleteSession(sessionId);
+            if (!existed) {
+                return reply.code(404).send({
+                    success: false,
+                    error: 'Session not found'
+                });
+            }
+            logger.info(`Session deleted successfully: ${sessionId}`, LOG_MODULES.SESSION_API);
+            return reply.send({
+                success: true,
+                message: 'Session deleted successfully'
+            });
+        }
+        catch (error) {
+            logger.error('Failed to delete session:', error, LOG_MODULES.SESSION_API);
+            return reply.code(500).send({
+                success: false,
+                error: 'Failed to delete session'
+            });
+        }
+    });
+}

package/dist/server/src/api/ws/events.d.ts

@@ -0,0 +1,29 @@
+/**
+ * WebSocket Event Routes
+ *
+ * Registers WebSocket endpoints for real-time event communication between the MCP Hub Lite server and connected clients.
+ * This module sets up the WebSocket infrastructure using the @fastify/websocket plugin and creates connection
+ * handlers for managing client connections and message routing.
+ *
+ * The WebSocket API enables bidirectional communication for real-time updates including:
+ * - Server status changes
+ * - Tool and resource updates
+ * - Log entries and system events
+ * - Configuration changes
+ * - Client connection/disconnection events
+ *
+ * Clients can subscribe to specific event types and receive live updates without polling,
+ * providing an efficient and responsive user experience for monitoring and managing the MCP ecosystem.
+ *
+ * @param fastify - The Fastify instance to register routes on
+ * @returns Promise that resolves when WebSocket routes are registered
+ *
+ * @example
+ * ```typescript
+ * // Register WebSocket routes
+ * await webSocketRoutes(app);
+ * ```
+ */
+import type { FastifyInstance } from 'fastify';
+export declare function webSocketRoutes(fastify: FastifyInstance): Promise<void>;
+//# sourceMappingURL=events.d.ts.map

package/dist/server/src/api/ws/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../../../src/api/ws/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAM/C,wBAAsB,eAAe,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB7E"}

package/dist/server/src/api/ws/events.js

@@ -0,0 +1,44 @@
+/**
+ * WebSocket Event Routes
+ *
+ * Registers WebSocket endpoints for real-time event communication between the MCP Hub Lite server and connected clients.
+ * This module sets up the WebSocket infrastructure using the @fastify/websocket plugin and creates connection
+ * handlers for managing client connections and message routing.
+ *
+ * The WebSocket API enables bidirectional communication for real-time updates including:
+ * - Server status changes
+ * - Tool and resource updates
+ * - Log entries and system events
+ * - Configuration changes
+ * - Client connection/disconnection events
+ *
+ * Clients can subscribe to specific event types and receive live updates without polling,
+ * providing an efficient and responsive user experience for monitoring and managing the MCP ecosystem.
+ *
+ * @param fastify - The Fastify instance to register routes on
+ * @returns Promise that resolves when WebSocket routes are registered
+ *
+ * @example
+ * ```typescript
+ * // Register WebSocket routes
+ * await webSocketRoutes(app);
+ * ```
+ */
+import fastifyWebSocket from '@fastify/websocket';
+import { WebSocketHandler } from './ws-handler.js';
+import { eventBus } from '../../services/event-bus.service.js';
+import { logger, LOG_MODULES } from '../../utils/logger.js';
+export async function webSocketRoutes(fastify) {
+    // Register WebSocket plugin
+    await fastify.register(fastifyWebSocket);
+    // Register WebSocket routes
+    fastify.register(async function (fastify) {
+        // WebSocket endpoint: /ws
+        fastify.get('/ws', { websocket: true }, (socket, request) => {
+            logger.info(`connection established from ${request.ip}`, LOG_MODULES.WEBSOCKET);
+            const handler = new WebSocketHandler(socket, eventBus);
+            handler.initialize();
+        });
+    });
+    logger.info('WebSocket routes registered', LOG_MODULES.WEBSOCKET);
+}

package/dist/server/src/api/ws/ws-handler.d.ts

@@ -0,0 +1,83 @@
+/**
+ * WebSocket Connection Handler
+ *
+ * Manages the complete lifecycle and message handling for individual WebSocket connections
+ * between MCP Hub Lite clients and the server. This class handles client subscriptions,
+ * message routing, heartbeat management, and event distribution through the system's
+ * event bus architecture.
+ *
+ * The handler supports multiple message types including:
+ * - Subscription management (subscribe/unsubscribe to event types)
+ * - Heartbeat/ping-pong for connection health monitoring
+ * - Historical log retrieval requests
+ * - Real-time event delivery from the event bus
+ *
+ * It maintains a mapping between WebSocket event types and internal system event types,
+ * ensuring proper protocol translation and secure message delivery. The handler also
+ * implements robust error handling and connection cleanup to prevent resource leaks.
+ *
+ * @example
+ * ```typescript
+ * // Create a new WebSocket handler instance
+ * const handler = new WebSocketHandler(socket, eventBus);
+ * handler.initialize();
+ * ```
+ */
+import { WebSocket } from 'ws';
+import { EventBusService } from '../../services/event-bus.service.js';
+export declare class WebSocketHandler {
+    private socket;
+    private eventBus;
+    private subscriptions;
+    private heartbeatInterval?;
+    constructor(socket: WebSocket, eventBus: EventBusService);
+    /**
+     * Initialize WebSocket connection
+     */
+    initialize(): void;
+    /**
+     * Handle client messages
+     */
+    private handleMessage;
+    /**
+     * Handle fetch historical logs request
+     */
+    private handleFetchLogs;
+    /**
+     * Handle subscription events
+     */
+    private handleSubscribe;
+    /**
+     * Handle unsubscribe events
+     */
+    private handleUnsubscribe;
+    /**
+     * Handle connection close
+     */
+    private handleClose;
+    /**
+     * Handle heartbeat request
+     */
+    private handlePing;
+    /**
+     * Handle connection error
+     */
+    private handleError;
+    /**
+     * Send message to client
+     */
+    private send;
+    /**
+     * Send error message
+     */
+    private sendError;
+    /**
+     * Start heartbeat detection
+     */
+    private startHeartbeat;
+    /**
+     * Stop heartbeat detection
+     */
+    private stopHeartbeat;
+}
+//# sourceMappingURL=ws-handler.d.ts.map

package/dist/server/src/api/ws/ws-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws-handler.d.ts","sourceRoot":"","sources":["../../../../../src/api/ws/ws-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAC/B,OAAO,EAAE,eAAe,EAAc,MAAM,gCAAgC,CAAC;AAgC7E,qBAAa,gBAAgB;IAKzB,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,QAAQ;IALlB,OAAO,CAAC,aAAa,CAAkD;IACvE,OAAO,CAAC,iBAAiB,CAAC,CAAiB;gBAGjC,MAAM,EAAE,SAAS,EACjB,QAAQ,EAAE,eAAe;IAGnC;;OAEG;IACH,UAAU,IAAI,IAAI;IAWlB;;OAEG;IACH,OAAO,CAAC,aAAa;IA6BrB;;OAEG;IACH,OAAO,CAAC,eAAe;IAevB;;OAEG;IACH,OAAO,CAAC,eAAe;IA6BvB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAsBzB;;OAEG;IACH,OAAO,CAAC,WAAW;IAWnB;;OAEG;IACH,OAAO,CAAC,UAAU;IAOlB;;OAEG;IACH,OAAO,CAAC,WAAW;IAInB;;OAEG;IACH,OAAO,CAAC,IAAI;IAMZ;;OAEG;IACH,OAAO,CAAC,SAAS;IAOjB;;OAEG;IACH,OAAO,CAAC,cAAc;IAStB;;OAEG;IACH,OAAO,CAAC,aAAa;CAKtB"}

package/dist/server/src/api/ws/ws-handler.js

@@ -0,0 +1,217 @@
+/**
+ * WebSocket Connection Handler
+ *
+ * Manages the complete lifecycle and message handling for individual WebSocket connections
+ * between MCP Hub Lite clients and the server. This class handles client subscriptions,
+ * message routing, heartbeat management, and event distribution through the system's
+ * event bus architecture.
+ *
+ * The handler supports multiple message types including:
+ * - Subscription management (subscribe/unsubscribe to event types)
+ * - Heartbeat/ping-pong for connection health monitoring
+ * - Historical log retrieval requests
+ * - Real-time event delivery from the event bus
+ *
+ * It maintains a mapping between WebSocket event types and internal system event types,
+ * ensuring proper protocol translation and secure message delivery. The handler also
+ * implements robust error handling and connection cleanup to prevent resource leaks.
+ *
+ * @example
+ * ```typescript
+ * // Create a new WebSocket handler instance
+ * const handler = new WebSocketHandler(socket, eventBus);
+ * handler.initialize();
+ * ```
+ */
+import { WebSocket } from 'ws';
+import { EventTypes } from '../../services/event-bus.service.js';
+import { logStorage } from '../../services/log-storage.service.js';
+import { logger, LOG_MODULES } from '../../utils/logger.js';
+import { WEB_SOCKET_EVENT_TYPES } from '../../../shared/types/websocket.types.js';
+// Event type mapping
+const eventTypeMap = {
+    [EventTypes.SERVER_STATUS_CHANGE]: WEB_SOCKET_EVENT_TYPES.SERVER_STATUS,
+    [EventTypes.SERVER_CONNECTED]: WEB_SOCKET_EVENT_TYPES.SERVER_CONNECTED,
+    [EventTypes.SERVER_DISCONNECTED]: WEB_SOCKET_EVENT_TYPES.SERVER_DISCONNECTED,
+    [EventTypes.SERVER_ADDED]: WEB_SOCKET_EVENT_TYPES.SERVER_ADDED,
+    [EventTypes.SERVER_UPDATED]: WEB_SOCKET_EVENT_TYPES.SERVER_UPDATED,
+    [EventTypes.SERVER_DELETED]: WEB_SOCKET_EVENT_TYPES.SERVER_DELETED,
+    [EventTypes.TOOLS_UPDATED]: WEB_SOCKET_EVENT_TYPES.TOOLS,
+    [EventTypes.RESOURCES_UPDATED]: WEB_SOCKET_EVENT_TYPES.RESOURCES,
+    [EventTypes.LOG_ENTRY]: WEB_SOCKET_EVENT_TYPES.LOG,
+    [EventTypes.TOOL_CALL_STARTED]: WEB_SOCKET_EVENT_TYPES.TOOL_CALL_STARTED,
+    [EventTypes.TOOL_CALL_COMPLETED]: WEB_SOCKET_EVENT_TYPES.TOOL_CALL_COMPLETED,
+    [EventTypes.TOOL_CALL_ERROR]: WEB_SOCKET_EVENT_TYPES.TOOL_CALL_ERROR,
+    [EventTypes.CONFIGURATION_UPDATED]: WEB_SOCKET_EVENT_TYPES.CONFIGURATION_UPDATED,
+    [EventTypes.CLIENT_CONNECTED]: WEB_SOCKET_EVENT_TYPES.CLIENT_CONNECTED,
+    [EventTypes.CLIENT_DISCONNECTED]: WEB_SOCKET_EVENT_TYPES.CLIENT_DISCONNECTED
+};
+export class WebSocketHandler {
+    socket;
+    eventBus;
+    subscriptions = new Map(); // Store subscriptions and their corresponding unsubscribe functions
+    heartbeatInterval;
+    constructor(socket, eventBus // Event bus instance
+    ) {
+        this.socket = socket;
+        this.eventBus = eventBus;
+    }
+    /**
+     * Initialize WebSocket connection
+     */
+    initialize() {
+        this.socket.on('message', this.handleMessage.bind(this));
+        this.socket.on('close', this.handleClose.bind(this));
+        this.socket.on('error', this.handleError.bind(this));
+        // Start heartbeat detection
+        this.startHeartbeat();
+        logger.debug('connection established', LOG_MODULES.WEBSOCKET);
+    }
+    /**
+     * Handle client messages
+     */
+    handleMessage(data) {
+        try {
+            const message = JSON.parse(data.toString());
+            switch (message.type) {
+                case 'subscribe':
+                    this.handleSubscribe(message);
+                    break;
+                case 'unsubscribe':
+                    this.handleUnsubscribe(message);
+                    break;
+                case 'ping':
+                    this.handlePing();
+                    break;
+                case 'fetch-logs':
+                    this.handleFetchLogs(message);
+                    break;
+                default:
+                    logger.warn(`Unknown message type: ${message.type}`, LOG_MODULES.WEBSOCKET);
+            }
+        }
+        catch (error) {
+            logger.error(`Failed to parse WebSocket message: ${error}`, LOG_MODULES.WEBSOCKET);
+            this.sendError('Invalid message format');
+        }
+    }
+    /**
+     * Handle fetch historical logs request
+     */
+    handleFetchLogs(message) {
+        const logs = logStorage.getLogs(message.serverId, {
+            limit: message.limit || 100,
+            since: message.since
+        });
+        this.send({
+            type: 'log',
+            data: {
+                serverId: message.serverId,
+                logs: logs
+            }
+        });
+    }
+    /**
+     * Handle subscription events
+     */
+    handleSubscribe(message) {
+        message.eventTypes.forEach((eventType) => {
+            // Map WebSocket event types to internal event types
+            const internalEventType = Object.entries(eventTypeMap).find(([, wsType]) => wsType === eventType)?.[0];
+            if (internalEventType && !this.subscriptions.has(internalEventType)) {
+                // Subscribe to event bus
+                const unsubscribe = this.eventBus.subscribe(internalEventType, (data) => {
+                    const mappedType = eventTypeMap[internalEventType];
+                    if (mappedType) {
+                        this.send({
+                            type: mappedType,
+                            data
+                        });
+                    }
+                });
+                this.subscriptions.set(internalEventType, unsubscribe);
+            }
+        });
+        logger.info(`Subscribed to events: ${Array.from(this.subscriptions.keys()).sort().join(', ')}`, LOG_MODULES.WEBSOCKET);
+    }
+    /**
+     * Handle unsubscribe events
+     */
+    handleUnsubscribe(message) {
+        message.eventTypes.forEach((eventType) => {
+            // Map WebSocket event types to internal event types
+            const internalEventType = Object.entries(eventTypeMap).find(([, wsType]) => wsType === eventType)?.[0];
+            if (internalEventType) {
+                const unsubscribe = this.subscriptions.get(internalEventType);
+                if (unsubscribe) {
+                    unsubscribe(); // Call unsubscribe function
+                    this.subscriptions.delete(internalEventType);
+                }
+            }
+        });
+        logger.info(`Remaining subscriptions: ${Array.from(this.subscriptions.keys()).sort().join(', ')}`, LOG_MODULES.WEBSOCKET);
+    }
+    /**
+     * Handle connection close
+     */
+    handleClose() {
+        logger.info('connection closed', LOG_MODULES.WEBSOCKET);
+        this.stopHeartbeat();
+        // Unsubscribe from all events
+        this.subscriptions.forEach((unsubscribe) => {
+            unsubscribe();
+        });
+        this.subscriptions.clear();
+    }
+    /**
+     * Handle heartbeat request
+     */
+    handlePing() {
+        this.send({
+            type: 'pong',
+            timestamp: Date.now()
+        });
+    }
+    /**
+     * Handle connection error
+     */
+    handleError(error) {
+        logger.error(`error: ${error}`, LOG_MODULES.WEBSOCKET);
+    }
+    /**
+     * Send message to client
+     */
+    send(message) {
+        if (this.socket.readyState === WebSocket.OPEN) {
+            this.socket.send(JSON.stringify(message));
+        }
+    }
+    /**
+     * Send error message
+     */
+    sendError(message) {
+        this.send({
+            type: 'error',
+            data: { message }
+        });
+    }
+    /**
+     * Start heartbeat detection
+     */
+    startHeartbeat() {
+        this.heartbeatInterval = setInterval(() => {
+            this.send({
+                type: 'pong',
+                timestamp: Date.now()
+            });
+        }, 30000); // Send heartbeat every 30 seconds
+    }
+    /**
+     * Stop heartbeat detection
+     */
+    stopHeartbeat() {
+        if (this.heartbeatInterval) {
+            clearInterval(this.heartbeatInterval);
+        }
+    }
+}

package/dist/server/src/app.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Creates and configures a Fastify application instance for the MCP Hub Lite service.
+ *
+ * This function sets up the complete HTTP server with all necessary routes, middleware,
+ * and static file serving capabilities. It configures CORS headers for development,
+ * registers all API routes (MCP gateway, web APIs, and WebSocket endpoints), and serves
+ * the frontend SPA from the client directory.
+ *
+ * The application follows a layered architecture:
+ * - API routes are registered first to ensure proper routing precedence
+ * - Static file serving is configured for the built frontend assets
+ * - SPA fallback handling redirects non-API routes to index.html for client-side routing
+ *
+ * @returns {Promise<import('fastify').FastifyInstance>} A configured Fastify instance ready to listen for requests
+ * @throws {Error} If Fastify fails to initialize or register plugins
+ *
+ * @example
+ * ```typescript
+ * const app = await buildApp();
+ * await app.listen({ port: 3000, host: '0.0.0.0' });
+ * ```
+ */
+export declare function buildApp(): Promise<import("fastify").FastifyInstance<import("node:http").Server<typeof import("node:http").IncomingMessage, typeof import("node:http").ServerResponse>, import("node:http").IncomingMessage, import("node:http").ServerResponse<import("node:http").IncomingMessage>, import("fastify").FastifyBaseLogger, import("fastify").FastifyTypeProviderDefault>>;
+//# sourceMappingURL=app.d.ts.map

package/dist/server/src/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../../src/app.ts"],"names":[],"mappings":"AA6BA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,QAAQ,mWAqE7B"}

package/dist/server/src/app.js

@@ -0,0 +1,108 @@
+import Fastify from 'fastify';
+import fastifyStatic from '@fastify/static';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { configManager } from './config/config-manager.js';
+import { setJsonPrettyConfigGetter } from './utils/json-utils.js';
+// MCP Protocol Routes
+import { mcpGatewayRoutes } from './api/mcp/gateway.js';
+// Web API Routes
+import { webServerRoutes } from './api/web/servers.js';
+import { webSearchRoutes } from './api/web/search.js';
+import { webHealthRoutes } from './api/web/health.js';
+import { webMcpStatusRoutes } from './api/web/mcp-status.js';
+import { configRoutes } from './api/web/config.js';
+import { webLogRoutes } from './api/web/logs.js';
+import { webHubToolsRoutes } from './api/web/hub-tools.js';
+import { webClientRoutes } from './api/web/clients.js';
+import { webResourceRoutes } from './api/web/resources.js';
+import { webSessionRoutes } from './api/web/sessions.js';
+// WebSocket Routes
+import { webSocketRoutes } from './api/ws/events.js';
+// Get __dirname equivalent in ESM
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+/**
+ * Creates and configures a Fastify application instance for the MCP Hub Lite service.
+ *
+ * This function sets up the complete HTTP server with all necessary routes, middleware,
+ * and static file serving capabilities. It configures CORS headers for development,
+ * registers all API routes (MCP gateway, web APIs, and WebSocket endpoints), and serves
+ * the frontend SPA from the client directory.
+ *
+ * The application follows a layered architecture:
+ * - API routes are registered first to ensure proper routing precedence
+ * - Static file serving is configured for the built frontend assets
+ * - SPA fallback handling redirects non-API routes to index.html for client-side routing
+ *
+ * @returns {Promise<import('fastify').FastifyInstance>} A configured Fastify instance ready to listen for requests
+ * @throws {Error} If Fastify fails to initialize or register plugins
+ *
+ * @example
+ * ```typescript
+ * const app = await buildApp();
+ * await app.listen({ port: 3000, host: '0.0.0.0' });
+ * ```
+ */
+export async function buildApp() {
+    const config = configManager.getConfig();
+    const fastify = Fastify({
+        logger: false // We use our own logger
+    });
+    // Set up config getters for json-utils
+    setJsonPrettyConfigGetter(() => configManager.getConfig());
+    // Set HTTP connection timeouts for SSE long-lived connections
+    // Use idleConnectionTimeout from config (default 5 minutes)
+    // Add extra buffer to prevent premature disconnect
+    const idleTimeout = config.security.idleConnectionTimeout;
+    fastify.server.keepAliveTimeout = idleTimeout;
+    fastify.server.headersTimeout = idleTimeout + 5000; // headersTimeout must be longer than keepAliveTimeout
+    // Simple CORS for dev
+    fastify.addHook('onRequest', (request, reply, done) => {
+        reply.header('Access-Control-Allow-Origin', '*');
+        reply.header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
+        reply.header('Access-Control-Allow-Headers', 'Content-Type');
+        if (request.method === 'OPTIONS') {
+            reply.send();
+            return;
+        }
+        done();
+    });
+    // Register API routes first (before static files)
+    fastify.register(mcpGatewayRoutes);
+    fastify.register(webServerRoutes);
+    fastify.register(webSearchRoutes);
+    fastify.register(webHealthRoutes);
+    fastify.register(webMcpStatusRoutes);
+    fastify.register(configRoutes);
+    fastify.register(webLogRoutes);
+    fastify.register(webHubToolsRoutes);
+    fastify.register(webClientRoutes);
+    fastify.register(webResourceRoutes);
+    fastify.register(webSessionRoutes);
+    fastify.register(webSocketRoutes);
+    // Serve static files from dist/client (frontend build output)
+    const clientPath = path.join(__dirname, '../../client');
+    fastify.register(fastifyStatic, {
+        root: clientPath,
+        prefix: '/' // Serve at root
+    });
+    // Fallback route for SPA (redirect all non-API routes to index.html)
+    fastify.setNotFoundHandler((request, reply) => {
+        // Check if this is an API request
+        if (request.url.startsWith('/api') ||
+            request.url.startsWith('/web') ||
+            request.url.startsWith('/mcp')) {
+            reply.code(404).send({
+                message: `Route ${request.method}:${request.url} not found`,
+                error: 'Not Found',
+                statusCode: 404
+            });
+        }
+        else {
+            // For non-API routes, serve index.html (SPA fallback)
+            reply.sendFile('index.html');
+        }
+    });
+    return fastify;
+}