feat: otel instrumentation as per MCP semantic convention (#306)

* feat(telemetry): OTel Instrumentation as per MCP Semantic Convention

* feat(telemetry): session duration record at session close

* feat(telemetry): close adk session for duration capture

Author: AjmeraParth132

package-lock.json

@@ -47,6 +47,7 @@ export class ToolboxClient {
     session?: AxiosInstance | null,
     clientHeaders?: ClientHeadersConfig | null,
     protocol: Protocol = Protocol.MCP,
+    telemetryEnabled = false,
   ) {
     this.coreClient = new CoreToolboxClient(
       url,
@@ -55,6 +56,7 @@ export class ToolboxClient {
       protocol,
       'toolbox-adk-js',
       VERSION,
+      telemetryEnabled,
     );
   }
 
@@ -107,4 +109,12 @@ export class ToolboxClient {
     );
     return coreTools.map(coreTool => new ToolboxTool(coreTool));
   }
+
+  /**
+   * Closes the client and flushes any pending telemetry (e.g. session duration metric).
+   * Should be called when the client is no longer needed.
+   */
+  async close(): Promise<void> {
+    await this.coreClient.close();
+  }
 }

packages/toolbox-adk/src/toolbox_adk/client.ts

@@ -28,6 +28,7 @@ import {VERSION} from '../src/toolbox_adk/version.js';
 type MockCoreClient = {
   loadTool: typeof mockLoadTool;
   loadToolset: typeof mockLoadToolset;
+  close: typeof mockClose;
 };
 
 // Define the signature of the mock constructor itself
@@ -38,8 +39,11 @@ type MockCoreClientConstructor = (
   protocol?: string | null,
   clientName?: string,
   clientVersion?: string,
+  telemetryEnabled?: boolean,
 ) => MockCoreClient;
 
+const mockClose = jest.fn<() => Promise<void>>();
+
 const mockLoadTool =
   jest.fn<
     (
@@ -64,6 +68,7 @@ const MockCoreToolboxClient = jest
   .mockImplementation(() => ({
     loadTool: mockLoadTool,
     loadToolset: mockLoadToolset,
+    close: mockClose,
   }));
 
 const MockToolboxTool = jest.fn();
@@ -88,6 +93,7 @@ describe('ToolboxClient', () => {
   beforeEach(() => {
     mockLoadTool.mockReset();
     mockLoadToolset.mockReset();
+    mockClose.mockReset();
     MockCoreToolboxClient.mockClear();
     MockToolboxTool.mockClear();
   });
@@ -105,6 +111,7 @@ describe('ToolboxClient', () => {
       'mcp-default',
       'toolbox-adk-js',
       VERSION,
+      false,
     );
   });
 
@@ -179,4 +186,28 @@ describe('ToolboxClient', () => {
 
     expect(mockLoadToolset).toHaveBeenCalledWith(undefined, {}, {}, false);
   });
+
+  it.each([false, true])(
+    'should forward telemetryEnabled=%s to core client',
+    telemetryEnabled => {
+      new ToolboxClient(
+        'http://test.url',
+        null,
+        null,
+        undefined,
+        telemetryEnabled,
+      );
+      const callArgs = MockCoreToolboxClient.mock.calls[0] as unknown[];
+      expect(callArgs[6]).toBe(telemetryEnabled);
+    },
+  );
+
+  it('should delegate close() to coreClient.close()', async () => {
+    mockClose.mockResolvedValue(undefined);
+    const client = new ToolboxClient('http://test.url');
+
+    await client.close();
+
+    expect(mockClose).toHaveBeenCalledTimes(1);
+  });
 });

packages/toolbox-adk/test/test.client.ts

@@ -61,7 +61,13 @@
         "uuid": "^11.1.0"
     },
     "peerDependencies": {
-        "zod": "^3.24.4"
+        "zod": "^3.24.4",
+        "@opentelemetry/api": "^1.9.0"
+    },
+    "peerDependenciesMeta": {
+        "@opentelemetry/api": {
+            "optional": true
+        }
     },
     "devDependencies": {
         "rimraf": "^6.1.2"

packages/toolbox-core/package.json

@@ -57,8 +57,14 @@ class ToolboxClient {
    * requests. If not provided, a new one will be created.
    * @param {ClientHeadersConfig} [clientHeaders] - Optional initial headers to
    * be included in each request.
+   * @param {Protocol} [protocol] - MCP protocol version to use. Defaults to
+   * the latest supported version. Pass a specific version (e.g.,
+   * `Protocol.MCP_v20241105`) to pin to an older revision.
    * @param {string} [clientName] - Optional name of the client package.
    * @param {string} [clientVersion] - Optional version of the client package.
+   * @param {boolean} [telemetryEnabled] - Set to `true` to enable OpenTelemetry
+   * tracing and metrics. Requires the optional `@opentelemetry/api` peer
+   * dependency. Silently ignored if the package is not installed.
    */
   constructor(
     url: string,
@@ -67,6 +73,7 @@ class ToolboxClient {
     protocol: Protocol = Protocol.MCP,
     clientName?: string,
     clientVersion?: string,
+    telemetryEnabled = false,
   ) {
     this.#clientHeaders = clientHeaders || {};
     warnIfHttpAndHeaders(url, this.#clientHeaders);
@@ -88,6 +95,7 @@ class ToolboxClient {
           protocol,
           clientName,
           clientVersion,
+          telemetryEnabled,
         );
         break;
       case Protocol.MCP_v20250326:
@@ -97,6 +105,7 @@ class ToolboxClient {
           protocol,
           clientName,
           clientVersion,
+          telemetryEnabled,
         );
         break;
       case Protocol.MCP_v20250618:
@@ -106,6 +115,7 @@ class ToolboxClient {
           protocol,
           clientName,
           clientVersion,
+          telemetryEnabled,
         );
         break;
       case Protocol.MCP_v20251125:
@@ -115,6 +125,7 @@ class ToolboxClient {
           protocol,
           clientName,
           clientVersion,
+          telemetryEnabled,
         );
         break;
       default:
@@ -360,6 +371,14 @@ class ToolboxClient {
 
     return tools;
   }
+
+  /**
+   * Closes the client and flushes any pending telemetry (e.g. session duration metric).
+   * Should be called when the client is no longer needed.
+   */
+  async close(): Promise<void> {
+    await this.#transport.close();
+  }
 }
 
 export {ToolboxClient};