Add integration tests for vMCP server (#2624)

* Add integration tests for vMCP server

The tests use real MCP backend servers created with mark3labs/mcp-go SDK
to ensure authentic protocol behavior.

Test helpers in test/integration/vmcp/helpers/ provide reusable utilities
for creating vMCP servers, MCP clients, backend servers, and common
test assertions.

* Fix race condition in context cancellation check

Use select statement instead of ctx.Err() check to avoid race condition
when checking for context cancellation in the goroutine error handler.

This follows Go best practices for context handling.

Addresses review comment from @yrobla.

Author: jhrozek

test/integration/vmcp/helpers/backend.go

@@ -0,0 +1,240 @@
+// Package helpers provides test utilities for vMCP integration tests.
+package helpers
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/mark3labs/mcp-go/mcp"
+	"github.com/mark3labs/mcp-go/server"
+)
+
+// BackendTool defines a tool for MCP backend servers.
+// It provides a simplified interface for creating tools with handlers in tests.
+//
+// The handler function receives a context and arguments map, and returns a string
+// result. The result should typically be valid JSON matching the tool's output schema.
+type BackendTool struct {
+	// Name is the unique identifier for the tool
+	Name string
+
+	// Description explains what the tool does
+	Description string
+
+	// InputSchema defines the expected input structure using JSON Schema.
+	// The schema validates the arguments passed to the tool.
+	InputSchema mcp.ToolInputSchema
+
+	// Handler processes tool calls and returns results.
+	// The handler receives the tool arguments as a map and should return
+	// a string representation of the result (typically JSON).
+	Handler func(ctx context.Context, args map[string]any) string
+}
+
+// NewBackendTool creates a new BackendTool with sensible defaults.
+// The default InputSchema is an empty object schema that accepts any properties.
+//
+// Example:
+//
+//	tool := testkit.NewBackendTool(
+//	    "create_issue",
+//	    "Create a GitHub issue",
+//	    func(ctx context.Context, args map[string]any) string {
+//	        title := args["title"].(string)
+//	        return fmt.Sprintf(`{"issue_id": 123, "title": %q}`, title)
+//	    },
+//	)
+func NewBackendTool(name, description string, handler func(ctx context.Context, args map[string]any) string) BackendTool {
+	return BackendTool{
+		Name:        name,
+		Description: description,
+		InputSchema: mcp.ToolInputSchema{
+			Type:       "object",
+			Properties: map[string]any{},
+		},
+		Handler: handler,
+	}
+}
+
+// contextKey is a private type for context keys to avoid collisions.
+type contextKey string
+
+// httpHeadersContextKey is the context key for storing HTTP headers.
+const httpHeadersContextKey contextKey = "http-headers"
+
+// GetHTTPHeadersFromContext retrieves HTTP headers from the context.
+// Returns nil if headers are not present in the context.
+func GetHTTPHeadersFromContext(ctx context.Context) http.Header {
+	headers, _ := ctx.Value(httpHeadersContextKey).(http.Header)
+	return headers
+}
+
+// BackendServerOption is a functional option for configuring a backend server.
+type BackendServerOption func(*backendServerConfig)
+
+// backendServerConfig holds configuration for creating a backend server.
+type backendServerConfig struct {
+	serverName      string
+	serverVersion   string
+	endpointPath    string
+	withTools       bool
+	withResources   bool
+	withPrompts     bool
+	captureHeaders  bool
+	httpContextFunc server.HTTPContextFunc
+}
+
+// WithBackendName sets the backend server name.
+// This name is reported in the server's initialize response.
+//
+// Default: "test-backend"
+func WithBackendName(name string) BackendServerOption {
+	return func(c *backendServerConfig) {
+		c.serverName = name
+	}
+}
+
+// WithCaptureHeaders enables capturing HTTP request headers in the context.
+// When enabled, tool handlers can access request headers via GetHTTPHeadersFromContext(ctx).
+// This is useful for testing authentication header injection.
+//
+// Default: false
+func WithCaptureHeaders() BackendServerOption {
+	return func(c *backendServerConfig) {
+		c.captureHeaders = true
+	}
+}
+
+// CreateBackendServer creates an MCP backend server using the mark3labs/mcp-go SDK.
+// It returns an *httptest.Server ready to accept streamable-HTTP connections.
+//
+// The server automatically registers all provided tools with proper closure handling
+// to avoid common Go loop variable capture bugs. Each tool's handler is invoked when
+// the tool is called via the MCP protocol.
+//
+// The server uses the streamable-HTTP transport, which is compatible with ToolHive's
+// vMCP server and supports both streaming and non-streaming requests.
+//
+// The returned httptest.Server should be closed after use with defer server.Close().
+//
+// Example:
+//
+//	// Create a simple echo tool
+//	echoTool := testkit.NewBackendTool(
+//	    "echo",
+//	    "Echo back the input message",
+//	    func(ctx context.Context, args map[string]any) string {
+//	        msg := args["message"].(string)
+//	        return fmt.Sprintf(`{"echoed": %q}`, msg)
+//	    },
+//	)
+//
+//	// Start backend server
+//	backend := testkit.CreateBackendServer(t, []BackendTool{echoTool},
+//	    testkit.WithBackendName("echo-server"),
+//	    testkit.WithBackendEndpoint("/mcp"),
+//	)
+//	defer backend.Close()
+//
+//	// Use backend URL to connect MCP client
+//	client := testkit.NewMCPClient(ctx, t, backend.URL+"/mcp")
+//	defer client.Close()
+func CreateBackendServer(tb testing.TB, tools []BackendTool, opts ...BackendServerOption) *httptest.Server {
+	tb.Helper()
+
+	// Apply default configuration
+	config := &backendServerConfig{
+		serverName:      "test-backend",
+		serverVersion:   "1.0.0",
+		endpointPath:    "/mcp",
+		withTools:       true,
+		withResources:   false,
+		withPrompts:     false,
+		captureHeaders:  false,
+		httpContextFunc: nil,
+	}
+
+	// Apply functional options
+	for _, opt := range opts {
+		opt(config)
+	}
+
+	// If captureHeaders is enabled and no custom httpContextFunc is set, use default header capture
+	if config.captureHeaders && config.httpContextFunc == nil {
+		config.httpContextFunc = func(ctx context.Context, r *http.Request) context.Context {
+			// Clone headers to avoid concurrent map access issues
+			headers := make(http.Header, len(r.Header))
+			for k, v := range r.Header {
+				headers[k] = v
+			}
+			return context.WithValue(ctx, httpHeadersContextKey, headers)
+		}
+	}
+
+	// Create MCP server with configured capabilities
+	mcpServer := server.NewMCPServer(
+		config.serverName,
+		config.serverVersion,
+		server.WithToolCapabilities(config.withTools),
+		server.WithResourceCapabilities(config.withResources, config.withResources),
+		server.WithPromptCapabilities(config.withPrompts),
+	)
+
+	// Register tools with proper closure handling to avoid loop variable capture
+	for i := range tools {
+		tool := tools[i] // Capture loop variable for closure
+		mcpServer.AddTool(
+			mcp.Tool{
+				Name:        tool.Name,
+				Description: tool.Description,
+				InputSchema: tool.InputSchema,
+			},
+			func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+				// Extract arguments from request, defaulting to empty map
+				args, ok := req.Params.Arguments.(map[string]any)
+				if !ok {
+					args = make(map[string]any)
+				}
+
+				// Invoke the tool handler
+				result := tool.Handler(ctx, args)
+
+				// Return successful result with text content
+				return &mcp.CallToolResult{
+					Content: []mcp.Content{
+						mcp.NewTextContent(result),
+					},
+				}, nil
+			},
+		)
+	}
+
+	// Create streamable HTTP server with configured endpoint
+	streamableOpts := []server.StreamableHTTPOption{
+		server.WithEndpointPath(config.endpointPath),
+	}
+
+	// Add HTTP context function if configured
+	if config.httpContextFunc != nil {
+		streamableOpts = append(streamableOpts, server.WithHTTPContextFunc(config.httpContextFunc))
+	}
+
+	streamableServer := server.NewStreamableHTTPServer(
+		mcpServer,
+		streamableOpts...,
+	)
+
+	// Start HTTP test server
+	httpServer := httptest.NewServer(streamableServer)
+
+	tb.Logf("Created MCP backend server %q (v%s) at %s%s",
+		config.serverName,
+		config.serverVersion,
+		httpServer.URL,
+		config.endpointPath,
+	)
+
+	return httpServer
+}