@dollhousemcp/mcp-server/dist/telemetry/OperationalTelemetry.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.

/**
 * Operational Telemetry System
 *
 * Privacy-first anonymous installation analytics
 *
 * What is collected:
 * - Anonymous installation UUID (generated locally, persistent per install)
 * - Server version, OS type, Node.js version, MCP client type
 * - Installation timestamp
 *
 * What is NOT collected:
 * - User identity, personal information, or identifiable data
 * - Element content, persona data, or user-created content
 * - Usage patterns, commands, or interactions
 * - Network data, file paths, or system details beyond OS type
 *
 * Telemetry control:
 * - DOLLHOUSE_TELEMETRY=true  - Enables local telemetry (default: OFF)
 * - DOLLHOUSE_TELEMETRY=false - Disables all telemetry (local and remote)
 * - DOLLHOUSE_TELEMETRY_OPTIN=true - Enables remote telemetry with default PostHog project
 * - DOLLHOUSE_TELEMETRY_NO_REMOTE=true - Local telemetry only, no PostHog
 * - POSTHOG_API_KEY - Custom PostHog project key (overrides default)
 * - Delete telemetry files: rm ~/.dollhouse/.telemetry-id ~/.dollhouse/telemetry.log
 *
 * Data storage (only when enabled):
 * - Local: ~/.dollhouse/.telemetry-id (UUID) and ~/.dollhouse/telemetry.log (events)
 * - Remote (opt-in): PostHog analytics when DOLLHOUSE_TELEMETRY_OPTIN=true or POSTHOG_API_KEY is set
 *
 * Design principles:
 * - Fail gracefully: errors never crash the server
 * - Debug-only logging: no user-facing telemetry noise
 * - Check opt-out early: no file operations if disabled
 * - Remote telemetry is opt-in: requires DOLLHOUSE_TELEMETRY_OPTIN=true or explicit POSTHOG_API_KEY
 * - Local telemetry is opt-in: requires DOLLHOUSE_TELEMETRY=true
 */
import type { AutoLoadMetrics } from './types.js';
import { IFileOperationsService } from '../services/FileOperationsService.js';
export declare class OperationalTelemetry {
    private fileOperations;
    private installId;
    private initialized;
    private posthog;
    private logListener?;
    addLogListener(fn: (level: 'debug' | 'info' | 'warn' | 'error', message: string, data?: Record<string, unknown>) => void): () => void;
    constructor(fileOperations: IFileOperationsService);
    /**
     * Check if telemetry is enabled
     * Respects DOLLHOUSE_TELEMETRY environment variable (default: false/opt-in)
     * @returns true if telemetry is enabled, false otherwise
     */
    isEnabled(): boolean;
    /**
     * Initialize PostHog client for remote telemetry
     *
     * Three ways to enable remote telemetry:
     * 1. DOLLHOUSE_TELEMETRY_OPTIN=true - Uses default PostHog project (simplest opt-in)
     * 2. POSTHOG_API_KEY=<key> - Uses custom PostHog project (backward compatibility)
     * 3. DOLLHOUSE_TELEMETRY_OPTIN=true with POSTHOG_API_KEY=<key> - Custom key takes precedence
     *
     * PostHog project keys are safe to expose publicly - they are write-only and cannot
     * be used to read data. This allows embedding a default key for simple opt-in telemetry.
     *
     * Respects DOLLHOUSE_TELEMETRY_NO_REMOTE=true to disable all remote telemetry
     */
    private initPostHog;
    /**
     * Get telemetry configuration paths
     * @returns Configuration with paths to telemetry files
     */
    private getConfig;
    /**
     * Ensure installation UUID exists, generating if needed
     * UUID is persistent across server restarts but unique per installation
     * @returns Installation UUID or null if telemetry disabled or error
     */
    private ensureUUID;
    /**
     * Check if this is the first run for current version
     * Looks for existing installation event with current UUID and version
     * @returns true if this is the first run (no matching install event found)
     */
    private isFirstRun;
    /**
     * Detect MCP client environment
     * Uses dedicated clientDetector module for consistency
     * @returns Client identifier string
     */
    private getMCPClient;
    /**
     * Record installation event to telemetry log
     * Appends JSON line to log file (JSONL format)
     * Also sends to PostHog if configured
     */
    private recordInstallation;
    /**
     * Write telemetry event to log file
     * Internal method for appending events to telemetry.log
     * @param event - Event object to write
     */
    private writeEvent;
    /**
     * Initialize telemetry system
     * Checks opt-out status, generates UUID if needed, records installation event on first run
     *
     * Safe to call multiple times - will only initialize once
     * Always fails gracefully - errors are logged but never thrown
     */
    initialize(): Promise<void>;
    /**
     * Record auto-load metrics to telemetry log
     * @param metrics Auto-load performance metrics
     */
    recordAutoLoadMetrics(metrics: AutoLoadMetrics): Promise<void>;
    /**
     * Shutdown telemetry system
     * Flushes any pending PostHog events and cleans up resources
     * Safe to call even if not initialized
     */
    shutdown(): Promise<void>;
}
//# sourceMappingURL=OperationalTelemetry.d.ts.map