@dollhousemcp/mcp-server
Version:
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.
144 lines • 6.11 kB
TypeScript
/**
* DollhouseMCP Web UI Server
*
* Lightweight Express server for browsing portfolio elements in a browser.
* Bound to 127.0.0.1 only (localhost). Read-only for V1.
*
* Can be started standalone (`--web` flag) or from within the MCP server
* process via `openPortfolioBrowser()`.
*
* @see https://github.com/DollhouseMCP/mcp-server-v2-refactor/issues/704
* @see https://github.com/DollhouseMCP/mcp-server-v2-refactor/issues/774
*/
import type { MCPAQLHandler } from '../handlers/mcp-aql/MCPAQLHandler.js';
import type { MemoryLogSink } from '../logging/sinks/MemoryLogSink.js';
import type { MemoryMetricsSink } from '../metrics/sinks/MemoryMetricsSink.js';
import type { ConsoleTokenStore } from './console/consoleToken.js';
/** Check whether the web server has been started in this process. */
export declare function isWebServerRunning(): boolean;
/**
* Reset module-level server state. Exported for testing only —
* allows tests to exercise startWebServer/bindAndListen without
* interference from prior runs in the same process.
* @internal
*/
export declare function _resetServerState(): void;
/**
* Gracefully shut down the HTTP server (#1856).
* Closes the active server and resets module state so the port is freed
* immediately rather than lingering until process exit.
*/
export declare function shutdownWebServer(): void;
/**
* Options for starting the web server.
*/
export interface WebServerOptions {
/** Port to bind to (defaults to `DOLLHOUSE_WEB_CONSOLE_PORT`, see `src/config/env.ts`) */
port?: number;
/** Path to the portfolio directory (e.g., ~/.dollhouse/portfolio) */
portfolioDir: string;
/** Open the browser automatically after starting (default: false) */
openBrowser?: boolean;
/**
* MCPAQLHandler for routing through the MCP-AQL pipeline.
* When provided, API routes use the gateway (validated, cached, gatekeeper-checked).
* When absent, falls back to direct filesystem access (legacy behavior).
* Issue #796: Web MCP-AQL Gateway.
*/
mcpAqlHandler?: MCPAQLHandler;
/** MemoryLogSink for log routes (optional — logs tab disabled if not provided) */
memorySink?: MemoryLogSink;
/** MemoryMetricsSink for metrics routes (optional — metrics tab disabled if not provided) */
metricsSink?: MemoryMetricsSink;
/** Additional routers to mount before the SPA fallback (e.g., ingest routes) */
additionalRouters?: import('express').Router[];
/**
* Console token store (#1780). When provided, the server will:
* 1. Mount Bearer token auth middleware before protected routers.
* 2. Inject the primary token into index.html so the browser client
* can attach it to fetch calls and EventSource URLs.
* 3. Append the token file location to the startup banner.
* Auth enforcement is still gated on DOLLHOUSE_WEB_AUTH_ENABLED — the
* middleware is a pass-through when the flag is false (the Phase 1 default).
*/
tokenStore?: ConsoleTokenStore;
/** Stable Dollhouse session identity shown in the web console UI. */
sessionId?: string;
/** Runtime-unique session identity for diagnostics. */
runtimeSessionId?: string;
}
/**
* Result of attempting to bind the HTTP server to a port.
*/
export interface BindResult {
success: boolean;
error?: 'EADDRINUSE' | 'OTHER';
detail?: string;
}
/**
* Result of starting the web server, including hooks for DI wiring.
*/
export interface WebServerResult {
/** Express app instance — for mounting additional routes (e.g., ingest routes) */
app?: import('express').Express;
/** Log broadcast function — call with each entry to push to SSE clients */
logBroadcast?: (entry: import('../logging/types.js').UnifiedLogEntry) => void;
/** Metrics snapshot function — call with each snapshot to push to SSE clients */
metricsOnSnapshot?: (snapshot: import('../metrics/types.js').MetricSnapshot) => void;
/** Result of the port binding attempt */
bindResult?: BindResult;
}
/**
* Result of attempting to open the browser.
*/
export interface BrowserOpenResult {
/** The URL the server is running on */
url: string;
/** Whether the server was already running (true) or just started (false) */
alreadyRunning: boolean;
/** Whether the browser was successfully opened */
browserOpened: boolean;
/** Warning message if the browser could not be opened */
warning?: string;
}
/**
* Start the portfolio web server.
*
* Binds to 127.0.0.1 only (localhost). Serves the portfolio browser
* frontend and API routes for reading elements.
*
* Idempotent: if the server is already running, optionally opens the
* browser without starting a second instance.
*
* @param options - Server configuration
* @returns Hooks for DI wiring (log broadcast, metrics onSnapshot)
*/
export declare function startWebServer(options: WebServerOptions): Promise<WebServerResult>;
export { findPidOnPort, killStaleProcess, recoverStalePort } from './console/StaleProcessRecovery.js';
/**
* Open the portfolio browser from within the MCP server process.
*
* Starts the web server if not already running, then opens the system
* browser to the portfolio UI. Returns a result object indicating
* whether the server started and the browser opened successfully.
*
* Called by the `open_portfolio_browser` MCP-AQL operation (Issue #774).
*
* @param portfolioDir - Path to the portfolio directory (e.g., ~/.dollhouse/portfolio)
* @param port - Port to bind to (defaults to `DOLLHOUSE_WEB_CONSOLE_PORT`)
* @returns Result with URL, server status, and browser open status
*/
/**
* Options for opening the portfolio browser.
*/
export interface OpenBrowserOptions {
portfolioDir: string;
port?: number;
mcpAqlHandler?: MCPAQLHandler;
tab?: string;
urlParams?: Record<string, string>;
memorySink?: MemoryLogSink;
metricsSink?: MemoryMetricsSink;
}
export declare function openPortfolioBrowser(options: OpenBrowserOptions): Promise<BrowserOpenResult>;
//# sourceMappingURL=server.d.ts.map