@dollhousemcp/mcp-server/dist/web/portDiscovery.d.ts

DollhouseMCP - A Model Context Protocol (MCP) server that enables dynamic AI persona management from markdown files, allowing Claude and other compatible AI assistants to activate and switch between different behavioral personas.

/**
 * Dynamic port allocation and port file discovery for the web console.
 *
 * When multiple DollhouseMCP sessions run simultaneously (e.g., multiple
 * Claude Code windows, IDE instances, or agent sessions), each needs its
 * own web console port. This module handles:
 *
 * 1. Finding an available port starting from the configured default
 *    (see `DOLLHOUSE_WEB_CONSOLE_PORT` in `src/config/env.ts`)
 * 2. Writing port discovery files so external tools know which port to use
 * 3. Cleaning up port files on process exit
 *
 * Port files are written to ~/.dollhouse/run/:
 * - permission-server-{pid}.port — per-process file (cleaned on exit)
 * - permission-server.port — latest port (convenience for scripts)
 */
/**
 * Find an available port starting from the given port.
 *
 * Tries sequential ports, logging each attempt. Returns both the port number
 * and a held server to prevent TOCTOU race conditions. The caller should
 * close the held server after binding their own Express app to the port.
 *
 * @param startPort - Port to try first (see `DOLLHOUSE_WEB_CONSOLE_PORT` for the default)
 * @param maxAttempts - Maximum ports to try (default: 10, configurable via DOLLHOUSE_MAX_PORT_ATTEMPTS)
 * @returns Object with port number and held server, or throws if all attempts fail
 */
export declare function findAvailablePort(startPort: number, maxAttempts?: number): Promise<number>;
/**
 * Write the active server port to a discoverable file.
 *
 * Creates two files:
 * - PID-keyed file for per-process cleanup
 * - Latest file for convenience (scripts can read this without knowing the PID)
 *
 * @param port - The port the web server is listening on
 * @returns Path to the PID-keyed port file
 */
export declare function writePortFile(port: number): Promise<string>;
/**
 * Restore or update the shared latest port file for the active listener.
 *
 * Returns true when the file had to be written or updated, false when it
 * already matched the active port.
 */
export declare function ensureLatestPortFile(port: number, customDir?: string): Promise<boolean>;
/**
 * Clean up port file on shutdown.
 */
export declare function cleanupPortFile(): Promise<void>;
/**
 * Register process exit handlers to clean up port files.
 * Should be called once after the web server successfully starts.
 */
export declare function registerPortCleanup(): void;
/**
 * Sweep stale port files from ~/.dollhouse/run/ on startup (#1856).
 *
 * Scans for permission-server-{pid}.port files and removes any whose PID
 * is no longer alive. This prevents unbounded accumulation of port files
 * from crashed or abandoned sessions.
 *
 * Note: This only removes metadata files, not processes or ports. The port
 * binding itself (in bindAndListen) is atomic via listen(). There is no race
 * between sweeping files and binding — they operate on independent resources.
 *
 * Safe to call on every startup — only removes files for dead processes.
 */
export declare function sweepStalePortFiles(customDir?: string): Promise<number>;
/**
 * Discover an available port, write discovery files, and register cleanup.
 *
 * This is the recommended entry point for Container startup. Combines
 * port discovery, file writing, and cleanup registration in one call.
 *
 * @param defaultPort - Port to try first (see `DOLLHOUSE_WEB_CONSOLE_PORT` for the default)
 * @returns The port the server should bind to, or undefined if discovery failed
 */
export declare function discoverAndBindPort(defaultPort?: number): Promise<number | undefined>;
//# sourceMappingURL=portDiscovery.d.ts.map