feat: tests + export client metadata

Author: AjmeraParth132

docs/en/reference/cli.md

@@ -24,6 +24,7 @@ description: >
 |              | `--telemetry-gcp`          | Enable exporting directly to Google Cloud Monitoring.                                                                                                                     |             |
 |              | `--telemetry-otlp`         | Enable exporting using OpenTelemetry Protocol (OTLP) to the specified endpoint (e.g. 'http://127.0.0.1:4318')                                                             |             |
 |              | `--telemetry-service-name` | Sets the value of the service.name resource attribute for telemetry data.                                                                                                 | `toolbox`   |
+|              | `--sql-commenter`          | Append SQLCommenter-format comments (traceparent, server, tool.name, db.system.name, client metadata from `_meta["dev.mcp-toolbox/telemetry"]`) to executed SQL.          |             |
 |              | `--config`                 | File path specifying the tool configuration. Cannot be used with --configs or --config-folder.                                                                            |             |
 |              | `--configs`                | Multiple file paths specifying tool configurations. Files will be merged. Cannot be used with --config or --config-folder.                                                |             |
 |              | `--config-folder`          | Directory path containing YAML tool configuration files. All .yaml and .yml files in the directory will be loaded and merged. Cannot be used with --config or --configs.  |             |

internal/server/mcp.go

@@ -708,6 +708,29 @@ func processMcpMessage(ctx context.Context, body []byte, s *Server, protocolVers
 		attribute.String("network.protocol.name", networkProtocolName),
 	)
 
+	// Set client telemetry attributes from _meta["dev.mcp-toolbox/telemetry"]
+	if ta := util.TelemetryAttributesFromContext(ctx); ta != nil {
+		telemetryAttrs := make([]attribute.KeyValue, 0, 5)
+		if ta.ClientName != "" {
+			telemetryAttrs = append(telemetryAttrs, attribute.String("client.name", ta.ClientName))
+		}
+		if ta.ClientVersion != "" {
+			telemetryAttrs = append(telemetryAttrs, attribute.String("client.version", ta.ClientVersion))
+		}
+		if ta.ClientModel != "" {
+			telemetryAttrs = append(telemetryAttrs, attribute.String("client.model", ta.ClientModel))
+		}
+		if ta.ClientUserID != "" {
+			telemetryAttrs = append(telemetryAttrs, attribute.String("client.user.id", ta.ClientUserID))
+		}
+		if ta.ClientAgentID != "" {
+			telemetryAttrs = append(telemetryAttrs, attribute.String("client.agent.id", ta.ClientAgentID))
+		}
+		if len(telemetryAttrs) > 0 {
+			span.SetAttributes(telemetryAttrs...)
+		}
+	}
+
 	// Set network protocol version if available
 	if networkProtocolVersion != "" {
 		span.SetAttributes(attribute.String("network.protocol.version", networkProtocolVersion))

internal/server/mcp_test.go

@@ -31,6 +31,10 @@ import (
 	"github.com/googleapis/mcp-toolbox/internal/server/mcp/jsonrpc"
 	"github.com/googleapis/mcp-toolbox/internal/server/resources"
 	"github.com/googleapis/mcp-toolbox/internal/telemetry"
+	"github.com/googleapis/mcp-toolbox/internal/util"
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/propagation"
+	"go.opentelemetry.io/otel/trace"
 
 	"github.com/googleapis/mcp-toolbox/internal/testutils"
 )
@@ -1198,3 +1202,86 @@ func TestSseManagerGetNilSessionValue(t *testing.T) {
 		t.Error("expected nil session for nil session value")
 	}
 }
+
+// withTraceContextPropagator registers the W3C trace-context propagator globally
+// for the duration of the test. extractMeta delegates to otel.GetTextMapPropagator,
+// and the default global propagator is a no-op — so without this helper the
+// "extracted" trace context would always be invalid.
+func withTraceContextPropagator(t *testing.T) {
+	t.Helper()
+	prev := otel.GetTextMapPropagator()
+	otel.SetTextMapPropagator(propagation.TraceContext{})
+	t.Cleanup(func() { otel.SetTextMapPropagator(prev) })
+}
+
+func TestExtractMeta_EmptyOrInvalidBody(t *testing.T) {
+	cases := map[string][]byte{
+		"empty":      []byte(""),
+		"not json":   []byte("not json"),
+		"no _meta":   []byte(`{"params":{}}`),
+		"no params":  []byte(`{"method":"tools/call"}`),
+		"empty meta": []byte(`{"params":{"_meta":{}}}`),
+	}
+	for name, body := range cases {
+		t.Run(name, func(t *testing.T) {
+			ctx := extractMeta(context.Background(), body)
+			if util.TelemetryAttributesFromContext(ctx) != nil {
+				t.Error("expected no telemetry attributes")
+			}
+		})
+	}
+}
+
+func TestExtractMeta_TraceparentOnly(t *testing.T) {
+	withTraceContextPropagator(t)
+	body := []byte(`{"params":{"_meta":{"traceparent":"00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01"}}}`)
+	ctx := extractMeta(context.Background(), body)
+
+	sc := trace.SpanContextFromContext(ctx)
+	if !sc.IsValid() {
+		t.Fatal("expected valid span context from extracted traceparent")
+	}
+	if got := sc.TraceID().String(); got != "0af7651916cd43dd8448eb211c80319c" {
+		t.Errorf("trace id mismatch: got %s", got)
+	}
+	if util.TelemetryAttributesFromContext(ctx) != nil {
+		t.Error("expected no telemetry attributes when only traceparent is sent")
+	}
+}
+
+func TestExtractMeta_TelemetryAttrsOnly(t *testing.T) {
+	body := []byte(`{"params":{"_meta":{"dev.mcp-toolbox/telemetry":{` +
+		`"client.name":"toolbox-langchain-python",` +
+		`"client.version":"v0.1.0",` +
+		`"client.model":"gemini-2.5-flash",` +
+		`"client.user.id":"user-123",` +
+		`"client.agent.id":"agent-456"}}}}`)
+
+	ta := util.TelemetryAttributesFromContext(extractMeta(context.Background(), body))
+	if ta == nil {
+		t.Fatal("expected TelemetryAttributes in context")
+	}
+	want := util.TelemetryAttributes{
+		ClientName: "toolbox-langchain-python", ClientVersion: "v0.1.0",
+		ClientModel: "gemini-2.5-flash", ClientUserID: "user-123", ClientAgentID: "agent-456",
+	}
+	if *ta != want {
+		t.Errorf("got %+v, want %+v", *ta, want)
+	}
+}
+
+func TestExtractMeta_TraceparentAndTelemetryBoth(t *testing.T) {
+	withTraceContextPropagator(t)
+	body := []byte(`{"params":{"_meta":{` +
+		`"traceparent":"00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01",` +
+		`"dev.mcp-toolbox/telemetry":{"client.name":"foo","client.version":"v1"}}}}`)
+	ctx := extractMeta(context.Background(), body)
+
+	if !trace.SpanContextFromContext(ctx).IsValid() {
+		t.Error("expected valid span context")
+	}
+	ta := util.TelemetryAttributesFromContext(ctx)
+	if ta == nil || ta.ClientName != "foo" || ta.ClientVersion != "v1" {
+		t.Errorf("expected telemetry attrs alongside traceparent, got %+v", ta)
+	}
+}