chore: expose a hook to specify telemetry hosting mode MCP-166 (#501)

Author: nirinchev

src/telemetry/telemetry.ts

@@ -35,14 +35,21 @@ export class Telemetry {
         userConfig: UserConfig,
         deviceId: DeviceId,
         {
-            commonProperties = { ...MACHINE_METADATA },
+            commonProperties = {},
             eventCache = EventCache.getInstance(),
         }: {
+            commonProperties?: Partial<CommonProperties>;
             eventCache?: EventCache;
-            commonProperties?: CommonProperties;
         } = {}
     ): Telemetry {
-        const instance = new Telemetry(session, userConfig, commonProperties, { eventCache, deviceId });
+        const mergedProperties = {
+            ...MACHINE_METADATA,
+            ...commonProperties,
+        };
+        const instance = new Telemetry(session, userConfig, mergedProperties, {
+            eventCache,
+            deviceId,
+        });
 
         void instance.setup();
         return instance;

src/telemetry/types.ts

@@ -53,24 +53,85 @@ export type ServerEvent = TelemetryEvent<ServerEventProperties>;
  * Interface for static properties, they can be fetched once and reused.
  */
 export type CommonStaticProperties = {
+    /**
+     * The version of the MCP server (as read from package.json).
+     */
     mcp_server_version: string;
+
+    /**
+     * The name of the MCP server (as read from package.json).
+     */
     mcp_server_name: string;
+
+    /**
+     * The platform/OS the MCP server is running on.
+     */
     platform: string;
+
+    /**
+     * The architecture of the OS the server is running on.
+     */
     arch: string;
+
+    /**
+     * Same as platform.
+     */
     os_type: string;
+
+    /**
+     * The version of the OS the server is running on.
+     */
     os_version?: string;
 };
 
 /**
  * Common properties for all events that might change.
  */
 export type CommonProperties = {
+    /**
+     * The device id - will be populated with the machine id when it resolves.
+     */
     device_id?: string;
+
+    /**
+     * A boolean indicating whether the server is running in a container environment.
+     */
     is_container_env?: boolean;
+
+    /**
+     * The version of the MCP client as reported by the client on session establishment.
+     */
     mcp_client_version?: string;
+
+    /**
+     * The name of the MCP client as reported by the client on session establishment.
+     */
     mcp_client_name?: string;
+
+    /**
+     * The transport protocol used by the MCP server.
+     */
     transport?: "stdio" | "http";
+
+    /**
+     * A boolean indicating whether Atlas credentials are configured.
+     */
     config_atlas_auth?: TelemetryBoolSet;
+
+    /**
+     * A boolean indicating whether a connection string is configured.
+     */
     config_connection_string?: TelemetryBoolSet;
+
+    /**
+     * The randomly generated session id.
+     */
     session_id?: string;
+
+    /**
+     * The way the MCP server is hosted - e.g. standalone for a server running independently or
+     * "vscode" if embedded in the VSCode extension. This field should be populated by the hosting
+     * application to differentiate events coming from an MCP server it's hosting.
+     */
+    hosting_mode?: string;
 } & CommonStaticProperties;

src/transports/base.ts

@@ -14,12 +14,14 @@ import {
     type ConnectionErrorHandler,
     connectionErrorHandler as defaultConnectionErrorHandler,
 } from "../common/connectionErrorHandler.js";
+import type { CommonProperties } from "../telemetry/types.js";
 
 export type TransportRunnerConfig = {
     userConfig: UserConfig;
     createConnectionManager?: ConnectionManagerFactoryFn;
     connectionErrorHandler?: ConnectionErrorHandler;
     additionalLoggers?: LoggerBase[];
+    telemetryProperties?: Partial<CommonProperties>;
 };
 
 export abstract class TransportRunnerBase {
@@ -28,16 +30,19 @@ export abstract class TransportRunnerBase {
     protected readonly userConfig: UserConfig;
     private readonly createConnectionManager: ConnectionManagerFactoryFn;
     private readonly connectionErrorHandler: ConnectionErrorHandler;
+    private readonly telemetryProperties: Partial<CommonProperties>;
 
     protected constructor({
         userConfig,
         createConnectionManager = createMCPConnectionManager,
         connectionErrorHandler = defaultConnectionErrorHandler,
         additionalLoggers = [],
+        telemetryProperties = {},
     }: TransportRunnerConfig) {
         this.userConfig = userConfig;
         this.createConnectionManager = createConnectionManager;
         this.connectionErrorHandler = connectionErrorHandler;
+        this.telemetryProperties = telemetryProperties;
         const loggers: LoggerBase[] = [...additionalLoggers];
         if (this.userConfig.loggers.includes("stderr")) {
             loggers.push(new ConsoleLogger(Keychain.root));
@@ -85,7 +90,9 @@ export abstract class TransportRunnerBase {
             keychain: Keychain.root,
         });
 
-        const telemetry = Telemetry.create(session, this.userConfig, this.deviceId);
+        const telemetry = Telemetry.create(session, this.userConfig, this.deviceId, {
+            commonProperties: this.telemetryProperties,
+        });
 
         const result = new Server({
             mcpServer,

tests/integration/transports/streamableHttp.test.ts

@@ -1,7 +1,7 @@
 import { StreamableHttpRunner } from "../../../src/transports/streamableHttp.js";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import { describe, expect, it, beforeAll, afterAll, beforeEach } from "vitest";
+import { describe, expect, it, beforeAll, afterAll, beforeEach, afterEach } from "vitest";
 import { config } from "../../../src/common/config.js";
 import type { LoggerType, LogLevel, LogPayload } from "../../../src/common/logger.js";
 import { LoggerBase, LogId } from "../../../src/common/logger.js";
@@ -159,4 +159,26 @@ describe("StreamableHttpRunner", () => {
             expect(serverStartedMessage?.level).toBe("info");
         });
     });
+
+    describe("with telemetry properties", () => {
+        afterEach(async () => {
+            await runner.close();
+            config.telemetry = oldTelemetry;
+            config.loggers = oldLoggers;
+            config.httpHeaders = {};
+        });
+
+        it("merges them with the base properties", async () => {
+            config.telemetry = "enabled";
+            runner = new StreamableHttpRunner({
+                userConfig: config,
+                telemetryProperties: { hosting_mode: "vscode-extension" },
+            });
+            await runner.start();
+
+            const server = await runner["setupServer"]();
+            const properties = server["telemetry"].getCommonProperties();
+            expect(properties.hosting_mode).toBe("vscode-extension");
+        });
+    });
 });