feat(contrib/mark3labs/mcp-go): expose captured intent to tool handlers via context

The intent-capture middleware annotates the LLMObs span with the client-
supplied telemetry.intent, but tool handlers had no way to read it without
re-parsing the telemetry blob (which the same middleware strips before the
handler runs).

Stash the intent on context.Context alongside the existing LLMObs annotation
and export IntentFromContext / ContextWithIntent helpers so handlers can
forward the intent downstream (e.g. to a search API for retrieval/ranking
experiments).

Ported from internal dd-source PR #443664.

Author: jboolean

contrib/mark3labs/mcp-go/intent_capture.go

@@ -141,6 +141,36 @@ func requiredAsStringSlice(raw any) ([]string, bool) {
 	}
 }
 
+// intentCtxKey is the context key used to stash the captured intent so tool
+// handlers can forward it downstream (e.g. to a search API). Kept unexported
+// to force callers through IntentFromContext.
+type intentCtxKey struct{}
+
+// IntentFromContext returns the captured intent for the current MCP tool call,
+// if intent capture is enabled and the client supplied a non-empty
+// telemetry.intent. The boolean is false when no intent is available.
+func IntentFromContext(ctx context.Context) (string, bool) {
+	if ctx == nil {
+		return "", false
+	}
+	v, ok := ctx.Value(intentCtxKey{}).(string)
+	if !ok || v == "" {
+		return "", false
+	}
+	return v, true
+}
+
+// ContextWithIntent returns a copy of ctx that carries the given intent. The
+// middleware uses this internally; it is exported so tests (and callers that
+// fabricate their own contexts outside the standard middleware chain) can seed
+// the value that IntentFromContext will later read.
+func ContextWithIntent(ctx context.Context, intent string) context.Context {
+	if intent == "" {
+		return ctx
+	}
+	return context.WithValue(ctx, intentCtxKey{}, intent)
+}
+
 // Removing tracing parameters from the tool call request so its not sent to the tool.
 // This must be registered after the tool handler middleware (mcp-go runs middleware in registration order).
 // This removes the telemetry parameter before user-defined middleware or tool handlers can see it.
@@ -149,7 +179,10 @@ var processAndRemoveTelemetryToolMiddleware = func(next server.ToolHandlerFunc)
 		if m, ok := request.Params.Arguments.(map[string]any); ok && m != nil {
 			if telemetryVal, has := m[instrmcp.TelemetryKey]; has {
 				if telemetryMap, ok := telemetryVal.(map[string]any); ok {
-					processTelemetry(ctx, telemetryMap)
+					if intent := extractIntent(telemetryMap); intent != "" {
+						annotateIntentOnSpan(ctx, intent)
+						ctx = ContextWithIntent(ctx, intent)
+					}
 				} else if instr != nil && instr.Logger() != nil {
 					instr.Logger().Warn("mcp-go intent capture: telemetry value is not a map")
 				}
@@ -161,26 +194,35 @@ var processAndRemoveTelemetryToolMiddleware = func(next server.ToolHandlerFunc)
 	}
 }
 
-func processTelemetry(ctx context.Context, telemetryVal map[string]any) {
+// extractIntent pulls the intent string out of the telemetry map supplied by
+// the MCP client. It returns "" when the entry is missing, the wrong type, or
+// empty — callers should treat that as "no intent" and skip further work.
+func extractIntent(telemetryVal map[string]any) string {
 	if telemetryVal == nil {
-		return
+		return ""
 	}
-
 	intentVal, exists := telemetryVal[instrmcp.IntentKey]
 	if !exists {
-		return
+		return ""
 	}
-
 	intent, ok := intentVal.(string)
-	if !ok || intent == "" {
-		return
+	if !ok {
+		return ""
 	}
+	return intent
+}
 
+// annotateIntentOnSpan records intent on the active LLM Obs tool span, if one
+// is present on ctx. It is a no-op when no span is active or the active span
+// is not a tool span, so it is always safe to call.
+func annotateIntentOnSpan(ctx context.Context, intent string) {
+	if intent == "" {
+		return
+	}
 	span, ok := llmobs.SpanFromContext(ctx)
 	if !ok {
 		return
 	}
-
 	toolSpan, ok := span.AsTool()
 	if !ok {
 		return

contrib/mark3labs/mcp-go/intent_capture_test.go

@@ -25,6 +25,8 @@ func TestIntentCapture(t *testing.T) {
 	srv := server.NewMCPServer("test-server", "1.0.0", WithMCPServerTracing(&TracingConfig{IntentCaptureEnabled: true}))
 
 	var receivedArgs map[string]any
+	var receivedIntent string
+	var receivedIntentOK bool
 	calcTool := mcp.NewTool("calculator",
 		mcp.WithDescription("A simple calculator"),
 		mcp.WithString("operation", mcp.Required(), mcp.Description("The operation to perform")),
@@ -33,6 +35,7 @@ func TestIntentCapture(t *testing.T) {
 
 	srv.AddTool(calcTool, func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
 		receivedArgs = request.Params.Arguments.(map[string]any)
+		receivedIntent, receivedIntentOK = IntentFromContext(ctx)
 		return mcp.NewToolResultText(`{"result":8}`), nil
 	})
 
@@ -81,6 +84,11 @@ func TestIntentCapture(t *testing.T) {
 	assert.Equal(t, float64(3), receivedArgs["y"])
 	assert.NotContains(t, receivedArgs, "telemetry")
 
+	// Verify intent was stashed in ctx so the handler can forward it downstream
+	// (e.g. into a search API request) without re-reading the telemetry blob.
+	assert.True(t, receivedIntentOK, "IntentFromContext should report a value")
+	assert.Equal(t, "test intent description", receivedIntent)
+
 	// Verify intent was recorded on the LLMObs span
 	spans := tt.WaitForLLMObsSpans(t, 1)
 	require.Len(t, spans, 1)
@@ -92,6 +100,53 @@ func TestIntentCapture(t *testing.T) {
 	assert.Equal(t, "test intent description", toolSpan.Meta["intent"])
 }
 
+func TestIntentFromContext(t *testing.T) {
+	ctx := context.Background()
+
+	_, ok := IntentFromContext(ctx)
+	assert.False(t, ok)
+
+	ctx2 := ContextWithIntent(ctx, "find recent errors")
+	got, ok := IntentFromContext(ctx2)
+	assert.True(t, ok)
+	assert.Equal(t, "find recent errors", got)
+
+	// Empty intent does not seed the context.
+	ctx3 := ContextWithIntent(ctx, "")
+	_, ok = IntentFromContext(ctx3)
+	assert.False(t, ok)
+}
+
+func TestIntentFromContext_AbsentWhenNoTelemetry(t *testing.T) {
+	tt := testTracer(t)
+	defer tt.Stop()
+
+	srv := server.NewMCPServer("test-server", "1.0.0", WithMCPServerTracing(&TracingConfig{IntentCaptureEnabled: true}))
+
+	var receivedIntent string
+	var receivedIntentOK bool
+	calcTool := mcp.NewTool("calculator",
+		mcp.WithDescription("A simple calculator"),
+		mcp.WithString("operation", mcp.Required(), mcp.Description("The operation to perform")),
+		mcp.WithNumber("x", mcp.Required(), mcp.Description("First number")),
+		mcp.WithNumber("y", mcp.Required(), mcp.Description("Second number")))
+
+	srv.AddTool(calcTool, func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+		receivedIntent, receivedIntentOK = IntentFromContext(ctx)
+		return mcp.NewToolResultText(`{"result":8}`), nil
+	})
+
+	ctx := context.Background()
+	session := &mockSession{id: "test"}
+	session.Initialize()
+	ctx = srv.WithContext(ctx, session)
+
+	srv.HandleMessage(ctx, []byte(`{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"calculator","arguments":{"operation":"add","x":5,"y":3}}}`))
+
+	assert.False(t, receivedIntentOK, "IntentFromContext should be empty when no telemetry was supplied")
+	assert.Empty(t, receivedIntent)
+}
+
 func TestIntentCaptureRawInputSchemaPreservesUnknownFields(t *testing.T) {
 	// Tools defined with NewToolWithRawSchema may declare JSON Schema
 	// keywords beyond what mcp.ToolInputSchema models (additionalProperties,