UNPKG

mcp-use

Version:

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.

840 lines (834 loc) • 26.2 kB
import { logger } from "./chunk-U7F22OTV.js"; import { __name } from "./chunk-3GQAWCBQ.js"; // src/version.ts var VERSION = "1.12.1"; function getPackageVersion() { return VERSION; } __name(getPackageVersion, "getPackageVersion"); // src/telemetry/events.ts var BaseTelemetryEvent = class { static { __name(this, "BaseTelemetryEvent"); } }; var MCPAgentExecutionEvent = class extends BaseTelemetryEvent { constructor(data) { super(); this.data = data; } static { __name(this, "MCPAgentExecutionEvent"); } get name() { return "mcp_agent_execution"; } get properties() { return { // Core execution info execution_method: this.data.executionMethod, query: this.data.query, query_length: this.data.query.length, success: this.data.success, // Agent configuration model_provider: this.data.modelProvider, model_name: this.data.modelName, server_count: this.data.serverCount, server_identifiers: this.data.serverIdentifiers, total_tools_available: this.data.totalToolsAvailable, tools_available_names: this.data.toolsAvailableNames, max_steps_configured: this.data.maxStepsConfigured, memory_enabled: this.data.memoryEnabled, use_server_manager: this.data.useServerManager, // Execution parameters (always include, even if null) max_steps_used: this.data.maxStepsUsed, manage_connector: this.data.manageConnector, external_history_used: this.data.externalHistoryUsed, // Execution results (always include, even if null) steps_taken: this.data.stepsTaken ?? null, tools_used_count: this.data.toolsUsedCount ?? null, tools_used_names: this.data.toolsUsedNames ?? null, response: this.data.response ?? null, response_length: this.data.response ? this.data.response.length : null, execution_time_ms: this.data.executionTimeMs ?? null, error_type: this.data.errorType ?? null, conversation_history_length: this.data.conversationHistoryLength ?? null }; } }; function createServerRunEventData(server, transport) { const toolRegistrations = Array.from(server.registrations.tools.values()); const promptRegistrations = Array.from(server.registrations.prompts.values()); const resourceRegistrations = Array.from( server.registrations.resources.values() ); const templateRegistrations = Array.from( server.registrations.resourceTemplates.values() ); const allResources = resourceRegistrations.map((r) => ({ name: r.config.name, title: r.config.title ?? null, description: r.config.description ?? null, uri: r.config.uri ?? null, mime_type: r.config.mimeType ?? null })); const appsSdkResources = allResources.filter( (r) => r.mime_type === "text/html+skybridge" ); const mcpUiResources = allResources.filter( (r) => r.mime_type === "text/uri-list" || r.mime_type === "text/html" ); const mcpAppsResources = allResources.filter( (r) => r.mime_type === "text/html+mcp" ); return { transport, toolsNumber: server.registeredTools.length, resourcesNumber: server.registeredResources.length, promptsNumber: server.registeredPrompts.length, auth: !!server.oauthProvider, name: server.config.name, description: server.config.description ?? null, baseUrl: server.serverBaseUrl ?? null, toolNames: server.registeredTools.length > 0 ? server.registeredTools : null, resourceNames: server.registeredResources.length > 0 ? server.registeredResources : null, promptNames: server.registeredPrompts.length > 0 ? server.registeredPrompts : null, tools: toolRegistrations.length > 0 ? toolRegistrations.map((r) => ({ name: r.config.name, title: r.config.title ?? null, description: r.config.description ?? null, input_schema: r.config.schema ? JSON.stringify(r.config.schema) : null, output_schema: r.config.outputSchema ? JSON.stringify(r.config.outputSchema) : null })) : null, resources: allResources.length > 0 ? allResources : null, prompts: promptRegistrations.length > 0 ? promptRegistrations.map((r) => ({ name: r.config.name, title: r.config.title ?? null, description: r.config.description ?? null, args: r.config.args ? JSON.stringify(r.config.args) : null })) : null, templates: templateRegistrations.length > 0 ? templateRegistrations.map((r) => ({ name: r.config.name, title: r.config.title ?? null, description: r.config.description ?? null })) : null, capabilities: { logging: true, resources: { subscribe: true, listChanged: true } }, appsSdkResources: appsSdkResources.length > 0 ? appsSdkResources : null, appsSdkResourcesNumber: appsSdkResources.length, mcpUiResources: mcpUiResources.length > 0 ? mcpUiResources : null, mcpUiResourcesNumber: mcpUiResources.length, mcpAppsResources: mcpAppsResources.length > 0 ? mcpAppsResources : null, mcpAppsResourcesNumber: mcpAppsResources.length }; } __name(createServerRunEventData, "createServerRunEventData"); var ServerRunEvent = class extends BaseTelemetryEvent { constructor(data) { super(); this.data = data; } static { __name(this, "ServerRunEvent"); } get name() { return "server_run"; } get properties() { return { transport: this.data.transport, tools_number: this.data.toolsNumber, resources_number: this.data.resourcesNumber, prompts_number: this.data.promptsNumber, auth: this.data.auth, name: this.data.name, description: this.data.description ?? null, base_url: this.data.baseUrl ?? null, tool_names: this.data.toolNames ?? null, resource_names: this.data.resourceNames ?? null, prompt_names: this.data.promptNames ?? null, tools: this.data.tools ?? null, resources: this.data.resources ?? null, prompts: this.data.prompts ?? null, templates: this.data.templates ?? null, capabilities: this.data.capabilities ? JSON.stringify(this.data.capabilities) : null, apps_sdk_resources: this.data.appsSdkResources ? JSON.stringify(this.data.appsSdkResources) : null, apps_sdk_resources_number: this.data.appsSdkResourcesNumber ?? 0, mcp_ui_resources: this.data.mcpUiResources ? JSON.stringify(this.data.mcpUiResources) : null, mcp_ui_resources_number: this.data.mcpUiResourcesNumber ?? 0, mcp_apps_resources: this.data.mcpAppsResources ? JSON.stringify(this.data.mcpAppsResources) : null, mcp_apps_resources_number: this.data.mcpAppsResourcesNumber ?? 0 }; } }; var ServerInitializeEvent = class extends BaseTelemetryEvent { constructor(data) { super(); this.data = data; } static { __name(this, "ServerInitializeEvent"); } get name() { return "server_initialize_call"; } get properties() { return { protocol_version: this.data.protocolVersion, client_info: JSON.stringify(this.data.clientInfo), client_capabilities: JSON.stringify(this.data.clientCapabilities), session_id: this.data.sessionId ?? null }; } }; var ServerToolCallEvent = class extends BaseTelemetryEvent { constructor(data) { super(); this.data = data; } static { __name(this, "ServerToolCallEvent"); } get name() { return "server_tool_call"; } get properties() { return { tool_name: this.data.toolName, length_input_argument: this.data.lengthInputArgument, success: this.data.success, error_type: this.data.errorType ?? null, execution_time_ms: this.data.executionTimeMs ?? null }; } }; var ServerResourceCallEvent = class extends BaseTelemetryEvent { constructor(data) { super(); this.data = data; } static { __name(this, "ServerResourceCallEvent"); } get name() { return "server_resource_call"; } get properties() { return { name: this.data.name, description: this.data.description, contents: this.data.contents, success: this.data.success, error_type: this.data.errorType ?? null }; } }; var ServerPromptCallEvent = class extends BaseTelemetryEvent { constructor(data) { super(); this.data = data; } static { __name(this, "ServerPromptCallEvent"); } get name() { return "server_prompt_call"; } get properties() { return { name: this.data.name, description: this.data.description, success: this.data.success, error_type: this.data.errorType ?? null }; } }; var ServerContextEvent = class extends BaseTelemetryEvent { constructor(data) { super(); this.data = data; } static { __name(this, "ServerContextEvent"); } get name() { return `server_context_${this.data.contextType}`; } get properties() { return { context_type: this.data.contextType, notification_type: this.data.notificationType ?? null }; } }; var MCPClientInitEvent = class extends BaseTelemetryEvent { constructor(data) { super(); this.data = data; } static { __name(this, "MCPClientInitEvent"); } get name() { return "mcpclient_init"; } get properties() { return { code_mode: this.data.codeMode, sandbox: this.data.sandbox, all_callbacks: this.data.allCallbacks, verify: this.data.verify, servers: this.data.servers, num_servers: this.data.numServers, is_browser: this.data.isBrowser }; } }; var ConnectorInitEvent = class extends BaseTelemetryEvent { constructor(data) { super(); this.data = data; } static { __name(this, "ConnectorInitEvent"); } get name() { return "connector_init"; } get properties() { return { connector_type: this.data.connectorType, server_command: this.data.serverCommand ?? null, server_args: this.data.serverArgs ?? null, server_url: this.data.serverUrl ?? null, public_identifier: this.data.publicIdentifier ?? null }; } }; var ClientAddServerEvent = class extends BaseTelemetryEvent { constructor(data) { super(); this.data = data; } static { __name(this, "ClientAddServerEvent"); } get name() { return "client_add_server"; } get properties() { const { serverName, serverConfig } = this.data; const url = serverConfig.url; return { server_name: serverName, server_url_domain: url ? this._extractHostname(url) : null, transport: serverConfig.transport ?? null, has_auth: !!(serverConfig.authToken || serverConfig.authProvider) }; } _extractHostname(url) { try { return new URL(url).hostname; } catch { return null; } } }; var ClientRemoveServerEvent = class extends BaseTelemetryEvent { constructor(data) { super(); this.data = data; } static { __name(this, "ClientRemoveServerEvent"); } get name() { return "client_remove_server"; } get properties() { return { server_name: this.data.serverName }; } }; // src/telemetry/utils.ts function getModelProvider(llm) { return llm._llm_type || llm.constructor.name.toLowerCase(); } __name(getModelProvider, "getModelProvider"); function getModelName(llm) { if ("_identifyingParams" in llm) { const identifyingParams = llm._identifyingParams; if (typeof identifyingParams === "object" && identifyingParams !== null) { for (const key of [ "model", "modelName", "model_name", "modelId", "model_id", "deploymentName", "deployment_name" ]) { if (key in identifyingParams) { return String(identifyingParams[key]); } } } } return llm.model || llm.modelName || llm.constructor.name; } __name(getModelName, "getModelName"); function extractModelInfo(llm) { return [getModelProvider(llm), getModelName(llm)]; } __name(extractModelInfo, "extractModelInfo"); // src/telemetry/telemetry-browser.ts function generateUUID() { if (typeof globalThis !== "undefined" && globalThis.crypto && typeof globalThis.crypto.randomUUID === "function") { return globalThis.crypto.randomUUID(); } if (typeof globalThis !== "undefined" && globalThis.crypto && typeof globalThis.crypto.getRandomValues === "function") { const array = new Uint8Array(16); globalThis.crypto.getRandomValues(array); const hex = Array.from(array, (v) => v.toString(16).padStart(2, "0")).join( "" ); return `${hex.substring(0, 8)}-${hex.substring(8, 12)}-${hex.substring(12, 16)}-${hex.substring(16, 20)}-${hex.substring(20)}`; } return `${Date.now()}-${Math.random().toString(36).substring(2, 15)}-${Math.random().toString(36).substring(2, 15)}`; } __name(generateUUID, "generateUUID"); function secureRandomString() { if (typeof window !== "undefined" && window.crypto && typeof window.crypto.getRandomValues === "function") { const array = new Uint8Array(8); window.crypto.getRandomValues(array); return Array.from(array, (v) => v.toString(16).padStart(2, "0")).join(""); } if (typeof globalThis !== "undefined" && globalThis.crypto && typeof globalThis.crypto.getRandomValues === "function") { const array = new Uint8Array(8); globalThis.crypto.getRandomValues(array); return Array.from(array, (v) => v.toString(16).padStart(2, "0")).join(""); } return Math.random().toString(36).substring(2, 15); } __name(secureRandomString, "secureRandomString"); var USER_ID_STORAGE_KEY = "mcp_use_user_id"; function detectRuntimeEnvironment() { try { if (typeof window !== "undefined" && typeof document !== "undefined") { return "browser"; } return "unknown"; } catch { return "unknown"; } } __name(detectRuntimeEnvironment, "detectRuntimeEnvironment"); function getStorageCapability(env) { if (env === "browser") { try { if (typeof localStorage !== "undefined") { localStorage.setItem("__mcp_use_test__", "1"); localStorage.removeItem("__mcp_use_test__"); return "localStorage"; } } catch { } } return "session-only"; } __name(getStorageCapability, "getStorageCapability"); var cachedEnvironment = null; function getRuntimeEnvironment() { if (cachedEnvironment === null) { cachedEnvironment = detectRuntimeEnvironment(); } return cachedEnvironment; } __name(getRuntimeEnvironment, "getRuntimeEnvironment"); var Telemetry = class _Telemetry { static { __name(this, "Telemetry"); } static instance = null; PROJECT_API_KEY = "phc_lyTtbYwvkdSbrcMQNPiKiiRWrrM1seyKIMjycSvItEI"; HOST = "https://eu.i.posthog.com"; UNKNOWN_USER_ID = "UNKNOWN_USER_ID"; _currUserId = null; _posthogBrowserClient = null; _posthogLoading = null; _runtimeEnvironment; _storageCapability; _source; constructor() { this._runtimeEnvironment = getRuntimeEnvironment(); this._storageCapability = getStorageCapability(this._runtimeEnvironment); this._source = this._getSourceFromLocalStorage() || this._runtimeEnvironment; const telemetryDisabled = this._checkTelemetryDisabled(); const canSupportTelemetry = this._runtimeEnvironment !== "unknown"; if (telemetryDisabled) { this._posthogBrowserClient = null; logger.debug("Telemetry disabled via localStorage"); } else if (!canSupportTelemetry) { this._posthogBrowserClient = null; logger.debug( `Telemetry disabled - unknown environment: ${this._runtimeEnvironment}` ); } else { logger.info( "Anonymized telemetry enabled. Set MCP_USE_ANONYMIZED_TELEMETRY=false in localStorage to disable." ); this._posthogLoading = this._initPostHogBrowser(); } } _getSourceFromLocalStorage() { try { if (typeof localStorage !== "undefined") { return localStorage.getItem("MCP_USE_TELEMETRY_SOURCE"); } } catch { } return null; } _checkTelemetryDisabled() { if (typeof localStorage !== "undefined" && localStorage.getItem("MCP_USE_ANONYMIZED_TELEMETRY") === "false") { return true; } return false; } async _initPostHogBrowser() { try { const posthogModule = await import("posthog-js"); const posthogModuleTyped = posthogModule; const posthog = posthogModuleTyped.default || posthogModuleTyped.posthog; if (!posthog || typeof posthog.init !== "function") { throw new Error("posthog-js module did not export expected interface"); } posthog.init(this.PROJECT_API_KEY, { api_host: this.HOST, persistence: "localStorage", autocapture: false, // We only want explicit captures capture_pageview: false, // We don't want automatic pageview tracking disable_session_recording: true, // No session recording loaded: /* @__PURE__ */ __name(() => { logger.debug("PostHog browser client initialized"); }, "loaded") }); this._posthogBrowserClient = posthog; } catch (e) { logger.warn(`Failed to initialize PostHog browser telemetry: ${e}`); this._posthogBrowserClient = null; } } /** * Get the detected runtime environment */ get runtimeEnvironment() { return this._runtimeEnvironment; } /** * Get the storage capability for this environment */ get storageCapability() { return this._storageCapability; } static getInstance() { if (!_Telemetry.instance) { _Telemetry.instance = new _Telemetry(); } return _Telemetry.instance; } /** * 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) { this._source = source; try { if (typeof localStorage !== "undefined") { localStorage.setItem("MCP_USE_TELEMETRY_SOURCE", source); } } catch { } logger.debug(`Telemetry source set to: ${source}`); } /** * Get the current source identifier. */ getSource() { return this._source; } /** * Check if telemetry is enabled. */ get isEnabled() { return this._posthogBrowserClient !== null; } get userId() { if (this._currUserId) { return this._currUserId; } try { switch (this._storageCapability) { case "localStorage": this._currUserId = this._getUserIdFromLocalStorage(); break; case "session-only": default: try { this._currUserId = `session-${generateUUID()}`; } catch (uuidError) { this._currUserId = `session-${Date.now()}-${secureRandomString()}`; } break; } } catch (e) { this._currUserId = this.UNKNOWN_USER_ID; } return this._currUserId; } /** * Get or create user ID from localStorage (Browser) */ _getUserIdFromLocalStorage() { try { if (typeof localStorage === "undefined") { throw new Error("localStorage is not available"); } try { localStorage.setItem("__mcp_use_test__", "1"); localStorage.removeItem("__mcp_use_test__"); } catch (testError) { throw new Error(`localStorage is not writable: ${testError}`); } let userId = localStorage.getItem(USER_ID_STORAGE_KEY); if (!userId) { try { userId = generateUUID(); } catch (uuidError) { userId = `${Date.now()}-${secureRandomString()}`; } localStorage.setItem(USER_ID_STORAGE_KEY, userId); } return userId; } catch (e) { logger.debug(`Failed to access localStorage for user ID: ${e}`); let sessionId; try { sessionId = `session-${generateUUID()}`; } catch (uuidError) { sessionId = `session-${Date.now()}-${secureRandomString()}`; } return sessionId; } } async capture(event) { if (this._posthogLoading) { await this._posthogLoading; } if (!this._posthogBrowserClient) { return; } const currentUserId = this.userId; const properties = { ...event.properties }; properties.mcp_use_version = getPackageVersion(); properties.language = "typescript"; properties.source = this._source; properties.runtime = this._runtimeEnvironment; if (this._posthogBrowserClient) { try { this._posthogBrowserClient.capture(event.name, { ...properties, distinct_id: currentUserId }); } catch (e) { logger.debug( `Failed to track PostHog Browser event ${event.name}: ${e}` ); } } } // ============================================================================ // Agent Events // ============================================================================ async trackAgentExecution(data) { if (!this.isEnabled) return; const event = new MCPAgentExecutionEvent(data); await this.capture(event); } // ============================================================================ // Server Events // ============================================================================ /** * Track server run event directly from an MCPServer instance. */ async trackServerRunFromServer(server, transport) { if (!this.isEnabled) return; const data = createServerRunEventData(server, transport); const event = new ServerRunEvent(data); await this.capture(event); } async trackServerInitialize(data) { if (!this.isEnabled) return; const event = new ServerInitializeEvent(data); await this.capture(event); } async trackServerToolCall(data) { if (!this.isEnabled) return; const event = new ServerToolCallEvent(data); await this.capture(event); } async trackServerResourceCall(data) { if (!this.isEnabled) return; const event = new ServerResourceCallEvent(data); await this.capture(event); } async trackServerPromptCall(data) { if (!this.isEnabled) return; const event = new ServerPromptCallEvent(data); await this.capture(event); } async trackServerContext(data) { if (!this.isEnabled) return; const event = new ServerContextEvent(data); await this.capture(event); } // ============================================================================ // Client Events // ============================================================================ async trackMCPClientInit(data) { if (!this.isEnabled) return; const event = new MCPClientInitEvent(data); await this.capture(event); } async trackConnectorInit(data) { if (!this.isEnabled) return; const event = new ConnectorInitEvent(data); await this.capture(event); } async trackClientAddServer(serverName, serverConfig) { if (!this.isEnabled) return; const event = new ClientAddServerEvent({ serverName, serverConfig }); await this.capture(event); } async trackClientRemoveServer(serverName) { if (!this.isEnabled) return; const event = new ClientRemoveServerEvent({ serverName }); await this.capture(event); } // ============================================================================ // React Hook / Browser specific events // ============================================================================ async trackUseMcpConnection(data) { if (!this.isEnabled) return; await this.capture({ name: "usemcp_connection", properties: { url_domain: new URL(data.url).hostname, // Only domain for privacy transport_type: data.transportType, success: data.success, error_type: data.errorType ?? null, connection_time_ms: data.connectionTimeMs ?? null, has_oauth: data.hasOAuth, has_sampling: data.hasSampling, has_elicitation: data.hasElicitation } }); } async trackUseMcpToolCall(data) { if (!this.isEnabled) return; await this.capture({ name: "usemcp_tool_call", properties: { tool_name: data.toolName, success: data.success, error_type: data.errorType ?? null, execution_time_ms: data.executionTimeMs ?? null } }); } async trackUseMcpResourceRead(data) { if (!this.isEnabled) return; await this.capture({ name: "usemcp_resource_read", properties: { resource_uri_scheme: data.resourceUri.split(":")[0], // Only scheme for privacy success: data.success, error_type: data.errorType ?? null } }); } // ============================================================================ // Browser-specific Methods // ============================================================================ /** * Identify the current user (useful for linking sessions) * Browser only */ identify(userId, properties) { if (this._posthogBrowserClient) { try { this._posthogBrowserClient.identify(userId, properties); } catch (e) { logger.debug(`Failed to identify user: ${e}`); } } } /** * Reset the user identity (useful for logout) * Browser only */ reset() { if (this._posthogBrowserClient) { try { this._posthogBrowserClient.reset(); } catch (e) { logger.debug(`Failed to reset user: ${e}`); } } this._currUserId = null; } // ============================================================================ // Node.js-specific Methods (no-ops in browser) // ============================================================================ /** * Flush the telemetry queue (Node.js only - no-op in browser) */ flush() { } /** * Shutdown the telemetry client (Node.js only - no-op in browser) */ shutdown() { } /** * Track package download event (Node.js only - no-op in browser) */ async trackPackageDownload(properties) { } }; var Tel = Telemetry; function setTelemetrySource(source) { Tel.getInstance().setSource(source); } __name(setTelemetrySource, "setTelemetrySource"); export { VERSION, getPackageVersion, extractModelInfo, Telemetry, Tel, setTelemetrySource };