Merge branch 'main' into fgrosse/479-connection-closing-callback

Author: fgrosse

README.md

@@ -21,7 +21,7 @@ software development kit (SDK) for the Model Context Protocol (MCP).
 
 ## Package documentation
 
-The SDK consists of three importable packages:
+The SDK consists of several importable packages:
 
 - The
   [`github.com/modelcontextprotocol/go-sdk/mcp`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp)
@@ -34,6 +34,10 @@ The SDK consists of three importable packages:
   [`github.com/modelcontextprotocol/go-sdk/auth`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/auth)
   package provides some primitives for supporting oauth.
 
+- The
+  [`github.com/modelcontextprotocol/go-sdk/oauthex`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/oauthex)
+  package provides extensions to the OAuth protocol, such as ProtectedResourceMetadata.
+
 ## Getting started
 
 To get started creating an MCP server, create an `mcp.Server` instance, add

docs/troubleshooting.md

@@ -39,12 +39,15 @@ func ExampleLoggingTransport() {
 	if _, err := client.Connect(ctx, logTransport, nil); err != nil {
 		log.Fatal(err)
 	}
-	fmt.Println(b.String())
+	// Sort for stability: reads are concurrent to writes.
+	for _, line := range slices.Sorted(strings.SplitSeq(b.String(), "\n")) {
+		fmt.Println(line)
+	}
+
 	// Output:
-	// write: {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{"roots":{"listChanged":true}},"clientInfo":{"name":"client","version":"v0.0.1"},"protocolVersion":"2025-06-18"}}
 	// read: {"jsonrpc":"2.0","id":1,"result":{"capabilities":{"logging":{}},"protocolVersion":"2025-06-18","serverInfo":{"name":"server","version":"v0.0.1"}}}
+	// write: {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{"roots":{"listChanged":true}},"clientInfo":{"name":"client","version":"v0.0.1"},"protocolVersion":"2025-06-18"}}
 	// write: {"jsonrpc":"2.0","method":"notifications/initialized","params":{}}
-
 }
 ```
 

internal/readme/README.src.md

@@ -20,7 +20,7 @@ software development kit (SDK) for the Model Context Protocol (MCP).
 
 ## Package documentation
 
-The SDK consists of three importable packages:
+The SDK consists of several importable packages:
 
 - The
   [`github.com/modelcontextprotocol/go-sdk/mcp`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp)
@@ -33,6 +33,10 @@ The SDK consists of three importable packages:
   [`github.com/modelcontextprotocol/go-sdk/auth`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/auth)
   package provides some primitives for supporting oauth.
 
+- The
+  [`github.com/modelcontextprotocol/go-sdk/oauthex`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/oauthex)
+  package provides extensions to the OAuth protocol, such as ProtectedResourceMetadata.
+
 ## Getting started
 
 To get started creating an MCP server, create an `mcp.Server` instance, add

mcp/cmd_test.go

@@ -226,7 +226,7 @@ func TestCmdTransport(t *testing.T) {
 			&mcp.TextContent{Text: "Hi user"},
 		},
 	}
-	if diff := cmp.Diff(want, got); diff != "" {
+	if diff := cmp.Diff(want, got, ctrCmpOpts...); diff != "" {
 		t.Errorf("greet returned unexpected content (-want +got):\n%s", diff)
 	}
 	if err := session.Close(); err != nil {

mcp/content_nil_test.go

@@ -72,7 +72,7 @@ func TestContentUnmarshalNil(t *testing.T) {
 			}
 
 			// Verify that the Content field was properly populated
-			if cmp.Diff(tt.want, tt.content) != "" {
+			if cmp.Diff(tt.want, tt.content, ctrCmpOpts...) != "" {
 				t.Errorf("Content is not equal: %v", cmp.Diff(tt.content, tt.content))
 			}
 		})
@@ -222,3 +222,5 @@ func TestContentUnmarshalNilWithInvalidContent(t *testing.T) {
 		})
 	}
 }
+
+var ctrCmpOpts = []cmp.Option{cmp.AllowUnexported(mcp.CallToolResult{})}

mcp/event_test.go

@@ -287,7 +287,7 @@ func BenchmarkMemoryEventStore(b *testing.B) {
 			payload := make([]byte, test.datasize)
 			start := time.Now()
 			b.ResetTimer()
-			for i := 0; i < b.N; i++ {
+			for i := range b.N {
 				sessionID := sessionIDs[i%len(sessionIDs)]
 				streamID := streamIDs[i%len(sessionIDs)][i%3]
 				store.Append(ctx, sessionID, streamID, payload)

mcp/mcp_test.go

@@ -234,7 +234,7 @@ func TestEndToEnd(t *testing.T) {
 				&TextContent{Text: "hi user"},
 			},
 		}
-		if diff := cmp.Diff(wantHi, gotHi); diff != "" {
+		if diff := cmp.Diff(wantHi, gotHi, ctrCmpOpts...); diff != "" {
 			t.Errorf("tools/call 'greet' mismatch (-want +got):\n%s", diff)
 		}
 
@@ -253,7 +253,7 @@ func TestEndToEnd(t *testing.T) {
 				&TextContent{Text: errTestFailure.Error()},
 			},
 		}
-		if diff := cmp.Diff(wantFail, gotFail); diff != "" {
+		if diff := cmp.Diff(wantFail, gotFail, ctrCmpOpts...); diff != "" {
 			t.Errorf("tools/call 'fail' mismatch (-want +got):\n%s", diff)
 		}
 
@@ -1717,7 +1717,7 @@ func TestPointerArgEquivalence(t *testing.T) {
 		if err != nil {
 			t.Fatal(err)
 		}
-		if diff := cmp.Diff(r0, r1); diff != "" {
+		if diff := cmp.Diff(r0, r1, ctrCmpOpts...); diff != "" {
 			t.Errorf("CallTool(%v) with no arguments mismatch (-%s +%s):\n%s", args, t0.Name, t1.Name, diff)
 		}
 	}
@@ -1733,7 +1733,7 @@ func TestPointerArgEquivalence(t *testing.T) {
 			if err != nil {
 				t.Fatal(err)
 			}
-			if diff := cmp.Diff(r0, r1); diff != "" {
+			if diff := cmp.Diff(r0, r1, ctrCmpOpts...); diff != "" {
 				t.Errorf("CallTool({\"In\": %q}) mismatch (-%s +%s):\n%s", in, t0.Name, t1.Name, diff)
 			}
 		})
@@ -1837,3 +1837,70 @@ func TestEmbeddedStructResponse(t *testing.T) {
 		t.Errorf("CallTool() failed: %v", err)
 	}
 }
+
+func TestToolErrorMiddleware(t *testing.T) {
+	ctx := context.Background()
+	ct, st := NewInMemoryTransports()
+
+	s := NewServer(testImpl, nil)
+	AddTool(s, &Tool{
+		Name:        "greet",
+		Description: "say hi",
+	}, sayHi)
+	AddTool(s, &Tool{Name: "fail", InputSchema: &jsonschema.Schema{Type: "object"}},
+		func(context.Context, *CallToolRequest, map[string]any) (*CallToolResult, any, error) {
+			return nil, nil, errTestFailure
+		})
+
+	var middleErr error
+	s.AddReceivingMiddleware(func(h MethodHandler) MethodHandler {
+		return func(ctx context.Context, method string, req Request) (Result, error) {
+			res, err := h(ctx, method, req)
+			if err == nil {
+				if ctr, ok := res.(*CallToolResult); ok {
+					middleErr = ctr.getError()
+				}
+			}
+			return res, err
+		}
+	})
+	_, err := s.Connect(ctx, st, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	client := NewClient(&Implementation{Name: "test-client"}, nil)
+	clientSession, err := client.Connect(ctx, ct, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer clientSession.Close()
+
+	_, err = clientSession.CallTool(ctx, &CallToolParams{
+		Name:      "greet",
+		Arguments: map[string]any{"Name": "al"},
+	})
+	if err != nil {
+		t.Errorf("CallTool() failed: %v", err)
+	}
+	if middleErr != nil {
+		t.Errorf("middleware got error %v, want nil", middleErr)
+	}
+	res, err := clientSession.CallTool(ctx, &CallToolParams{
+		Name: "fail",
+	})
+	if err != nil {
+		t.Errorf("CallTool() failed: %v", err)
+	}
+	if !res.IsError {
+		t.Fatal("want error, got none")
+	}
+	// Clients can't see the error, because it isn't marshaled.
+	if err := res.getError(); err != nil {
+		t.Fatalf("got %v, want nil", err)
+	}
+	if middleErr != errTestFailure {
+		t.Errorf("middleware got err %v, want errTestFailure", middleErr)
+	}
+}
+
+var ctrCmpOpts = []cmp.Option{cmp.AllowUnexported(CallToolResult{})}

mcp/protocol.go

@@ -103,13 +103,26 @@ type CallToolResult struct {
 	// tool handler returns an error, and the error string is included as text in
 	// the Content field.
 	IsError bool `json:"isError,omitempty"`
+
+	// The error passed to setError, if any.
+	// It is not marshaled, and therefore it is only visible on the server.
+	// Its only use is in server sending middleware, where it can be accessed
+	// with getError.
+	err error
 }
 
 // TODO(#64): consider exposing setError (and getError), by adding an error
 // field on CallToolResult.
 func (r *CallToolResult) setError(err error) {
 	r.Content = []Content{&TextContent{Text: err.Error()}}
 	r.IsError = true
+	r.err = err
+}
+
+// getError returns the error set with setError, or nil if none.
+// This function always returns nil on clients.
+func (r *CallToolResult) getError() error {
+	return r.err
 }
 
 func (*CallToolResult) isResult() {}

mcp/protocol_test.go

@@ -499,7 +499,7 @@ func TestContentUnmarshal(t *testing.T) {
 		if err := json.Unmarshal(data, out); err != nil {
 			t.Fatal(err)
 		}
-		if diff := cmp.Diff(in, out); diff != "" {
+		if diff := cmp.Diff(in, out, ctrCmpOpts...); diff != "" {
 			t.Errorf("mismatch (-want, +got):\n%s", diff)
 		}
 	}

mcp/server.go

@@ -292,7 +292,7 @@ func toolForErr[In, Out any](t *Tool, h ToolHandlerFor[In, Out]) (*Tool, ToolHan
 			// https://modelcontextprotocol.io/specification/2025-06-18/server/tools#structured-content.
 			if res.Content == nil {
 				res.Content = []Content{&TextContent{
-					Text: string(outbytes),
+					Text: string(outJSON),
 				}}
 			}
 		}