@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.
109 lines • 4.22 kB
TypeScript
/**
* Event ingestion routes for the unified web console.
*
* The console leader mounts these routes so follower MCP servers can
* forward their logs, metrics, and session lifecycle events. All ingested
* entries are stamped with `_sessionId` in their data field and then
* broadcast to SSE clients via the existing log/metrics broadcast hooks.
*
* Routes:
* - POST /api/ingest/logs — Batched log entries from a follower
* - POST /api/ingest/metrics — Metric snapshots from a follower
* - POST /api/ingest/session — Session lifecycle events (started/stopped/heartbeat)
* - GET /api/sessions — Active session list for the UI
*
* @since v2.1.0 — Issue #1700
*/
import { Router } from 'express';
import type { UnifiedLogEntry } from '../../logging/types.js';
import type { MetricSnapshot } from '../../metrics/types.js';
import { type SessionClientPlatformId } from './sessionClientPlatform.js';
/**
* Tracked session information.
*/
export interface SessionInfo {
/** Unique identifier for this session (UUID or `console-<pid>`). */
sessionId: string;
/** Friendly puppet name (e.g., "Kermit", "Punch") or "Web Console". */
displayName: string;
/** Canonical hex color for this puppet character. */
color: string;
/** OS process ID of the MCP server or web console process. */
pid: number;
/** ISO timestamp when the session started. */
startedAt: string;
/** ISO timestamp of the most recent heartbeat (followers) or registration (leader/console). */
lastHeartbeat: string;
/** Lifecycle status — 'active' until ended or reaped for staleness. */
status: 'active' | 'ended';
/** True if this session won leader election and owns the token file. */
isLeader: boolean;
/** Whether this session connected with a valid Bearer token (#1805). */
authenticated: boolean;
/** Session kind — 'mcp' for MCP stdio sessions, 'console' for the web console itself (#1805). */
kind: 'mcp' | 'console';
/** DollhouseMCP package version reported by the session. */
serverVersion: string;
/** Console/session contract version used for compatibility-aware takeover. */
consoleProtocolVersion: number;
/** Explicit MCP host platform, when the session reported one. */
clientPlatform: SessionClientPlatformId | null;
/** Human-readable MCP host label for UI rendering. */
clientPlatformLabel: string;
}
/**
* Payload for POST /api/ingest/logs
*/
export interface IngestLogPayload {
sessionId: string;
entries: UnifiedLogEntry[];
}
/**
* Payload for POST /api/ingest/metrics
*/
export interface IngestMetricsPayload {
sessionId: string;
snapshot: MetricSnapshot;
}
/**
* Payload for POST /api/ingest/session
*/
export interface SessionEventPayload {
sessionId: string;
event: 'started' | 'stopped' | 'heartbeat';
pid: number;
startedAt: string;
serverVersion?: string;
consoleProtocolVersion?: number;
clientPlatform?: string;
}
/**
* Callbacks provided by the unified console orchestrator for broadcasting
* ingested events through the existing SSE infrastructure.
*/
export interface IngestBroadcasts {
logBroadcast: (entry: UnifiedLogEntry) => void;
metricsOnSnapshot?: (snapshot: MetricSnapshot) => void;
storeMetricsSnapshot?: (snapshot: MetricSnapshot, sessionId: string) => void;
sessionBroadcast?: (event: SessionInfo) => void;
}
/**
* Result of creating ingest routes.
*/
export interface IngestRoutesResult {
router: Router;
/** Get all tracked sessions */
getSessions: () => SessionInfo[];
/** Register the leader as a session */
registerLeaderSession: (sessionId: string, pid: number, clientPlatform?: string | null) => void;
/** Register the web console as a session so the indicator is never empty (#1805) */
registerConsoleSession: () => void;
}
/**
* Create the ingestion routes and session registry.
*
* @param broadcasts - Callbacks to forward ingested events to SSE clients
* @returns Router and session management functions
*/
export declare function createIngestRoutes(broadcasts: IngestBroadcasts): IngestRoutesResult;
//# sourceMappingURL=IngestRoutes.d.ts.map