Add support for _meta field in tool calls

Implements support for the optional _meta field in CallToolRequest as
specified in the MCP specification (2025-11-25). The echo tool now
accepts metadata in requests and echoes it back in responses, enabling
validation of metadata propagation through MCP clients, proxies, and
routers.

Common metadata use cases include request tracking (progressToken),
client context, debugging, and testing metadata propagation through
complex MCP architectures.

Fixes #67

Author: yrobla

cmd/yardstick-server/README.md

@@ -73,9 +73,10 @@ docker run -p 8080:8080 -e MCP_TRANSPORT=streamable-http -e PORT=8080 ghcr.io/st
 ```
 
 ## Tools
+
 ### `echo` Tool
 
-The server exposes a single tool called `echo` with the following specification:
+A deterministic echo tool for basic testing and validation. This tool also supports metadata echoing for testing metadata propagation through MCP implementations.
 
 **Input Schema:**
 ```json
@@ -92,13 +93,77 @@ The server exposes a single tool called `echo` with the following specification:
 }
 ```
 
-**Output:**
+**Output (StructuredContent):**
 ```json
 {
   "output": "input_string"
 }
 ```
 
+**Metadata Support:**
+The `echo` tool accepts and echoes back the optional `_meta` field from tool call requests. Any metadata provided in the request's `_meta` field will be returned in the response's `_meta` field, enabling validation that:
+- MCP clients correctly pass metadata in tool calls
+- Servers properly return metadata in responses
+- Proxies and routers preserve metadata throughout the request/response lifecycle
+- Metadata can be used for request tracking, debugging, and observability
+
+When metadata is present, it is also logged to the server's output for debugging purposes.
+
+**Example Request with Metadata:**
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "tools/call",
+  "params": {
+    "name": "echo",
+    "arguments": {
+      "input": "test123"
+    },
+    "_meta": {
+      "progressToken": "task123",
+      "requestId": "req-456",
+      "clientInfo": "test-client-v1"
+    }
+  }
+}
+```
+
+**Example Response with Metadata:**
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "content": [
+      {
+        "type": "text",
+        "text": "{\"output\":\"test123\"}"
+      }
+    ],
+    "_meta": {
+      "progressToken": "task123",
+      "requestId": "req-456",
+      "clientInfo": "test-client-v1"
+    }
+  }
+}
+```
+
+## Metadata Field Support
+
+The `echo` tool supports the optional `_meta` field as specified in the [MCP specification (2025-11-25)](https://modelcontextprotocol.io). The `_meta` field allows clients and servers to attach additional metadata to their interactions without exposing it to the LLM.
+
+**Common use cases:**
+- **Request tracking**: Using `progressToken` for progress notifications
+- **Client context**: Passing client version, user information, or session data
+- **Debugging**: Including trace IDs, debug levels, or diagnostic information
+- **Testing**: Validating metadata propagation through complex MCP architectures
+
+**Standard Fields:**
+While the `_meta` field accepts any key-value pairs, the MCP specification defines some standard fields:
+- `progressToken`: An opaque token for associating progress notifications with requests
+
 ## Development
 
 ### Running tests

cmd/yardstick-server/integration_test.go

@@ -175,7 +175,8 @@ func TestEndToEndEchoFunctionality(t *testing.T) {
 				assert.True(t, result.IsError)
 			} else {
 				assert.NoError(t, err)
-				assert.Nil(t, result) // When successful, result is nil and response contains the data
+				// Result is nil when no metadata is present (original behavior)
+				assert.Nil(t, result)
 				assert.NotNil(t, response)
 				assert.Equal(t, tc.input, response.Output)
 			}
@@ -206,6 +207,7 @@ func TestServerStartup(t *testing.T) {
 
 			result, response, err := echoHandler(context.Background(), req, params)
 			assert.NoError(t, err)
+			// Result is nil when no metadata (original behavior)
 			assert.Nil(t, result)
 			assert.NotNil(t, response)
 		})
@@ -232,8 +234,9 @@ func TestConcurrentEchoRequests(t *testing.T) {
 				return
 			}
 
-			if result != nil {
-				results <- fmt.Errorf("expected nil result for request %d", id)
+			// Result is nil when no metadata is present (this is expected)
+			if result != nil && result.IsError {
+				results <- fmt.Errorf("unexpected error result for request %d", id)
 				return
 			}
 

cmd/yardstick-server/main.go

@@ -56,7 +56,14 @@ func authWrapper(next http.Handler) http.Handler {
 	})
 }
 
-func echoHandler(_ context.Context, _ *mcp.CallToolRequest, params EchoRequest) (*mcp.CallToolResult, EchoResponse, error) {
+func echoHandler(_ context.Context, req *mcp.CallToolRequest, params EchoRequest) (*mcp.CallToolResult, EchoResponse, error) {
+	// Extract metadata from request to echo back in response
+	var metadata mcp.Meta
+	if req.Params != nil && len(req.Params.Meta) > 0 {
+		log.Printf("echo tool called with metadata: %+v", req.Params.Meta)
+		metadata = req.Params.Meta
+	}
+
 	if !validateAlphanumeric(params.Input) {
 		return &mcp.CallToolResult{
 			Content: []mcp.Content{&mcp.TextContent{Text: "input must be alphanumeric only"}},
@@ -68,6 +75,17 @@ func echoHandler(_ context.Context, _ *mcp.CallToolRequest, params EchoRequest)
 		Output: params.Input,
 	}
 
+	// Return result with metadata echoed back only if metadata is present
+	// When result is nil, SDK auto-populates Content from response
+	// When result is non-nil with empty Content, SDK should still auto-populate Content
+	if len(metadata) > 0 {
+		result := &mcp.CallToolResult{
+			Meta: metadata,
+		}
+		return result, response, nil
+	}
+
+	// No metadata, return nil result (original behavior)
 	return nil, response, nil
 }
 
@@ -96,8 +114,9 @@ func main() {
 
 	// Add echo tool to server using the new API
 	mcp.AddTool(server, &mcp.Tool{
-		Name:        "echo",
-		Description: "Echo back an alphanumeric string for deterministic testing",
+		Name: "echo",
+		Description: "Echo back an alphanumeric string for deterministic testing. " +
+			"Also echoes back any _meta field from the request for testing metadata propagation.",
 		InputSchema: inputSchema,
 	}, echoHandler)
 

cmd/yardstick-server/main_test.go

@@ -93,6 +93,7 @@ func TestEchoHandler(t *testing.T) {
 				assert.True(t, result.IsError)
 			} else {
 				assert.NoError(t, err)
+				// Result is nil when no metadata is present (original behavior)
 				assert.Nil(t, result)
 				assert.NotNil(t, response)
 				assert.Equal(t, tt.expectedOutput, response.Output)
@@ -188,3 +189,102 @@ func TestCheckAuth_Disabled(t *testing.T) {
 	err = checkAuth(req)
 	assert.NoError(t, err)
 }
+
+func TestEchoHandler_WithMetadata(t *testing.T) {
+	// Create request with metadata
+	requestMeta := mcp.Meta{
+		"progressToken": "test123",
+		"customKey":     "customValue",
+	}
+	req := &mcp.CallToolRequest{
+		Params: &mcp.CallToolParamsRaw{
+			Meta: requestMeta,
+		},
+	}
+	params := EchoRequest{Input: "hello"}
+
+	// Call handler
+	result, response, err := echoHandler(context.Background(), req, params)
+
+	// Verify response
+	assert.NoError(t, err)
+	assert.NotNil(t, result)
+	assert.NotNil(t, response)
+	assert.Equal(t, "hello", response.Output)
+
+	// Verify metadata is echoed back
+	assert.NotNil(t, result.Meta)
+	assert.Equal(t, requestMeta["progressToken"], result.Meta["progressToken"])
+	assert.Equal(t, requestMeta["customKey"], result.Meta["customKey"])
+}
+
+func TestEchoHandler_WithMultipleMetadataFields(t *testing.T) {
+	tests := []struct {
+		name     string
+		metadata mcp.Meta
+	}{
+		{
+			name:     "with progressToken",
+			metadata: mcp.Meta{"progressToken": "token123"},
+		},
+		{
+			name: "with multiple fields",
+			metadata: mcp.Meta{
+				"progressToken": "token456",
+				"requestId":     "req789",
+				"clientInfo":    "test-client",
+			},
+		},
+		{
+			name:     "with nested metadata",
+			metadata: mcp.Meta{"debug": map[string]any{"level": "verbose"}},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			// Create request with metadata
+			req := &mcp.CallToolRequest{
+				Params: &mcp.CallToolParamsRaw{
+					Meta: tt.metadata,
+				},
+			}
+			params := EchoRequest{Input: "test123"}
+
+			// Call handler
+			result, response, err := echoHandler(context.Background(), req, params)
+
+			// Verify response
+			assert.NoError(t, err)
+			assert.NotNil(t, result)
+			assert.NotNil(t, response)
+			assert.Equal(t, "test123", response.Output)
+
+			// Verify metadata is echoed back
+			assert.NotNil(t, result.Meta)
+			for key, expectedValue := range tt.metadata {
+				actualValue, exists := result.Meta[key]
+				assert.True(t, exists, "Expected metadata key %s to exist", key)
+				assert.Equal(t, expectedValue, actualValue, "Metadata value mismatch for key %s", key)
+			}
+		})
+	}
+}
+
+func TestEchoHandler_WithoutMetadata(t *testing.T) {
+	// Create request without metadata
+	req := &mcp.CallToolRequest{
+		Params: &mcp.CallToolParamsRaw{},
+	}
+	params := EchoRequest{Input: "test123"}
+
+	// Call handler
+	result, response, err := echoHandler(context.Background(), req, params)
+
+	// Verify response
+	assert.NoError(t, err)
+	// Result should be nil when no metadata is present (original behavior)
+	assert.Nil(t, result)
+	assert.NotNil(t, response)
+	assert.Equal(t, "test123", response.Output)
+}