mcp-use/dist/src/telemetry/telemetry.d.ts

Opinionated MCP Framework for TypeScript (@modelcontextprotocol/sdk compatible) - Build MCP Agents, Clients and Servers with support for ChatGPT Apps, Code Mode, OAuth, Notifications, Sampling, Observability and more.

import type { BaseTelemetryEvent, MCPAgentExecutionEventData, ServerInitializeEventData, ServerToolCallEventData, ServerResourceCallEventData, ServerPromptCallEventData, ServerContextEventData, MCPClientInitEventData, ConnectorInitEventData, MCPServerTelemetryInfo } from "./events.js";
/**
 * Detected runtime environment types
 */
export type RuntimeEnvironment = "node" | "browser" | "cloudflare-workers" | "edge" | "deno" | "bun" | "unknown";
/**
 * Storage capabilities for user ID persistence
 */
type StorageCapability = "filesystem" | "localStorage" | "session-only";
/**
 * Check if we're in a browser environment
 */
export declare function isBrowserEnvironment(): boolean;
/**
 * Unified Telemetry class that works in both Node.js and browser environments.
 *
 * Automatically detects the runtime environment and uses the appropriate
 * PostHog library (posthog-node for Node.js, posthog-js for browser).
 *
 * Usage: Tel.getInstance().trackMCPClientInit(...)
 */
export declare class Telemetry {
    private static instance;
    private readonly PROJECT_API_KEY;
    private readonly HOST;
    private readonly SCARF_GATEWAY_URL;
    private readonly UNKNOWN_USER_ID;
    private _currUserId;
    private _posthogNodeClient;
    private _posthogBrowserClient;
    private _posthogLoading;
    private _scarfClient;
    private _runtimeEnvironment;
    private _storageCapability;
    private _source;
    private _userIdPath;
    private _versionDownloadPath;
    private constructor();
    private _checkTelemetryDisabled;
    private _initPostHog;
    private _initPostHogBrowser;
    private _initPostHogNode;
    /**
     * Get the detected runtime environment
     */
    get runtimeEnvironment(): RuntimeEnvironment;
    /**
     * Get the storage capability for this environment
     */
    get storageCapability(): StorageCapability;
    static getInstance(): Telemetry;
    /**
     * Set the source identifier for telemetry events.
     * This allows tracking usage from different applications.
     * @param source - The source identifier (e.g., "my-app", "cli", "vs-code-extension")
     */
    setSource(source: string): void;
    /**
     * Get the current source identifier.
     */
    getSource(): string;
    /**
     * Check if telemetry is enabled.
     */
    get isEnabled(): boolean;
    get userId(): string;
    /**
     * Get or create user ID from filesystem (Node.js/Bun)
     * Falls back to session ID if filesystem operations fail
     */
    private _getUserIdFromFilesystem;
    /**
     * Get or create user ID from localStorage (Browser)
     */
    private _getUserIdFromLocalStorage;
    private _getCacheHome;
    capture(event: BaseTelemetryEvent): Promise<void>;
    /**
     * Track package download event.
     * This is a public wrapper that safely accesses userId.
     */
    trackPackageDownload(properties?: Record<string, any>): Promise<void>;
    /**
     * Internal method to track package download with explicit userId.
     */
    private _trackPackageDownloadInternal;
    trackAgentExecution(data: MCPAgentExecutionEventData): Promise<void>;
    /**
     * Track server run event directly from an MCPServer instance.
     */
    trackServerRunFromServer(server: MCPServerTelemetryInfo, transport: string): Promise<void>;
    trackServerInitialize(data: ServerInitializeEventData): Promise<void>;
    trackServerToolCall(data: ServerToolCallEventData): Promise<void>;
    trackServerResourceCall(data: ServerResourceCallEventData): Promise<void>;
    trackServerPromptCall(data: ServerPromptCallEventData): Promise<void>;
    trackServerContext(data: ServerContextEventData): Promise<void>;
    trackMCPClientInit(data: MCPClientInitEventData): Promise<void>;
    trackConnectorInit(data: ConnectorInitEventData): Promise<void>;
    trackClientAddServer(serverName: string, serverConfig: Record<string, any>): Promise<void>;
    trackClientRemoveServer(serverName: string): Promise<void>;
    trackUseMcpConnection(data: {
        url: string;
        transportType: string;
        success: boolean;
        errorType?: string | null;
        connectionTimeMs?: number | null;
        hasOAuth: boolean;
        hasSampling: boolean;
        hasElicitation: boolean;
    }): Promise<void>;
    trackUseMcpToolCall(data: {
        toolName: string;
        success: boolean;
        errorType?: string | null;
        executionTimeMs?: number | null;
    }): Promise<void>;
    trackUseMcpResourceRead(data: {
        resourceUri: string;
        success: boolean;
        errorType?: string | null;
    }): Promise<void>;
    /**
     * Identify the current user (useful for linking sessions)
     * Browser only - no-op in Node.js
     */
    identify(userId: string, properties?: Record<string, any>): void;
    /**
     * Reset the user identity (useful for logout)
     * Browser only - no-op in Node.js
     */
    reset(): void;
    /**
     * Flush the telemetry queue (Node.js only)
     */
    flush(): void;
    /**
     * Shutdown the telemetry client (Node.js only)
     */
    shutdown(): void;
}
/**
 * Alias for Telemetry - shorter name for convenience
 *
 * Usage: Tel.getInstance().trackMCPClientInit(...)
 */
export declare const Tel: typeof Telemetry;
/**
 * Convenience function to set telemetry source globally
 */
export declare function setTelemetrySource(source: string): void;
export {};
//# sourceMappingURL=telemetry.d.ts.map