Merge branch 'main' into output-validation

Author: jba

examples/server/distributed/main.go

@@ -80,7 +80,6 @@ func parent() {
 	var wg sync.WaitGroup
 	childURLs := make([]*url.URL, len(ports))
 	for i, port := range ports {
-		wg.Add(1)
 		childURL := fmt.Sprintf("http://localhost:%s", port)
 		childURLs[i], err = url.Parse(childURL)
 		if err != nil {
@@ -89,6 +88,8 @@ func parent() {
 		cmd := exec.CommandContext(ctx, exe, os.Args[1:]...)
 		cmd.Env = append(os.Environ(), fmt.Sprintf("%s=%s", childPortVar, port))
 		cmd.Stderr = os.Stderr
+
+		wg.Add(1)
 		go func() {
 			defer wg.Done()
 			log.Printf("starting child %d at %s", i, childURL)

examples/server/middleware/main.go

@@ -64,6 +64,12 @@ func main() {
 					"duration_ms", duration.Milliseconds(),
 					"has_result", result != nil,
 				)
+				// Log more for tool results.
+				if ctr, ok := result.(*mcp.CallToolResult); ok {
+					logger.Info("tool result",
+						"isError", ctr.IsError,
+						"structuredContent", ctr.StructuredContent)
+				}
 			}
 			return result, err
 		}
@@ -103,7 +109,7 @@ func main() {
 				Content: []mcp.Content{
 					&mcp.TextContent{Text: message},
 				},
-			}, nil, nil
+			}, message, nil
 		},
 	)
 

mcp/server.go

@@ -9,6 +9,7 @@ import (
 	"context"
 	"encoding/base64"
 	"encoding/gob"
+	"encoding/json"
 	"fmt"
 	"iter"
 	"maps"
@@ -153,10 +154,18 @@ func (s *Server) RemovePrompts(names ...string) {
 // If present, the output schema must also have type "object".
 //
 // When the handler is invoked as part of a CallTool request, req.Params.Arguments
-// will be a json.RawMessage. Unmarshaling the arguments and validating them against the
-// input schema are the handler author's responsibility.
+// will be a json.RawMessage.
 //
-// Most users should use the top-level function [AddTool].
+// Unmarshaling the arguments and validating them against the input schema are the
+// caller's responsibility.
+//
+// Validating the result against the output schema, if any, is the caller's responsibility.
+//
+// Setting the result's Content, StructuredContent and IsError fields are the caller's
+// responsibility.
+//
+// Most users should use the top-level function [AddTool], which handles all these
+// responsibilities.
 func (s *Server) AddTool(t *Tool, h ToolHandler) {
 	if t.InputSchema == nil {
 		// This prevents the tool author from forgetting to write a schema where
@@ -180,26 +189,6 @@ func (s *Server) AddTool(t *Tool, h ToolHandler) {
 		func() bool { s.tools.add(st); return true })
 }
 
-// ToolFor returns a shallow copy of t and a [ToolHandler] that wraps h.
-//
-// If the tool's input schema is nil, it is set to the schema inferred from the In
-// type parameter, using [jsonschema.For]. The In type parameter must be a map
-// or a struct, so that its inferred JSON Schema has type "object".
-//
-// For tools that don't return structured output, Out should be 'any'.
-// Otherwise, if the tool's output schema is nil the output schema is set to
-// the schema inferred from Out, which must be a map or a struct.
-//
-// Most users will call [AddTool]. Use [ToolFor] if you wish to modify the
-// tool's schemas or wrap the ToolHandler before calling [Server.AddTool].
-func ToolFor[In, Out any](t *Tool, h ToolHandlerFor[In, Out]) (*Tool, ToolHandler) {
-	tt, hh, err := toolForErr(t, h)
-	if err != nil {
-		panic(fmt.Sprintf("ToolFor: tool %q: %v", t.Name, err))
-	}
-	return tt, hh
-}
-
 // TODO(v0.3.0): test
 func toolForErr[In, Out any](t *Tool, h ToolHandlerFor[In, Out]) (*Tool, ToolHandler, error) {
 	tt := *t
@@ -265,26 +254,35 @@ func toolForErr[In, Out any](t *Tool, h ToolHandlerFor[In, Out]) (*Tool, ToolHan
 			return nil, fmt.Errorf("tool output: %w", err)
 		}
 
-		// TODO: return the serialized JSON in a TextContent block, as per spec?
-		// https://modelcontextprotocol.io/specification/2025-06-18/server/tools#structured-content
-		// But people may use res.Content for other things.
 		if res == nil {
 			res = &CallToolResult{}
 		}
-		if res.Content == nil {
-			res.Content = []Content{} // avoid returning 'null'
-		}
-		res.StructuredContent = out
+		// Marshal the output and put the RawMessage in the StructuredContent field.
+		var outval any = out
 		if elemZero != nil {
 			// Avoid typed nil, which will serialize as JSON null.
-			// Instead, use the zero value of the non-zero
+			// Instead, use the zero value of the unpointered type.
 			var z Out
 			if any(out) == any(z) { // zero is only non-nil if Out is a pointer type
-				res.StructuredContent = elemZero
+				outval = elemZero
 			}
 		}
+		outbytes, err := json.Marshal(outval)
+		if err != nil {
+			return nil, fmt.Errorf("marshaling output: %w", err)
+		}
+		res.StructuredContent = json.RawMessage(outbytes) // avoid a second marshal over the wire
+
+		// If the Content field isn't being used, return the serialized JSON in a
+		// TextContent block, as the spec suggests:
+		// https://modelcontextprotocol.io/specification/2025-06-18/server/tools#structured-content.
+		if res.Content == nil {
+			res.Content = []Content{&TextContent{
+				Text: string(outbytes),
+			}}
+		}
 		return res, nil
-	}
+	} // end of handler
 
 	return &tt, th, nil
 }
@@ -329,10 +327,12 @@ func setSchema[T any](sfield **jsonschema.Schema, rfield **jsonschema.Resolved)
 // For tools that don't return structured output, Out should be 'any'.
 // Otherwise, if the tool's output schema is nil the output schema is set to
 // the schema inferred from Out, which must be a map or a struct.
-//
-// It is a convenience for s.AddTool(ToolFor(t, h)).
 func AddTool[In, Out any](s *Server, t *Tool, h ToolHandlerFor[In, Out]) {
-	s.AddTool(ToolFor(t, h))
+	tt, hh, err := toolForErr(t, h)
+	if err != nil {
+		panic(fmt.Sprintf("AddTool: tool %q: %v", t.Name, err))
+	}
+	s.AddTool(tt, hh)
 }
 
 // RemoveTools removes the tools with the given names.

mcp/streamable.go

@@ -72,8 +72,8 @@ type StreamableHTTPOptions struct {
 
 	// TODO: support session retention (?)
 
-	// jsonResponse is forwarded to StreamableServerTransport.jsonResponse.
-	jsonResponse bool
+	// JSONResponse is forwarded to StreamableServerTransport.jsonResponse.
+	JSONResponse bool
 }
 
 // NewStreamableHTTPHandler returns a new [StreamableHTTPHandler].
@@ -233,7 +233,7 @@ func (h *StreamableHTTPHandler) ServeHTTP(w http.ResponseWriter, req *http.Reque
 		transport = &StreamableServerTransport{
 			SessionID:    sessionID,
 			Stateless:    h.opts.Stateless,
-			jsonResponse: h.opts.jsonResponse,
+			jsonResponse: h.opts.JSONResponse,
 		}
 
 		// To support stateless mode, we initialize the session with a default
@@ -487,7 +487,7 @@ type stream struct {
 	// jsonResponse records whether this stream should respond with application/json
 	// instead of text/event-stream.
 	//
-	// See [StreamableServerTransportOptions.jsonResponse].
+	// See [StreamableServerTransportOptions.JSONResponse].
 	jsonResponse bool
 
 	// signal is a 1-buffered channel, owned by an incoming HTTP request, that signals

mcp/streamable_test.go

@@ -84,7 +84,7 @@ func TestStreamableTransports(t *testing.T) {
 			// Start an httptest.Server with the StreamableHTTPHandler, wrapped in a
 			// cookie-checking middleware.
 			handler := NewStreamableHTTPHandler(func(req *http.Request) *Server { return server }, &StreamableHTTPOptions{
-				jsonResponse: useJSON,
+				JSONResponse: useJSON,
 			})
 
 			var (
@@ -1175,7 +1175,10 @@ func TestStreamableStateless(t *testing.T) {
 				req(2, "tools/call", &CallToolParams{Name: "greet", Arguments: hiParams{Name: "World"}}),
 			},
 			wantMessages: []jsonrpc.Message{
-				resp(2, &CallToolResult{Content: []Content{&TextContent{Text: "hi World"}}}, nil),
+				resp(2, &CallToolResult{
+					Content:           []Content{&TextContent{Text: "hi World"}},
+					StructuredContent: json.RawMessage("null"),
+				}, nil),
 			},
 			wantSessionID: false,
 		},
@@ -1186,7 +1189,10 @@ func TestStreamableStateless(t *testing.T) {
 				req(2, "tools/call", &CallToolParams{Name: "greet", Arguments: hiParams{Name: "foo"}}),
 			},
 			wantMessages: []jsonrpc.Message{
-				resp(2, &CallToolResult{Content: []Content{&TextContent{Text: "hi foo"}}}, nil),
+				resp(2, &CallToolResult{
+					Content:           []Content{&TextContent{Text: "hi foo"}},
+					StructuredContent: json.RawMessage("null"),
+				}, nil),
 			},
 			wantSessionID: false,
 		},