Add docs

Author: nirinchev

src/telemetry/telemetry.ts

@@ -14,7 +14,10 @@ type EventResult = {
 };
 
 export class Telemetry {
-    public static hostingMode?: string;
+    public static baseCommonProperties: CommonProperties = {
+        ...MACHINE_METADATA,
+        hosting_mode: "standalone",
+    };
 
     private isBufferingEvents: boolean = true;
     /** Resolves when the setup is complete or a timeout occurs */
@@ -37,14 +40,13 @@ export class Telemetry {
         userConfig: UserConfig,
         deviceId: DeviceId,
         {
-            commonProperties = { ...MACHINE_METADATA },
+            commonProperties = this.baseCommonProperties,
             eventCache = EventCache.getInstance(),
         }: {
             eventCache?: EventCache;
             commonProperties?: CommonProperties;
         } = {}
     ): Telemetry {
-        commonProperties.hosting_mode = Telemetry.hostingMode;
         const instance = new Telemetry(session, userConfig, commonProperties, { eventCache, deviceId });
 
         void instance.setup();

src/telemetry/types.ts

@@ -53,25 +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;

tests/unit/telemetry.test.ts

@@ -214,7 +214,10 @@ describe("Telemetry", () => {
         });
 
         it("should add hostingMode to events if set", async () => {
-            Telemetry.hostingMode = "vscode-extension";
+            Telemetry.baseCommonProperties = {
+                ...Telemetry.baseCommonProperties,
+                hosting_mode: "vscode-extension",
+            };
             telemetry = Telemetry.create(session, config, mockDeviceId, {
                 eventCache: mockEventCache as unknown as EventCache,
             });